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

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 update the translations of an app:

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.