Work with translation files

After you prepare a component for translation, use the extract-i18n Angular CLI command to extract the marked text in the component into a source language file.

The marked text includes text marked with i18n, attributes marked with i18n-attribute, and text tagged with $localize as described in Prepare component for translation.

Complete the following steps to create and update translation files for your project.

1. Extract the source language file.
   1. Optionally, change the location, format, and name.
2. Copy the source language file to create a translation file for each language.
3. Translate each translation file.
4. Translate plurals and alternate expressions separately.
   1. Translate plurals.
   2. Translate alternate expressions.
   3. Translate nested expressions.

Extract the source language file

To extract the source language file, complete the following actions.

1. Open a terminal window.
2. Change to the root directory of your project.
3. Run the following CLI command.

         
   ng add @angular/localize
   ng extract-i18n
   ng extract-i18n --output-path src/locale
   ng extract-i18n --format=xlf
   ng extract-i18n --format=xlf2
   ng extract-i18n --format=xmb
   ng extract-i18n --format=json
   ng extract-i18n --format=arb
   ng extract-i18n --out-file source.xlf
   ng build --localize
   ng serve --configuration=fr
   ng build --configuration=production,fr
   
       

The extract-i18n command creates a source language file named messages.xlf in the root directory of your project. For more information about the XML Localization Interchange File Format (XLIFF, version 1.2), see XLIFF.

Use the following extract-i18n command options to change the source language file location, format, and file name.

Change the source language file location

To create a file in the src/locale directory, specify the output path as an option.

extract-i18n --output-path example

The following example specifies the output path as an option.

      
ng add @angular/localize
ng extract-i18n
ng extract-i18n --output-path src/locale
ng extract-i18n --format=xlf
ng extract-i18n --format=xlf2
ng extract-i18n --format=xmb
ng extract-i18n --format=json
ng extract-i18n --format=arb
ng extract-i18n --out-file source.xlf
ng build --localize
ng serve --configuration=fr
ng build --configuration=production,fr

    

Change the source language file format

The extract-i18n command creates files in the following translation formats.

Specify the translation format explicitly with the --format command option.

extract-i18n --format example

The following example demonstrates several translation formats.

      
ng add @angular/localize
ng extract-i18n
ng extract-i18n --output-path src/locale
ng extract-i18n --format=xlf
ng extract-i18n --format=xlf2
ng extract-i18n --format=xmb
ng extract-i18n --format=json
ng extract-i18n --format=arb
ng extract-i18n --out-file source.xlf
ng build --localize
ng serve --configuration=fr
ng build --configuration=production,fr

    

Change the source language file name

To change the name of the source language file generated by the extraction tool, use the --out-file command option.

extract-i18n --out-file example

The following example demonstrates naming the output file.

      
ng add @angular/localize
ng extract-i18n
ng extract-i18n --output-path src/locale
ng extract-i18n --format=xlf
ng extract-i18n --format=xlf2
ng extract-i18n --format=xmb
ng extract-i18n --format=json
ng extract-i18n --format=arb
ng extract-i18n --out-file source.xlf
ng build --localize
ng serve --configuration=fr
ng build --configuration=production,fr

    

Create a translation file for each language

To create a translation file for a locale or language, complete the following actions.

1. Extract the source language file.

2. Make a copy of the source language file to create a translation file for each language.

3. Rename the translation file to add the locale.

         
   messages.xlf --> messages.{locale}.xlf
       

4. Create a new directory at your project root named locale.

         
   src/locale
       

5. Move the translation file to the new directory.

6. Send the translation file to your translator.

7. Repeat the above steps for each language you want to add to your application.

extract-i18n example for French

For example, to create a French translation file, complete the following actions.

1. Run the extract-i18n command.
2. Make a copy of the messages.xlf source language file.
3. Rename the copy to messages.fr.xlf for the French language (fr) translation.
4. Move the fr translation file to the src/locale directory.
5. Send the fr translation file to the translator.

Translate each translation file

Unless you are fluent in the language and have the time to edit translations, you will likely complete the following steps.

1. Send each translation file to a translator.
2. The translator uses an XLIFF file editor to complete the following actions.
   1. Create the translation.
   2. Edit the translation.

Translation process example for French

To demonstrate the process, review the messages.fr.xlf file in the Example Angular Internationalization application. The Example Angular Internationalization application includes a French translation for you to edit without a special XLIFF editor or knowledge of French.

The following actions describe the translation process for French.

1. Open messages.fr.xlf and find the first <trans-unit> element. This is a translation unit, also known as a text node, that represents the translation of the <h1> greeting tag that was previously marked with the i18n attribute.

   The id="introductionHeader" is a custom ID, but without the @@ prefix required in the source HTML.

2. Duplicate the <source>... </source> element in the text node, rename it to target, and then replace the content with the French text.

   In a more complex translation, the information and context in the description and meaning elements help you choose the right words for translation.

3. Translate the other text nodes. The following example displays the way to translate.

If you change either the text or the meaning, then the id attribute changes. For more about managing text updates and IDs, see custom IDs.

Translate plurals

Add or remove plural cases as needed for each language.

minute plural example

To translate a plural, translate the ICU format match values.

• just now
• one minute ago
• <x id="INTERPOLATION" equiv-text="{{minutes}}"/> minutes ago

The following example displays the way to translate.

      
<h1 i18n="User welcome|An introduction header for this sample@@introductionHeader">
  Hello i18n!
</h1>
<ng-container i18n>I don't output any element</ng-container>
<br />
<img [src]="logo" i18n-title title="Angular logo" alt="Angular logo"/>
<br>
<button type="button" (click)="inc(1)">+</button> <button type="button" (click)="inc(-1)">-</button>
<span i18n>Updated {minutes, plural, =0 {just now} =1 {one minute ago} other {{{ minutes }} minutes ago}}</span>
({{ minutes }})
<br><br>
<button type="button" (click)="male()">♂</button>
<button type="button" (click)="female()">♀</button>
<button type="button" (click)="other()">⚧</button>
<span i18n>The author is {gender, select, male {male} female {female} other {other}}</span>
<br><br>
<span i18n>Updated: {minutes, plural,
  =0 {just now}
  =1 {one minute ago}
  other {{{ minutes }} minutes ago by {gender, select, male {male} female {female} other {other}}}}
</span>