Transloco’s New Dev Tools Make i18n in Angular Easy as Pie

For the past few months, the Transloco team has worked hard to provide you with a better i18n development experience in Angular. In this article, we’ll explore all the new 😎 stuff Transloco has to offer:

🔑 Keys Manager

Translation is a tiresome and repetitive task. Each time we add new text, we need to create a new entry in the translation file, find the correct placement for it, etc. Moreover, when we delete existing keys, we need to remember to remove them from each translation file.

To make the process less burdensome, we’ve created two tools for the Transloco library, which will do the monotonous work for you. Let’s examine each one:

Installation

Assuming that you’ve already added Transloco to your project, run the following new schematics command:

ng g @ngneat/transloco:keys-manager

At this point, you’ll have to choose whether you want to use the CLI, Webpack Plugin, or both. The project will be updated according to your choice.

The following functionality is available once the installation is complete:

Keys Extractor

As its name suggests, this tool extracts translatable keys from template and typescript files. Transloco Keys Manager provides two ways of using it:

CLI Usage

If you chose the CLI option, you should see the following script in your project’s package.json file:

{
  "i18n:extract": "transloco-keys-manager extract"
}

Run yarn i18n:extract, and it'll extract translatable keys from your project.

Webpack Plugin Usage

The TranslocoExtractKeysWebpackPlugin provides you with the ability to extract the keys during development, while you’re working on the project.

The angular-cli doesn’t support adding a custom Webpack config out of the box. To make it easier for you, when you choose the Webpack Plugin option, it’ll do the work for you.

You should see a new file named webpack-dev.config.js configured with TranslocoExtractKeysWebpackPlugin:

Also you should see an updated definition of the npm start command:

Now run npm start, and it’ll generate new keys whenever a save is made to the project.

Scopes Support

The extractor supports scopes out of the box. When you define a new scope in the providers array:

It’ll extract the scope (admin in our case) keys into the relevant folder:

The extractor also supports dynamic keys, the read input, and static ternary. You can check out the docs for more information.

Keys Detective

This tool detects two things: First, it detects any key that exists in one of your translation files, but is missing in any of the others. Secondly, it detects any key that exists in the translation files, but is missing from any of the templates or typescript files.

When you run the following command, you’ll get a lovely table that summarizes the keys found:

You can set the addMissingKey to true, and it’ll automatically add them for you.

🤔 Comments for Translators

There are times when we need to help the translator by adding a description referencing the meaning of the text to be translated. This information gives the translator added context, which in turn can lead to a more accurate translation.

Let’s take for example the following translation key:

Is this a “book” (noun) or to “book” (verb)? We need to communicate this context to our translators.

For each translation key that requires an additional description, we can add a companion key, postfixed with “.comment”, as shown in the example below:

We don’t want these keys to be part of our production bundle, so we can remove them using the optimize library (see the relevant section) when building the production environment files.

✋🏻 Translation Files Validation

We’ve all been there: We resolve a merge conflict in our translation file, and suddenly the JSON is invalid; Usually because we forgot to add a comma, or we’ve added a duplicate key (the latter case would pass JSON.parse, but is still considered invalid, and an unwanted phenomenon on our part).

To prevent the invalid JSON from reaching our production environment and breaking our application in runtime, we’ve created a micro package, which validates the staged translation files before they’ve been committed.

First, set up husky and lint-staged, and install @ngneat/transloco-validator. Then, update your package.json file to the following:

This will ensure no one accidentally commits an invalid translation file.

💑 Merge Translation Files

When working with scopes (i.e. lazy loading), we split the translation files per feature. In large applications, we might have many scoped translation files, something which can be cumbersome both for us and for translators

To make the process easier and more comfortable, we’ve created two new schematics commands — join and split.

The build command merges all of the project’s translation files into a single one, so we can send one file to the translators. Let’s say our translation folder looks like this:

When we run ng g @ngneat/transloco:join, the script will output a single file:

The split command performs the opposite process to that of the join command. It splits a single translation file into multiple files and places them in the project’s various translation folders. Let’s say we get the translation files back from the translators:

When we run ng g @ngneat/transloco:spilt, It will go over each one of the files, and split the translation object to the corresponding scope.

Check out the documentation for the available options.

🙌 Transloco Optimize

During runtime, Transloco under the hood flattens the translation object. This offers faster value access and lower memory consumption.

We can skip this step in the production environment, by using the optimize plugin, which performs the flattening process AOT.

In addition to that, the optimize plugin minifies each one of the translation files, and removes keys that end with the word comment (e.g. “book.comment”).

To install it, run the following:

npm install @ngneat/transloco-optimize

‌Next, add the following code to your package.json:

Finally, add the following config option to the application’s Transloco config object:

Check out the documentation if you prefer to use it with Gulp (a Webpack plugin is on the way).

🚀 In Case You Missed It

• Akita: One of the leading state management libraries, used in countless production environments. Whether it’s entities arriving from the server or UI state data, Akita has custom-built stores, powerful tools, and tailor-made plugins, which all help to manage the data and negate the need for massive amounts of boilerplate code.
• Spectator: A library that runs as an additional layer on top of the Angular testing framework, that saves you from writing a ton of boilerplate.
• And of course, Transloco: The Internationalization library Angular 😀

Follow me on Medium or Twitter to read more about Angular, Akita and JS!