@locl/cli

Dev tools to help you with $localize and Angular i18n.

Usage no npm install needed!

<script type="module">
  import loclCli from 'https://cdn.skypack.dev/@locl/cli';
</script>

README

Locl CLI

Dev tools to help you with $localize and Angular i18n.

Installation

Install the cli tools with npm:

npm install @locl/cli --save-dev

Usage

You can get a full list of commands with npx locl --help.

Extraction

You can use locl extract to extract translations from your ivy application:

npx locl extract -s="dist/apps/demo/*.js" -f=json -o="src/assets/i18n/en.json"

The extraction tool will find any call to $localize within your bundle files (in code and in templates), but there is a limitation inherent to the way Angular files are generated by the compiler: you need to build your application with the AOT mode to generate template translations using $localize. Always use --prod or --aot when you build your application. Also make sure to not build for a specific language.

Options:

  • --source (-s): A glob pattern indicating what files to search for translations, e.g. ./dist/**/*.js. This can be absolute or relative to the current working directory.
  • --format (-f): the format of the translation file to generate. Either xlf, xlf2, xmb or json.
  • --outputPath (-o): A path to where the translation file will be written. This can be absolute or relative to the current working directory. If the given path is a file, it will aggregate the translations of all the source files into one translation file. Otherwise it will generate one translation file per file parsed.
  • --locale (-l): The locale for the extracted file, "en" by default.

Conversion

You can use locl convert to convert translations from one format to another:

npx locl convert -s="fr.xlf" -f=json -o="src/assets/i18n/fr.json"

The conversion tool will read all translation files from the source glob and generate a file of the specified format at the specified output path.

Since the source glob can be used to take multiple files as input, it is possible to use this tool to aggregate multiple translation files into one:

npx locl convert -s="src/assets/i18n/*.xlf" -f=json -o="src/assets/i18n/fr.json"

It is recommended to use this tool to convert your files to json if you want to lazy load the translations at bootstrap, since it is the only format that is supported by the existing loaders, and it is the most optimized one in terms of size.

Options:

  • --source (-s): A glob pattern indicating what files to convert, e.g. ./assets/**/*.xlf. This can be absolute or relative to the current working directory. Only translation files are supported (json, xtb & xlf but not xmb).
  • --format (-f): The format of the translation files to generate. Either xlf, xlf2, xtb or json.
  • --outputPath (-o): A path to where the translation file will be written. This can be absolute or relative to the current working directory.