Study guide · Multilingual Sites and Translations
One website in several languages: content, labels and character sets
Editors translate pages and content in the backend, and the integrator makes sure that fixed labels such as “Read more” appear in every language. On this page you make a website trilingual, from the site configuration through XLIFF files to the language switcher. By the end you also understand why an ä sometimes turns into two strange characters.
The music school goes trilingual
The integrator Mara is building the website of the Lindenau Music School with TYPO3 14.3 and her own site package lindenau_site. The website is in German. English is added for international students and Polish, because many families from the neighbouring country enrol their children.
Mara separates two kinds of text.
- Content is written by the editors: pages, content elements, records such as news or courses, and the metadata of images. It lives in the database and is translated in the backend.
- Labels sit in templates and extensions, for example “Register for a course” or “Contact”. They live in XLIFF files and are translated there.
Mara does not need an extension for multilingual sites. Out of the box, TYPO3 manages content, records and metadata in as many languages as you like.
Languages in the site configuration
Which languages a website has is defined in the site configuration, not in page TSconfig or in the .htaccess file. In the backend you edit it in the “Sites” area, in the module “Setup”, on the tab “Languages”. It is stored as the file config.yaml in the folder config/sites.
Each language has these important settings:
- languageId is the number of the language. The default language always has 0, further languages get higher numbers. Once content exists, the number must not change any more.
- title is the name in the backend, navigationTitle the name in the language menu.
- base is the entry point of the language, for example the prefix “en” or a domain of its own.
- locale controls date and number formats, among other things, for example
pl_PL.UTF-8. - hreflang is the language tag for search engines. TYPO3 derives it from the locale, but you can override it.
- flag chooses the flag that the backend shows next to the language.
- enabled switches the language on or off in the frontend. Editors can still translate in the backend.
languages:
- languageId: 0
title: Deutsch
base: /
locale: de_DE.UTF-8
flag: de
- languageId: 1
title: English
base: /en/
locale: en_GB.UTF-8
flag: gb
fallbackType: strict
- languageId: 2
title: Polski
base: /pl/
locale: pl_PL.UTF-8
flag: pl
fallbackType: fallback
fallbacks: '0'When a translation is missing, the fallbackType of the language decides:
- strict only shows content that exists in this language. Untranslated elements are left out. This is also the default when nothing is set.
- fallback shows the content of the languages in the fallbacks list for missing translations, in order from left to right.
- free only shows records that were created in this language itself, independent of the original.
For English, Mara chooses strict, because half German pages would confuse international students. Polish is set to fallback with 0: if a Polish text is missing, families see the German one.
Translating pages and content
Before editors can translate content, the page itself needs a translation. Only then is there a Polish version of the page that Polish content elements can sit on. You do not need a separate page tree for each language.
In the “Content” area, the module “Layout” has two views.
- The columns view, called “Layout” in the backend, shows the columns of the backend layout in one chosen language.
- The language view, called “Language Comparison” in the backend, puts the languages side by side. This lets you compare original and translation. Since TYPO3 14 you can select several languages there at once.
The translation wizard. Since TYPO3 14, the same step-by-step wizard opens in all backend modules whenever someone translates something. It offers two modes:
- Translate creates a connected translation that is attached to its original.
- Copy creates an independent copy in free mode.
Automatic translation by AI is not part of the wizard.
Other records such as news, courses or categories are translated in the module “Records”. With the language selector, editors show one or more languages there and see original and translations together.
Files. For the teachers' photos, what gets translated is not the image files but their metadata, that is, title, description and alternative text. These records live in the table sys_file_metadata. In the module “Media” you open the metadata of a file and create a translation. The file itself stays the same for all languages, and nobody uploads it again for each language. A content element uses the translated metadata. On the file reference in the content element, you can also override title and alternative text for each language.
Keeping track. Which pages are translated into which languages is shown by the Localization Overview in the “Content” area, in the module “Status”. It shows the page tree with all languages, and you can also create translations for many pages at once.
Searching the page tree. A teacher only knows the Polish title of a page. The search field above the page tree still finds it, because since TYPO3 14.1 it also searches translated page titles. This is controlled by the user TSconfig option options.pageTree.searchInTranslatedPages, which defaults to 1. With 0 you switch it off for single users or groups. Each user can also toggle the search in the page tree menu.
Connected, free and mixed
Connected mode. Each translation is attached to its original. It takes over its order and column. If an editor moves a German element up, the English and Polish translations follow the new order. When the original changes, the translation is recognisable as outdated and can be updated.
Free mode. The elements of the language are independent of the original. Each language keeps its own structure, with its own elements and its own order. This fits when a language version is meant to be built differently, and it fits the fallbackType free.
Mixed mode. If connected and freely created elements sit side by side in one language of a page, the module “Layout” shows the notice “Mixed Mode”. This happens, for example, when someone adds freely created elements to connected translations. Maintenance then becomes difficult: when reordering, only the connected elements follow the original, the free ones stay where they are. The module no longer offers the translation wizard for this language.
How do you get rid of mixed mode? Clearing the cache does not help, because the state is stored in the records. Decide on one mode. Remove the elements that do not fit and translate missing content again in that mode. TYPO3 converts nothing by itself.
Language packs for the backend
The backend interface has its own languages, independent of the website languages. A backend in Polish needs the translations of the Core and the extensions. They come as language packs.
In the “System” area, open the module “Maintenance” and there “Manage Language Packs”. Here you select languages and download or update their translations. Afterwards, each user sets their backend language in their user settings.
On the command line, for example during a deployment, one command does the job:
vendor/bin/typo3 language:updateIt downloads the translations of all active extensions for the selected languages. In a Composer project the files end up in var/labels. Since TYPO3 14.2 the command belongs to the Core and also works without the install extension.
Labels in XLIFF files
XLIFF stands for XML Localisation Interchange File Format. It is an XML format that stores texts with an identifier and their translations. TYPO3 uses it for all fixed labels in the backend and the frontend.
Mara puts the language files of the site package in the folder Resources/Private/Language. The base file is called locallang.xlf and is always in English, even though the website starts in German. Translations sit next to it, with the language code in front: de.locallang.xlf for German and pl.locallang.xlf for Polish. If an identifier is missing in a file such as de_CH.locallang.xlf, TYPO3 looks in de.locallang.xlf and finally in the English base file.
Two versions. Since TYPO3 14, TYPO3 reads XLIFF 1.2 and XLIFF 2.x. Both formats work side by side, even in the same project. Existing 1.2 files do not need to be converted.
- In XLIFF 1.2, each entry sits in a trans-unit element with an id. Inside, the English text is in source and the translation in target.
- In XLIFF 2.0, the entry is called unit. It contains a segment with source and target.
The loader detects the version by itself: by the namespace urn:oasis:names:tc:xliff:document:2.0 or by the version attribute of the root element. You need no setting, no special file extension and no special folder.
<?xml version="1.0" encoding="UTF-8"?>
<xliff version="2.0" xmlns="urn:oasis:names:tc:xliff:document:2.0" srcLang="en" trgLang="pl">
<file id="f1">
<unit id="course.register">
<segment state="final">
<source>Register for a course</source>
<target>Zapisz się na kurs</target>
</segment>
</unit>
</file>
</xliff>Approved or not. By default, TYPO3 only uses approved translations. This is controlled by the setting requireApprovedLocalizations, which is true. Since TYPO3 14 it lives in the LANG area of the system configuration. Before, it was under SYS and lang.
- In XLIFF 1.2, an entry carries the attribute approved. With the value no, the translation is skipped.
- In XLIFF 2.0, the state is in the state attribute of the segment. The values are initial, translated, reviewed and final. Only reviewed and final count as approved.
- If the attribute is missing entirely, the translation counts as approved.
Translation domains and overrides
Up to TYPO3 13, you could only reference a label through a long path. This is what that looks like.
LLL:EXT:lindenau_site/Resources/Private/Language/locallang.xlf:course.registerSince TYPO3 14 there are translation domains for this. The format is package, dot, resource, colon, identifier. The package is the extension key. The resource is the file name without the extension and without the old prefix “locallang_”. For the file locallang.xlf the word messages is used. So the long path becomes lindenau_site.messages:course.register.
backend.toolbar:savemeans the identifier save in the filelocallang_toolbar.xlfof the extension backend.- Domains work in PHP and in Fluid. You do not have to register them anywhere, TYPO3 finds the files by itself.
- The old notation with LLL and EXT remains valid.
Overriding the labels of a plugin. The parents' area of the music school uses the login plugin felogin. Mara does not like the heading above the login form. She overrides it in the plugin's TypoScript with _LOCAL_LANG, per language and identifier:
plugin.tx_felogin_login._LOCAL_LANG {
de.welcome_header = Anmeldung für Eltern
pl.welcome_header = Logowanie dla rodziców
}Overriding labels for the whole project. For labels of the Core or third-party extensions, for example in the backend, Mara uses the setting resourceOverrides in the LANG area of the system configuration. It points to an XLIFF file of her own in the site package. Its identifiers replace those of the original, the other labels stay as they are. This setting used to be called locallangXMLOverride and lived under SYS.
$GLOBALS['TYPO3_CONF_VARS']['LANG']['resourceOverrides']['de']
['EXT:frontend/Resources/Private/Language/locallang_tca.xlf'][]
= 'EXT:lindenau_site/Resources/Private/Language/Overrides/de.locallang_tca.xlf';The ViewHelper f:translate
In a Fluid template, f:translate outputs a label from XLIFF in the current language. The ViewHelper does not translate page content and does not switch the language. Editorial content is translated in the backend.
How does it find the file? That depends on what you give it:
- In an Extbase context, the argument key is enough. The ViewHelper then looks in the
locallang.xlfof the current extension. - Outside Extbase, for example in a page template with PAGEVIEW, you add domain or extensionName to key. If both are set, domain takes precedence.
- The identifier can also contain the domain itself, for example
lindenau_site.messages:course.register. - A full reference with LLL and EXT works everywhere, also outside Extbase.
A typical mistake. In the page template, Mara writes only an f:translate with the key form.legend, and the page fails with an exception. Without an Extbase context, the ViewHelper cannot work out the extension. The fix is domain with the value lindenau_site, extensionName, or a full LLL reference.
default sets a fallback text that appears when the identifier is missing from the language file. It is no fix for the exception: it hides the problem, and only the fallback text ever appears.
Inserting values. If a label contains placeholders such as %s or %d, you pass the values with the argument arguments. They replace the placeholders in their order. Numbered placeholders pick a specific value. This way a translation can change the word order without changing the call.
<!-- Label: "%2$s hat noch %1$d freie Plätze" -->
<f:translate key="course.seats" domain="lindenau_site"
arguments="{0: course.freeSeats, 1: course.title}" />Plural and gender with ICU. Since TYPO3 14.2, TYPO3 understands the ICU MessageFormat. With it you write plural forms, selections with select, for example by gender, and named placeholders. Detection is automatic: if you pass named arguments, that is, an associative array, and the label contains an ICU pattern, the ICU MessageFormatter is used. With numbered values and %s, the old replacement stays in place, and curly braces alone do not switch ICU on. This applies to XLIFF 1.2 and 2.x, in the frontend and in the backend.
<!-- Label: {count, plural, =0 {Keine freien Plätze} one {Ein freier Platz} other {# freie Plätze}} -->
<f:translate key="free_seats" domain="lindenau_site" arguments="{count: course.freeSeats}" />Setting the language. In a FluidEmail sent by a scheduler task or a console command, there is no frontend or backend request. The ViewHelper then cannot tell which language applies. With languageKey, for example pl, you set it explicitly.
As an attribute value. A tag cannot sit inside an attribute. For the alternative text of an image you therefore use the inline notation:
<f:image image="{teacher.photo}" alt="{f:translate(key: 'image.alt', domain: 'lindenau_site')}" />The language switcher
A language switcher should sit at the top right of the website. Its data comes from the LanguageMenuProcessor, language-menu for short. It reads the languages from the site configuration and passes them to the Fluid template through dataProcessing. This works with PAGEVIEW just as with FLUIDTEMPLATE.
page.10 = PAGEVIEW
page.10 {
paths.10 = EXT:lindenau_site/Resources/Private/PageView/
dataProcessing.20 = language-menu
dataProcessing.20 {
languages = auto
as = languageNavigation
addQueryString.exclude = utm_source,utm_medium
}
}- languages is set to auto, so the processor takes all languages of the site. Alternatively you give a list of language IDs, for example 0,1,2.
- as sets the name of the variable in the template. Without it, the variable is called languagemenu.
- addQueryString.exclude names parameters that should be dropped from the language links. The processor copies the current URL parameters into every language link, at the music school also tracking parameters from the newsletter.
Each menu item carries, among other things: link, hreflang, navigationTitle, title, active and available. Who created a translation, or when, is not provided by the processor. The hreflang comes straight from the site configuration and matters for search engines.
Two values are often confused:
- active marks the language the visitor is currently viewing.
- available tells whether the current page exists in this language.
<f:for each="{languageNavigation}" as="item">
<f:if condition="{item.available}">
<f:then>
<a href="{item.link}" hreflang="{item.hreflang}" class="{f:if(condition: item.active, then: 'active')}">{item.navigationTitle}</a>
</f:then>
<f:else>
<span>{item.navigationTitle}</span>
</f:else>
</f:if>
</f:for>The processor does not detect the browser language and does not redirect visitors. It only provides the data for the menu.
Character sets and UTF-8
Polish brings characters such as ł, ż and ę. They only arrive correctly if the encoding is right.
A character set, or charset, defines which characters exist and which numeric values they have. The encoding defines how these numbers are stored as bytes. The font has nothing to do with it, it only defines the appearance.
- ASCII uses 7 bits and knows 128 characters: English letters, digits and punctuation, but no umlauts.
- ISO-8859-1, also called Latin-1, uses one byte per character and knows 256 characters, mostly Western European ones. The ä is included, the Polish ł is not.
- UTF-8 covers the whole Unicode range, that is, all scripts. It is the standard on the web today, and TYPO3 uses it throughout.
UTF-8 needs 1 to 4 bytes per character. ASCII characters take one byte and are byte-identical with ASCII. So an ASCII text is already valid UTF-8.
Umlauts take 2 bytes, many scripts such as Chinese take 3, emojis 4. This leads to two typical errors:
- Garbled text on import. An old CSV file with course data shows umlauts as ä. In UTF-8, the ä consists of two bytes. If a program reads them as ISO-8859-1, two separate characters appear. The cause is an encoding read wrongly, not the font. Both sides must use the same encoding.
- Lost emojis in MySQL. The old MySQL character set utf8, more precisely utf8mb3, stores at most 3 bytes per character. Emojis need 4 bytes and get lost. For the full Unicode range the database needs utf8mb4.
Key points
- Languages are defined in the site configuration, and the locale must be installed on the server.
- strict only shows what is translated, fallback fills gaps from the fallbacks list, free only shows the language's own records.
- Translate the page first, then the content. Translate creates connected translations, Copy free copies.
- Connected translations follow the order and column of the original. Mixed mode is cleaned up to one mode.
- Language packs come through “Manage Language Packs” or the command language:update into
var/labels. - XLIFF 1.2 uses trans-unit, XLIFF 2.0 uses unit and segment. TYPO3 14 detects the version by itself.
- Without approval, a translation is skipped as long as
requireApprovedLocalizationsis active. - Translation domains shorten paths: messages stands for
locallang.xlf. - Plugins are overridden with
_LOCAL_LANG, whole projects withresourceOverridesin the LANG area. - Outside Extbase,
f:translateneeds domain, extensionName or a full LLL reference. - In the language switcher you check active and available.
- UTF-8 needs 1 to 4 bytes per character, and MySQL needs utf8mb4 for it.
Terms
- Fallback chain
- List of substitute languages that TYPO3 searches in order when a translation is missing.
- Free mode
- Translations as independent elements with their own structure.
- Mixed mode
- Connected and free elements in the same language of a page.
- ICU MessageFormat
- Standard for labels with plural forms, selections and named placeholders.
- Locale
- Setting for language and region, controls date and number formats, among other things.
- Language pack
- Translations of the Core and the extensions for the backend interface.
- Translation domain
- Short name for a language file made of package and resource, for example lindenau_site.messages.
- UTF-8
- Encoding for all of Unicode with 1 to 4 bytes per character.
- Connected mode
- Translations that are attached to their original and follow it.
- XLIFF
- XML format for language files with identifiers and translations.