Documentation

The <t> component

Wrap your content in the <t> component to translate it. The original content is shown until the translation loads.

<t>This content will be translated</t>

Text with bindings works too. The content is translated again whenever it changes, for example when name changes:

<t>Hello {{ name() }}</t>

For values that change often, such as names and counts, use variables instead, so the text is translated only once.

All translations requested at the same time are sent to the API in a single request, and translations are cached. You can use as many <t> components as you like.

<mt-translate> works as an alternative selector, and Translate is the same component as T.

Inputs

InputTypeDescription
formality'informal' | 'formal'Sets the formality of the translation.
idstringLets you edit this use of the text on its own. It is not set as the element's id.
langLanguageOverrides the language set with provideMagicTranslate.
vRecord<string, unknown>Values that are not translated, referenced as $name in the content. See Variables.
<t lang="fr" formality="formal">How are you?</t>

Variables

Pass values that change, such as a name or a count, in [v] and reference them as $name in the content:

<t [v]="{ name: user.name, count: unread() }">
  Hi $name, you have $count new messages
</t>

Magic Translate translates the text around the values once, as Hi {0}, you have {1} new messages, and puts the values back in your app. The translation is cached and works for every name and every count, and the values themselves are never sent to Magic Translate. When only the values change, no new request is made.

The values are numbered in the order they first appear. The translation can move them wherever the language needs them, for example {1} neue Nachrichten für {0}.

The text around the values can contain HTML, and the values can be formatted with pipes first:

<t [v]="{ count: cart.items.length, total: cart.total | currency }">
  You have <b>$count items</b> in your cart, totalling <b>$total</b>.
</t>

A few rules:

  • Only keys of [v] are replaced, so text such as $5 stays as it is. If two keys start the same way, such as count and counts, the longest one wins.
  • The same name can appear more than once.
  • Values are inserted as text, never as HTML. Put markup in the text around them instead: Hi <b>$name</b>.
  • Variables are replaced in text only, not in attributes such as href or title.
  • In development mode, a key that does not appear in the text logs a warning, which catches typos.
  • With server-side rendering, a <t> with [v] renders empty on the server and appears once the app runs in the browser.

Variables use $name rather than {name} because Angular reads a single { in a template as the start of an ICU message, and the template does not compile.

Limitations

  1. You cannot put Angular components inside the <t> component. Plain HTML elements are fine (see the example below). The translated markup goes through Angular's HTML sanitizer.
  2. The content inside a <t> component cannot exceed 10 KB, which is about 5,000 characters.
<!-- this is OK, since <a> is a plain HTML element -->
<t>
  <a href="mailto:info@i42.ch">Please send us an email</a>
</t>


<!-- this does NOT work, since <app-button> is an Angular component -->
<t>
  <app-button>Click me</app-button>
</t>

To translate attributes and other strings, use the t pipe.

PreviousAngularNextThe t pipe