---
title: "Managing translations in TYPO3"
manual: "TYPO3 Explained"
version: "14.3"
permalink: "https://docs.typo3.org/permalink/t3coreapi:managing-translating@14.3"
source: "ApiOverview/Localization/ManagingTranslations.rst"
rendered: "2026-09-22T15:25:43+00:00"
---

# Managing translations in TYPO3 {#managing-translating}

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

**Table of contents**

-   [Fetching translations or updating language packs](https://docs.typo3.org/permalink/t3coreapi:fetching-translations-or-updating-language-packs@14.3)
-   [Loading an additional language pack](https://docs.typo3.org/permalink/t3coreapi:loading-an-additional-language-pack@14.3)
-   [Translating XLIFF files locally](https://docs.typo3.org/permalink/t3coreapi:translating-xliff-files-locally@14.3)
-   [Overriding or extending translations](https://docs.typo3.org/permalink/t3coreapi:overriding-or-extending-translations@14.3)
-   [Adding custom languages](https://docs.typo3.org/permalink/t3coreapi:adding-custom-languages@14.3)

## Fetching translations or updating language packs {#xliff-translating-fetch}

The backend module **System > 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()](https://docs.typo3.org/permalink/t3coreapi:environment-labels-path@14.3).

![](../../Images/ManualScreenshots/AdminTools/ManageLanguagePacks.png)

Language packs can also be fetched using the command line:

**Composer-based installation**

```bash
vendor/bin/typo3 language:update
```

**Classic mode installation (no Composer)**

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

## Loading an additional language pack {#load-language-pack}

Administrators can install additional language packs directly in the backend:

1.  Go to **System > Maintenance > Manage Language Packs**

    ![Manage language packs](../../Images/ManualScreenshots/Modules/ManageLanguage.png)
1.  Select **Add Language** and activate the new language:

    ![Add a language](../../Images/ManualScreenshots/Modules/ManageLanguagePacksAddLanguage.png)
1.  The selected language is now available:

    ![A language has been added](../../Images/ManualScreenshots/Modules/ManageLanguagePacksAddLanguageAddSuccess.png)

## Translating XLIFF files locally {#xliff-translating-local}

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 {#xliff-translating-custom}

<!-- TODO: no Markdown rendering for "versionchanged" -->

$GLOBALS['TYPO3_CONF_VARS']['SYS']['locallangXMLOverride'] has been moved
to $GLOBALS['TYPO3_CONF_VARS']['LANG']['resourceOverrides'].

<!-- TODO: no Markdown rendering for "versionchanged" -->

The overridden file can also be addressed by its
translation domain instead of its path.
See Important: #109672 - Translation domain syntax supported in resourceOverrides.

Option [$GLOBALS\['TYPO3_CONF_VARS'\]\['LANG'\]\['resourceOverrides'\]](https://docs.typo3.org/permalink/t3coreapi:confval-globals-typo3-conf-vars-lang-resourceoverrides@14.3)
allows overriding XLIFF files. This applies to both translations and default
(language = English) files.

**EXT:examples/ext_localconf.php**

```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';
// The translation domain can be used as key instead of the file path
$GLOBALS['TYPO3_CONF_VARS']['LANG']['resourceOverrides']['core.common'][]
    = 'EXT:examples/Resources/Private/Language/custom.xlf';

```

The German language file could look like this:

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

```xml
<?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>

```

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

The result can be seen in the backend:

![Custom label](../../Images/ManualScreenshots/Internationalization/InternationalizationLabelOverride.png)

> [!WARNING]
> **Attention**
>
> -   You only need to include the labels you want to override.
> -   The file to be overridden is addressed either by its
>     [translation domain](https://docs.typo3.org/permalink/t3coreapi:label-reference-domain@14.3), for example
>     `core.common`, or by a path that starts with
>     `EXT:my_extension/...` and ends with `.xlf`.

> [!WARNING]
> **Attention**
>
> The following is a **known limitation**:
>
> -   Custom label files must be located inside an extension.
>     Other locations are ignored.
> -   The original translation must exist in the environment’s
>     [getLabelsPath()](https://docs.typo3.org/permalink/t3coreapi:environment-labels-path@14.3) or next to the base translation file in
>     the extension, for example in
>     `my_extension/Resources/Private/Language/`.

## Adding custom languages {#xliff-translating-languages}

TYPO3 [supports many languages](https://docs.typo3.org/permalink/t3coreapi:i18n-languages@14.3) 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**

    ```php
    $GLOBALS['TYPO3_CONF_VARS']['SYS']['localization']['locales']['user'] = [
        'gsw_CH' => 'Swiss German',
    ];
    ```
1.  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**

    ```php
    $GLOBALS['TYPO3_CONF_VARS']['SYS']['localization']['locales']['dependencies'] = [
        'gsw_CH' => ['de_AT', 'de'],
    ];
    ```

    In this example, "gsw_CH" falls back to "de_AT" and then to "de".
1.  Add translation files

    Translation files for system and extension labels must be stored under the
    correct subfolder of the environment’s [getLabelsPath()](https://docs.typo3.org/permalink/t3coreapi:environment-labels-path@14.3).
    The minimum requirement is to translate the language name so it appears
    in the user settings.

    **XLIFF 2.0 (recommended)**

    **gsw_CH/setup/Resources/Private/Language/gsw_CH.locallang.xlf**

    ```xml
    <?xml version="1.0" encoding="UTF-8"?>
    <xliff version="2.0" xmlns="urn:oasis:names:tc:xliff:document:2.0"
    srcLang="en" trgLang="gsw_CH">
      <file id="f1">
        <unit id="lang_gsw_CH">
          <segment>
            <source>Swiss German</source>
            <target state="final">Schwiizertüütsch</target>
          </segment>
        </unit>
      </file>
    </xliff>

    ```

    **XLIFF 1.2 (legacy)**

    **gsw_CH/setup/Resources/Private/Language/gsw_CH.locallang.xlf**

    ```xml

    <?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>

    ```

    The new language is now available in the backend user settings:

    ![](../../Images/ManualScreenshots/Internationalization/CustomLanguage.png)

    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.

> [!NOTE]
> **See also**
>
> Configure `typo3Language` to use custom languages in the frontend.
> See [Adding languages](https://docs.typo3.org/permalink/t3coreapi:sitehandling-addinglanguages@14.3) for details.