Design theme localization

Contents...

In order to display various localized text strings on a website, such as “Subscribe for news” or “Shopping cart”, it is convenient to use the design theme localization mechanism.

The operating principle of the design theme localization is similar to that of gettext, i.e. a basic version of a string is used as its identifier (it is usually specified in English), and translations for that string are specified for other available locales. If no translation is specified for some locale, then the string id is used for that locale instead of a translation.

Design theme localization strings and their translations must be specified in the theme.xml manifest file in the form of a common locales element containing several nested locale elements corresponding to individual strings.

Each locale element must contain one child element msgid with the string id and an arbitrary number of msgstr elements, each for one available locale, for which a translation is required. Each msgstr must have a locale attribute containing the corresponding locale name. If no translation of a string is required for some locale, then no msgstr element should be added for that string.

Below is shown an example of the locales section for the theme.xml file:

<locales>
    <locale>
        <msgid>Subscribe for news</msgid>
        <msgstr locale="ru_RU">Подписаться на новости</msgstr>
    </locale>
    <locale>
        <msgid>Shopping cart</msgid>
        <msgstr locale="ru_RU">Корзина</msgstr>
    </locale>
</locales>

Use of localization strings in template files

Localized strings must be added to design theme templates using the [`string`] syntax. Here is how you can use one of the strings declared in the example above:

<p>[`Subscribe for news`]</p>

If Russian locale (in this example) is specified or automatically detected for a website settlement utilizing such a design theme (ru_RU), then the corresponding translation will be returned to a user's browser instead of [`Subscribe for news`]:

<p>Подписаться на новости</p>

Otherwise the string's id will be returned:

<p>Subscribe for news</p>