XLIFF coding guidelines 

Changed in version 14.0

With TYPO3 14.0 the TYPO3 Core supports the XLIFF formats 1.2 and 2.0.

Language files are typically stored in XLIFF files. XLIFF is based on XML.

Table of contents

Directory and file names 

  • Files have the ending .xlf.
  • Language files are located in the directory EXT:my_extension/Resources/Private/Language/.
  • Historically language files where named locallang.xlf or with a locallang_ prefix. This is not recommended anymore. For a standard translation name messages.xlf is suggested.

Indentation in XLIFF files 

Changed in version 14.0

With TYPO3 14.0 the TYPO3 Core switched from indentation with tabs to spaces.

  • Use 2 spaces for indentation.

Language keys 

TYPO3 is designed to be fully localizable. Hard-coded strings should thus be avoided unless there are some technical limitations (for example, some very early or low-level stuff where a $GLOBALS['LANG'] object is not yet available).

Defining localized strings 

Here are some rules to respect when working with labels in locallang.xlf files:

  • Always check the existing locallang.xlf files to see, if a given localized string already exists, in particular EXT:core/Resources/Private/Language/locallang_common.xlf (GitHub) and EXT:core/Resources/Private/Language/locallang_core.xlf (GitHub).
  • Localized strings should never be all uppercase. If uppercase is needed, then appropriate methods should be used to transform them to uppercase.
  • Localized strings must not be split into several parts to include stuff in their middle. Rather use a single string with sprintf() markers (%s, %d, etc.).
  • When a localized string contains several sprintf() markers, it must use numbered arguments (for example, %1$d).
  • Localized strings should never contain configuration options (for example, index_config:timer_frequency, which would display a link or EXT:wizard_crpages/cshimages/wizards_1.png, which would show an image). Configuration like this does not belong in language labels, but in TypoScript.
  • Localized strings are not supposed to contain HTML tags. They should be avoided whenever possible.
  • Punctuation marks must be included in the localized string – including trailing marks – as different punctuation marks (for example, "?" and "¿") may be used in various languages. Also some languages include blanks before some punctuation marks.

Once a localized string appears in a released version of TYPO3, it cannot be changed (unless it needs grammar or spelling fixes).

A localization string can be deprecated in one major TYPO3 version and be removed with the next one

If the label of a localized string has to be changed, a new one should be introduced instead.