ez.no / documentation / ez publish / technical manual / 4.6 / features / multi-language / configuring your site locale

Caution: This documentation is for eZ Publish legacy, from version 3.x to 5.x.
For 5.x documentation covering Platform see eZ Documentation Center, for difference between legacy and Platform see 5.x Architecture overview.

Configuring your site locale

eZ Publish uses the "eng-GB" locale by default. This behavior is determined by the "Locale" INI setting located in the "[RegionalSettings]" block of the "settings/site.ini" configuration file. If you wish to use another locale for your site then you have to override this setting. Please note that the specified locale will be used as the default value for the "l10n" operator unless you explicitly specify the desired locale when using this operator in your templates. The following examples demonstrate how you can set the site locale.

Example 1

Let's say that you need to use "nor-NO" as system locale for all your siteaccesses. The following instructions reveal how this can be done.

  1.  Open the "site.ini.append.php" configuration file located in the "settings/override" directory and edit it (if the file does not exist, create it).
  2.  Add the following lines under the "[RegionalSettings]" block:

  3.  Clear the caches.

The system will start to use the locale settings specified in the "share/locale/nor-NO.ini" file for all your siteaccesses.

Example 2

Let's say that you need to use the "nor-NO" locale for one of your siteaccesses. To do this, edit the "site.ini.append.php" file located in the "settings/siteaccess/example/" directory (where "example" is the name of your siteaccess) as described in the previous example and make sure that no locale is specified in the "settings/override/site.ini.append.php" file. After clearing the caches, the "example" siteaccess will start to use the "nor-NO" locale. However, this may not result in the translation of all parts of the interface for this siteaccess (like "Login" and "Sign up" links/buttons etc.) into Norwegian. To do this, you should add the following line under the "[RegionalSettings]" block of the siteaccess "site.ini.append.php" file:


This will instruct the system that the strings marked with "i18n" in the templates should be translated according to the current locale. This means that if you set the "nor-NO" locale for your admin siteaccess and enable the "TextTranslation" setting then everything in the administration interface will be translated into Norwegian. (The "TextTranslation" configuration setting is disabled by default.)

You can also specify different locales for the remaining siteaccesses in the same way, otherwise the default "eng-GB" locale will be used for them.

Adding missing locales

eZ Publish provides many default locale settings where each locale is described in an INI file named by the locale identifier and placed in the "share/locale" directory. "To contribute new locales and/or translations to eZ Publish, visit the Community Translation project page here: http://projects.ez.no/ezpublish_translation, log-in, navigate to the team page ( http://projects.ez.no/ezpublish_translation/team/members ) and request membership. You will be promptly able to contribute new translations and locale to eZ Publish ! ". The following example demonstrates how to add a missing locale.


Let's say that you need to use the "ell-GR" locale on your site. To do this, download Greek translation for eZ Publish from the eZ Publish translation pages http://projects.ez.no/ezpublish_translation (you have to be a member as described in "Adding missing locales above") and unpack it into a temporary location. You should see there a sub-directory called "share" which contains the locale configuration file (share/locale/ell-GR.ini) and the translation file for eZ Publish (share/translations/ell-GR/translation.ts). In addition, the downloaded package may contain a flag icon (share/icons/flags/ell-GR.gif) and/or translation file(s) for some extensions located in the "extension" sub-directory.

Please note that the "translation.ts" file contains eZ Publish specific strings translated into Greek language (the strings that are used in the templates and PHP code). If the "TextTranslation" setting is enabled, the strings from this file will be used for translating different parts of the interface, system messages, warnings etc.

If you copy the "share" sub-directory to the root directory of your eZ Publish installation, set the "ell-GR" locale (as described in the previous two examples) and clear the caches, the system will start to use Greek locale.

Custom locales

In addition to the default locale settings that come with eZ Publish, it is possible to create custom locales. For every custom locale you must have either a translation.ts or a fallback other than "eng-GB". The fallback is necessary when you wish to use the translation cache. The fallback is made in "i18n.ini". For a custom locale, you still need to also update "i18.ini" by an override.

Note that the locale must fallback to the untranslated language.

We strongly recommend this fallback procedure, since setting up this fallback will make the system use the translation cache.
Note: no fallback = no translation cache used = bad performance

The following examples demonstrate how this can be done.

Example 1

Let's say that you wish to use Icelandic locale on your site. You can create a custom locale configuration file for this based on the "eng-GB" locale settings. To do this, do the following:

  1.  Go to the "share/locale" directory and copy the "eng-GB.ini" configuration file to a new file called "ice-IS.ini".
  2.  Open this file and edit the locale settings.
  3.  Set your site locale to "ice-IS".

Example 2

Let's say that you wish to modify the Norwegian locale. The original locale file should not be changed because it will be overwritten next time you upgrade eZ Publish. Instead, you should create a custom locale file based on the original "nor-NO" locale settings. The following text reveals how this can be done.

  1.  Go to the "share/locale" directory and copy the "nor-NO.ini" configuration file to a new file called "nor-NO@custom.ini".
  2.  Open the newly copied file and edit the locale settings.
  3.  Make sure that your siteaccess uses the "nor-NO@custom" locale.
  4.  Clear the caches.

Standard for naming eZ locales

You must decide the locale code of your language. eZ Publish uses locale codes on the form aaa-AA, where the 3 first lowercase letters describe the language, while the last two uppercase letters describe the country in which the language is spoken. For instance, English as it is spoken in Great Britain would be eng-GB, while US English is eng-US.

Countries are specified by the ISO 3166 Country Code: http://www.iso.ch/iso/en/prods-services/iso3166ma/index.html

Language is specified by the ISO 639-2 Language Code: http://www.loc.gov/standards/iso639-2/php/code_list.php

You can also create a variation of a locale, you will for instance find two variations of nor-NO, nor-NO@intl and nor-NO@spraakraad, that are slight modifications of the original.

This list shows the current ini-files with eZ locales in use in eZ Publish installations:

Locales ini file

Language (Country)


Catalan (Spain)


Chinese (China)


Chinese (Hong Kong)


Chinese (Taiwan)


Croatian (Croatia)


Czech (Czech Republic)


Danish (Denmark)


Dutch (Netherlands)


Greek (Greece)


English (Australia)


English (Canada)


English (Great Britain)


English (Euro support)


English (New Zealand)


English (USA)


Spanish (Spain)


Spanish (Mexico)


Finnish (Finland)


French (Belgium)


French (Canada)


French (France)


German (Germany)


German (Euro support)


Hebrew (Israel)


Hindi (India)


Hungarian (Hungary)


Indonesian (Indonesia)


Italian (italy)


Japanese (Japan)


Japanese (Kanji)


Korean (South Korea)


Norwegian - Nynorsk (Norway)


Norwegian - Bokmål (Norway)

nor-NO@intl.ini Norway

Norwegian (intl)


Norwegian (Standard set by Språkrådet)


Polish (Poland)


Portugese (Brazil)


Portugese (Mozambique)


Portugese (Portugal)


Portugese (Euro support)


Russian (Russia)


Serbian (Srpski)


Slovak (Slovakia)


Serbian (Српски)


Swedish (Sweden)


Turkish (Turkey)


Ukrainian (Ukraine)

Geir Arne Waaler (30/11/2010 9:50 am)

Geir Arne Waaler (28/03/2011 9:07 am)


There are no comments.