In eZ publish 3.7 and earlier versions, you have to specify one primary / main language that affects every content object (i.e. each object must exist at least in this language). In addition, you are allowed to specify additional languages which the content objects can be translated to. The multi-language functionality is implemented at the version level and allows an object's version to exist in several languages (a language in this case is referred to as a translation). One disadvantage of the old solution is that when several translations are needed, only one translator can work on the object. In other words, the translators must work sequentially and thus wait for eachother because only one user is allowed to edit an object's version. This functionality has been changed.

From 3.8, there is no need for primary / main language anymore. You can have for example one article which is only available in English and another article which is only available in French. After choosing the languages for your content objects, it is possible to translate them to any of these languages. The translations of the same object can be created and edited separately and simultaneously by multiple users (a user only edits one version and translation at a time). The next subsections will briefly explain some main principles and terms that will be used when describing the multi-language functionality.

Translatable class attributes

From 3.9, it is possible to translate the class names and the attribute names. In other words, you can for example have "Car" and "Bil" as class names in English and Norwegian along with "Top speed" and "Topphastighet" as attribute names. Refer to the "Translatable class attributes" documentation page for more information.

Locales

A locale is a set of country specific settings i.e. language, character sets, number formats, currency format, date and time format, abbreviations of months and weekdays etc. eZ publish provides many default locale settings where each locale is described in an INI file located in the "share/locale" directory. These configuration files are named according to locale identifiers.

A locale identifier consists of a three-letter language code and a two-letter uppercase country code e.g. "eng-US" (English, USA) or "nor-NO" (Norwegian, Norway). Language and country codes are specified by ISO 639 and ISO 3166-1 alpha-2 standards accordingly.

eZ publish uses the "eng-GB" locale by default. Please refer to the "Configuring your site locale" section for information about setting locale for your site, translating the administration interface, creating custom locales etc.

Default language

From 3.8, the "ContentObjectLocale" INI setting does not specify the primary / main language but the default language. This language will be used as the default value in PHP functions that support an optional parameter for language. The default value of this INI setting is "eng-GB".

Example

Let's say that you have specified "nor-NO" in the "ContentObjectLocale" setting. In this case, if you try to instantiate an object of some class using the "eZContentClass::instantiate()" function and do not explicitly specify the language to use then the Norwegian language will be used.

Translatable country names

From 3.9, it is possible to translate the names of countries to different languages. For example, you can instruct the system to use "Frankrike" instead of "France" and "Norge" instead of "Norway" whenever the list of countries is displayed on a siteaccess where Norwegian locale is used. Refer to the "Translatable country names" documentation page for more information.

Translation languages

It is possible to choose the languages that you wish your content to be created in and/or translated to. This set of languages is referred to as translation languages. These can be managed via the administration interface. The maximum number of languages that can be used simultaneously is 30.

Initial/main language

An object can be created in any of the languages that have been added either using the setup wizard or the "Languages" part of the "Setup" tab in the administration interface. When an object is created, it's initial/main language will be set to the language that was used during creation. For example, if an article is created in Hungarian, it's initial/main language will of course be set to Hungarian.

Content that is in the initial/main language can not be removed from the object. However, if the contents of the object exists in several languages, the initial/main language can be changed and thus content that is not in the initial/main language can be removed. Changing the initial/main language and removing languages/translations from an object can be done from within the "Languages" window (in the first three tabs) in the administration interface.

Important note

Please note that the terms "initial language" and "main language" refer to the same thing. While the code and database tables use "initial language", the administration interface uses "main language". This inconsistency will hopefully be fixed in a future release.

Site languages

From 3.8, you can specify which languages the contents of a site should be displayed in. This set of languages is referred to as site languages. These languages can be controlled per siteaccess using the "SiteLanguageList[]" configuration setting located under the "[RegionalSettings]" section of the siteaccess "site.ini.append.php" file. You can specify the site languages and their priorities by adding the corresponding locale identifiers to this array. The languages that appear at the top will get higher priority than the others. The first element in this array determines the most prioritized language. The system will try to display content in this language first. If an object is not translated to this language then the second prioritized language (specified as the second element of the array) will be displayed. If an object does not exist in this language, the third prioritized language will be used and so on. If an object does not exist in any of the site languages, it will not be shown unless it is always available or if you configure the siteaccess to display untranslated content.

Please note that if the "SiteLanguageList" setting is not specified, the system will use the old "ContentObjectLocale" setting and thus only the default language will be shown.

Example

Let's say that your translation languages are English, French and Norwegian. If you specify two of them as site languages for your public siteaccess (for example English as the most prioritized language and French as the second prioritized one), the system will display content in these two languages to your visitors while Norwegian content will not be shown. If you create one article in English, another one in French and the third one in Norwegian, then only first and second article will be displayed. If you translate the third article from Norwegian into one of the site languages, the translated version of the article will be displayed on your site while the original Norwegian version will still not be shown. If an article is available in both English and French, it will be displayed in English (since English is the most prioritized language for the siteaccess).

Please refer to the "Configuring the site languages" section for more information about site languages.

Objects which are always available

Some objects always need to be available even if they do not exist in any of the languages that are configured for a sitaccess. For example, the system must be able to fetch user objects no matter which siteaccess is used. Because of this, a new flag called "always available" has been introduced at the object level. It makes it possible to individually control the availability of the different objects. When an object doesn't exist in any of the site/prioritized languages and it is always available, the system will use the object's initial/main language to display its contents.

The default object availability can be controlled on the class level. By default this setting is enabled for the "Folder", "User", "User group", "Image", "File" etc. classes, so that objects of these classes will be marked as "always available" when created. Changing the default setting at the class level will not affect the existing objects because it simply dictates the initial value for the "always available" flag which is stored for each object.

Example

Let's say that one of your folders only exists in Norwegian, is marked as always available and contains several articles (the articles are in English, French and Norwegian and none of them are marked as always available). If you specify English and French as site languages for your public siteaccess, this folder will still be displayed since it's always available. Your visitors will thus be able to view the articles that are in it. If the folder is not marked as always available then it will not be displayed and thus your visitors will not be able to read the articles located under it until you translate the folder itself into English or French.