React Intl / FormatJS

Using React Intl / FormatJS? Follow these steps to integrate doloc into your workflow.

Setup React Intl

If you already have react-intl configured you can skip this step.

Follow the official FormatJS guide to set up React Intl in your React project.

Recommendations for the source files

When creating files for the target languages, please consider the following recommendations:

• The filename should include the language code, e.g. whatever.fr.json for French. (This allows doloc to automatically detect the language of the source and target files.)
• The file format should be the FormatJS default
• New files should be initialized with {} (curl does not transmit the file name for empty files, hence language detections fails in that case.)

Add doloc to your workflow

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

{
  "scripts": {
    // other scripts ...
    "extract": "formatjs extract \"src/**/*.ts*\" --ignore=\"**/*.d.ts\" --out-file src/lang/en.json --id-interpolation-pattern '[sha512:contenthash:base64:6]'",
    "doloc-fr": "curl https://api.doloc.io -H \"Authorization: Bearer $API_TOKEN\" -F source=\"@src/lang/en.json\" -F target=\"@src/lang/fr.json\" -o src/lang/fr.json",
    "doloc-es": "curl https://api.doloc.io -H \"Authorization: Bearer $API_TOKEN\" -F source=\"@src/lang/es.json\" -F target=\"@src/lang/es.json\" -o src/lang/es.json",
    "format-js-compile-en": "formatjs compile src/lang/en.json --ast --out-file src/compiled-lang/en.json",
    "format-js-compile-fr": "formatjs compile src/lang/fr.json --ast --out-file src/compiled-lang/fr.json",
    "format-js-compile-es": "formatjs compile src/lang/es.json --ast --out-file src/compiled-lang/es.json",
    "update-i18n": "npm run extract && npm run doloc-fr && npm run doloc-es && npm run format-js-compile-en && npm run format-js-compile-fr && npm run format-js-compile-es"
  }
}

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, automatically translate and compile them! 🎉

Running the script

This script should be run by the developer after adding or updating translations - and not on the CI/CD pipeline. Using the naming from FormatJS, doloc behaves like a “local translation tool” and not like a “cloud based translation service”. (This highlights doloc’s lightweight and easy to use nature, which is a key differentiator from other translation services. 😉)

Handling explicit IDs

In case you use explicit IDs (i.e. not auto generated by FormatJS), then you need to take extra care when updating existing texts. For every changed text, you need to clear the translations for that key in the target file, so that they are translated again!

Instead of using explicit IDs, FormatJS recommends auto generated IDs, which is an additional setup step, but integrates better.

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 react-intl and doloc work well together and cover most use cases.

For more advanced configurations, you can check the options of FormatJS CLI. doloc can be configured by passing options in the URL - see Options for general information and JSON for specific options.