Study guide · Multilingualism and Multisite
Several languages and several websites with TYPO3
Several languages and several websites in one installation are among the strengths of TYPO3. They are also where projects become expensive if the basic decisions are wrong. On this page you follow a client project from the language concept to a finished multisite installation. Afterwards you can advise a client which setup suits them.
The client project and the basic decisions
Your client is the tourism association of the Seetal holiday region. The main website seetal.example should be available in German, English and French. There is also a second website for the guest card, seetal-card.example, in German and English only. A small separate team maintains it. Most French-speaking guests come from Switzerland.
The good news: TYPO3 supports multiple languages out of the box. Pages, content elements, records such as news and the metadata of files can all be translated. You need neither a paid extension nor an installation per language. The number of languages is not limited. The practical limit is the editorial effort.
The default language. Every site has a default language with the language ID 0. All translations hang on records in this language. Further languages get numbers greater than 0. Choose the language in which most content is written first, which for Seetal is German. Switching later is a lot of work.
The language “All”. The special language ID minus 1 stands for “all languages”. A record with this language appears in every language without being translated, a logo for example. There is no translate button for it.
One tree or several?
- In a single-tree setup there is one page tree. Pages and content have translations attached to the original. The structure is the same in all languages, and the language switcher leads to the matching page. This is the normal case.
- In a multi-tree setup each language or country gets its own page tree with its own root page, usually as a separate site. This allows very different structures, but it doubles the maintenance.
For Seetal you recommend a single-tree setup with three languages, because the content is largely the same.
Translate or localize?
- A translation carries existing texts over into another language. If the original has a headline and an image, so does the translation, no more and no less.
- Localization also adapts content to a region and its culture. A localized page can therefore contain different content from the original.
Localization covers the region's date, number and currency formats, and units of measurement. It also covers images, examples and a tone of voice that suit the target culture. Legal notices and mandatory information of the target country belong to it as well. So do language variants, such as Swiss Standard German, which does without the sharp s.
i18n stands for internationalization, L10n for localization. The number counts the letters left out between the first and the last letter of the English word. Internationalization prepares software technically for several languages and regions. Localization is the concrete adaptation to one language or region.
These practices keep localization consistent:
- A glossary fixes the technical terms for each language.
- A style guide sets the tone and the form of address.
- Layouts cope with longer texts, because German texts are often longer than English ones.
- Text does not belong in graphics, otherwise every graphic has to be recreated for every language.
Languages in the site configuration
You do not define a website's languages in the page properties, but per site in the site configuration. In TYPO3 14 you edit it in the module “Setup” in the “Sites” section. This module is reserved for administrators. Each language has, among others, these settings:
- The languageId is the number of the language. Once content exists, you must not change it, because pages, content and records are assigned to their language by this number.
- title is the name in the backend, navigationTitle the name in the language menu.
- base is the entry point of the language, either a URL prefix such as “en” or a domain of its own.
- locale controls things like date and number formats. It must be installed on the server. If you give several values, TYPO3 tries them in order.
- hreflang is the language hint for search engines. TYPO3 derives it from the locale, but you can override it.
- enabled switches the language on or off in the frontend.
- fallbackType and fallbacks control what happens when a translation is missing.
languages:
- languageId: 0
title: Deutsch
base: /
locale: de_DE.UTF-8
- languageId: 1
title: English
base: /en/
locale: en_GB.UTF-8
fallbackType: strict
- languageId: 2
title: Français
base: /fr/
locale: fr_CH.UTF-8
enabled: false
fallbackType: fallback
fallbacks: '1,0'When you add a language, you can create it from scratch or pick a preset. The third option is called “Use language from existing site” and takes over a language from another site. With several sites, the documentation recommends this option. That way English has the same languageId on both Seetal websites, which makes shared permissions and configuration easier.
When a translation is missing
The fallbackType decides what happens to missing content:
- With strict, TYPO3 fetches the records of the default language and lays the translations over them. Anything not translated is left out.
- With fallback, TYPO3 starts the same way. If the translation is missing, it goes through the list fallbacks from left to right and shows the first language that exists. This list is called the fallback chain.
- With free, TYPO3 only fetches the records of this language. The default language plays no role.
There is no fallbackType “connected”. Connected and free are terms for working in the backend.
Whole pages work in a similar way. With strict, an untranslated page leads to “page not found”. With fallback, TYPO3 only reports this when it finds the page in no language of the chain.
Translating pages and content
Before you can translate content, the page itself needs a translation. A copy of the page in the page tree would be a new page instead, not a translation.
- Open the module “Layout” in the “Content” section and select the page.
- Switch to the language view, called “Language Comparison” in the backend.
- In the select box “Create a new translation of this page”, choose one of the configured languages.
- In the page properties of the translation, enter the translated title.
- Then translate the content elements with the translation wizard.
The translation wizard. Since TYPO3 14, a new step-by-step wizard guides you through every translation, in all backend modules. It offers two options. “Translate” creates a connected translation. “Copy” creates an independent copy in free mode. If translations already exist, it only offers the matching option.
A freshly translated element starts out as a copy of the original. TYPO3 puts a note in square brackets in front of the texts, such as “Translate to Français”. The element is also hidden, so that half-finished translations do not show up on the website. The editor replaces the text and then makes the element visible.
Two views. The module “Layout” has two views. In the column view, which the backend labels as the view “Layout”, you choose one language and see the content areas in that language. In the language view the languages stand side by side as columns, so you can compare original and translation. Since TYPO3 14 you can select several languages at once there.
Records and files. You translate records such as news in the module “Records”. Its language selector shows one or more languages, so you see the original and its translations together. You translate the metadata of a file, that is title, description and alternative text, in the module “Media”. You open the metadata and create a translation for the language. The file itself stays the same.
Embedded elements. If a content element contains several images as inline elements, also called IRRE, they appear grayed out when you translate it. TYPO3 does not translate them automatically. “Localize all records” creates all of them in the target language, “Localize” creates individual ones. If the original changes later, you bring them in line with “Synchronize with original language”.
Connected, free and mixed
Connected mode. The translation keeps its link to the original through the field l10n_parent. Order, start time and end time come from the original. When the original changes, the translation can be recognized as out of date. While editing you see the changes and update the translation accordingly. Nothing is translated automatically, though.
Free mode. The content consists of independent copies. You can arrange, drop or add elements freely. You lose the comparison with changes in the original.
Mixed mode. If connected and free elements of the same language sit on one page, TYPO3 shows “Mixed Mode”. This happens, for example, when someone translates some elements and copies others. Editing then becomes error-prone, for example when changing the order. The fix: bring the page back to a single mode. For example, remove the deviating elements and translate them again consistently. TYPO3 does not convert anything by itself.
This is how the backend and the site configuration fit together: connected translations work with strict or fallback. Freely copied content belongs with the fallbackType free.
Hiding pages and keeping track
The Localization Overview in the module “Status” in the “Content” section shows which pages are translated into which languages. Up to TYPO3 13 the module was called “Info”. You see the page tree with all languages, several levels deep:
- Green: the page is translated and visible.
- Red: the page cannot be reached in this language. Calling it leads to an error message, and menus filter it out.
- Gray: there is no translation, but the page can be reached and follows the site's fallback setting.
This is also where you create translations for many pages at once. Select the pages and choose “Create new translation headers”. You then translate the content in the module “Layout”.
Hiding untranslated pages. Without further settings, an untranslated page appears in the menu with the title in the default language. In the “Language” tab of the page properties there is the option “Hide page if no translation for current language exists”. The page then disappears from the menu in that language, and calling it directly leads to an error message.
Reversing the behavior. With the global setting hidePagesIfNotTranslatedByDefault in the frontend section of the system configuration, untranslated pages are hidden from the start. The checkbox in the page properties then reads “Show page even if no translation exists”.
A page in another language only. Pages always need a record in the default language. For a page in French only, you create the page in German as a placeholder and translate it. Then you activate the option that hides the default language of the page. The documentation calls it “Hide default translation of page”, in TYPO3 14 the field is labelled “Hide default language of page”.
Searching the page tree. The search field above the page tree finds pages by keyword, ID or frontend URL. It also takes translated page titles into account. So you find a page even if you only know its French title.
Labels, language packs and translator permissions
Fixed labels such as “Read more” or “Search” come from templates and extensions. Such labels are not stored in the database, but in language files in the XLIFF format, an XML format with the file extension xlf.
- The default language sits in a file such as
locallang.xlf, translations in files with a language prefix such asde.locallang.xlf. - You can override labels of a third-party extension in your own site package, without changing the extension.
Editorial content, on the other hand, is translated as records in the database.
Language packs. The languages of the backend interface are independent of the languages of the website. Their translations come as language packs. You download them in the module “Maintenance” in the “System” section, under “Manage Language Packs”. After that, every user chooses their backend language in the User Settings.
Permissions for translators. A translator should only edit French content, not the German originals. For this, their backend group has the setting “Limit to languages” in the “Record Permissions” tab. If you allow only French, they may only edit French records. They still need to be able to read the source language.
- If no language is ticked at all, a user may edit all languages.
- Records with the language “All” can be edited by everyone.
Several websites in one installation
One TYPO3 installation can run many websites. Each site has its own root page, its own site configuration, its own domain and its own languages. You recognize the root page in the page tree by its globe icon.
At the very top is the node with the TYPO3 logo, the page with ID 0. It is not a website, but the container for installation-wide records such as backend users, backend groups and file mounts. Only administrators may edit records there.
How a site is created. When you create a page at the top level, TYPO3 automatically generates a basic site configuration. The same applies to pages with “Use as Root Page” set. You then adjust the identifier and the domain in the module “Setup”.
Where it is stored. The site configuration lives in the file system, not in the database. In a Composer installation that is the folder config, inside it sites, and inside that one folder per site with the file config.yaml. In Classic mode the sites folder lives under typo3conf. The module “Setup” looks like a normal form, but it writes YAML files. These belong in version control. Otherwise they get lost during deployments or drift apart between environments.
The entry point. Specify the base, called “Entry Point” in the form, as precisely as possible. Use protocol and domain, so https and seetal.example, rather than just a slash. This makes TYPO3 resolve pages more reliably. Mixing path prefixes and domains can make the assignment ambiguous.
Base variants. The developer works locally under kunde.ddev.site, while the live site runs under www.kunde.de. Instead of changing the base after every deployment, you use a base variant. It consists of a different base URL and a condition in the Symfony Expression Language, which checks the application context, for example. Never create two site configurations for the same root page, though, or the last one defined wins.
base: 'https://www.kunde.de/'
baseVariants:
- base: 'https://kunde.ddev.site/'
condition: 'applicationContext == "Development"'A separate robots.txt per site. A robots.txt in the web root would give the same answer for every domain. With a static route in the site configuration, each site delivers its own content under a fixed path, such as robots.txt.
Site settings. When someone saves settings in the backend module “Settings” of a site, TYPO3 creates a file settings.yaml. As soon as it exists, only its values apply, and the settings section in config.yaml is ignored. Remove that section then, to avoid confusion.
Domain records on pages no longer exist since TYPO3 10. Domains live in the site configuration.
Pros, cons and permissions in a multisite setup
All sites in an installation share the same TYPO3 version and the same extensions, plus the database and backend user management. Domain, languages and templates, among other things, are separate.
The advantages, for example for a client with ten brand websites:
- Only one installation needs to be updated and maintained.
- Content, users and extensions can be maintained centrally and shared.
- Editorial teams can be limited to their own website through groups and mounts.
The disadvantages and risks you should name openly:
- Updates and maintenance windows affect all websites at the same time. Different major versions are not possible.
- A bug in an extension can hit every site.
- All sites share the server resources. Load on one site affects the others.
- Permissions need careful planning, and administrators always see all sites.
By the way, there are no license costs per site, because TYPO3 has no licenses.
Limiting editors to their site works through backend groups:
- A DB mount defines from which page a user sees the page tree.
- Page permissions control what they may do with these pages.
- File mounts limit access to file folders.
That way the guest card team only sees its own page tree and its own file folder. Table and field permissions, however, apply to the whole installation, not per site.
For Seetal the decision is clear: one installation with two sites. Both belong to the same association and use the same design.
Key points
- Translation carries text over, localization also adapts formats, images, legal matters and tone to the region.
- The default language has ID 0, the language “All” has ID minus 1.
- Single-tree means one tree with translations, multi-tree means a separate tree per language or country.
- strict leaves out untranslated content, fallback goes through the chain from left to right, free only shows records of the language itself.
- Translate the page first, then the content: “Translate” for connected, “Copy” for free.
- Bring a mixed mode back to a single consistent mode.
- Labels live in XLIFF files, backend languages come as language packs.
- The site configuration is a YAML file and belongs in version control.
- Multisite saves maintenance, but couples the version, updates and risks of all sites.
Terms
- Base variant
- A different base URL for a site that applies under a condition, for example locally instead of live.
- DB mount
- The page from which a user sees the page tree.
- Default language
- The language with ID 0, on which all translations hang.
- Fallback chain
- The order of substitute languages when a translation is missing.
- File mount
- A file folder that a user may access.
- Localization
- Adapting content to a language and region, abbreviated L10n.
- Mixed mode
- Connected and free elements in the same language on one page.
- Root page
- The home page of a website in the page tree, recognizable by the globe.
- XLIFF
- XML format for language files with fixed labels.