A PHP package to manage i18n: translations, pluralization, date and number formatting according to a localization.
To create a new I18n instance, you need to pass it a I18n\Loader
object:
// Creation of the I18n Loader
$i18n_loader = new \I18n\Loader(array(
// this is the directory where your language strings are defined
'language_directory' => __DIR__.'/i18n',
// this is the list of available languages
'available_languages' => array(
'en' => 'en_US_USD',
'gb' => 'en_GB_UKP',
'fr' => 'fr_FR_EUR'
),
'default_language' => 'en',
// this is the tag construction used for replacements in strings
// by default, "%arg%" will be replacement by the argument "arg" value
// as this will be passed to a 'sprintf' PHP function, literal percent is written '%%'
'arg_wrapper_mask' => "%%%s%%",
));
// Creation of the I18n instance (statically) passing it the Loader
$translator = \I18n\I18n::getInstance($i18n_loader);
For a full list of possible Loader options, please have a look in source code.
Any option value defining a directory path or a filename construction can contains a %s
tag that will be replaced by the current language.
// for instance:
'language_directory' => __DIR__.'/i18n/%s'
// will render, for the EN language:
'language_directory' => __DIR__.'/i18n/EN'
As you can see, the I18n class is defined as a Singleton object: any future call of
\I18n\I18n::getInstance()
will refer to the first created object instance.
Then, to actually use the translated value of a string, use the translate
method:
$translator->translate( 'string_index' [, array( arguments )] [, language code] )
You can use the pluralize
method to choose a translated string depending on a number of items:
$indexes = array(
0=>'test_item_zero',
1=>'test_item_one',
2=>'test_item_two',
3=>'test_item_multi'
);
$translator->pluralize( $indexes, $number_of_items [, array( arguments )] [, language code] )
By default (this can be over-write in the Loader), the I18n object will load the strings defined as a PHP array like:
$i18n_en = array (
'datetime_mask' => '%a %e %m %Y %H:%M:%S',
'test' => 'Test in english',
'test_args' => 'I received arguments : « %arg1% » and « %arg2% »',
'test_item_zero' => 'No item',
'test_item_one' => 'Just one item',
'test_item_two' => 'Two items',
'test_item_multi' => 'There are %nb% items',
);
This may be defined in a file called i18n.CODE.php
where CODE
is the two letter reference
of the language. These files will be searched and loaded from the language_directory
loader
option value.
The I18n object is designed to be able to load multiple language files easily with:
$i18n->loadFile( my file path )
Each file loaded is stored in the internal cache system of the object (a simple PHP array).
A set of aliases functions, defined in the global namespace, are available and auto-loaded by Composer:
function _T(...) = $i18n->translate(...)
# or
function translate(...) = $i18n->translate(...)
function _P(...) = $i18n->pluralize(...)
# or
function pluralize(...) = $i18n->pluralize(...)
function _D(...) = $i18n->getLocalizedDateString(...)
# or
function datify(...) = $i18n->getLocalizedDateString(...)
The package embeds an extension to use the class in the Twig template engine. See the Twig Extension page for more infos.
For a complete information about how to install this package and load its namespace, please have a look at our USAGE documentation.
If you are a Composer user, just add the package to the
requirements of your project's composer.json
manifest file:
"atelierspierrot/internationalization": "@stable"
You can use a specific release or the latest release of a major version using the appropriate version constraint.
Please note that this package depends on the externals PHP Patterns and PHP Library.
Internationalization
Copyright (c) 2010-2016, Pierre Cassat and contributors
Licensed under the Apache 2.0 license.
Les Ateliers Pierrot - Paris, France