{"id":6296,"date":"2025-04-28T06:07:00","date_gmt":"2025-04-28T06:07:00","guid":{"rendered":"https:\/\/poeditor.com\/blog\/?p=6296"},"modified":"2026-04-20T12:51:17","modified_gmt":"2026-04-20T12:51:17","slug":"angular-internationalization-localization","status":"publish","type":"post","link":"https:\/\/poeditor.com\/blog\/angular-internationalization-localization\/","title":{"rendered":"Angular internationalization and localization: A complete guide"},"content":{"rendered":"\n
\"angular<\/figure>\n\n\n\n

Angular is a frontend JavaScript framework built for creating large, maintainable web applications. But out of the box, you\u2019re only able to display content in one language \u2014 whatever text you hardcode into your templates.<\/p>\n\n\n\n

If you’re building something for a global audience, or just want your app to support multiple languages, you’ll need to set up localization and internationalization<\/a>.<\/p>\n\n\n\n

You may ask: what do those even mean?<\/p>\n\n\n\n

In plain terms, internationalization is the process of preparing your app to support different languages and regional settings. Localization, on the other hand, is the actual implementation \u2014 translating your content and formatting things like dates, numbers, and currencies to match the user\u2019s language.<\/p>\n\n\n\n

In this guide, we\u2019ll walk through Angular internationalization and localization step by step. You\u2019ll learn how to mark text for translation in your Angular app, handle pluralization and dynamic values, generate translation files, and build separate language versions of the app.<\/p>\n\n\n\n

Getting started<\/h2>\n\n\n\n

Before we do anything fancy, it\u2019s assumed you already have an Angular application you want to work with \u2014 or at least some basic understanding of how Angular works. So we\u2019ll skip things like setting up components or modules.<\/p>\n\n\n\n

But just in case you don\u2019t have a project yet, here\u2019s how to spin one up:<\/p>\n\n\n\n

# install Angular CLI\nnpm install -g @angular\/cli\n\n# create a new Angular project\nng new angular-i18n-demo\n\n# navigate into the folder and serve the project\ncd angular-i18n-demo && ng serve\n<\/code><\/pre>\n\n\n\n
Once that’s running, open src\/app\/app.component.html<\/code> and replace everything with this:<\/p>\n\n\n\n
<div class=\"container\">\n  <h1>Welcome to MyApp<\/h1>\n  <p>This is a simple localized Angular app.<\/p>\n\n  <h2>Ongoing Tasks<\/h2>\n  <p>You have {{ tasksCount }} tasks.<\/p>\n<\/div><\/code><\/pre>\n\n\n\n
Then in src\/app\/app.component.ts<\/code>, add the tasksCount<\/code> variable:<\/p>\n\n\n\n
export class AppComponent {\n  tasksCount = 3;\n}<\/code><\/pre>\n\n\n\n
You now have a basic UI with some text we\u2019ll localize in the next steps.<\/p>\n\n\n\n
Installing the localization package<\/h2>\n\n\n\n
Angular doesn\u2019t include localization support by default \u2014 you have to add it yourself. Fortunately, the Angular team provides an official package<\/a>.<\/p>\n\n\n\n
To install it, run:<\/p>\n\n\n\n
ng add @angular\/localize<\/code><\/pre>\n\n\n\n
This installs the package and adds the required import<\/a> to your polyfills file, so Angular knows to use the localization system during builds.<\/p>\n\n\n\n
That\u2019s it. You don\u2019t have to import anything manually or write any special code to use it.<\/p>\n\n\n\n
Marking text for translation<\/h2>\n\n\n\n
Now that localization is set up, the next step is to mark the text in your templates that you want Angular to translate.<\/p>\n\n\n\n
Angular doesn\u2019t automatically translate anything. You have to tell it: \u201cThis string should be translated.\u201d You do that using the i18n<\/code> attribute.<\/p>\n\n\n\n
Here\u2019s an example:<\/p>\n\n\n\n
<h1 i18n>Welcome to MyApp<\/h1><\/code><\/pre>\n\n\n\n
That i18n<\/code> attribute won\u2019t show up in the rendered page, but when you extract translations, Angular will include that line in the output file. If you go ahead to extract translation stirring this way, Angular will generate some hash-looking values as the custom ID to serve as a unique identifier:<\/p>\n\n\n\n
<trans-unit id=\"6273847362193874621\" datatype=\"html\">\n  <source>Welcome to MyApp<\/source>\n<\/trans-unit><\/code><\/pre>\n\n\n\n
That\u2019s fine for simple apps, but not great when working with external translation tools like POEditor<\/a> \u2014 because those tools rely on stable IDs to track changes, reuse strings, and sync across teams.<\/p>\n\n\n\n
You can avoid that by assigning your own stable ID using the @@<\/code> syntax:<\/p>\n\n\n\n
<h1 i18n=\"@@pageTitle\">Welcome to MyApp<\/h1><\/code><\/pre>\n\n\n\n
This gives you predictable output:<\/p>\n\n\n\n
<trans-unit id=\"pageTitle\" datatype=\"html\">\n  <source>Welcome to MyApp<\/source>\n<\/trans-unit><\/code><\/pre>\n\n\n\n
You can also add a description to help translators understand what a string means \u2014 especially when the text is generic (like \u201cStart\u201d or \u201cSubmit\u201d).<\/p>\n\n\n\n
<p i18n=\"Intro text shown under the heading\">\n  This is a simple localized Angular app.\n<\/p><\/code><\/pre>\n\n\n\n
Angular still generates the ID automatically in this case, but the note gets added. You can combine both a custom ID and a description this way:<\/p>\n\n\n\n
<p i18n=\"Intro message shown under the heading@@introText\">\n  This is a simple localized Angular app.\n<\/p><\/code><\/pre>\n\n\n\n
Now you get both:<\/p>\n\n\n\n
<trans-unit id=\"introText\" datatype=\"html\">\n  <source>This is a simple localized Angular app.<\/source>\n  <note priority=\"1\" from=\"description\">Intro message shown under the heading<\/note>\n<\/trans-unit><\/code><\/pre>\n\n\n\n
Extracting translation strings<\/h2>\n\n\n\n
Once you’ve marked your text with the i18n<\/code> attribute, the next step is to extract those strings into a translation file that Angular or a translator can work with.<\/p>\n\n\n\n
By default, when you run:<\/p>\n\n\n\n
ng extract-i18n<\/code><\/pre>\n\n\n\n
Angular creates a file called messages.xlf<\/code> in the root of your project. But you’re not locked into .xlf<\/code> if that doesn’t work for your team or translation workflow. You can specify a different format, filename, and output path using flags.<\/p>\n\n\n\n
Here are the main options:<\/p>\n\n\n\n
Option<\/th>What it does<\/th><\/tr><\/thead>
--format<\/code><\/td>Sets the file format. Angular supports xlf<\/code>, xlf2<\/code>, xmb<\/code>, json<\/code><\/td><\/tr>
--out-file<\/code><\/td>Changes the name of the file<\/td><\/tr>
--output-path<\/code><\/td>Sets the folder where the file is saved<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
For example, you can extract as JSON to a custom folder:<\/p>\n\n\n\n
ng extract-i18n --format json --out-file strings.en.json --output-path src\/i18n<\/code><\/pre>\n\n\n\n
This will generate:<\/p>\n\n\n\n
src\/i18n\/strings.en.json<\/code><\/pre>\n\n\n\n
The content of the file will still depend on what you’ve marked with i18n<\/code> in your templates, but the structure will be JSON instead of XML.<\/p>\n\n\n\n
But for this guide, we\u2019ll stick to using the default format and store translations in the src\/locale<\/code> folder using this command:<\/p>\n\n\n\n
ng extract-i18n --output-path src\/locale<\/code><\/pre>\n\n\n\n
This will create a file called messages.xlf inside the src\/locale folder.<\/p>\n\n\n\n
What the .xlf file looks like<\/h3>\n\n\n\n
Here\u2019s a simplified example of what you’ll see:<\/p>\n\n\n\n
<?xml version=\"1.0\" encoding=\"UTF-8\" ?>\n<xliff version=\"1.2\">\n  <file source-language=\"en-US\" datatype=\"plaintext\" original=\"ng2.template\">\n    <body>\n      <trans-unit id=\"introText\" datatype=\"html\">\n        <source>This is a simple localized Angular app.<\/source>\n        <note priority=\"1\" from=\"description\">Intro message shown under the heading<\/note>\n      <\/trans-unit>\n    <\/body>\n  <\/file>\n<\/xliff>\n<\/code><\/pre>\n\n\n\n
Let\u2019s break that down:<\/p>\n\n\n\n