XLIFF 1.2

File format value

xliff:1.2

XLIFF 1.2 is a standard format for exchanging localization data between tools. It is widely used in the localization industry and is supported by many translation management systems. It is an XML-based format that allows you to store translations, comments, and other localization-related information in a structured way. XLIFF 1.2 is also widely used in Xcode projects for iOS and macOS applications, you can find it in .xcloc files.

Format structure

The XLIFF 1.2 format consists of a root <xliff> element, which contains one or more <file> elements. Each <file> element represents a single translation file and contains one or more <body> elements.

<?xml version="1.0" encoding="UTF-8"?>
<xliff version="1.2">
  <file source-language="en" target-language="pl" datatype="plaintext" original="messages">
    <body>
      <trans-unit id="hello_world">
        <source>Hello World</source>
        <target>Witaj Świecie</target>
        <note>My comment</note>
      </trans-unit>
    </body>
  </file>
</xliff>

The file usually contains translations for two languages, the source language and the target language. The source-language attribute specifies the source language, and the target-language attribute specifies the target language.

Attributes

source-language: The language code of the source language.
target-language: The language code of the target language.
datatype: The type of data in the file. It can be plaintext, html, or xhtml.
original: The name of the original file.
xml:space: The xml:space attribute specifies how whitespace should be handled. It can be preserve or default.

Comments

You can add comments and description to your translation units using the <note> element. The <note> element can be used to provide additional information about the translation, such as context or usage notes.

Review status

SimpleLocalize supports the state attribute on <target> elements for review status handling.

On import:

state="final" or state="signed-off" sets the translation status to REVIEWED.
Any other value leaves the status unchanged.

On export:

Reviewed translations are exported with state="final".
Translations that exist but are not reviewed are exported with state="translated".

translate attribute

SimpleLocalize supports the translate attribute on <trans-unit> elements. If translate="no" or translate="false", translation is locked in the editor. This attribute is preserved during both import and export.

resname attribute

The resname attribute on <trans-unit> elements is imported and stored in the translation key attributes. It is also exported back to the XLIFF file.

Context support

XLIFF 1.2 context groups (<context-group>) are imported and saved in translation key attributes, and exported back to the XLIFF file.

Custom attributes

SimpleLocalize stores XLIFF 1.2 file metadata in key attributes so it can be reused during export.

Supported keys:

resname — exported as resname attribute on <trans-unit>
Context groups — preserved and exported back as <context-group> elements

Limitations

The following limitations apply:

The xml:space attribute is always set to preserve in the exported file. It will be ignored during import.
The datatype attribute is always set to plaintext in the exported file. It will be ignored during import.
The original attribute can have up to 128 characters. If it exceeds this limit, it will be skipped during import/export.
For export, some of the newer features (review status, context, resname, translate attribute) are only available for projects created after April 10, 2026. For older projects, the XLIFF_12_VERSION_2 upload/download option is required to enable these features.

Automatic namespace detection

When importing XLIFF 1.2 files, SimpleLocalize can automatically detect namespaces based on the original attribute of the <file> element. To enable this feature, use the ORIGINAL_AS_NAMESPACE import option.

Projects created before November 23, 2025, have this option enabled by default to maintain backward compatibility.

Upload source translations

To upload source translations to SimpleLocalize, use the upload command with the --uploadFormat xliff:1.2 parameter, and provide the path to your en.xliff file using the --uploadPath parameter, and the language key using the --languageKey parameter.

simplelocalize upload \
  --apiKey PROJECT_API_KEY \
  --uploadLanguageKey en \
  --uploadFormat xliff:1.2 \
  --uploadPath ./en.xliff

Learn more about upload command.

Add --overwrite flag to update existing translations in SimpleLocalize from the imported file. Otherwise, only new translations will be added.

Export translations

To export translations from SimpleLocalize to the Android Strings file format, use the download command with the --downloadFormat xliff:1.2 parameter, and provide the path to the output file using the --downloadPath parameter.

simplelocalize download \
  --apiKey PROJECT_API_KEY \
  --downloadFormat xliff:1.2 \
  --downloadLanguageKeys pl,de \
  --downloadPath ./{lang}.xliff

Please note that the --downloadLanguageKeys parameter is optional. If you don't provide it, all translations will be downloaded. However, it's recommended to provide it to download only the necessary translations.