Angular Localization: A Complete Guide to Implementation and Internationalization

Companies today serve content to global audiences across web, mobile, and other digital platforms. To deliver a consistent user experience, applications must adapt not just to different devices but also to languages, regions, and cultural conventions. Localization enables this. 

The good news for Angular developers is that the framework provides excellent support for localization through its @angular/localize package. It handles everything from static text translation to date, number, and currency formatting. 

In this piece, we’ll break down what localization in Angular is, how it works under the hood, and how to implement it.

Table of contents

What is localization in Angular?

Localization is the process of customizing an application’s content and UI to suit a specific language or region. Angular provides built-in tools to implement localization and internationalization. Most of the Angular localization functionality is encapsulated within the localize package. 

But before we go over how to use this package for Angular localization, let’s cover some fundamentals.

Angular internationalization vs. localization

A lot of developers often use the terms internationalization and localization interchangeably, but they are not the same thing.

Angular Internationalization (i18n) is about preparing your app to support multiple languages and regions. It lays the groundwork for localization.

Localization is the process of actually translating and building the app for a specific locale.

In Angular, the typical steps needed for internationalization are:

• Adding the @angular/localize package

• Tagging strings with the $localize function

• Adapting dates, numbers, and currencies to different locales

• Organizing your templates and layout in a way that can handle RTL (right-to-left) languages if needed

Once your app is internationalized, Angular localization is where you take that foundation and produce actual builds for each locale. In this stage, you:

• Extract translatable messages using Angular CLI (extract-i18n)

• Create or import translation files (usually in XLIFF format)

• Build the app for each target locale with the proper translation file

• Optionally adjust routes, assets, or branding per region

So, think of internationalization as making your app “locale-ready,” and localization as producing “locale-specific” versions of that app. Angular allows you to implement both, without needing to install a third-party library.

Why is Angular localization important?

Here are some reasons why Angular localization is so important:

• Sets the right structure early: When you introduce internationalization early on, your app’s structure is set up to easily accommodate multiple locales later, without needing any major refactoring.

• Improves user experience: People are more likely to stay, engage, and convert when content feels native to them: right language, right format, right layout.

• Increases conversion rates: For e-commerce and SaaS apps, localized content can directly affect signups, purchases, and other key metrics.

• Acts as a unique selling point: Properly localized content shows that your product is built with your audience in mind, which builds trust and can set you apart from competitors.

• Enables better SEO in global markets: Through Angular localization, you can build localized routes and content that help with region-specific search rankings.

How to implement localization in Angular

Here’s a step-by-step breakdown of how to implement localization in Angular:

1. Add the @angular/localize package

Run this command to set up localization support:

ng add @angular/localize

This adds the package and sets up everything you need to localize.

2. Refer to locales by ID

Next, configure the source and target locales in your angular.json. This tells Angular what your base language is and where to find translations for other languages.

For example:

"projects": {

  "your-app-name": {

    ...

    "i18n": {

      "sourceLocale": "en-US",

      "locales": {

        "fr": "src/locale/messages.fr.xlf",

        "es": "src/locale/messages.es.xlf"

      }

    }

  }

}

The keys like fr and es refer to locale IDs (e.g., fr-FR, en-CA, es-MX), and the values point to the corresponding translation files.

3. Format data based on locale

Angular's pipes auto-format values based on locale settings. You can explicitly pass a locale if needed. For example:

    <p>B: {{ b | currency: 'CAD' : 'symbol-narrow' : '4.2-2' }}</p>

This pipe formats the b variable as Canadian dollars, using the narrow $ symbol. It shows at least four digits before the decimal and exactly two digits after.

4. Prepare components for translations

Angular supports localization in both templates and TypeScript files.

In templates:

For static text, it would look like:

<h1 i18n="@@welcomeHeader">Welcome to our app!</h1>

Here’s what’s happening:

• i18n tells Angular this text should be extracted for translation.

• @@welcomeHeader is a custom ID for this string, making it easier to reference in translation files.

In component code:

Use the $localize tagged string to mark content for translation:

$localize `my string to localize`

You can also provide extra metadata to give translators more context. The format looks like this:

$localize`:meaning|description@@id:source message text`;

5. Work with translation files

After tagging all strings, extract them with the CLI:

ng extract-i18n

This generates a messages.xlf file containing all translatable content. 

Next, to create translation files for each locale, follow these steps:

1. Duplicate the generated messages.xlf file for each target language you plan to support.

2. Rename each translation file to include the locale. For example:

messages.xlf → messages.fr.xlf

messages.xlf → messages.es.xlf

3. Place your translation files inside a new directory named locale at the project root.

4. Copy each renamed .xlf file into the src/locale directory.

5. Provide the .xlf files to a translator or localization service. They’ll update the <target> elements inside each file with the correct translated strings.

6. Merge translations into the app

Once your translation files are ready, use the Angular CLI to build localized versions of your app. Each localized version is a complete set of distributable files with all i18n messages replaced with the correct translations.

Run the following command:

ng build --localize

This tells Angular to:

• Read the translation files linked to each locale in your angular.json

• Replace all tagged strings (i18n, i18n-*, $localize) with their translated versions

• Output a separate, fully translated build for each locale

7. Deploy multiple locales

When Angular builds localized versions of your app using --localize, each language variant is placed in its own subdirectory. For example: myapp/fr for French or myapp/es for Spanish.

The CLI automatically updates the <base href> for each build based on the locale and its subPath value from angular.json. For example:

"i18n": {

  "sourceLocale": "en-US",

  "locales": {

    "fr": {

      "translation": "src/locale/messages.fr.xlf",

      "subPath": ""

    }

  }

}

To serve these builds, configure your server (e.g., Nginx or Apache) to redirect users to the correct locale based on the Accept-Language HTTP header. If no preference is found, the server uses the default language. 

Note: If you use Angular with server-side rendering (outputMode: 'server'), Angular handles the redirection for you automatically using the Accept-Language header. In this case, you don’t need to do any manual server configurations.

Angular localization tutorial: Best practices

Next up in this Angular localization tutorial, let’s go over some best practices to ensure a smooth and maintainable implementation:

• Keep the source language content clear and consistent to make translations easier and more accurate.

• Use custom IDs (@@id) for important strings so that translations stay stable even if the source text changes.

• Group related translation strings by feature or module to stay organized.

• Avoid hardcoding dynamic values into strings. Instead, use placeholders and name them clearly.

• Don’t concatenate strings; instead, use full template literals with placeholders.

• Use descriptive meaning and description metadata to give translators context.

• Regularly extract messages and update translation files as your app evolves.

• Consider using tools or services to manage translation workflows if your app supports many languages.

• Test each locale build thoroughly to catch issues with layout, RTL support, or missing translations.

• Avoid inline styles that conflict with locale-specific formatting or layout direction.
  
  

Common challenges and solutions in Angular localization

We’ll finish off with some common challenges you may face while implementing Angular localization, along with advice on how to solve them. 

1. Missing or untranslated strings

Sometimes, even after tagging and translating, certain texts show up untranslated in the app.

Solutions:

• Make sure all strings are properly tagged with i18n or $localize

• Re-run ng extract-i18n to catch any newly added text

• Double-check that the translation file has the correct <target> for each message

2. Placeholder issues in translated strings

Dynamic values don’t render correctly or break the message structure in some translations.

Solutions:

• Use named placeholders in $localize expressions

• Ensure translators don’t remove or alter the placeholder syntax

• Test translated output with real data to catch issues early

3. Managing multiple translation files

If you have too many .xlf files across versions or teams, managing them all can get messy.

Solutions:

• Use a consistent file naming and folder structure (e.g., src/locale/messages.{locale}.xlf)

• Keep translations in version control with the codebase

• Use translation management tools for large teams or many languages

4. Route handling per locale

You need to serve different versions of the app based on language, but routing isn’t working as expected.

Solutions:

• Use subdirectory-based routing (e.g., /fr/, /es/) with proper server config

• Adjust baseHref per locale using Angular’s subPath config

• If using SSR, it’s best to use Angular’s built-in Accept-Language support for automatic redirection

Conclusion

When managing multilingual enterprise apps, it’s crucial to have a solid project structure and configuration that supports ongoing localization efforts. Angular, with its built-in i18n tools and CLI support, makes our job as developers much more manageable. We hope this guide gave you a clear roadmap on how to implement localization in Angular.

Sign up to receive articles and tutorials on Angular and ButterCMS.