Skip to main content

Angular Translation Files

Introduction​

Translation files form the backbone of internationalization (i18n) in Angular applications. These files contain all the translatable text in your application, organized by language, allowing your app to display content in multiple languages without changing the application code.

In this guide, we'll explore how Angular manages translation files, their structure, and how to work with them effectively to create a truly global application.

Understanding Translation Files in Angular​

Angular's internationalization system relies on standard formats for translation files, primarily using XML Localization Interchange File Format (XLIFF) and other formats like XMB/XTB.

These files:

  • Contain all translatable strings from your templates and TypeScript code
  • Separate content from presentation
  • Allow translators to work without understanding the application code
  • Support various languages without modifying your original source code

Basic Structure of Angular Translation Files​

XLIFF Format​

XLIFF (XML Localization Interchange File Format) is the default and most commonly used format in Angular. Here's a basic example of how an XLIFF file looks:

xml
<?xml version="1.0" encoding="UTF-8" ?>
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
  <file source-language="en" datatype="plaintext" original="ng2.template">
    <body>
      <trans-unit id="welcomeMessage" datatype="html">
        <source>Welcome to our application!</source>
        <target>¡Bienvenido a nuestra aplicación!</target>
        <context-group purpose="location">
          <context context-type="sourcefile">src/app/home/home.component.html</context>
          <context context-type="linenumber">5</context>
        </context-group>
        <note priority="1" from="description">Welcome message on home page</note>
      </trans-unit>
    </body>
  </file>
</xliff>

Key elements:

  • <trans-unit>: Contains a single translatable message
  • <source>: The original text from your application
  • <target>: The translated text
  • <context-group>: Information about where the text appears in your code
  • <note>: Optional description or instructions for translators

Creating Translation Files​

To generate translation files for your Angular application, you'll use the Angular CLI's extract-i18n command:

bash
ng extract-i18n --output-path src/locale

This command:

  1. Scans your application for i18n markers
  2. Creates a source translation file (default: messages.xlf)
  3. Places it in the specified output directory

Marking Text for Translation​

Before extraction, you need to mark text for translation in your templates using the i18n attribute:

html
<h1 i18n="@@homeTitle">Welcome to our website</h1>
<p i18n="Homepage introduction|An introduction header for the homepage@@homeIntro">
  This website demonstrates Angular internationalization features.
</p>

The format for the i18n attribute is:

  • i18n="meaning|description@@id"
  • meaning: helps translators understand context
  • description: explains the text purpose
  • id: unique identifier (prefixed with @@)

Managing Multiple Languages​

For each language you support, you'll need a separate translation file. Let's see how to handle this:

  1. Generate your base translation file:
bash
ng extract-i18n --output-path src/locale
  1. Copy the generated file (e.g., messages.xlf) for each language:
bash
cp src/locale/messages.xlf src/locale/messages.fr.xlf
cp src/locale/messages.xlf src/locale/messages.es.xlf
  1. Edit each file to add translations in the <target> elements.

French Example (messages.fr.xlf)​

xml
<?xml version="1.0" encoding="UTF-8" ?>
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
  <file source-language="en" target-language="fr" datatype="plaintext" original="ng2.template">
    <body>
      <trans-unit id="welcomeMessage" datatype="html">
        <source>Welcome to our application!</source>
        <target>Bienvenue à notre application !</target>
      </trans-unit>
      <trans-unit id="homeIntro" datatype="html">
        <source>This website demonstrates Angular internationalization features.</source>
        <target>Ce site Web démontre les fonctionnalités d'internationalisation d'Angular.</target>
      </trans-unit>
    </body>
  </file>
</xliff>

Building Localized Versions​

To build your application with translations, you need to configure your Angular project in angular.json:

json
{
  "projects": {
    "my-app": {
      "i18n": {
        "sourceLocale": "en-US",
        "locales": {
          "fr": {
            "translation": "src/locale/messages.fr.xlf",
            "baseHref": "/fr/"
          },
          "es": {
            "translation": "src/locale/messages.es.xlf",
            "baseHref": "/es/"
          }
        }
      },
      "architect": {
        "build": {
          "configurations": {
            "fr": {
              "localize": ["fr"]
            },
            "es": {
              "localize": ["es"]
            }
          }
        },
        "serve": {
          "configurations": {
            "fr": {
              "browserTarget": "my-app:build:fr"
            },
            "es": {
              "browserTarget": "my-app:build:es"
            }
          }
        }
      }
    }
  }
}

Now you can build or serve localized versions:

bash
# Build English version
ng build

# Build French version
ng build --configuration=fr

# Serve Spanish version
ng serve --configuration=es

Real-World Example: Building a Multilingual Blog​

Let's implement a practical example of a blog application with internationalization support:

html
<header>
  <h1 i18n="@@appTitle">My Multilingual Blog</h1>
  <nav>
    <a routerLink="/home" i18n="@@navHome">Home</a>
    <a routerLink="/about" i18n="@@navAbout">About</a>
    <a routerLink="/blog" i18n="@@navBlog">Blog</a>
    <a routerLink="/contact" i18n="@@navContact">Contact</a>
  </nav>
  <div class="language-selector">
    <a href="/en-US/">English</a>
    <a href="/fr/">Français</a>
    <a href="/es/">Español</a>
  </div>
</header>

<main>
  <router-outlet></router-outlet>
</main>

<footer>
  <p i18n="@@footerCopyright">© 2023 My Multilingual Blog. All rights reserved.</p>
</footer>

After extracting and translating this content, you'd have multiple XLIFF files like messages.fr.xlf and messages.es.xlf. The application would then display content in the appropriate language based on the URL or user preference.

Best Practices for Managing Translation Files​

  1. Use meaningful IDs: Always include custom IDs (@@id) for your translations to ensure they remain stable when text changes.
html
<!-- Good -->
<h1 i18n="@@headerWelcome">Welcome to our site</h1>

<!-- Not recommended -->
<h1 i18n>Welcome to our site</h1>
  1. Provide context for translators: Add meaning and description to complex phrases.
html
<p i18n="User profile header|Title on the user profile page@@userProfileTitle">User Profile</p>
  1. Handle pluralization: Use ICU (International Components for Unicode) expressions for plurals.
html
<span i18n>
  {itemCount, plural,
    =0 {No items}
    =1 {One item}
    other {{{itemCount}} items}
  }
</span>
  1. Automate the workflow: Set up scripts to extract and manage translation files.
json
// package.json
{
  "scripts": {
    "extract-i18n": "ng extract-i18n --output-path src/locale",
    "start:fr": "ng serve --configuration=fr",
    "build:all": "ng build && ng build --configuration=fr && ng build --configuration=es"
  }
}
  1. Organize large files: For large applications, consider splitting translation files by feature or module.

Working with Translation Services​

Many projects use professional translation services or specialized software. Here's how to integrate such workflows:

  1. Export your XLIFF files for translation
  2. Provide context and screenshots for translators
  3. Import completed translations back into your project
  4. Verify translations in context by running localized builds

Some popular translation management systems compatible with Angular include:

  • Lokalise
  • Crowdin
  • POEditor
  • Phrase

Summary​

Translation files are essential building blocks for creating multilingual Angular applications. By understanding their structure and best practices, you can efficiently manage translations in your projects:

  • Angular primarily uses XLIFF format for translation files
  • Translation files are generated using the ng extract-i18n command
  • Each language requires its own translation file with the source text translated
  • Configuration in angular.json enables building localized versions
  • Good practices include providing context for translators and using stable IDs

With proper management of translation files, your Angular application can seamlessly serve users across different languages and cultures, expanding your potential audience and improving user experience.

Additional Resources​

Exercises​

  1. Create a simple Angular application with a home page and about page, then extract the translation file.
  2. Add support for at least two additional languages to your application.
  3. Implement a language switcher component that changes the displayed language without reloading the page (hint: you'll need to explore runtime translation libraries like ngx-translate).
  4. Create a translation file for a complex form with validation messages in multiple languages.
  5. Set up a continuous integration process that automatically extracts translation files when source code changes.

If you spot any mistakes on this website, please let me know at [email protected]. I’d greatly appreciate your feedback! :)