l10n-tools – catalog tools for the tuicom/l10n library

This package is a collection of tools to work with the tuicom/l10n library.

Installation

This package is available via NPM:

npm install --save-dev @tuicom/l10n-tools

Usage

The catalog manager is a CLI tool and has two tasks:

1. It extracts all translatable strings into a .po catalog.
2. It builds translation tables as a lightweight JSON objects.

The catalog manager needs PHP >= 7.1 in your development environment. Why do we use PHP in a JavaScript module? Because of the great Gettext library by Oscar Otero which provides very powerful tools to analyze source code and to manage translations. We weren’t able to find something similar written in JavaScript, so for now we will be using PHP.

The npx l10n tool is the CLI frontend to the catalog manager.

Extracting message strings

First, we need to go through our code and find all translatable strings, i.e. the ones we’ve wrapped in our l10n.t, l10n.n and l10n.x functions.

Luckily, we have a tool for this, but first, we must specify the desired target languages. Simply add the following entry to your project’s package.json file:

{
  "l10n" : {
      "directory" : "l10n",
      "locales" : [
          "de-DE",
          "fr-FR"
      ],
      "extract" : [
        "main.js",
        "other.js",
        "|src/.*|"
      ]
  }
}

The directory key specifies where the translations catalogs will be stored.

The locales key specifies the locales into which your package should be translated. The format for locales is: two lowercase letters for the language, followed by a hyphen (not an underscore!), followed by two uppercase letters for the region/country. NOTE: This tool assumes the en-US locale as default, therefore you don’t need to add it.

The extract key contains a list which specifies the files to be considered for the catalog. Each item in this list can either be a verbatim file name or a regular expression (PCRE).

When you’re done configuring your locales and catalog source files, you can run the extractor. It will find all occurences of our translation functions and add them to one catalog per locale:

npx l10n extract

Assuming you are using the configuration from the above example, the extractor will create or update the catalogs for German and French. Catalogs would be stored in the ./l10n directory. So after running the command for the first time, you will find the new files ./l10n/de-DE.po and ./l10n/fr-FR.po in your project. Don’t forget to put them under version control.

The *.po files can be given to a human translator or be run through a translation tool which supports this format (there are lots of them). After the .po files have been updated, we can create the JSON translation tables.

Creating translations tables

In order to use the translations in your code, you must transform the .po files into JSON, which is done by the tables subcommand.

So, again we start with some configuration. In your package.json file, add a tables key to the l10n entry. The tables key contains an object, where each entry is a target file for the JSON table mapped to a list of source files. Each item in this list can either be a verbatim file name or a regular expression (PCRE). Each JSON file will contain the translations for all languages for all strings in the referenced source files. For example:

{
    "l10n": {
        "tables": {
            "l10n/translations.json": [
                "first.js",
                "second.js",
                "third.js"
            ]
        }
    }
}

Now run the following command to create the l10n/translations.json:

npx l10n tables

After that, you can use the l10n/translations.json in your module, as described in the l10n documentation.

NOTE: In the above example, we have only one JSON target file. But you could have multiple JSON tables per project as well. Why is that? Because you may want to create multiple subsets of translations, e.g. when parts of your application are lazy-loaded.