Multilanguage—Use any Locale now in TYPO3 v12

The admin interface and all TYPO3 plugins are English by default, and all labels reside in files of the XLIFF standard. But before v12, the way TYPO3 approached language had some quirks. The TYPO3 “supported languages” is a fixed list of “language codes“ (such as ”de“ for German) which Kasper Skarhooj originally introduced over 20 years ago. Over time, the list has expanded to over 57 supported languages. The TYPO3 Localization Team works hard to translate the English strings and labels into these languages. In mid-2023, the translation for TYPO3 in Arabic was completed. This is a great community effort and an amazing system that works well. Every TYPO3 installation can download additional “language packs” for their extensions—even third-party extensions—in any of the 57 supported languages.

When using German for a site language or an editor in the TYPO3 backend, the Localization system automatically checks for available language packs in the local setup. It references a “de.mylabels.xlf” file, checks for the label, and returns it. If the label doesn’t exist in the XLF file, it falls back to the English version.

However, the challenge comes when a project needs to use a different “language” for a different version of a language, for example, German for Switzerland. This is where “locales” come into play. The format usually is bound to a Locale system where “de” is the ISO 639 language code (2 letters in lowercase), and an optional 2-letter country code (ISO 3166–1 alpha 2) separated by an underscore—resulting in “de_CH”. Previously, you could “add” an additional language with any format, such as “de_CH” (or any other kind of way), but you also needed to define the system to fall back to “de” and then to English, to override any necessary words or sentences.

Once manually registered and defined as a “dependency” in TYPO3 (until v11), the language system then checked for “de_CH.mylabels.xlf” — then, for a “de.mylabels.xlf” and then for the fallback to “mylabels.xlf”, when referenced. 

For the website output, language setup is handled in the Site Configuration. One example for a setting would be to define if a language or locale for your website should be rendered “right to left” or “left to right”. For editors, there are a lot of different language settings in Site Config that make it complicated to use.

TYPO3 v12 ships with a list of all ISO 639 language codes, which can literally be combined with any other Country or Region code, and handles the fallback automatically. The fixed list of ISO 639 letter codes as defined in TYPO3 Core is still valid—but the changes introduced in version 12 should result in a reduction in the direct usages of the two-letter “language” format. 

In addition, a Locale class has been introduced, which can handle both BCP 47-like formats as well as previous syntax formats. When referencing a translation file then, the Locale is used and the fallback logic for multiple languages applies automatically.

$languageService = $languageServiceFactory->create(new Locale('de-CH));
$myTranslatedString = $languageService->sL('LLL:EXT:my_extension/Resources/Private/Language/myfile.xlf:my-label');

In addition, the necessary options for setting up a new Language in TYPO3 v12 have been drastically reduced, so it’s now easier than ever to configure a new language: