@translation/angular

Translation.io client for Angular

Add this package to localize your Angular application (see Installation).

Use the official Angular i18n syntax in your components.

Write only the source text in your Angular application, and keep it synchronized with your translators on Translation.io.

Need help? [e-mail]

Table of contents

• Localization syntax overview
  • i18n attribute in templates
  • $localize in classes and functions
• Installation
• Usage
  • Sync
  • Read-only Sync
  • Sync & purge
• Manage locales
• Localization syntax in details
• Advanced configuration options
• List of clients for Translation.io
  • Ruby on Rails (Ruby)
  • Laravel (PHP)
  • React, React Native and JavaScript
  • Others
• License

Localization syntax overview

i18n attribute in templates

Mark the text in a HTML element as translatable by using the i18n attribute in your components' templates.

<!-- Simple use of the i18n attribute -->
<h1 i18n>Welcome to our Angular application!</h1>

<!-- Variable interpolation -->
<!-- Translators will see "Hi {name}, welcome to your dashboard!" -->
<p i18n>Hi {{ name }}, welcome to your dashboard!</p>

<!-- Simple HTML tags interpolation -->
<!-- Translators will see "Text with <1>HTML</1> tags." -->
<p i18n>Text with <em>HTML</em> tags.</p>

<!-- Translatable attribute -->
<img [src]="cat.png" i18n-alt alt="A fluffy cat" />

<!-- ICU plural form -->
<!-- Translators will see "There are no cats", "There is one cat", "There are {x} cats" -->
<p i18n>{count, plural,
  =0 {There are no cats}
  =1 {There is one cat}
  other {There are {{count}} cats}
}</p>

$localize in classes and functions

Mark text (literal strings) as translatable in your component classes and functions using $localize and surrounding the text with backticks ( ` ).

// Simple use of the $localize function
let text = $localize `Welcome to our Angular application!`;

To explore the syntax more in details (specifying metadata, using plurals and interpolations), please check out the "Localization syntax in details" section below.

Installation

1. Check your Angular i18n configuration

Make sure that you have Angular's localize package installed, or install it.

ng add @angular/localize

Configure the i18n options in the angular.json file at the root of your project.

2. Install our @translation/angular package

Run the following command at the root of your project to install our package:

# NPM
npm install @translation/angular

# Yarn
yarn add @translation/angular

3. Create a new translation project

Sign in to our platform and create your new project from the UI, selecting the appropriate source and target locales.

4. Copy the generated tio.config.json file to the root of your application

This configuration file should look like this:

{
  "api_key": "abcdefghijklmnopqrstuvwxyz123456",
  "source_locale": "en",
  "target_locales": ["fr", "it", "es"]
}

5. Add scripts to your package.json

To make your life easier, add these lines to the package.json at the root of your application:

{
  "scripts": {
    "extract": "ng extract-i18n --output-path=src/locale",
    "translation:init": "npm run extract && tio init",
    "translation:sync": "npm run extract && tio sync"
  }
}

N.B. If you are using Angular version 10 or lower, replace extract-i18n by xi18n in the "extract" command.

6. Initialize your project

To push your source keys and existing translations (if any) to Translation.io, run the following command:

# NPM
npm run translation:init

# YARN
yarn translation:init

Usage

Sync

To push new translatable source keys/strings and get translations from Translation.io, simply run:

# NPM
npm run translation:sync

# YARN
yarn translation:sync

Read-only Sync

To retrieve translations without pushing new source keys, you can run:

# NPM
npm run translation:sync -- --readonly

# YARN
yarn translation:sync -- --readonly

Sync & Purge

If you need to remove unused source keys/strings from Translation.io, using your current local application as reference, run the following command:

# NPM
npm run translation:sync -- --purge

# YARN
yarn translation:sync -- --purge

Warning: all source keys/strings that are not present in your current local branch will be permanently deleted from Translation.io.

Manage locales

Add or remove locales

You can add or remove a locale by updating "target_locales": [] in your tio.config.json file, and syncing your project again.

If you want to add a new locale with existing translations (for instance if you already have a translated XLF file in your project), you will need to create a new empty project on Translation.io and init your project for them to appear.

Edit locales

To edit existing locales while keeping their translations (e.g. changing from en to en-US):

1. Create a new project on Translation.io with the correct locales.
2. Update the tio.config.json file with the new API key and correct locales.
3. Adapt the locale codes in the XLF files' names.
4. Initialize your new project and check that everything went fine.
5. Invite your collaborators in the new project.
6. Remove the old project.

Since you created a new project, the translation history and tags will unfortunately be lost.

Localization syntax in details

i18n attributes and $localize

The text in a HTML element can be marked as translatable by using the i18n attribute in the components' templates.

<h1 i18n>Welcome to our Angular application!</h1>

The attributes of HTML elements can also be marked as translatable by using i18n-{attribute_name} attributes.

<img [src]="cat.png" i18n-alt alt="A fluffy cat" />

You can interpolate variables (component properties) into translatable strings.

<!-- Translators will see "Hi {name}, welcome to your dashboard!" -->
<p i18n>Hi {{ name }}, welcome to your dashboard!</p>

And you can also interpolate valid HTML tags.

<!-- Translators will see "Text with <1>HTML</1> tags." -->
<p i18n>Text with <em>HTML</em> tags.</p>

<!-- Translators will see "Text with a <1><2>partly-emphasized</2> link</1>." -->
<p i18n>Text with a <a href="#"><em>partly-emphasized</em> link</a>.</p>

Literal strings in your component classes and functions can also be marked as translatable using $localize and surrounding the source text with backticks ( ` ).

let text = $localize `Hello, we hope you will enjoy this app.`;

This syntax also allows for variable interpolation.

// Translators will see "Hi {name}, welcome to your dashboard!"
let text = $localize `Hi ${name}, welcome to your dashboard!`;

The official Angular documentation for the syntax can be found here.

Optional metadata for translation

You can use metadata as the value of the i18n attribute to specify a custom ID, a meaning and a description.

The syntax for the metadata, is the following: {meaning}|{description}@@{custom_id}

<!-- Specifying only the meaning (the pipe | is required) -->
<h1 i18n="Welcome message|">Welcome to our app!</h1>

<!-- Specifying only the description -->
<h1 i18n="Message used on the homepage">Welcome to our app!</h1>

<!-- Specifying only the indetifier -->
<h1 i18n="@@home-welcome-message">Welcome to our app!</h1>

<!-- Specifying a meaning, a description and an identifier -->
<h1 i18n="Welcome message|Message used on the homepage@@home-welcome-message">Welcome to our app!</h1>

Metadata can also be used with $localize, but it must then be formatted as follows: :{meaning}|{description}@@{custom_id}:{source_text}.

// Specifying only the meaning (the pipe | is required)
let text = $localize `:Welcome message|:Welcome to our Angular app!`;

// Specifying only the description
let text = $localize `:Message used on the homepage:Welcome to our Angular app!`;

// Specifying only the identifier
let text = $localize `:@@home-welcome-message:Welcome to our Angular app!`;

// Specifying a meaning, a description and an identifier
let text = $localize `:Welcome message|Message used on the homepage@@home-welcome-message:Welcome to our Angular app!`;

The official Angular documentation for optional metadata can be found here.

Our recommendations for metadata

The "unicity" of a source key is determined by its source text, its custom ID (if any) and its meaning (if any). The description plays no role in this unicity.

If you choose to use custom IDs, make sure that your IDs are unique (or that you always use the same source text with the same ID), otherwise only the first source text will be associated with the ID (see official documentation).

To avoid any problems, we strongly recommend that you opt for the use of "meanings" instead of IDs. Note: If you use a meaning without a description, make sure to add a pipe (|) after the meaning, otherwise it will be considered as a description.

<!-- Good use cases: -->

  <!-- Example 1
    The meaning helps distinguish between two keys with the same source text
    => This will result in two distinct source keys
  -->
  <span i18n="Numbered day in a calendar|">Date</span>
  <span i18n="Social meeting with someone|">Date</span>

  <!-- Example 2
    Adding a description after the meaning will be useful to translators
    => This will result in two distinct source keys
  -->
  <span i18n="Verb|Text on a button used to report a problem">Report</span>
  <span i18n="Noun|Title of the Report section in the app">Report</span>

<!-- Bad use cases: -->

  <!-- Example 1
    Using only descriptions, without meanings (note the missing pipe | )
    -> This will result in only one source key
  -->
  <label i18n="Label for the datepicker">Date</label>
  ...
  <option i18n="Type of event in a dropdown">Date</option>

  <!-- Example 2
    Using the same ID with two different source texts
    -> This will result in only one source key (the first one)
  -->
  <h2 i18n="@@section-title">First section</h2>
  <h2 i18n="@@section-title">Second section</h2>

ICU expressions (plural and select)

Pluralization

Pluralization rules may vary from one locale to another, and it is recommended to use the plural syntax in your code to facilitate translation. This syntax is expressed as follows: { component_property, plural, pluralization_categories }.

<!-- Translators will see "There are no cats", "There is one cat", "There are {x} cats" -->
<p i18n>{count, plural,
  =0 {There are no cats}
  =1 {There is one cat}
  other {There are {{count}} cats}
}</p>

The official Angular documentation for plurals can be found here.

Select clause

The select clause allows to display alternate text depending on the value of a variable. This syntax is expressed as follows: { component_property, select, selection_categories }.

<span i18n>The user is {gender, select, male {a man} female {a woman} other { other }}.</span>

The official Angular documentation for select clauses can be found here.

Our recommendations for plural and select expressions

To facilitate the work of translators, try to avoid complicated or nested expressions.

Advanced configuration options

The tio.config.json file, at the root of your application, can take other optional configuration options.

We always favor "convention over configuration", so we strongly recommend that you use the default paths and file names in your localization process, but you may specify custom source and target paths for your application if necessary.

Custom path for the source locale file

If your source locale file (XLF) is not located in the default src/locale directory and/or is not named messages.xlf (default name), you may specify a custom source locale path in your tio.config.json file:

{
  "source_file_path" : "src/translations/sources.xlf"
}

Warning! The name of your source file should match the one generated by the extract script. Make sure to stay consistent in your package.json:

{
  "scripts": {
    "extract": "ng extract-i18n --output-path=src/translations  --out-file=sources.xlf"
  }
}

Custom path for target locale files

You may also specify a custom path for the target locale files (XLF) if you need them to have a name other than the defaut messages.{lang}.xlf or to be located in a directory other than the default src/locale directory. Simply add the following line to your tio.config.json, but make sure that it contains the {lang} placeholder as such:

{
  "target_files_path": "src/translations/translations.{lang}.xlf"
}

or

{
  "target_files_path": "src/locale/{lang}/translations.xlf"
}

Note: our package will attempt to create any missing directories. If it fails (for example, if permissions are strict on your side), please make sure to create the required directories manually.

Proxy

If you need to use a proxy to connect to Translation.io, add the following line to your tio.config.json file:

{
  "proxy": "http://login:pass@127.0.0.1:8080"
}

List of clients for Translation.io

Implementations were usually started by contributors for their own projects. The following are officially supported by Translation.io and are well documented.

We are thankful to all contributors for their hard work!

Ruby on Rails (Ruby)

Officially supported on https://translation.io/rails

• GitHub: https://github.com/translation/rails
• RubyGems: https://rubygems.org/gems/translation/

Credits: @aurels, @michaelhoste

Laravel (PHP)

Officially supported on https://translation.io/laravel

• GitHub: https://github.com/translation/laravel
• Packagist: https://packagist.org/packages/tio/laravel

Credits: @armandsar, @michaelhoste

React, React Native and JavaScript

Officially supported on https://translation.io/lingui

Translation.io is directly integrated in the great Lingui internationalization project.

• GitHub: https://github.com/translation/lingui
• NPM: https://www.npmjs.com/package/@translation/lingui

Angular

Officially supported on https://translation.io/angular

• GitHub: https://github.com/translation/angular
• NPM: https://www.npmjs.com/package/@translation/angular

Others

If you want to create a new client for your favorite language or framework, please read our Create a Translation.io Library guide and use the special init and sync endpoints.

You can also use the more traditional API.

Feel free to contact us on [e-mail] if you need some help or if you want to share your library.

Licence

The MIT License (MIT). Please see License File for more information.

Changelog

v1.2.0 (2022-10-13)

New features:

• Handle custom source_file_path and target_files_path.
• Start by validating the configuration file with nice errors before Init/Sync.