Managing translations in TYPO3 

This section highlights the different ways to translate and manage TYPO3 language files (XLIFF 1.2 and 2.x).

Fetching translations or updating language packs 

The backend module Admin Tools > Maintenance > Manage Language Packs displays a list of available languages and can fetch or update language packs for system and extension translations from the official TYPO3 translation server.

The module is straightforward to use. 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
Copied!
typo3/sysext/core/bin/typo3 language:update
Copied!

Loading an additional language pack 

Administrators can install additional language packs directly in the backend:

  1. Go to Admin Tools > Maintenance > Manage Language Packs

    Manage language packs

    Open the backend language administration module

  2. Select Add Language and activate the new language:

    Add a language

    Add the desired language

  3. The selected language is now available:

    A language has been added

Translating XLIFF files locally 

You can translate TYPO3 XLIFF files directly in your development environment using any XML or translation editor that supports the XLIFF format.

TYPO3 v14 and newer support both XLIFF 1.2 and XLIFF 2.x:

  • XLIFF 2.x: uses <unit> elements and the <target state="…"> attribute (state="reviewed" / state="final" = approved)
  • XLIFF 1.2: uses <trans-unit> and the approved="yes" attribute

Both formats are automatically detected and parsed by TYPO3.

You can use any text or translation editor to modify .xlf files locally. Ensure that your chosen tool supports the XLIFF 2.x format, which is the default for TYPO3 v14 and later.

Overriding or extending translations 

Changed in version 14.0

Option $GLOBALS['TYPO3_CONF_VARS']['LANG']['resourceOverrides'] allows overriding XLIFF files. This applies to both translations and default (language = English) files.

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']['LANG']['resourceOverrides']
    ['EXT:frontend/Resources/Private/Language/locallang_tca.xlf'][]
        = 'EXT:examples/Resources/Private/Language/custom.xlf';
// Override a German ("de") translation
$GLOBALS['TYPO3_CONF_VARS']['LANG']['resourceOverrides']['de']
    ['EXT:news/Resources/Private/Language/locallang_modadministration.xlf'][]
        = 'EXT:examples/Resources/Private/Language/Overrides/de.locallang_modadministration.xlf';
Copied!

The German language file could look like this:

EXT:examples/Resources/Private/Language/Overrides/de.locallang_modadministration.xlf
<?xml version="1.0" encoding="UTF-8"?>
<xliff version="2.0" xmlns="urn:oasis:names:tc:xliff:document:2.0" srcLang="en" trgLang="de">
    <file id="f1">
        <unit id="pages.title_formlabel">
            <segment>
                <source>Most important title</source>
                <target state="final">Wichtigster Titel</target>
            </segment>
        </unit>
    </file>
</xliff>
Copied!

TYPO3 loads either XLIFF 1.2 or 2.x — the format is detected automatically.

The result can be seen in the backend:

Custom label

Custom translation in the TYPO3 backend

Adding custom languages 

TYPO3 supports many languages by default, but you can also add custom languages and provide your own translations using XLIFF 1.2 or 2.x.

  1. Define the language

    Example: add "gsw_CH" (Swiss German) as an additional language.

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

    This language does not have to be translated completely. It can fall back to another language so that only differing labels need translation.

    config/system/additional.php | typo3conf/system/additional.php
    $GLOBALS['TYPO3_CONF_VARS']['SYS']['localization']['locales']['dependencies'] = [
        'gsw_CH' => ['de_AT', 'de'],
    ];
    Copied!

    In this example, "gsw_CH" falls back to "de_AT" and then to "de".

  3. Add translation files

    Translation files for system and extension labels must be stored under the correct subfolder of the environment’s getLabelsPath(). The minimum requirement is to translate the language name so it appears in the user settings.

    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 new language is now available in the backend user settings:

    The new language appears in the user preferences

    For your own extensions, provide the custom language files in the Resources/Private/Language/ folder, for example gsw_CH.locallang_db.xlf.

Each language always falls back on the default one (English) if no translation is found. A custom language automatically falls back on its defined dependencies. For example, "de_AT" would fall back on "de" automatically.