Managing translations

This sections highlights the different ways to translate and manage XLIFF files.

Fetching translations

The backend module Admin Tools > Maintenance > Manage Language Packs allows to manage the list of available languages to your users and can fetch and update language packs of TER and Core extensions from the official translation server. The module is rather straightforward to use and should be pretty much self-explanatory. Downloaded language packs are stored in the environment's getLabelsPath().

The Languages module with some active languages and status of extensions language packs

Language packs can also be fetched using the command line:

vendor/bin/typo3 language:update

typo3/sysext/core/bin/typo3 language:update

Local translations

With t3ll it is possible to translate XLIFF files locally. t3ll is an open source, cross-platform application and runs on console under Linux, MacOS and Windows. It opens its editor inside a Google Chrome or Chromium window.

Just call on a console, for example:

t3ll path/to/your/extension/Resources/Private/Language/locallang.xlf

t3ll.exe path\to\your\extension\Resources\Private\Language\locallang.xlf

Translating files locally is useful for extensions which should not be published or for creating custom translations.

Custom translations

$GLOBALS['TYPO3_CONF_VARS']['SYS']['locallangXMLOverride'] allows to override XLIFF files. Actually, this is not just about translations. Default language files can also be overridden. The syntax is as follows:

EXT:examples/ext_localconf.php

<?php

declare(strict_types=1);

defined('TYPO3') or die();
// Override a file in the default language

$GLOBALS['TYPO3_CONF_VARS']['SYS']['locallangXMLOverride']
    ['EXT:frontend/Resources/Private/Language/locallang_tca.xlf'][]
        = 'EXT:examples/Resources/Private/Language/custom.xlf';
// Override a German ("de") translation
$GLOBALS['TYPO3_CONF_VARS']['SYS']['locallangXMLOverride']['de']
    ['EXT:news/Resources/Private/Language/locallang_modadministration.xlf'][]
        = 'EXT:examples/Resources/Private/Language/Overrides/de.locallang_modadministration.xlf';

The German language file looks like this:

        EXT:examples/Resources/Private/Language/Overrides/de.locallang_modadministration.xlf
    

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<xliff version="1.0">
    <file source-language="en" datatype="plaintext" date="2013-03-09T18:44:59Z" product-name="examples">
        <body>
            <trans-unit id="pages.title_formlabel" approved="yes">
                <source>Most important title</source>
                <target>Wichtigster Titel</target>
            </trans-unit>
        </body>
    </file>
</xliff>

and the result can be easily seen in the backend:

Custom label — Custom translation in the TYPO3 backend

Attention

You do not have to copy the full reference file, but only the labels you want to translate.
The path to the file to be overridden must be specified as EXT:my_extension/... and have the extension xlf.

Attention

The following is a bug but must be taken as a constraint for now:

The files containing the custom labels must be located inside an extension. Other locations will not be considered.
The original translation needs to exist in the environment's getLabelsPath() or next to the base translation file in extensions, for example in my_extension/Resources/Private/Language/.

Custom languages

TYPO3 supports many languages by default. But it is also possible to add custom languages and create the translations locally using XLIFF files.

Define the language

As example, we "gsw_CH" (the official code for “Schwiizertüütsch” - that is "Swiss German") as additional language:

config/system/additional.php | typo3conf/system/additional.php
```
$GLOBALS['TYPO3_CONF_VARS']['SYS']['localization']['locales']['user'] = [
    'gsw_CH' => 'Swiss German',
];
```
Copied!
Add fallback to another language

This new language does not have to be translated entirely. It can be defined as a fallback to another language, so that only differing labels have to be translated:

config/system/additional.php | typo3conf/system/additional.php
```
$GLOBALS['TYPO3_CONF_VARS']['SYS']['localization']['locales']['dependencies'] = [
    'gsw_CH' => ['de_AT', 'de'],
];
```
Copied!
In this case, we define that "gsw_CH" can fall back on "de_AT" (another custom translation) and then on "de".
Add translation files

The translations for system extensions and extensions from TER must be stored in the appropriate labels path sub-folder (getLabelsPath()), in this case gsw_CH.

The least you need to do is to translate the label with the name of the language itself so that it appears in the user settings. In our example, this would be in the file gsw_CH/setup/Resources/Private/Language/gsw_CH.locallang.xlf.

gsw_CH/setup/Resources/Private/Language/gsw_CH.locallang.xlf
```
<?xml version="1.0" encoding="UTF-8"?>
<xliff xmlns="urn:oasis:names:tc:xliff:document:1.2" version="1.2">
    <file source-language="en" target-language="gsw_CH" datatype="plaintext" original="EXT:setup/Resources/Private/Language/locallang.xlf">
        <body>
            <trans-unit id="lang_gsw_CH" approved="yes">
                <source>Swiss German</source>
                <target>Schwiizertüütsch</target>
            </trans-unit>
        </body>
    </file>
</xliff>
```
Copied!
The custom language is now available in the user settings:

The new language appears in the user preferences

For translations in own extensions you can provide the custom language files in the Resources/Private/Language/ folder of the extension, for example gsw_CH.locallang_db.xlf.

Note

Each language will always fall back on the default one (i.e. English) if no a translation is found. A custom language will fall back on its "parent" language automatically. Thus, in our second example of "de_AT" (German for Austria), there would be no need to define a fallback for "de_AT" if it fell back to "de".