Multi Language i18n & Localization in Pimcore
Localization is a very important aspect in every content management. In Pimcore localization can be centrally configured and has influence on multiple aspects within the system.
Bottom line is that using Pimcore in a multi language mode is pretty easy for users and developers. Pimcore takes care of all technical aspects and by doing so follows the ZF patterns.
Pimcore has different sets of languages/locales and translations for the back end (CMS) and front end (website). This allows you to have the user interface of Pimcore in different languages than the website. You need to be aware of this when requesting the current and available locales, as they are different depending on the context. If a user is saving an object in Pimcore which is set to English, the current locale is different then when a visitor on your French website triggers a save action.
The available languages for content are configured centrally in system settings (Settings > System Settings
Localization & Internationalization (i18n/l10n)).
Following settings can be defined here:
- Available languages
- System wide default language
- Fallback language for each language: if defined, Pimcore returns values from fallback language if primary language has no values set.
Localized Content Areas
The activated languages have influence to following modules of content within Pimcore:
- Document - Localization (system property for language)
- Shared Translations (Zend_Translate)
- Localized Fields for Objects (object localization)
- Structured Data Fields - Classification Store
Dealing with Locales within our Code
Pimcore offers localization for documents as described above. If you don't want to use that, you can set the locale manually in your controller/action:
Alternatively you can use the following (does not cover all functionalities - only ZF specific)
$locale = new \Zend_Locale("en_US"); \Zend_Registry::set("Zend_Locale",$locale);
Now every Pimcore and ZF module will respect your registered locale.
Pimcore Backend UI Localization
Pimcore backend UI localization is independent from content localization but works similar to Shared Translations. Basically every text in Pimcore backend is translatable, but there are two different sources for translations - Pimcore system translations and project specific translations.
Pimcore System Translations
This covers all labels and texts within Pimcore that ship with Pimcore installation package. Here the standard language English is maintained by the core team. In addition to that, every body can join the Pimcore translation project to add system translations in additional languages. With every Pimcore release, newly added translations are added to the Pimcore installation package.
Project Specific Translations
There are several components in the Pimcore backend UI which are configured differently for each project. These are
- object class names
- object field labels
- object layout components
- document types
- predefined properties
- custom views
- document editables
All these elements (except document editables) can be translated in Extras > Translations Admin similar to the Shared Translations. All installed system languages are available for translation.
Strings which are subject to special translations, but have not been translated yet, are displayed with a "+" in front and after the string, if Pimcore is in DEBUG mode.
Document editables are translated through a special view helper.
Example: Translation of options of a select editable
(view script) ... <?= $this->select("select", [ "store" => [ ["option1", $this->translateAdmin("Option One")], ["option2", $this->translateAdmin("Option Two")], ["option3", $this->translateAdmin("Option Three")] ] ]); ?> // short hands <?= $this->select("select", [ "store" => [ ["option1", $this->ts("Option One")], ["option2", $this->ts("Option Two")], ["option3", $this->ts("Option Three")] ] ]); ?>
After adding a new translation, the document needs to be loaded once in editmode. This adds the new translation keys to to the Admin Translations where all extra translations can be edited.
If you are a plugin developer, you can add translations to your plugins and provide them with your plugin as you wish. To see how plugins can hook into translations, please see the Plugin Developer's Guide.