Study guide · Multilingual Sites and Translations

One website in several languages: content, labels and character sets

As of November 15, 2026 · TYPO3 14.3 LTS · about 26 min read

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'
Excerpt from the music school's site configuration. German has languageId 0 and the base slash. English has ID 1, the prefix en and the fallbackType strict. Polish has ID 2, the prefix pl, the locale pl_PL and the fallbackType fallback, with the default language 0 as its fallback.

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.

Element C is moved up in German Connected Translate DE PL C A B C A B follow the original Wizard: Translate only Free Copy DE PL C A B A X B own order Wizard: Copy only Mixed both DE PL C A B C X A hard to control Wizard: blocked
What happens when reordering, depending on the mode.

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:update
Command on the command line: vendor bin typo3 language:update.

It 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>
Code example. The Polish file pl.locallang.xlf in XLIFF 2.0 format. The header has version 2.0, the namespace and source and target language. The unit with the id course.register contains a segment with the state final, the English text Register for a course and the Polish text Zapisz się na kurs.

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.register
Full label reference: LLL colon EXT colon, then the path to the file locallang.xlf in the site package, then a colon and the identifier course.register.

Since 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:save means the identifier save in the file locallang_toolbar.xlf of 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
}
TypoScript example. In the plugin tx_felogin_login, under _LOCAL_LANG, the identifier welcome_header is set to Anmeldung für Eltern for German and to Logowanie dla rodziców for Polish.

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';
Code example for the file additional.php. For German, the file locallang_tca.xlf of the frontend extension is overridden with a file of its own from the site package.

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.xlf of 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.
Where does f:translate look? Full LLL reference or domain inside key? yes exactly that file no Argument domain? yes that domain no Argument extensionName? yes locallang.xlf of the extension no Extbase context? yes locallang.xlf of the extension no Argument default? yes fallback text no Exception domain takes precedence over extensionName. If the key is missing in the file, default is shown.
How f:translate knows which file to search.

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}" />
Code example. The German label reads: percent two s has percent one d free places left. The call passes the number of free places as the first value and the course title as the second. So percent one d takes the number and percent two s the 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}" />
Code example. The label free_seats contains an ICU pattern: for zero, no free places, for one, one free place, otherwise the number followed by free places. In the template, f:translate passes the named argument count with the number of free places.

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')}" />
Code example. The ViewHelper f:image gets as its alt attribute the inline call of f:translate with the identifier image.alt and the 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
  }
}
TypoScript example. The page's PAGEVIEW object gets the data processor language-menu. languages is set to auto, the variable is called languageNavigation, and the parameters utm_source and utm_medium are removed from the language links.
  • 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>
Fluid example. For each entry in languageNavigation, the template checks item.available. If the language is available, it renders a link with hreflang and the navigation title, with the class active for the active language. Otherwise only the navigation title is shown without a link.

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.

How long is a character in UTF-8? A 41 1 byte ä C3 A4 2 bytes € E2 82 AC 3 bytes 🎵 F0 9F 8E B5 4 bytes Read wrongly: bytes as ISO-8859-1 ä C3 A4 Latin-1 Ã ¤ Emojis need 4 bytes, so MySQL needs utf8mb4.
UTF-8 has variable length. Read wrongly, one character turns into garbage.

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 requireApprovedLocalizations is active.
  • Translation domains shorten paths: messages stands for locallang.xlf.
  • Plugins are overridden with _LOCAL_LANG, whole projects with resourceOverrides in the LANG area.
  • Outside Extbase, f:translate needs 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.

As of: November 15, 2026 (TYPO3 14.3 LTS)

Sources:

  • TYPO3 Frontend Localization Guide 14.3 (languages, translating, language menu, XLIFF files)
  • TYPO3 Explained 14.3, chapters Site Handling (languages) and Localization (XLIFF format, managing translations)
  • Fluid ViewHelper Reference 14.3, Translate, and TypoScript Reference 14.3, LanguageMenuProcessor and _LOCAL_LANG
  • Changelog TYPO3 14, among others Feature 107710 (XLIFF 2), 93334 (translation domains), 108049 (translation wizard), 107961 (search in translated pages), 104546 (ICU MessageFormat), Breaking 107436 (LANG settings) and Important 108783 (language en instead of default)
  • Source code TYPO3 14.3 (typo3/cms-core, cms-backend, cms-fluid, cms-extbase, cms-frontend), checked for the XLIFF loader, approval state, overrides, TranslateViewHelper, LanguageMenuProcessor and SiteLanguage
  • Learning objectives TYPO3 CMS Certified Integrator 14 LTS, area Multilingual Sites and Translations

This study guide was written with AI and checked against the sources.

Certifications & exams

Which exam comes next?

You can already practise for 51 exams, and 16 are up for a vote. See all certifications with their official information, cast your vote or suggest your exam.

See all certifications