Table of contents

Automate Angular i18n Translation with XLIFF

Keep Angular localization files in your repository and translate new UI text after extraction. ng-extract-i18n-merge updates the XLIFF files; doloc fills the units selected for translation and returns the updated file in the same request.

Try one Angular XLIFF file first

Already have a target file such as src/messages.fr.xlf? Start free and build a command for your XLIFF file, or create an API token in your doloc account and set the API_TOKEN environment variable.

On macOS or Linux, send a target file containing at least one untranslated unit:

bash
curl --fail-with-body --silent --show-error --compressed \
  https://api.doloc.io \
  -H "Authorization: Bearer $API_TOKEN" \
  --data-binary @src/messages.fr.xlf \
  -o messages.fr.translated.xlf

The original file stays unchanged. Check that the command succeeds before opening messages.fr.translated.xlf; an HTTP error can leave an error message in that output file. For PowerShell, use the command builder.

The target language comes from the XLIFF file. Existing translations outside the selected untranslated states are retained. See the XLIFF 1.2 and XLIFF 2.0 references for state selection and inline placeholders.

After a successful test, use the workflow below to translate when source copy changes. The free plan includes 200 source texts per month; see pricing for how source texts are counted.

Setup Angular Localization

If you already have i18n configured you can skip this step.

Follow the official Angular guide to set up i18n in your Angular project.

Make sure to use the “XLIFF 1.2” or “XLIFF 2” format for your translation files (JSON is supported as well, but XLIFF has better support from Angular CLI).

Setup ng-extract-i18n-merge to manage translations

If you already use ng-extract-i18n-merge you can skip this step.

The ng-extract-i18n-merge tool allows you to extract and merge translations from your Angular project. Essentially, this keeps your translation files in sync with your source code, to make sure added, updated, or removed translations are reflected in your translation files. Technically, it is drop-in replacement for the ng extract-i18n command (which wraps the original ng extract-i18n).

To install ng-extract-i18n-merge, run:

bash
ng add ng-extract-i18n-merge

Add doloc to your workflow

For convenience, you can add doloc to your package.json scripts:

json
{
  "scripts": {
    // other scripts ...
    "auto-translate-fr": "curl --fail-with-body --silent --show-error --compressed https://api.doloc.io -H \"Authorization: Bearer $API_TOKEN\" --data-binary @src/messages.fr.xlf -o src/messages.fr.xlf",
    "auto-translate-it": "curl --fail-with-body --silent --show-error --compressed https://api.doloc.io -H \"Authorization: Bearer $API_TOKEN\" --data-binary @src/messages.it.xlf -o src/messages.it.xlf",
    "update-i18n": "ng extract-i18n && npm run auto-translate-fr && npm run auto-translate-it"
  }
}

Make sure to update the translation file paths and to replace $API_TOKEN with your API token or set a corresponding environment variable. The API token can be found or created in your doloc account.

With this setup, you can run npm run update-i18n to extract new translations and automatically translate them. 🎉

Running the script

Regularly, this script is run by the developer after adding or updating translations - this way, the translations are always up-to-date.

For details, please check out When to Run doloc?.

Storing the API token

Set API_TOKEN in your local environment or CI secret store. Keep the token out of committed scripts. You can revoke it and create a replacement in your doloc account.

Configuration

The default configurations of ng-extract-i18n-merge and doloc work well together and cover most use cases.

For more advanced configurations, you can configure ng-extract-i18n-merge in the angular.json file - see ng-extract-i18n-merge/README.md. doloc can be configured by passing options in the URL - see Options for general information and XLIFF 1.2/XLIFF 2.0 for specific options.

On HTTP errors, --fail-with-body exits non-zero, but because -o points at the target file, doloc’s error body may overwrite that file. Inspect it, revert the file from Git, fix the issue, and retry. See Curl Command Details for protected-output and CI variants.