---
title: "XLIFF coding guidelines"
manual: "TYPO3 Explained"
version: "main"
permalink: "https://docs.typo3.org/permalink/t3coreapi:cgl-xliff@main"
source: "CodingGuidelines/CglXliff/Index.rst"
rendered: "2026-09-19T06:56:03+00:00"
---

# XLIFF coding guidelines {#cgl-xliff}

<!-- TODO: no Markdown rendering for "versionchanged" -->

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

Language files are typically stored in [XLIFF](https://en.wikipedia.org/wiki/XLIFF)
files. XLIFF is based on XML.

**Table of contents**

-   [Directory and file names](https://docs.typo3.org/permalink/t3coreapi:directory-and-file-names@main)
-   [Indentation in XLIFF files](https://docs.typo3.org/permalink/t3coreapi:indentation-in-xliff-files@main)
-   [Language keys](https://docs.typo3.org/permalink/t3coreapi:language-keys@main)

> [!NOTE]
> **See also**
>
> [Translation files (XLIFF format)](https://docs.typo3.org/permalink/t3coreapi:xliff@main)

## Directory and file names {#cgl-xliff-filenames}

-   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 {#cgl-xliff-indentation}

<!-- TODO: no Markdown rendering for "versionchanged" -->

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

-   Use 2 spaces for indentation.

> [!TIP]
> Have a look into the [.editorconfig](https://docs.typo3.org/permalink/t3coreapi:cgl-ide@main) file,
> which allows you to enforce file formatting.

## Language keys {#cgl-xliff-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'\]](https://docs.typo3.org/permalink/t3coreapi:translator-api@main)
object is not yet available).

### Defining localized strings {#cgl-localization}

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)](https://github.com/typo3/typo3/blob/main/typo3/sysext/core/Resources/Private/Language/locallang_common.xlf)
    and [EXT:core/Resources/Private/Language/locallang_core.xlf (GitHub)](https://github.com/typo3/typo3/blob/main/typo3/sysext/core/Resources/Private/Language/locallang_core.xlf).
-   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()](https://www.php.net/manual/en/function.sprintf.php)
    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.