Configuring the site languages

No site languages are specified by default (i.e. after downloading and unpacking the eZ publish distribution). During the installation process, the setup wizard allows the user to choose the languages that should be used on the site which is being created. The list of available languages displayed at this step is built using the INI files located in the "share/locale" directory. Use the radio buttons to choose the default language (required), and the checkboxes to choose the additional languages (optional).

Please note that choosing the default language at this step will affect both default language and system locale. Please note that one of the radio buttons will be pre-selected i.e. the default language will be specified according to the language settings of your browser . However, you can choose another language instead. If you select for example "German", then both locale and default language will be set to "ger-DE" and your administration interface will be translated into German (in addition, the "TextTranslation" setting will be enabled).

All the selected languages will be added to the system as translation languages and recorded as site languages for both public and admin siteaccesses. The default language will be recorded as the most prioritized language. You will be able to use any of these languages for creating and translating your content after the setup wizard is finished. It is also possible to add new translation languages using the administration interface and to change the site languages configuration by editing your configuration settings.

Displaying untranslated content

Since it may be useful to display all translation languages, an additional configuration setting called "ShowUntranslatedObjects" has been added. It can be set to either "enabled" or "disabled". If this setting is enabled, the system will still use the language priorities determined by the "SiteLanguageList[]" array, but it will not filter away languages that are not on the list. In other words, all objects will be displayed regardless of which language they exist in - and objects that exist in a language specified in the priority list will be displayed using the prioritized language.

The "ShowUntranslatedObjects" setting is disabled by default. However, the setup wizard usually enables it for the admin siteaccess. This allows the site administrator to create and edit objects in any of the translation languages even if some of these languages are not listed as site languages.

Example

Let's say that you have selected British English as default language, French and Norwegian as additional languages (look at the following screenshot).

The language selection step in the setup wizard.

In this case, you will have the following settings for locale, default language and site languages after the setup wizard is finished:

[RegionalSettings]
Locale=eng-GB
ContentObjectLocale=eng-GB
SiteLanguageList[]=eng-GB
SiteLanguageList[]=fre-FR
SiteLanguageList[]=nor-NO

This means that the site locale is set to "eng-GB", the default language is English, the most prioritized language is English, the second prioritized language is French and the third prioritized language is Norwegian. The setup wizard will put these settings into the "site.ini.append.php" files for both public and admin siteaccesses. The "TextTranslation" setting will be disabled for both siteaccesses because the "eng-GB" locale is used.

Any of these three languages can be used for creating and translating your content. You can change the site language configuration later by editing the "site.ini.append.php" file for the desired siteaccess.

The setup wizard will add one more line in the "site.ini.append.php" file for the admin siteaccess:

ShowUntranslatedObjects=enabled

This will tell the system to make all the translation languages available when working with content objects in the administration interface.

You can add new translation languages using the admin interface. Let's go to "Setup - Languages" and add German. This language will not be displayed on your site (public siteaccess) because it is not included in the list of site languages (i.e. not specified in the "SiteLanguageList[]" array). However, after clearing the caches German will be displayed as the last item in the drop-down list of available languages for object creation in the administration interface (look at the next screenshot) because the "ShowUntranslatedObjects" setting is enabled for the admin siteaccess.

The "Create here" interface.

Changing the language priorities

The "SiteLanguageList[]" setting specified in the siteaccess "site.ini.append.php" file contains the prioritized list of site languages where items appearing at the top get higher priority than the others. The system will try to display content in the most prioritized language first. If an object is not translated to this language then the second prioritized language will be displayed. If an object does not exist in this language then 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.

To change the site language priorities, open the configuration file, edit it and re-arrange the elements of this array in the desired way.

Example

Let's say that the following settings are specified in the "site.ini.append.php" file for your public siteaccess:

[RegionalSettings]
SiteLanguageList[]
SiteLanguageList[]=eng-GB
SiteLanguageList[]=fre-FR
SiteLanguageList[]=ger-DE
SiteLanguageList[]=nor-NO

If an article exists in French and Norwegian languages, the system will follow the prioritized list of site languages and display the article in French which is the second prioritized language. This behavior will not change if you translate this article into German (the third prioritized language). However, if you translate the article into English (which is the most prioritized language), then it will be displayed in English.

If you move the line "SiteLanguageList[]=nor-NO" to the top of the list, then Norwegian will become the most prioritized language. This will instruct the system to display content in Norwegian and use other site languages only when a Norwegian translation is not available.

Using several public siteaccesses

In the previous example only one public siteaccess was used. A multi-language site typically uses several public siteaccesses. If your site content exists in for example English and French then it is recommended to have two public siteaccesses with the following language configuration:

[RegionalSettings]
SiteLanguageList[]
SiteLanguageList[]=eng-GB

[RegionalSettings]
SiteLanguageList[]
SiteLanguageList[]=fre-FR
SiteLanguageList[]=eng-GB

If an article exists only in English, it will be displayed to the visitors of both siteaccesses (because English is the only site language for the "gb" siteaccess and the second prioritized language for the "fr" siteaccess). If you translate this article into French, it will be shown in French when viewing the "fr" siteaccess (since French is the most prioritized language for this siteaccess). If an article exists only in French, it will be available for the visitors of the "fr" siteaccess but it will not show up in the "gb" siteaccess.

Now, let's say that you wish to start using for example Norwegian language on your site. In this case, you will probably add Norwegian as a new translation language, create a new siteaccess called "no" and specify the following settings in the "site.ini.append.php" file of the newly created siteaccess:

[RegionalSettings]
SiteLanguageList[]
SiteLanguageList[]=nor-NO

This will tell the system to use Norwegian as the only site language for this siteaccess. In other words, if an article does not exist in Norwegian, it will not be displayed.

Of course, it is possible to add the following line to these settings:

SiteLanguageList[]=eng-GB

In this case Norwegian will be the most prioritized language for the "no" siteaccess and English will be the second prioritized one (look at the next table).

Articles that exist only in English will be displayed in English to the visitors of all three siteaccesses. If an article exists only in Norwegian, it will be shown only on the "no" siteaccess.

Let's create a new article called "Lundi" (Monday) in French. This article will be displayed to the visitors of the "fr" siteaccess but not to the visitors of the "gb" and "no" siteaccesses (because French is not listed as site language for these siteaccesses). If you translate this article into Norwegian then it will become available as "Mandag" (Monday) when viewing the "no" siteaccess but still invisible for the users of the "gb" siteaccess. If you add English translation for this article, it will become available as "Monday" for the visitors of the "gb" siteaccess. However, nothing will change for the "fr" and "no" siteaccesses because English is their second prioritized language.