Building a multilingual site #

This page is for website creators who build a site in more than one language. In Exponential every object can hold a translation per content language, and every siteaccess decides which languages it shows, in which order. The full reference is Content languages; this page is the site builder's path through it.

Contents #

1. How languages work
2. Step by step: adding a second language
3. Fallbacks and untranslated content
4. Translators
5. Templates and interface texts
6. Things that delete content
7. Checklist

How languages work #

• Adding a content language translates nothing and changes no siteaccess. It only makes the language available for translations.
• A siteaccess shows each object in the first language of its SiteLanguageList[] that the object has.
• Objects in none of those languages are hidden, unless they are marked "always available" or the siteaccess has ShowUntranslatedObjects=enabled.
• Every object has a main language.
• Exponential knows a large set of locales, including right-to-left ones (Languages in Exponential). More than 30 content languages need a 64-bit PHP, because the languages of an object are stored as bits of one integer (2.2 PHP).

Step by step: adding a second language #

From Adding German to an English site:

1. Add the language in Setup > Languages > Add language (for example ger-DE).

2. Give it a siteaccess. Copy settings/siteaccess/site to settings/siteaccess/site_de and set:

   # settings/siteaccess/site_de/site.ini.append.php
   [RegionalSettings]
   Locale=ger-DE
   ContentObjectLocale=ger-DE
   SiteLanguageList[]
   SiteLanguageList[]=ger-DE
   SiteLanguageList[]=eng-US
   ShowUntranslatedObjects=disabled
   TextTranslation=enabled

3. Register it in AvailableSiteAccessList[] and RelatedSiteAccessList[] and set up matching: a path (/de) or a host (Language switchers and addresses per language).

4. Clear caches: php bin/php/ezcache.php --clear-tag=ini,content --allow-root-user (and the Velocity response cache, ./console exp:velocity cache clear --apply, when Velocity serves the site).

5. Translate, starting with the front page and the menu folders.

6. Mark shared objects always available (media folders, users) so they show without a translation.

7. Check the German address.

Fallbacks and untranslated content #

Translators #

Give translators a role with content/translate and content/edit limited by Language to their language, plus read access to the content. They then edit only their translation (Roles and policies).

Templates and interface texts #

• Texts written in templates go through |i18n( 'design/mysite' ) and are translated in .ts files of your design extension; TextTranslation=enabled and Locale choose the catalogue (the translations cookbook, doc/eng-us/examples/cookbook/translations.md).
• Dates and numbers follow the siteaccess's Locale.
• Set lang on the <html> element from $site.http_equiv.Content-language.

Things that delete content #

• Removing a translation deletes that translation for good.
• Removing a language is only possible when no object and no class uses it, so it never deletes content.
• Changing ContentObjectLocale on a site with content needs care; read the warning in settings/site.ini first.

Checklist #

• To do: One siteaccess per language, each with its SiteLanguageList[], Locale and SiteName.
• To do: The fallback order decided and written down.
• To do: Shared objects marked always available.
• To do: Translators limited to their language.
• To do: The design's own texts translated.
• To do: A language switcher on every page (Language switchers).
• To do: Right-to-left languages checked (Right-to-left sites).

Related pages #

• Languages (for editors)
• Planning multisite and multilingual projects
• 10.14 Multi-language sites
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.