DEV Community

Pantelis Theodosiou
Pantelis Theodosiou

Posted on • Updated on

Internationalization ( i18n ) with Angular

#angular #internationalization #i18n

Internationalization is the process of designing and preparing your app to be usable in different languages. Localization is the process of translating your internationalized app into specific languages for particular locales.

Therefore, just as you’d ensure that your design is aesthetically-pleasing and accessible, you should also ensure that your text is localized. This is the process of ensuring that your applications support multiple languages. In Angular, this is done in multiple ways.

For example, you can use third-party libraries, such us ngx-translate or you can just use the built-in i18n functionality.

Why is Internationalization so important?

These days, with so many websites to choose from, making applications available and user-friendly to a worldwide audience is important. It's the move to make a better user experience.

In this article, we will be focused on using the built-in i18n tool. So let's get started.

New Angular Project 

# Install Angular CLI globally
npm install --global @angular/cli

# Create Angular project
ng new ng-internationalization

# Would you like to add Angular routing? N
# Which stylesheet format would you like to use? SCSS
# Go to project's directory
cd ng-internationalization

# Open this folder with your favourite editor
code . 

# Serve the application
ng serve -o
Enter fullscreen mode Exit fullscreen mode

Translations

Angular's default locale is set to en-US. To support more languages, we need to update the default configuration and add additional locales. You can find a list of various locale codes here.

Project Templates

To be able to set the translations up, we need to add some basic content on our application. Head over to app.component.html and add some content.

<main>
  <section>
    <h1>Why is Internationalization so important?</h1>
    <p>
      These days, with so many websites to choose from, making applications
      available and user-friendly to a worldwide audience is important. It's the
      move to make a better user experience.
      <small
        >Find the full article
        <a
          href="https://github.com/ThPadelis/ng-internationalization"
          target="_blank"
          >here</a
        ></small
      >
    </p>
  </section>
</main>
Enter fullscreen mode Exit fullscreen mode

We can add some styles to make this site a bit more user-friendly, inside of app.component.scss

@import url("https://fonts.googleapis.com/css?family=Roboto&display=swap&subset=greek");

main {
  display: flex;
  justify-content: center;
  align-items: center;
  height: 100vh;
  background: #6441a5;
  background: -webkit-linear-gradient(to right, #6441a5, #2a0845);
  background: linear-gradient(to right, #6441a5, #2a0845);

  section {
    font-family: "Roboto", sans-serif;
    text-align: center;
    color: #cec6d4;
    border: solid thin #cec6d4;
    padding: 40px;
    width: 50%;
    -webkit-box-shadow: 15px 15px 5px 0px rgba(0, 0, 0, 0.75);
    -moz-box-shadow: 15px 15px 5px 0px rgba(0, 0, 0, 0.75);
    box-shadow: 15px 15px 5px 0px rgba(0, 0, 0, 0.75);

    a {
      color: inherit;
    }

    small {
      display: block;
      margin-top: 10px;
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

And finally, inside of styles.scss let's set the body styles

body {
  margin: 0px;
  padding: 0px;
  box-sizing: border-box;
}
Enter fullscreen mode Exit fullscreen mode

This is what we should have by this time

Screenshot_1

Text marking

To be able to translate the context in the application, we first need to mark the text with a custom attribute named i18n. After the text marking, we will be able to translate the application into our desire languages. In our case el-GR and fr-FR. I will be using Google Translate to translate the text into French.

Let's add the i18n attribute to all of the text that we want to translate

<main>
  <section>
    <h1 i18n>Why is Internationalization so important?</h1>
    <p i18n>
      These days, with so many websites to choose from, making applications
      available and user-friendly to a worldwide audience is important. It's the
      move to make a better user experience.
    </p>
    <small i18n
      >Find the full article
      <a
        href="https://dev.to/thpadelis/internationalization-i18n-with-angular-4ao7"
        target="_blank"
        >here</a
      ></small
    >
  </section>
</main>
Enter fullscreen mode Exit fullscreen mode

i18n is a custom attribute, recognized by Angular tools and compilers. After translation, the compiler removes it. It is not an Angular directive.

Now, we need a script that uses Angular CLI to extract this into a messages.xlf file. This file contains all of our marked items. Head over to packages.json and add this script

"scripts": {
    "i18n:extract": "ng xi18n --output-path src/locales"
}
Enter fullscreen mode Exit fullscreen mode

After adding this script, go ahead and run npm run i18n:extract. Then, open up scr/locales/messages.xlf and you will see something like this

<?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="4bcef995bebcf205074f9fd756b822a488b452cc" datatype="html">
        <source>Why is Internationalization so important?</source>
        <context-group purpose="location">
          <context context-type="sourcefile">src/app/app.component.html</context>
          <context context-type="linenumber">3</context>
        </context-group>
      </trans-unit>
      <trans-unit id="e8db4c58a5fc95a2a8d80183e4b527f4480fa06e" datatype="html">
        <source>
      These days, with so many websites to choose from, making applications
      available and user-friendly to a worldwide audience is important. It&apos;s the
      move to make a better user experience.
    </source>
        <context-group purpose="location">
          <context context-type="sourcefile">src/app/app.component.html</context>
          <context context-type="linenumber">4</context>
        </context-group>
      </trans-unit>
      <trans-unit id="0f16c7aaa76d2f52dbabcd329ebf11a39a26918d" datatype="html">
        <source>Find the full article
      <x id="START_LINK" ctype="x-a" equiv-text="&lt;a&gt;"/>here<x id="CLOSE_LINK" ctype="x-a" equiv-text="&lt;/a&gt;"/></source>
        <context-group purpose="location">
          <context context-type="sourcefile">src/app/app.component.html</context>
          <context context-type="linenumber">10</context>
        </context-group>
      </trans-unit>
    </body>
  </file>
</xliff>
Enter fullscreen mode Exit fullscreen mode

For each html element marked with the i18n directive, a trans-unit will be created.

<trans-unit id="4bcef995bebcf205074f9fd756b822a488b452cc" datatype="html">
    <source>Why is Internationalization so important?</source>
    <context-group purpose="location">
        <context context-type="sourcefile">src/app/app.component.html</context>
        <context context-type="linenumber">3</context>
    </context-group>
</trans-unit>
Enter fullscreen mode Exit fullscreen mode

We can provide more information about the translations using this structure by adding a description. Inside of app.component.hmtl, update the i18n items with a description.

<main>
  <section>
    <h1 i18n="Title for the article">
      Why is Internationalization so important?
    </h1>
    <p i18n="Description for the article">
      These days, with so many websites to choose from, making applications
      available and user-friendly to a worldwide audience is important. It's the
      move to make a better user experience.
    </p>
    <small i18n="Read the whole article"
      >Find the full article
      <a
        href="https://github.com/ThPadelis/ng-internationalization"
        target="_blank"
        >here</a
      ></small
    >
  </section>
</main>
Enter fullscreen mode Exit fullscreen mode

Additionally, we can help the translator with a description and a meaning by using this format

<!-- i18n="<meaning>|<description>" -->
<main>
  <section>
    <h1 i18n="Article Heading|Title for the article">
      Why is Internationalization so important?
    </h1>
    <p i18n="Article Description|Description for the article">
      These days, with so many websites to choose from, making applications
      available and user-friendly to a worldwide audience is important. It's the
      move to make a better user experience.
    </p>
    <small i18n="Full Article|Read the whole article"
      >Find the full article
      <a
        href="https://github.com/ThPadelis/ng-internationalization"
        target="_blank"
        >here</a
      ></small
    >
  </section>
</main>
Enter fullscreen mode Exit fullscreen mode

We can also se a custom id for persistence and maintenance

<!-- i18n="<meanin>|<description>@@customId" -->
<h1 i18n="Article Heading|Title for the article@@articleHeading">
    Why is Internationalization so important?
</h1>
Enter fullscreen mode Exit fullscreen mode

We can finally generate our translations

npm run i18n:extract
Enter fullscreen mode Exit fullscreen mode

Now that we have added meaning, description and id our messages.xml should look like this

<?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="articleHeading" datatype="html">
        <source>
      Why is Internationalization so important?
    </source>
        <context-group purpose="location">
          <context context-type="sourcefile">src/app/app.component.html</context>
          <context context-type="linenumber">3</context>
        </context-group>
        <note priority="1" from="description">Title for the article</note>
        <note priority="1" from="meaning">Article Heading</note>
      </trans-unit>
      <trans-unit id="articleDescription" datatype="html">
        <source>
      These days, with so many websites to choose from, making applications
      available and user-friendly to a worldwide audience is important. It&apos;s the
      move to make a better user experience.
    </source>
        <context-group purpose="location">
          <context context-type="sourcefile">src/app/app.component.html</context>
          <context context-type="linenumber">8</context>
        </context-group>
        <note priority="1" from="description">Description for the article</note>
        <note priority="1" from="meaning">Article Description</note>
      </trans-unit>
      <trans-unit id="fullArticle" datatype="html">
        <source>Find the full article
      <x id="START_LINK" ctype="x-a" equiv-text="&lt;a&gt;"/>here<x id="CLOSE_LINK" ctype="x-a" equiv-text="&lt;/a&gt;"/></source>
        <context-group purpose="location">
          <context context-type="sourcefile">src/app/app.component.html</context>
          <context context-type="linenumber">14</context>
        </context-group>
        <note priority="1" from="description">Read the whole article</note>
        <note priority="1" from="meaning">Full Article</note>
      </trans-unit>
    </body>
  </file>
</xliff>
Enter fullscreen mode Exit fullscreen mode

Translations

At this point, we have a messages.xlf file that contains all of the items that we want to translate. Let's create a copy messages.xlf for each language we want to translate the application.

cp src\locales\messages.xlf src\locales\messages.fr.xlf
cp src\locales\messages.xlf src\locales\messages.el.xlf
Enter fullscreen mode Exit fullscreen mode

Greek

Let's start with messages.el.xlf. We will translate the messages by using the target and source. The target attribute is the the translation in that language.

<?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="articleHeading" datatype="html">
        <source>Why is Internationalization so important?</source>
        <target>Γιατί είναι τόσο σημαντική η διεθνοποίηση;</target>
        <context-group purpose="location">
          <context context-type="sourcefile">src/app/app.component.html</context>
          <context context-type="linenumber">3</context>
        </context-group>
        <note priority="1" from="description">Title for the article</note>
        <note priority="1" from="meaning">Article Heading</note>
      </trans-unit>

      <trans-unit id="articleDescription" datatype="html">
        <source>These days, with so many websites to choose from, making applications available and user-friendly to a worldwide audience is important. It&apos;s the move to make a better user experience.</source>
        <target>Αυτές τις μέρες, ανάμεσα σε τόσους ιστότοπους για να διαλέξεις, κάνοντας εφαρμογές διαθέσιμες και φιλικές προς τον χρήστη είναι σημαντικό. Είναι μία κίνηση για καλύτερη εμπειρία χρήστη.</target>
        <context-group purpose="location">
          <context context-type="sourcefile">src/app/app.component.html</context>
          <context context-type="linenumber">8</context>
        </context-group>
        <note priority="1" from="description">Description for the article</note>
        <note priority="1" from="meaning">Article Description</note>
      </trans-unit>

      <trans-unit id="fullArticle" datatype="html">
        <source>Find the full article <x id="START_LINK" ctype="x-a" equiv-text="&lt;a&gt;"/>here<x id="CLOSE_LINK" ctype="x-a" equiv-text="&lt;/a&gt;"/></source>
        <target>Βρείτε ολόκληρο το άρθρο <x id="START_LINK" ctype="x-a" equiv-text="&lt;a&gt;"/>εδώ<x id="CLOSE_LINK" ctype="x-a" equiv-text="&lt;/a&gt;"/></target>
        <context-group purpose="location">
          <context context-type="sourcefile">src/app/app.component.html</context>
          <context context-type="linenumber">14</context>
        </context-group>
        <note priority="1" from="description">Read the whole article</note>
        <note priority="1" from="meaning">Full Article</note>
      </trans-unit>
    </body>
  </file>
</xliff>
Enter fullscreen mode Exit fullscreen mode

French

Now, let's do the same for messages.fr.xlf in French

<?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="articleHeading" datatype="html">
        <source>Why is Internationalization so important?</source>
        <target>Pourquoi l'internationalisation est-elle si importante?</target>
        <context-group purpose="location">
          <context context-type="sourcefile">src/app/app.component.html</context>
          <context context-type="linenumber">3</context>
        </context-group>
        <note priority="1" from="description">Title for the article</note>
        <note priority="1" from="meaning">Article Heading</note>
      </trans-unit>

      <trans-unit id="articleDescription" datatype="html">
        <source>These days, with so many websites to choose from, making applications available and user-friendly to a worldwide audience is important. It&apos;s the move to make a better user experience.</source>
        <target>Ces jours-ci, avec autant de sites Web à choisir, il est important de rendre les applications disponibles et conviviales pour un public mondial. C'est le geste d'améliorer l'expérience utilisateur.</target>
        <context-group purpose="location">
          <context context-type="sourcefile">src/app/app.component.html</context>
          <context context-type="linenumber">8</context>
        </context-group>
        <note priority="1" from="description">Description for the article</note>
        <note priority="1" from="meaning">Article Description</note>
      </trans-unit>

      <trans-unit id="fullArticle" datatype="html">
        <source>Find the full article <x id="START_LINK" ctype="x-a" equiv-text="&lt;a&gt;"/>here<x id="CLOSE_LINK" ctype="x-a" equiv-text="&lt;/a&gt;"/></source>
        <target>Retrouvez l'article complet <x id="START_LINK" ctype="x-a" equiv-text="&lt;a&gt;"/>ici<x id="CLOSE_LINK" ctype="x-a" equiv-text="&lt;/a&gt;"/></target>
        <context-group purpose="location">
          <context context-type="sourcefile">src/app/app.component.html</context>
          <context context-type="linenumber">14</context>
        </context-group>
        <note priority="1" from="description">Read the whole article</note>
        <note priority="1" from="meaning">Full Article</note>
      </trans-unit>
    </body>
  </file>
</xliff>
Enter fullscreen mode Exit fullscreen mode

NOTE: These are not correct translations for French. Be kind to me.

Locale build configuration

Perfect! Now, we have three versions of our application.

A good practice is to have a script that builds the application for each locale we want to support.

Head over to angular.json and add the below configurations.

{
  "projects": {
    "ng-internationalization": {
      "architect": {
        "build": {
          "configurations": {
            "fr-FR": {
              "aot": true,
              "outputPath": "dist/fr-FR",
              "i18nFile": "src/locales/messages.fr.xlf",
              "i18nFormat": "xlf",
              "i18nLocale": "fr",
              "i18nMissingTranslation": "error"
            },
            "el-GR": {
              "aot": true,
              "outputPath": "dist/el-GR",
              "i18nFile": "src/locales/messages.el.xlf",
              "i18nFormat": "xlf",
              "i18nLocale": "el-GR",
              "i18nMissingTranslation": "error"
            }
          }
        },
        "serve": {
          "configurations": {
            "production": {
              "browserTarget": "ng-internationalization:build:production"
            },
            "fr-FR": {
              "browserTarget": "ng-internationalization:build:fr-FR"
            },
            "el-GR": {
              "browserTarget": "ng-internationalization:build:el-GR"
            }
          }
        }
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

NOTE: I've omitted most of the file to keep it brief.

Let's create some more scripts inside the package.json file to be able to build and serve our new locales.

"scripts": {
    "start": "ng serve",
    "start:fr": "ng serve --configuration=fr-FR",
    "start:gr": "ng serve --configuration=el-GR",
    "build": "ng build",
    "build:fr": "ng build --configuration=fr-FR",
    "build:gr": "ng build --configuration=el-GR",
}
Enter fullscreen mode Exit fullscreen mode

NOTE: Once again, I kept the file brief.

It's time to see what we have created.

npm run start
npm run start:fr -- --port 4201
npm run start:gr -- --port 4202
Enter fullscreen mode Exit fullscreen mode

And there you go! | Et Voilà! | Μπουμ!

i18n

Conclusion

Internationalization and localization are an important part of an application. We can use angular-cli to support it or install and external library to save some time.

References / Resources

  1. i18n
  2. ngx-translate

If you found this post helpful or enjoyed it, consider supporting me by buying me a coffee. Your support helps me create more valuable content. ☕ Thank you!

Top comments (5)

Collapse
 
arielgueta profile image
Ariel Gueta •

Transloco is the hot thing now. github.com/ngneat/transloco

Collapse
 
ptheodosiou profile image
Pantelis Theodosiou •

Thanks for your response. I think that the idea behind these 3rd parties libraries have always been to provide support for i18n until Angular catches up, after that, these libraries will probably be deprecated.

Collapse
 
arielgueta profile image
Ariel Gueta •

I think that you will never get the same tools by using the built-in support.

Thread Thread
 
ptheodosiou profile image
Pantelis Theodosiou •

Maybe it's true, maybe it's not. Who knows? 🙃

Collapse
 
yagoferrer profile image
Yago •

How do you translate routes with Angular?

Read next

gergelyszerovay profile image

What's new in Angular 17.3

Gergely Szerovay -

gcascio profile image

Translating zod errors with next-intl

gcascio -

oz profile image

Preparing our Code for Zoneless Angular

Evgeniy OZ -

alisaduncan profile image

Flexible Authentication Configurations in Angular Applications Using Okta

Alisa -