Angular

Using Angular? Follow these steps to integrate doloc into your workflow.

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:

ng add ng-extract-i18n-merge

Add doloc to your workflow

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

{
  "scripts": {
    // other scripts ...
    "auto-translate-fr": "curl https://api.doloc.io -H \"Authorization: Bearer $API_TOKEN\" --data-binary @src/messages.fr.xlf -o src/messages.fr.xlf",
    "auto-translate-it": "curl 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.

Alternatively, you could integrate this into your CI/CD pipeline, but this adds the complexity of committing the updated translation files back to your repository.

Storing the API token

Your API tokens generally should not be shared publicly.

Having said that, if your repository is private, it is acceptable to store the API token in your repository. The worst-case scenario is that others might use your quota, but never access or change any of your data. Of course, you can always revoke the token and create a new one if needed.

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.