Internationalization & Localization

We fully rely on Angular's @angular/localize package for internationalization. You can follow the standards and instructions described in the Angular Internationalization Guide.

1. Prepare Building Blocks for Translation

You can use Angular's built-in i18n system in your Building Blocks' code and templates like you would in any other Angular component. Please refer to the Angular documentation for details.

2. Translations in Configuration Files

See this part of the TALY documentation for details about this topic.

3. Extract a Source Language File from Your Journey

TALY provides an extract-i18n executor to extract i18n messages from your journey into a so-called source language file. This executor isn't restricted to applications generated by TALY, it is also compatible with manually maintained applications.

It ensures that only relevant messages are included in a generated source language (e.g., messages.xlf) file. Therefore, we recommend using this executor over the default @angular-devkit/build-angular:extract-i18n builder.

A small drawback of the TALY executor is that it won't be able to extract an informative translation context, such as the location, source file, and line number where the text is being used.

3.1. Usage

Similar to other executors, a configuration in the project.json file is required. After that, you can run the executor using the npx nx extract-i18n your-project-name command.

💡 If you generated the journey project with the journey generator, the following configuration should already be set.

Example configuration for the extract-i18n executor:

{
  "my-project": {
    "targets": {
      "extract-i18n": {
        "executor": "@allianz/taly-nx:extract-i18n",
        "options": {
          "buildTarget": "my-project:build-generated-app",
          "outputPath": "apps/my-project"
        }
      }
    }
  }
}

💡 By default, Angular activates optimization options (optimization and buildOptimizer) for production builds. It's important not to manually disable these options to ensure proper functioning of the executor.

Options

3.2. Merge Functionality

The extract-i18n executor supports automatic merging of newly extracted translations with existing translation files using the --merge option.

⚠️ Note: Merge functionality only supports XLF format translation files. Other formats (JSON, ARB, etc.) are not supported for merging.

This feature will:

• Add new texts that need translation
• Keep your existing translations unchanged
• Update texts that have changed
• Remove outdated texts that are no longer used

Basic merge usage:

npx nx extract-i18n my-project --merge

This will automatically merge extracted translations with all configured translation files in your project.json i18n configuration.

Additional merge options:

• --noMatchFuzzy: Prevents fuzzy matching of similar translation units with changed IDs, useful for strict translation workflows
• --destinationFile: Merges only to a specific file instead of all configured translation files

Example with all merge options:

npx nx extract-i18n my-project --merge --no-match-fuzzy --destination-file="path/to/messages.fr.xlf"

4. Translate Each Translation File

While it is possible to do that manually, we advise to use tools for an XLIFF merge/sync (For example XLIFF Sync or similar) & Poedit or Poeditor to do the actual translation.

We recommend following these steps for the initial translation:

1. Generate your app and extract a source language file
2. Create a new target language file with either XLIFF Sync or Poedit
3. Open the translation file (e.g., messages.de.xlf) in Poedit and translate the texts. The "Pre-translate" feature might be used to load previously translated messages that are identical to other journeys

Follow these steps to manually update the translations of an app:

💡 For automatic merging, see the Merge Functionality section which describes the --merge option.

1. Generate your app and extract the updated source language file

2. Open the target translation file and use XLIFF Sync to update it from the source file. Ensure that the autoCheckMissingTranslations and autoCheckNeedWorkTranslations options are turned on. This will:

   1. Add new texts
   2. Tag changed text with "needs-adaptation". This is compatible with Poedit
   3. Remove outdated translations
   4. Existing translations that do not need to be updated will stay unchanged.

3. Open the file in Poedit. Add the new translations. Translations that need to be updated are highlighted

There is a talk from the eMerge conference available that goes into more detail about internationalization.

There's also a video about the XLIFF Sync capabilities available.

5. Merge Translations into the Application

Once the translation files are prepared, you can simply place them inside the config/locales folder under your project's root and re-generate your application. TALY will automatically add i18n configuration to your project.json file reflecting available translations in the config/locales folder.

For this to work your i18n files need to comply with this naming schema: [something].[localeName].[extension] (e.g., messages.de.xlf or messages.en-US.json). This works for all i18n file formats that are supported by Angular like xlf, json, arb, etc.

💡 If you need to strip the baseHref portion matching the locale or sourceLocale to allow a separate deployment use the --strip-locale-base-href option. Read more about baseHref here.

Then, you can follow the Angular guide to set up a build option and deploy your application.