Class I18n
I18n handles translation of Text and time format strings.
Constants
-
stringDEFAULT_LOCALE ¶'en_US'Default locale
Property Summary
-
$_collection protected static
Aura\Intl\TranslatorLocatorThe translators collection
-
$_defaultLocale protected static
stringThe environment default locale
Method Summary
-
clear() public static
Destroys all translator instances and creates a new empty translations collection.
-
config() public static
Registers a callable object that can be used for creating new translator instances for the same translations domain. Loaders will be invoked whenever a translator object is requested for a domain that has not been configured or loaded already.
-
defaultFormatter() public static
Sets the name of the default messages formatter to use for future translator instances. By default the
defaultandsprintfformatters are available. -
defaultLocale() public static
This returns the default locale before any modifications, i.e. the value as stored in the
intl.default_localePHP setting before any manipulation by this class. -
locale() public static
Sets the default locale to use for future translator instances. This also affects the
intl.default_localePHP setting. -
translator() public static
Returns an instance of a translator that was configured for the name and passed locale. If no locale is passed then it takes the value returned by the
locale()method. -
translators() public static
Returns the translators collection instance. It can be used for getting specific translators based of their name and locale or to configure some aspect of future translations that are not yet constructed.
-
useFallback() public static
Set if the domain fallback is used.
Method Detail
clear() ¶ public static
clear(): voidDestroys all translator instances and creates a new empty translations collection.
Returns
voidconfig() ¶ public static
config(string $name, callable $loader): voidRegisters a callable object that can be used for creating new translator instances for the same translations domain. Loaders will be invoked whenever a translator object is requested for a domain that has not been configured or loaded already.
Registering loaders is useful when you need to lazily use translations in multiple
different locales for the same domain, and don't want to use the built-in
translation service based of gettext files.
Loader objects will receive two arguments: The domain name that needs to be
built, and the locale that is requested. These objects can assemble the messages
from any source, but must return an Aura\Intl\Package object.
Example:
use Cake\I18n\MessagesFileLoader;
I18n::config('my_domain', function ($name, $locale) {
// Load src/Locale/$locale/filename.po
$fileLoader = new MessagesFileLoader('filename', $locale, 'po');
return $fileLoader();
});You can also assemble the package object yourself:
use Aura\Intl\Package;
I18n::config('my_domain', function ($name, $locale) {
$package = new Package('default');
$messages = (...); // Fetch messages for locale from external service.
$package->setMessages($message);
$package->setFallback('default);
return $package;
});Parameters
-
string$name The name of the translator to create a loader for
-
callable$loader A callable object that should return a Package instance to be used for assembling a new translator.
Returns
voiddefaultFormatter() ¶ public static
defaultFormatter(string|null $name = null): stringSets the name of the default messages formatter to use for future
translator instances. By default the default and sprintf formatters
are available.
If called with no arguments, it will return the currently configured value.
Parameters
-
string|null$name optional The name of the formatter to use.
Returns
stringdefaultLocale() ¶ public static
defaultLocale(): stringThis returns the default locale before any modifications, i.e.
the value as stored in the intl.default_locale PHP setting before
any manipulation by this class.
Returns
stringlocale() ¶ public static
locale(string|null $locale = null): string|voidSets the default locale to use for future translator instances.
This also affects the intl.default_locale PHP setting.
When called with no arguments it will return the currently configure
locale as stored in the intl.default_locale PHP setting.
Parameters
-
string|null$locale optional The name of the locale to set as default.
Returns
string|voidtranslator() ¶ public static
translator(string $name = 'default', string|null $locale = null, callable|null $loader = null): Aura\Intl\Translator|voidReturns an instance of a translator that was configured for the name and passed
locale. If no locale is passed then it takes the value returned by the locale() method.
This method can be used to configure future translators, this is achieved by passing a callable as the last argument of this function.
Example:
I18n::translator('default', 'fr_FR', function () {
$package = new \Aura\Intl\Package();
$package->setMessages([
'Cake' => 'Gâteau'
]);
return $package;
});
$translator = I18n::translator('default', 'fr_FR');
echo $translator->translate('Cake');You can also use the Cake\I18n\MessagesFileLoader class to load a specific
file from a folder. For example for loading a my_translations.po file from
the src/Locale/custom folder, you would do:
I18n::translator(
'default',
'fr_FR',
new MessagesFileLoader('my_translations', 'custom', 'po');
);Parameters
-
string$name optional The domain of the translation messages.
-
string|null$locale optional The locale for the translator.
-
callable|null$loader optional A callback function or callable class responsible for constructing a translations package instance.
Returns
Aura\Intl\Translator|voidtranslators() ¶ public static
translators(): Aura\Intl\TranslatorLocatorReturns the translators collection instance. It can be used for getting specific translators based of their name and locale or to configure some aspect of future translations that are not yet constructed.
Returns
Aura\Intl\TranslatorLocatoruseFallback() ¶ public static
useFallback(bool $enable = true): voidSet if the domain fallback is used.
Parameters
-
bool$enable optional flag to enable or disable fallback
Returns
void