Translation files (XLIFF format)

New in version 14.0

TYPO3 supports both XLIFF 1.2 and XLIFF 2.x translation file formats. The loader automatically detects which version is used and parses it accordingly.

Use XLIFF 2.x for all new projects (introduced with TYPO3 v14). Each label file is written in English (srcLang="en") and stored in EXT:my_ext/Resources/Private/Language/. Translations are stored in separate files such as de.locallang.xlf. TYPO3 considers only approved translations (state="reviewed" or state="final") by default.

To also load unapproved strings (for example state="translated"), set $GLOBALS['TYPO3_CONF_VARS']['LANG']['requireApprovedLocalizations'] to false.

Table of contents

About the XLIFF standard

The XML Localization Interchange File Format (or XLIFF) is an OASIS standard format for structured translations.

An XLIFF document contains one or more <file> elements (TYPO3 supports exactly one per file). Each <file> contains translation units that hold a <source> text and optionally a <target> translation.

The default language is always English (en). Set srcLang="en" for XLIFF 2.x or source-language="en" for 1.2.

Note

Having several <file> elements in one document is not supported by TYPO3.

XLIFF file examples

New in version 14.0

EXT:my_ext/Resources/Private/Language/locallang.xlf

<?xml version="1.0" encoding="UTF-8" ?>
<xliff version="2.0" xmlns="urn:oasis:names:tc:xliff:document:2.0" srcLang="en">
    <file id="f1">
        <unit id="headerComment">
            <segment>
                <source>The default Header Comment.</source>
            </segment>
        </unit>
        <unit id="generator">
            <segment>
                <source>The "Generator" Meta Tag.</source>
            </segment>
        </unit>
    </file>
</xliff>

XLIFF 2.x is the preferred format. Each <unit> contains a <segment> with <source> and optionally <target>.

EXT:my_ext/Resources/Private/Language/locallang.xlf

<?xml version="1.0" encoding="UTF-8"?>
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
    <file source-language="en" datatype="plaintext" original="EXT:my_extension/Resources/Private/Language/Modules/<file-name>.xlf" date="2020-10-18T18:20:51Z" product-name="my_ext">
        <header/>
        <body>
            <trans-unit id="headerComment">
                <source>The default Header Comment.</source>
            </trans-unit>
            <trans-unit id="generator">
                <source>The "Generator" Meta Tag.</source>
            </trans-unit>
        </body>
    </file>
</xliff>

This format remains supported for backward compatibility.

The following attributes should be populated properly to get the best support in external translation tools:

original (in <file> tag): Contains the path to the XLF file within the extension.

If the external tool depends on the attribute resname, you can also define it. TYPO3 ignores this attribute internally.

Translated XLIFF files and fallbacks

Translated files use the same name as the English source but are prefixed with the locale code, for example:

de.locallang.xlf de_CH.locallang.xlf

TYPO3 automatically falls back from de_CH to de if needed.

Note

The original file must always be in English. Do not create files with the prefix en.

The translation language is also defined in the file header: trgLang="de" (XLIFF 2.0) or target-language="de" (XLIFF 1.2).

Sample XLIFF translation files

New in version 14.0

EXT:my_extension/Resources/Private/Language/de.locallang.xlf

<?xml version="1.0" encoding="UTF-8" ?>
<xliff version="2.0" xmlns="urn:oasis:names:tc:xliff:document:2.0" srcLang="en">
    <file id="f1">
        <unit id="headerComment">
            <segment>
                <source>The default Header Comment.</source>
            </segment>
        </unit>
        <unit id="generator">
            <segment>
                <source>The "Generator" Meta Tag.</source>
            </segment>
        </unit>
    </file>
</xliff>

In XLIFF 2.0, the approval status of a translation is defined by the state attribute on the <target> element. Common values are:

initial: Translation not yet started.
translated: Translation provided but not yet reviewed.
reviewed: Translation reviewed and approved.
final: Final, approved translation ready for use.

TYPO3 treats translations with state="reviewed" or state="final" as approved.

EXT:my_extension/Resources/Private/Language/de.locallang.xlf

<?xml version="1.0" encoding="UTF-8"?>
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
    <file source-language="en" datatype="plaintext" original="EXT:my_extension/Resources/Private/Language/Modules/<file-name>.xlf" date="2020-10-18T18:20:51Z" product-name="my_ext">
        <header/>
        <body>
            <trans-unit id="headerComment">
                <source>The default Header Comment.</source>
            </trans-unit>
            <trans-unit id="generator">
                <source>The "Generator" Meta Tag.</source>
            </trans-unit>
        </body>
    </file>
</xliff>

In XLIFF 1.2, the optional approved attribute in a <trans-unit> tag indicates whether a translation has been reviewed and approved, for example approved="yes".

Only one language can be stored per file; each translation into another language is stored in an additional file.

By default, TYPO3 considers only approved translations for both XLIFF 1.2 and 2.x:

XLIFF 1.2: approved="yes" or missing attribute
XLIFF 2.x: state="reviewed" or state="final"

To also include unapproved translations (for example approved="no" or state="translated"), set the option $GLOBALS['TYPO3_CONF_VARS']['LANG']['requireApprovedLocalizations'] to false.

Where to store XLIFF files

In the TYPO3 Core, XLIFF files are located in the various system extensions and are expected to be stored in Resources/Private/Language.

In Extbase, the main file (locallang.xlf) is loaded automatically and is available in the controller and Fluid views without any further work. Other files must be explicitly referenced with the syntax LLL:EXT:extkey/Resources/Private/Language/myfile.xlf:my.label.

As mentioned above, translation files follow the same naming conventions but are prefixed with the language code and stored alongside the default language files.

Naming XLIFF IDs

It is recommended to apply the following rules for defining identifiers (the id attribute).

Separate XLIFF IDs by dots

Use dots to separate logical parts of the identifier.

Good example:

CType.menuAbstract

Bad examples:

CTypeMenuAbstract
CType-menuAbstract

Namespace convention for XLIFF IDs

Group identifiers together with a useful namespace.

Good example:

CType.menuAbstract

This groups all available content types for content elements by using the same prefix CType..

Bad example:

menuAbstract

Namespaces should be defined by context. menuAbstract.CType could also be a reasonable namespace if the context is about menuAbstract.

Use lowerCamelCase for XLIFF IDs

Generally, lowerCamelCase should be used:

Good example:

frontendUsers.firstName

For some specific cases where the referenced identifier is in a format other than lowerCamelCase, that format can be used:

For example, database table or column names often are written in snake_case, and the XLIFF key then might be something like fe_users.first_name.