Edit on GitHub

Localization

Plugins can have localization files in the lang subdirectory of the plugin directory. Plugins' localization files are registered automatically. The localization strings are supported automatically in the backend user interface menus, form labels, etc. - if you provide the localization key instead of a real string, the system will try to load it from the localization file. In other cases you need to load the localization string with the API.

NOTE: For translating frontend content, there are plugins that can be used for this purpose.

Localization directory and file structure

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

📂 plugins
 ┗ 📂 acme
   ┗ 📂 todo              <=== Plugin directory
     ┗ 📂 lang            <=== Localization directory
       ┣ 📂 en            <=== Language directory
       ┃ ┗ 📜 lang.php    <=== Localization file
       ┗ 📂 fr
         ┗ 📜 lang.php

The lang.php file should define and return an array of any depth, for example:

<?php

return [
    'app' => [
        'name' => 'Winter CMS',
        'tagline' => 'Getting back to basics'
    ]
];

The validation.php file has a similar structure to the lang.php and is used to specify your custom validation messages in a language file, for example:

<?php

return [
    'required' => 'We need to know your xxx!',
    'email.required' => 'We need to know your e-mail address!',
];

Accessing localization strings

The localization strings can be loaded with the Lang class. The parameter it accepts is the localization key string that consists of the plugin name, the localization file name and the path to the localization string inside the array returned from the file. The next example loads the app.name string from the plugins/acme/blog/lang/en/lang.php file (the language is set with the locale parameter in the config/app.php configuration file):

echo Lang::get('acme.blog::lang.app.name');

You can pass an array as the second parameter:

echo Lang::get('acme.blog::lang.app.test', ['key1' => $value_1, 'key2' => $value_2]);

The key will be found in the localization string and replaced with its value. An example localization string for such cases:

'app' => [
    'test' => 'Text text text :key1 text text :key2 text.',
],

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 lang.php file of the acme/blog plugin you should create the file in the following location:

📂 lang                 <=== App localization directory
 ┗ 📂 en                <=== Language directory
   ┗ 📂 acme            <=== Plugin / Module directory
     ┗ 📂 blog          <===^
       ┗ 📜 lang.php    <=== Localization override file

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

<?php

return [
    'app' => [
        'name' => 'Winter CMS!'
    ]
];

Keep informed

Sign up to our newsletter to receive updates on Winter CMS releases, new features in the works, and much more.
We'll never spam or give this address away.

Latest blog post

Winter: 16 Months Later

Published July 14, 2022
With the first year of Winter behind us, let's take a look at what we were able to achieve in 2021.

View this post Read all posts

Latest Winter CMS release

v1.2.1

Released October 20, 2022
14 UX/UI Improvements, 25 API Changes, 33 Bug Fixes, 4 Security Improvements, 5 Translation Improvements, 1 Performance Improvement, 2 Community Improvements, 2 Dependencies, 0 New Contributors * @cstorus made their first contribution in https://github.com/wintercms/winter/pull/616 * @simonmannsfeld made their first contribution in https://github.com/wintercms/winter/pull/623 * @quangtrongonline made their first contribution in https://github.com/wintercms/winter/pull/636 * @nathanlesage made their first contribution in https://github.com/wintercms/winter/pull/665 * @vllvll made their first contribution in https://github.com/wintercms/winter/pull/669 * @robertalexa made their first contribution in https://github.com/wintercms/winter/pull/668 * @iamyigitkoc made their first contribution in https://github.com/wintercms/winter/pull/624 * @hecc127 made their first contribution in https://github.com/wintercms/winter/pull/682 * @prsuhas made their first contribution in https://github.com/wintercms/winter/pull/723

View details View all releases