--- title: "Translation files (XLIFF format)" manual: "TYPO3 Explained" version: "main" permalink: "https://docs.typo3.org/permalink/t3coreapi:xliff@main" source: "ApiOverview/Localization/XliffFormat.rst" rendered: "2026-09-20T15:52:37+00:00" --- # Translation files (XLIFF format) {#xliff} 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'\]](https://docs.typo3.org/permalink/t3coreapi:confval-globals-typo3-conf-vars-sys-lang-requireapprovedlocalizations@main) to `false`. **Table of contents** - [About the XLIFF standard](https://docs.typo3.org/permalink/t3coreapi:about-the-xliff-standard@main) - [XLIFF file examples](https://docs.typo3.org/permalink/t3coreapi:xliff-file-examples@main) - [Translated XLIFF files and fallbacks](https://docs.typo3.org/permalink/t3coreapi:translated-xliff-files-and-fallbacks@main) - [Sample XLIFF translation files](https://docs.typo3.org/permalink/t3coreapi:sample-xliff-translation-files@main) - [Where to store XLIFF files](https://docs.typo3.org/permalink/t3coreapi:where-to-store-xliff-files@main) - [Naming XLIFF IDs](https://docs.typo3.org/permalink/t3coreapi:naming-xliff-ids@main) ## About the XLIFF standard {#xliff-about} The [XML Localization Interchange File Format](https://en.wikipedia.org/wiki/XLIFF) (or **XLIFF**) is an [OASIS standard](https://www.oasis-open.org/committees/xliff) format for structured translations. An XLIFF document contains one or more `` elements (TYPO3 supports exactly one per file). Each `` contains translation units that hold a `` text and optionally a `` 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 `` elements in one document is not supported by TYPO3. ## XLIFF file examples {#xliff-examples} **XLIFF 2.x (recommended)** **EXT:my_ext/Resources/Private/Language/locallang.xlf** ```xml The default Header Comment. The "Generator" Meta Tag. ``` XLIFF 2.x is the preferred format. Each `` contains a `` with `` and optionally ``. **XLIFF 1.2 (legacy)** **EXT:my_ext/Resources/Private/Language/locallang.xlf** ```xml

The default Header Comment.

The "Generator" Meta Tag. ``` 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 `` 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 {#xliff-translated-file-name} 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 {#xliff-sample-translations} **XLIFF 2.0** **EXT:my_extension/Resources/Private/Language/de.locallang.xlf** ```xml The default Header Comment. Der Standard-Header-Kommentar. The "Generator" Meta Tag. Der "Generator"-Meta-Tag. ``` In XLIFF 2.x, the approval status of a translation is defined by the `state` attribute on the `` 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"` on the `` tag as approved. **XLIFF 1.2** **EXT:my_extension/Resources/Private/Language/de.locallang.xlf** ```xml

The default Header Comment. Der Standard-Header-Kommentar.

The "Generator" Meta Tag. Der "Generator"-Meta-Tag. ``` In XLIFF 1.2, the optional `approved` attribute in a `` 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"` on the `` tag - XLIFF 2.x: `state="reviewed"` or `state="final"` on the `` tag > [!NOTE] > TYPO3 considers translations as approved if the `approved` attribute > (in XLIFF 1.2) or the `state` attribute (in XLIFF 2.x) is omitted. To also include unapproved translations (for example `approved="no"` or `state="translated"`), set the option [$GLOBALS\['TYPO3_CONF_VARS'\]\['LANG'\]\['requireApprovedLocalizations'\]](https://docs.typo3.org/permalink/t3coreapi:confval-globals-typo3-conf-vars-sys-lang-requireapprovedlocalizations@main) to `false`. ## Where to store XLIFF files {#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](https://docs.typo3.org/permalink/t3coreapi:extbase-extension-framework@main), 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](https://docs.typo3.org/permalink/t3coreapi:xliff-translated-file-name@main), translation files follow the same naming conventions but are prefixed with the language code and stored alongside the default language files. ## Naming XLIFF IDs {#xliff-id-naming} It is recommended to apply the following rules for defining identifiers (the `id` attribute). ### Separate XLIFF IDs by dots {#xliff-id-naming-dots} Use dots to separate logical parts of the identifier. Good example: ```none CType.menuAbstract ``` Bad examples: ```none CTypeMenuAbstract CType-menuAbstract ``` ### Namespace convention for XLIFF IDs {#xliff-id-naming-namespace} Group identifiers together with a useful namespace. Good example: ```none CType.menuAbstract ``` This groups all available content types for content elements by using the same prefix `CType.`. Bad example: ```none 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 {#xliff-id-naming-lower-camel} Generally, lowerCamelCase should be used: Good example: ```none 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`.