The XML Localization Interchange File Format (or XLIFF) is an OASIS-blessed standard format for translations.
In a nutshell, an XLIFF document contains one or more
Each file element usually corresponds to a source (file or database table) and
contains the source of the localizable data. Once translated, the corresponding
localized data is added for one, and only one, locale.
Localizable data is stored in
<source> element to store the source text and a
<target> element to store the translated text.
The default language is always English, even if you have changed your TYPO3
backend to another language. It is mandatory to set
<file> elements in the same XLIFF document is not
supported by the TYPO3 Core.
Here is a sample XLIFF file:
<?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_ext/Resources/Private/Language/Modules/<file-name>.xlf" date="2020-10-18T18:20:51Z" product-name="my_ext"> <header/> <body> <trans-unit id="headerComment" resname="headerComment"> <source>The default Header Comment.</source> </trans-unit> <trans-unit id="generator" resname="generator"> <source>The "Generator" Meta Tag.</source> </trans-unit> </body> </file> </xliff>
The following attributes should be populated properly in order to get the best support in external translation tools:
This property contains the path to the xlf file.
Its content is shown to translators. It should be a copy of the
The translated file is very similar. If the original file was named
locallang.xlf, the translated file for German (code "de") will be named
Changed in version 12.2.
One can use a custom label file, for example, with the locale prefix
de_CH.locallang.xlf in an extension next to
locallang.xlf (default language English).
When integrators then use "de-CH" within their
site configuration, TYPO3 first checks if a term is
de_CH.locallang.xlf, and then automatically falls back to
the non-region-specific "de" label file
de.locallang.xlf without any
further configuration to TYPO3.
Before TYPO v12.2, one has to define a custom language.
The original file must always be in English, so it is not allowed to create
a file with the prefix "en", for example
In the file itself, a
target-language attribute is added to the
<file> tag to indicate the translation language ("de" in our example).
TYPO3 does not consider the
target-language attribute for its own processing
of translations, but the filename prefix instead. The attribute might be useful
though for human translators or tools.
Then, for each
<source> tag there is a sibling
that contains the translated string.
This is how the translation of our sample file might look like:
<?xml version="1.0" encoding="UTF-8"?> <xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2"> <file source-language="en" target-language="de" datatype="plaintext" original="EXT:my_ext/Resources/Private/Language/Modules/<file-name>.xlf" date="2020-10-18T18:20:51Z" product-name="my_ext"> <header/> <body> <trans-unit id="headerComment" resname="headerComment" approved="yes"> <source>The default Header Comment.</source> <target>Der Standard-Header-Kommentar.</target> </trans-unit> <trans-unit id="generator" resname="generator" approved="yes"> <source>The "Generator" Meta Tag.</source> <target>Der "Generator"-Meta-Tag.</target> </trans-unit> </body> </file> </xliff>
Only one language can be stored per file, and each translation into another language is placed in an additional file.
approved attribute in a
indicates whether the translation has been approved by a reviewer.
Crowdin supports this attribute.
Currently, only approved translations are exported and available via the
TYPO3 translation server.
Changed in version 12.0: By default, only translations with no
approved attribute or with
the attribute set to
yes are taken into account when parsing XLF
files. Set the option requireApprovedLocalizations to
to use translations with the
approved attribute set to
File locations and naming¶
In the TYPO3 Core, XLIFF files are located in the various system extensions
as needed and are expected to be located in
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
As mentioned above, the translation files follow the same naming conventions, but are prepended with the language code and a dot. They are stored alongside the default language files.
It is recommended to apply the following rules for defining identifiers (the
Separate by dots¶
Use dots to separate logical parts of the identifier.
Group identifiers together with a useful namespace.
This groups all available content types for content elements by using
the same prefix
Namespaces should be defined by context.
menuAbstract.CType could also be a reasonable namespace
if the context is about
Generally, lowerCamelCase should be used:
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