Localization

Localization

Learn how to translate messages in the backend area.

The language strings defined here will only be loaded in the backend panel. For translating frontend content, visit the Theme Localization article.

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"
}

Laravel offers a PHP-based translation method as a supported alternative to using JSON. View the Laravel Localization article (opens new window) to learn more.

# 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');

# See Also