limoncello-php / l10n
Limoncello framework localization support.
Requires
- php: >=7.1.0
- ext-intl: *
- limoncello-php/contracts: ^0.10.0
Requires (Dev)
- mockery/mockery: ^1.0
- phpmd/phpmd: ^2.4
- phpunit/phpunit: ^7.0
- scrutinizer/ocular: ^1.4
- squizlabs/php_codesniffer: ^2.9
- dev-master
- dev-develop / 0.10.x-dev
- 0.10.0
- 0.9.3
- 0.9.2
- 0.9.1
- 0.9.0
- 0.8.10
- 0.8.9
- 0.8.8
- 0.8.7
- 0.8.6
- 0.8.5
- 0.8.4
- 0.8.3
- 0.8.2
- 0.8.1
- 0.8.0
- 0.7.4
- 0.7.3
- 0.7.2
- 0.7.1
- 0.7.0
- 0.6.x-dev
- 0.6.18
- 0.6.17
- 0.6.16
- 0.6.15
- 0.6.14
- 0.6.13
- 0.6.12
- 0.6.11
- 0.6.10
- 0.6.9
- 0.6.8
- 0.6.7
- 0.6.6
- 0.6.5
- 0.6.4
- 0.6.3
- 0.6.2
- 0.6.1
- 0.6.0
- 0.5.5
- 0.5.4
- 0.5.3
- 0.5.2
- 0.5.1
- 0.5.0
This package is auto-updated.
Last update: 2024-10-17 19:51:09 UTC
README
Summary
This is localization component for Limoncello Framework.
The component helps to translate an application into different languages. In particular, it provides an ability to manage localized files easily and extract localized strings for a given locale with a fallback to default one.
Message Localization
For a given resource storage data (later on this) the usage looks like
$storage = new BundleStorage($storageData); $localized = $storage->get('de_AT', 'ErrorMessages', 'id_or_message');
Where
- first parameter
de_AT
is a locale code. - second parameter
ErrorMessages
is messages' namespace name. Using a namespace allows message isolation across namespaces. Typically namespace is a resource file name without.php
file extension. - third parameter
id_or_message
is a message identity. A message identity should be unique across a namespace.
It first finds the closest locale (de_AT
, de
or a default one such as en
if no locale is found) and a corresponding message.
The result would contain the found message with their locale. For example
// $localized ['Hallo Welt', 'de'];
If resources for requested locale de_AT
existed the result could look like
// $localized ['Hallo Welt aus Österreich', 'de_AT'];
Resource Storage
In the example above resource storage data is an array that contains localized strings. The reason this object is introduced is a performance optimization. Looking for multiple files in a file system and analyzing their data is time and resource consuming. The storage data replaces many resource files with a single optimized for search array which could be cached.
For instance, there is a resource folder structure
Resources |_ de |_ Messages.php |_de_AT |_ Messages.php
Where Messages.php
is a plain PHP array file
<?php return [ 'Hello World' => 'Hallo Welt', ];
and
<?php return [ 'Hello World' => 'Hallo Welt aus Österreich', ];
Then, a storage array could be created as
$storageData = (new FileBundleEncoder('path/to/ResourcesFolder/'))->getStorageData('de');
Method getStorageData
has a default locale code as a first parameter.
Finally, complete example
$storageData = (new FileBundleEncoder('path/to/ResourcesFolder/'))->getStorageData('de'); $localized = (new BundleStorage($storageData))->get('de_AT', 'ErrorMessages', 'Hello World'); // $localized ['Hallo Welt aus Österreich', 'de_AT'];
Message Translation
In addition to Resource Storage, the package provides a helpful wrapper over MessageFormatter.
$storageData = (new FileBundleEncoder('path/to/ResourcesFolder/'))->getStorageData('en'); $translator = new Translator(new BundleStorage($storageData)); // 'Hallo Welt' (message is in the resources) $translator->translateMessage('de', 'Messages', 'Hello World'); // 'Hallo Welt aus Österreich' (message is in the resources) $translator->translateMessage('de_AT', 'Messages', 'Hello World'); // 'Good morning' (message not found in resources so it returns the key itself) $translator->translateMessage('de', 'Messages', 'Good morning');
Method translateMessage
has signature translateMessage(string $locale, string $namespace, string $key, array $args = []): string
. The method can accept formatting parameters via $args
parameter. For advanced formatting samples see MessageFormatter::formatMessage.
There is another wrapper for Translator
called Formatter
which hides locale code and namespace. It could be used in an environment where locale for current session is defined for a logged in user. So the code basically asks for FormatterInterface
for current locale and specified namespace.
$formatter = new Formatter('de', 'Messages', $translator); // 'Hallo Welt' $formatter->formatMessage('Hello World');
Recommended Usage
- Have a resource folder with locales needed for your application.
- For the resource folder and default locale create a storage data with
FileBundleEncoder
and cache it. - On page load read the storage data from the cache and load it into
Translator
withBundleStorage
. - Use the translator for message formatting.
Testing
$ composer test