General information Localization

App Localization

The application supports working with localizations, allowing you to translate both interface phrases and data specified in the admin panel.

Translation of Interface Phrases

To translate phrases, the php gettext extension is used, based on the Gettext internationalization library. In addition to installing the php extension, it is also necessary to have the corresponding localization installed in the system (on the server). You can check the list of available localizations by executing the following console command on the server:

locale -a

The result of the execution will be text similar to the following:

en_AU
en_AU.UTF-8
en_US
en_US.ISO8859-1
en_US.UTF-8
ru_RU
ru_RU.UTF-8

This indicates that the system has the en_AU, en_US, and ru_RU locales installed. If the required locale is missing, please contact the system administrator.

In the application code, the _t, _te, and _tejs methods are used for translating phrases, where the first parameter specifies the context, which is usually the name of the module and helps to understand in the context of which module the phrase is used. In PHP template files, it looks like this:

<div><?= _t('shops', 'Shop Name:'); ?></div>

In this example, the context is set to the 'shops' module, which can be understood from the text of the phrase.

All phrases available for translation are located in a translation file with a special format *.po or *.pot, which is dynamically generated when downloaded in the admin panel under "Site Settings / Localization". The file is a simple text file, where the above phrase example will look like this:

msgid "shops|Shop Name:"
msgstr ""

It consists of the following blocks:

  • msgid - the original phrase that needs to be left unchanged
  • shops| - the context prefix that is not part of the phrase itself, prefixes are located to the left of the phrase and are always separated by a vertical bar |
  • msgstr - the translation phrase, the field where the translation text is specified, if the field is empty "", the original phrase will be used

Let's consider an example of a phrase in the admin panel:

<div><?= _t('docs', 'Go to the link: [url]', [
    'url'=>'<a href="example.com">http://example.com</a>'
]); ?></div>

In the translation file, it will look like this:

msgctxt "admin"
msgid "docs|Go to the link: [url]."
msgstr "Follow this url: [url]"

And it consists of the following blocks:

  • msgctxt - the translation context "admin" indicates that it is used only in the admin panel, if this line is missing, the phrase is used in the user part of the site
  • msgid - the original phrase
  • docs| - the context prefix
  • [url] - a macro that will be replaced with data, in this case, a link, macros always consist of Latin text in square brackets, they are not translated and are inserted into the translation phrase as is
  • msgstr - the translation phrase, where the translation to English is specified in this example, as well

You can work with the translation file in a specialized translation editor like http://poedit.net/ or in a regular text file. If quotation marks like " appear in the translation text, a backslash should be placed before them \".

The available translation functions are:

_t('context', 'Text');
_t('context', 'Link: [url]', ['url'=>'http://example.com']);

If you need to escape special characters, use the _te() function:

<input type="button" value="<?= _te('users', 'Save') ?>">

When inserting a phrase into JavaScript code, use the special function _tejs:

<script>
    alert('<?= _tejs('users', 'Thank you!') ?>');
</script>

Extension Localization

Plugins and themes also support localization. For more information on how this works, read the Extensions / Localization section.

Component

To work with the current language within the application, you should use the bff::locale() component.

The main available methods are:

// the current language key in two-letter format 'ru'
bff::locale()->getCurrentLanguage();

// get the default language of the application
bff::locale()->getDefaultLanguage();

// get the list of all languages used in the application, which can be configured
// in the "Site Settings / Localization / Settings" section
bff::locale()->getLanguages();

There is also a method in the Site module that returns a list of languages visible to the user:

$languages = Site::languagesList();