Note that we will not go through the format of translation files or how to create and edit them; see http://ez.no/developer/translations for more information.

In theory

eZ Publish comes with default translation files in the share/translations folder, in sub-folders for each locale. In eZ Publish 4.1, it is possible to create a locale name where the first part is an actual local code – such as eng-GB, pol-PL, nor-NO and so on – and the second part is any descriptive string separated with an @ symbol: @override, for example. In this article, we will use the locale name eng-GB@override.

eZ Publish first looks for translations in the translation.ts file located in the locale's folder. This serves as the so-called base translation file for the locale we will specify later (as well as create an extension to contain our translation override file). The translated strings in the base file are then overridden by whatever strings exist in the specified locale's folder, which in our case will be the eng-GB@override folder. This approach is valid also for locale INI files. The list below illustrates the order in which translation files are read, assuming we are using eng-GB@override as our locale:

share/translations/eng-GB/utf-8/translation.ts
share/translations/eng-GB/translation.ts
extension/tsextension/translations/eng-GB@override/utf-8/translation.ts
extension/tsextension/translations/eng-GB@override/translation.ts

Here, strings in extension/tsextension/translations/eng-GB@override/translation.ts will override the ones from share/translations/eng-GB/translation.ts. Also, if translations in utf-8 sub-folders exist, they are read first. Of course, in this case the share/translations/eng-GB/translation.ts file is empty (and the fallback will be the default eZ Publish strings), but in any other language where translations exist, this is still valid.

In practice

To actually put this in place, we need to make a translation extension. In order to do so, we need to create a folder with:

extension/tsextension
          |
          | - settings
          |   |
          |   | - site.ini.append.php
          |
          | - translations
          |   |
          |   | - eng-GB@override
          |   |   |
          |   |   | - translation.ts

In tsextension/settings/site.ini.append.php, we need to put following settings, to inform eZ Publish that this is translation extension:

<?php /*

[RegionalSettings]
TranslationExtensions[]=tsextension

*/ ?>

Next, we have to activate tsextension in settings/override/site.ini.append.php:

[ExtensionSettings]
ActiveExtensions[]
ActiveExtensions[]=tsextension

Once this is done we have to change the regional settings for whatever siteaccess is using this extension, so that eZ Publish will know to look for eng-GB@override. In settings/siteaccess/(siteaccess)/site.ini.append.php:

[RegionalSettings]
Locale=eng-GB@override
TextTranslation=enabled

Enabled text translation is key in order to tell eZ Publish to pick up a translation.ts file. Original eng-GB strings will be replaced with the new ones from the eng-GB@override/translation.ts file. Strings for which there is no translation will fall back to the default eZ Publish strings (which happen to be eng-GB).

Note that if you do not override every translatable string in your translation override file, you will see some warnings about missing translations in your debug output. You can safely ignore these messages as long as your overrides are set up properly.

Summary

This quick example should give you an idea of how you can use the improved translation override system in eZ Publish in your project.