What you’ll need #️⃣

This guide covers Angular’s built-in i18n with XLIFF and ngx-translate / Transloco with JSON.

Before you start, make sure you have:

• Angular i18n set up in your project. Use either @angular/localize with i18n attributes, or ngx-translate/Transloco with JSON translation files
• Localazy CLI installed
• Strings already externalized (marked with i18n or extracted into JSON keys)

Set up the Localazy configuration file #️⃣

Create a localazy.json file in your project root. Use the block that matches your setup.

Native i18n (XLIFF) #️⃣

Angular extracts source strings to XLIFF with ng extract-i18n. Localazy recognizes both XLIFF 1.2 (the default) and XLIFF 2.0 automatically, so the type stays xliff either way.

{
  "writeKey": "your-write-key",
  "readKey": "your-read-key",
  "upload": {
    "type": "xliff",
    "files": "src/locale/messages.xlf",
    "features": ["output_entities", "parse_plurals_icu"]
  },
  "download": {
    "files": "src/locale/messages.${lang}.xlf"
  }
}

output_entities returns XML entities in the same form Angular expects, so downloaded files import back cleanly.

parse_plurals_icu handles the ICU plurals native i18n uses, converting them into Localazy’s plural structure so translators get proper plural forms. Only one ICU plural per string is converted (strings with more are left as-is), and the supported forms are zero, one, two, few, many, and other.

ngx-translate / Transloco (JSON) #️⃣

Runtime libraries keep translations in JSON, loaded per language without a separate build per locale.

{
  "writeKey": "your-write-key",
  "readKey": "your-read-key",
  "upload": {
    "type": "json",
    "files": "src/assets/i18n/en.json",
    "features": ["plural_icu"]
  },
  "download": {
    "files": "src/assets/i18n/${lang}.json"
  }
}

For Transloco’s per-scope files, use a glob so lazy-loaded feature scopes stay in their own files:

"upload": {
  "type": "json",
  "files": "src/assets/i18n/**/*.json"
}

plural_icu handles ICU plurals — the syntax both ngx-translate and Transloco use once you add their MessageFormat plugin. As with XLIFF, only one ICU plural per string is converted, and the supported forms are zero, one, two, few, many, and other. If your team handles plurals as separate keys in code instead, those upload as ordinary strings and need no extra configuration.

Upload source files #️⃣

localazy upload

This sends your source file to Localazy, where translators pick it up. For native i18n, run ng extract-i18n first to regenerate messages.xlf.

Download translated files #️⃣

localazy download

This pulls completed translations back into your project — one file per language, ready for ng build --localize (native i18n) or runtime loading (ngx-translate/Transloco).

Next steps #️⃣

• Translate your strings on the Localazy platform, then run localazy download to pull them back.
• Format docs: XLIFF 1.2, XLIFF 2.0, JSON.
• Add Localazy CLI into your CI/CD pipelines
• If you found an error in the guide, or have problems with the integration, contact us at team@localazy.com.