library l10n

limoncello-php/l10n

Limoncello framework localization support.

, _(*1)

Summary

This is localization component for Limoncello Framework., _(*2)

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., _(*3)

Message Localization

For a given resource storage data (later on this) the usage looks like, _(*4)

    $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., _(*5)

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., _(*6)

The result would contain the found message with their locale. For example, _(*7)

    // $localized
    ['Hallo Welt', 'de'];

If resources for requested locale de_AT existed the result could look like, _(*8)

    // $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., _(*9)

For instance, there is a resource folder structure, _(*10)

Resources
    |_ de
        |_ Messages.php
    |_de_AT
        |_ Messages.php

Where Messages.php is a plain PHP array file, _(*11)

```php Resource/de/Messages.php <?php return [ 'Hello World' => 'Hallo Welt', ];, <sub>(*12)</sub>

and

```php Resource/de_AT/Messages.php
<?php
return [
    'Hello World' => 'Hallo Welt aus Österreich',
];

Then, a storage array could be created as, <sub>(*13)</sub>

    $storageData = (new FileBundleEncoder('path/to/ResourcesFolder/'))->getStorageData('de');

Method getStorageData has a default locale code as a first parameter., <sub>(*14)</sub>

Finally, complete example, <sub>(*15)</sub>

    $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., <sub>(*16)</sub>

    $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., <sub>(*17)</sub>

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., <sub>(*18)</sub>

    $formatter = new Formatter('de', 'Messages', $translator);

    // 'Hallo Welt'
    $formatter->formatMessage('Hello World');

More info., <sub>(*19)</sub>

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 with BundleStorage.
• Use the translator for message formatting.

Testing

$ composer test