Skip to content

i18n

XELOS comes with an integrated translation system to allow an easy handling of all user outputs across different languages.

Translation of outputs (Tokens)

During the development of modules the localization of user output is required. All messges being shown for the user must be done using i18n tokens to make sure the output can be translated.

The translation is held in JSON files located at locales/XX.json within each module or theme. By default we require a de.json and en.json for each module. The structure of the locale JSON files is as follows:

{
  "news": {
    "create": {
      "formTitle": "Create new article",
      "fieldTitle": "News-Title",
      "messageSuccess": "The article {articleName} has been created!"
    }
  }
}

NOTE: In the past (prior X10) the tokens had been equal the english wording and were translated to German afterwards. As soon as a module implements the locaes/de.json files it must implement the new token version across the whole module - otherwise the translation checks will fail.

PHP

To output a token in a module you use the $this->mod->_() helper for a context sensitive translation. 

# Output simple string
echo $this->mod->_("news.create.formTitle");
> "Create new article"

# Output string with placeholder
echo $this->mod->_("news.create.messageSuccess", ['articleName' => 'Hello World']);
> "The article Hello World has been created!"

Template

Within the XELOS templates i18n tokens can be used as follows:

<!-- SIMPLE -->
<h2>
  +++news.create.formTitle+++
</h2>

<!-- WITH PLACEHOLDER (short) -->
<div class="success">
  <xt:i18n token="news.create.messageSuccess" articleName="Hello World">
</div>

<!-- WITH PLACEHOLDER (long) -->
<div class="success">
 <xt:i18n token="news.create.messageSuccess">
  <xt:param name="articleName"><xt:echo marker="article.title"/></xt:param>
 </xt:i8n>
</div>

Development Helper

For an easier usage within PHPStorm you can use the Plugin https://plugins.jetbrains.com/plugin/12981-i18n-support. It allows the display of translations for a certain token from your sourcecode. You should set the namespace to 'de,en' and the folder to 'locales'.

XELOS comes with some CLI tools to facilitate working with translations as developer.

# Check token validity / completeness of module (-v to include source reference)
> php xf i18n:token:check news -v  

# Update Database with ALL tokens
> php xf i18n:token:update  

# Update Database with ALL tokens and translations
> php xf i18n:token:update --with-translations

# Update Database with ALL tokens and translations of a module
> php xf i18n:token:update news --with-translations

# Compile and apply translations
> php xf i18n:token:apply

Attention: If not in development mode updating the JSON files will not be reflected in the output as the translation is not in the compiled gettext / po file. You need to update the translation db and compile the gettext / po file first. If you are in development mode, tokens from the JSON are being loaded on runtime.

Naming conventions

All technical tokens use the module name as its prefix. The token must be in lower case and should be structured logically, e.g. module_name.page.term => virus_scan.admin.finished

Migration

To migrate a module to technical tokens, follow the steps:

  • Ensure firstly that all tokens use $this->mod->_() instead of the global _().
  • Prepend each token with the technical token and @@, e.g. $this->mod->_("Overview") is changed to $this->mod->_("virus_scan.admin.overview@@Overview")
  • Run php xf i18n:token:migrate <module>
  • All tokens are replaced with the technical token, the de.json and en.json files are created.
  • Translate any remaining tokens in the de.json file.
  • Run php xf i18n:token:update <module> --with-translations to add all tokens and the translation to the token database.
  • Submit those tokens via the admin interface to the license server.

TODO

  • Migrate domain + basetoken of custom translations