Attention

TYPO3 v8 has reached its end-of-life March 31st, 2020 and is not maintained by the community anymore.

You can order Extended Long Term Support (ELTS) here: TYPO3 ELTS.

Introduction to XLIFF

The XML Localisation Interchange File Format (or XLIFF) is an OASIS-blessed standard format for translations.

Note

In a nutshell an XLIFF document contains one or more <file> elements. 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 for one, and only one, locale is added.

Localizable data are stored in <trans-unit> elements. The <trans-unit> contains a <source> element to store the source text and a (non-mandatory) <target> element to store the translated text.

Note that having several <file> elements in the same XLIFF document is not supported by the TYPO3 CMS Core.

Keep in mind that the default language is always considered to be english, even when you have changed your typo3 backend to another language, so source-language must always be source-language="en".

Basics

Here is a sample XLIFF file:

<?xml version="1.0" encoding="UTF-8"?>
<xliff version="1.0" xmlns:t3="http://typo3.org/schemas/xliff">
   <file source-language="en" datatype="plaintext" original="messages" date="2011-10-18T18:20:51Z" product-name="my-ext">
      <header/>
      <body>
         <trans-unit id="headerComment" xml:space="preserve">
            <source>The default Header Comment.</source>
         </trans-unit>
         <trans-unit id="generator" xml:space="preserve">
            <source>The "Generator" Meta Tag.</source>
         </trans-unit>
      </body>
   </file>
</xliff>

The translated file is very similar. If the original file was named locallang.xlf, the translated file for German (code "de") will be named de.locallang.xlf. Note that the original file must always be in english, so it is not allowed to create a file with the prefix "en" e.g. en.locallang.xlf. Inside the file itself, a <target-language> attribute is added in the <file> tag to indicate the translation language ("de" in our example). Then for each <source> tag there's a sibling <target> tag containing the translated string.

Here is what the translation of our sample file could look like:

<xliff version="1.0" xmlns:t3="http://typo3.org/schemas/xliff">
   <file source-language="en" target-language="de" datatype="plaintext" original="messages" date="2011-10-18T18:20:51Z" product-name="my-ext">
      <header/>
      <body>
         <trans-unit id="headerComment" xml:space="preserve">
            <source>The default Header Comment.</source>
            <target>Der Standard-Header-Kommentar.</target>
         </trans-unit>
         <trans-unit id="generator" xml:space="preserve">
            <source>The "Generator" Meta Tag.</source>
            <target>Der "Generator"-Meta-Tag.</target>
         </trans-unit>
      </body>
   </file>
</xliff>

Contrary to "locallang XML" files, only one language can be stored per file. Each translation in a different language goes to an additional file.

File locations and naming

The files follow the same naming conventions as the "locallang XML" files, except they use extension "xlf" instead of "xml".

In the TYPO3 Core, XLIFF files are located in the various system extensions as needed. The system extension "lang" provides several general purpose files plus the classes related to the localization API.

In Extbase-based extensions, XLIFF files are expected to be located in Resources/Private/Language. The main file (locallang.xlf) will be loaded automatically and available in the controller and Fluid views without further work needed. Other files will need to be referred to explicitly.

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.