Lingo.dev + XLIFF

Lingo.dev CLI translates XLIFF (XML Localization Interchange File Format) files while preserving document structure, translation units, and workflow states. The CLI supports both XLIFF 1.2 and 2.0 formats, maintains source language metadata, preserves file/group/unit hierarchies, handles CDATA sections for XML-sensitive content, and integrates with professional translation workflows and CAT tools.

Quick Setup

Configure for XLIFF files:

{
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de", "ja"]
  },
  "buckets": {
    "xliff": {
      "include": ["localization/[locale].xliff"]
    }
  }
}

Reminder: [locale] is a placeholder that should remain in the config literally, as it's replaced with the actual locale during CLI run.

Translate XLIFF Files

npx lingo.dev@latest i18n

Preserves XLIFF structure, translation states, and professional translation workflow metadata while translating content.

XLIFF File Structure

XLIFF 1.2 Format

<?xml version="1.0" encoding="utf-8"?>
<xliff xmlns="urn:oasis:names:tc:xliff:document:1.2" version="1.2">
  <file original="app.strings" source-language="en" target-language="es" datatype="plaintext">
    <header></header>
    <body>
      <trans-unit id="welcome" resname="welcome.message">
        <source>Welcome to our application</source>
        <target state="translated">Bienvenido a nuestra aplicación</target>
      </trans-unit>
      <trans-unit id="login" resname="auth.login">
        <source>Log In</source>
        <target state="new"></target>
      </trans-unit>
    </body>
  </file>
</xliff>

XLIFF 2.0 Format

<?xml version="1.0" encoding="utf-8"?>
<xliff xmlns="urn:oasis:names:tc:xliff:document:2.0" version="2.0" srcLang="en">
  <file id="messages">
    <unit id="welcome">
      <segment>
        <source>Welcome to our application</source>
      </segment>
    </unit>
    <group id="auth">
      <unit id="login">
        <segment>
          <source>Log In</source>
        </segment>
      </unit>
    </group>
  </file>
</xliff>

Key Generation

XLIFF keys are generated deterministically with URL encoding:

XLIFF 1.2 Keys

  • Based on resname attribute, then id, then source text
  • Simple format: welcome.message, auth.login

XLIFF 2.0 Keys

  • Hierarchical path structure: resources/{fileId}/{groupPath}{unitId}/source
  • URL-encoded paths: resources%2Fmessages%2Fauth%2FgroupUnits%2Flogin%2Fsource
  • Groups create nested paths with groupUnits separator

XLIFF-Specific Features

Translation States

<!-- XLIFF 1.2 target states -->
<target state="new">Untranslated content</target>
<target state="translated">Translated content</target>
<target state="reviewed">Reviewed translation</target>
<target state="final">Final approved translation</target>

Translation states are preserved and updated during processing.

Source Language Metadata

<!-- XLIFF 1.2 -->
<file source-language="en-US" target-language="es-ES">

<!-- XLIFF 2.0 -->
<xliff srcLang="en-US" trgLang="es-ES">

Source language information is automatically preserved and updated.

CDATA Sections

<source><![CDATA[Content with <tags> & "special" characters]]></source>

CDATA sections are used automatically for content containing XML-sensitive characters.

Group Organization

<!-- XLIFF 2.0 groups for logical organization -->
<group id="navigation">
  <unit id="home"><segment><source>Home</source></segment></unit>
  <unit id="settings"><segment><source>Settings</source></segment></unit>
</group>

Hierarchical group structures are preserved and reflected in key paths.

Advanced Configuration

Multiple XLIFF Files

"xliff": {
  "include": [
    "localization/app_[locale].xliff",
    "localization/ui_[locale].xliff"
  ]
}

File Extensions

"xliff": {
  "include": [
    "translations/[locale].xliff",
    "translations/[locale].xlf"
  ]
}

Both .xliff and .xlf extensions are supported.

Lock Translation Units

"xliff": {
  "include": ["localization/[locale].xliff"],
  "lockedKeys": ["app.version", "build.number"]
}

Professional Translation Workflow

XLIFF files integrate seamlessly with:

  • CAT (Computer-Assisted Translation) tools
  • Translation Management Systems (TMS)
  • Professional translator workflows
  • Quality assurance processes
  • Translation memory systems

The CLI preserves all workflow metadata while enabling AI-powered translation for rapid localization.