Localization

Plugins can have localization files inside lang subdirectory. Plugin localization files use the JSON format and detected by the system automatically in the backend panel. Using localization strings are supported natively in the backend user interface menus, form labels, etc.

# Active Language

The default language for your application is stored in the config/app.php configuration file's locale configuration option. You are free to modify this value to suit the needs of your application. Each user can set their preferred locale setting via the User Menu → Backend Preferences.

You can check the active language in PHP using the App::getLocale method and set the active language using App::setLocale that takes the language code as the first argument.

App::getLocale();

App::setLocale('fr');

# Localization File Structure

Below is an example of the plugin's lang directory.

├── plugins
|   └── acme
|       └── todo
|           └── lang
|               ├── en.json  ← Localization File
|               └── fr.json  ← Localization File

Using JSON files for localization is the preferred method of translation where strings use the "default" translation of the string as the key. For example, if your application has a French translation, you should create a lang/fr.json file.

{
    "I love programming.": "j'adore programmer"
}

# Accessing Localization Strings

The localization strings can be loaded with the __() helper function by passing the default translation of your string.

echo __('I love programming.');

Replacing parameters in translation strings is possible by passing an array as the second argument. Every parameter is prefixed with a : character.

echo __(':name loves programming.', ['name' => 'Jeff']);

# Pluralized Values

Different languages can have a variety of complex rules for pluralization. Using the | character, you may distinguish singular and plural forms of a string.

{
    "There is one apple|There are many apples": "Il y a une pomme|Il y a beaucoup de pommes"
}

More complex pluralization rules can specify translation strings for multiple ranges of values.

{
    "{0} There are none|[1,19] There are some|[20,*] There are many": "..."
}

The trans_choice function is used to process pluralized values.

echo __('There is one apple|There are many apples', 3);

# Overriding Localization Strings

System users can override plugin localization strings without altering the plugins' files. This is done by adding localization files to the lang directory. For example, to override the French translations you should create the file in the following location:

├── app
|   └── lang
|       └── fr.json  ← Override File

The file could contain only strings you want to override, there is no need to replace the entire file. Example:

{
    "I love programming.": "Coding is the best!"
}

Some plugins may ship with their own PHP-based language files. You may override these in the same location. Use the complete language key in the JSON file, for example, to override the rainlab.blog::lang.post_label value.

{
    "rainlab.blog::lang.post_label": "Article"
}

You may also use a nested folder structure to override a file using the PHP format. For example, a plugin name Acme.Blog places the file at lang/acme/blog/en/lang.php.

├── app
|   └── lang
|       └── acme  ← Plugin Author
|           └── todo  ← Plugin Name
|               └── en
|                   └── lang.php  ← Override File

# Programatically Overriding Strings

You can override language strings in PHP by using the Lang::set method. This takes the language key and new translated value as the arguments.

Lang::set('I love programming.', 'Coding is the best!');

By default this will override the active locale, the third argument can specify an explicit locale. The following example replaces the value for French.

Lang::set('I love programming.', 'Le codage est le meilleur!', 'fr');

# Contributing Language Strings

October CMS uses a service called Crowdin to better manage translations for popular languages. It also performs automated machine translations using Google's translation API for all other languages. If you discover missing or incorrect translations in October CMS, please follow the instructions below.

# Using Crowdin

You may check to see if your language is supported by the Crowdin project using the link below. This service allows you to contribute translations using a streamlined interface.

• October CMS Crowdin Project Page (opens new window)

If your language does not appear on this page, please follow the GitHub instructions below. Languages are added to Crowdin when we notice a language is becoming more active on GitHub.

# Using GitHub

You may visit the repository on GitHub (opens new window) to suggest updates for your language using a pull request. The language files are found in the various modules, so you may need to check multiple files to find the correct language string. In this example, we will modify the Dutch language using the nl language code and we know the string is located in the Tailor module.

1. Open the GitHub repository (opens new window).
2. Click on tailor, then lang to open the language directory for Tailor
3. Click on the nl.json file to open the language file for Dutch
4. At the top right, click the pencil icon to Edit this file

In the file you will see the English version on the left side and the Dutch version on the right side, for example:

{
  "Manage Entries": "Invoer beheren",
  "Create :name Entry": "Maak :name invoer"
}

When making the update, only modify the right side which contains the translated value. Some values may contain variables such as :name and these should be left intact. Once completed, click the Commit changes button to submit a new Pull Request. It will be reviewed by the team and included in subsequent releases.

# See Also