import { Component } from '@angular/core';
import { WrI18n, WrTDirective, WrTPipe } from 'ngwr/i18n';
@Component({ imports: [WrTDirective, WrTPipe] })
export class MyComponent {}WrI18n
Translate strings at runtime and switch the locale without a reload.
Installation
Import the class. This entry point has no stylesheet.
Live demo
Switch the locale; every wrT binding updates.
Reading a key from TypeScript
The use… and read… helpers need an injection context; t() and translate() work anywhere.
| Call | Returns | Runs in | Use it for |
|---|---|---|---|
useI18nText(input, key, fallback) | Signal<string> | Injection context | A string with an override input |
readI18nText(key, fallback) | Signal<string> | Injection context | A string with no override input |
useI18nFormatter(key, fallback) | (params) => string | Injection context | A label with params per row |
i18n.translate(key, params?) | Signal<string> | Anywhere | A reactive string, created later |
i18n.t(key, params?) | string | Anywhere | A one-off read, such as a toast |
import { WrI18n, readI18nText } from 'ngwr/i18n';
@Component({ /* … */ })
export class InvoiceCard {
private readonly i18n = inject(WrI18n);
// A field initializer is an injection context.
protected readonly heading = readI18nText('invoice.heading', 'Invoice');
protected onCopy(): void {
// A click handler is not: readI18nText() would throw NG0203 here.
this.toast.show(this.i18n.t('invoice.copied'));
}
}
// Anywhere else:
const label = runInInjectionContext(injector, () => readI18nText('x', 'X'));Call the signal in the template: a read at construction freezes the English fallback.
Service
| Name | Description | Type | Default |
|---|---|---|---|
WrI18n | Injectable service. | service | — |
locale | Active locale. Write it with use(). | Signal<string> | defaultLocale |
use(locale) | Switch the locale. Ignored outside availableLocales; stored under storageKey for the next visit. | (locale: string) => void | — |
t(key, params?, scope?) | Translate once. Returns the value or the missing-handler fallback. | (key, params?, scope?) => string | — |
translate(key, params?, scope?) | Translate as a signal that follows the locale and the catalogs. | (key, params?, scope?) => Signal<string> | — |
registerScope(scope) | Register a feature scope; its catalogs load on every locale change. | (scope: string) => Promise<WrI18nCatalog> | — |
available() | The configured locales. | () => readonly string[] | — |
Providers
Pick one loader, and add ngwr's own strings with provideWrI18nBaseCatalogs, never by spreading wrEn into your catalog.
| Name | Description | Type | Default |
|---|---|---|---|
provideWrI18n(options?) | Root provider: defaultLocale (from LOCALE_ID), availableLocales, storageKey, missingHandler, loader, all optional. A stored locale wins on boot; pass storageKey: null when the URL or the server decides. | (options: ProvideWrI18nOptions = {}) => EnvironmentProviders | — |
provideWrI18nStaticLoader(catalogs, scopes?) | Inline catalogs keyed by locale; scopes keyed by scope, then locale. Pass only your own keys here. | (catalogs: WrI18nStaticCatalogs, scopes?: WrI18nStaticScopedCatalogs) => Provider | — |
provideWrI18nBaseCatalogs(catalogs) | Register ngwr's catalogs (wrEn, wrRu, …) under yours, keyed by locale. Your keys win. | (catalogs: WrI18nBaseCatalogs) => Provider | — |
provideWrI18nHttpLoader({ path, rootPath? }) | Fetch JSON catalogs at runtime. {locale} and {scope} in the path are filled in. | ({ path, rootPath? }) => Provider | — |
Template helpers
| Name | Description | Type | Default |
|---|---|---|---|
WrTPipe — `| wrT[: params][: scope]` | Impure pipe; re-evaluates on every change detection. | pipe | — |
WrTDirective — `[wrT]="key" [wrTParams] [wrTScope]` | Writes the host element's text on every locale change. | directive | — |
useI18nFormatter(key, fallback) | Returns a (params) => string for the key. fallback is required English text, not a scope. | (key: string, fallback: string) => (params?: WrI18nParams) => string | — |
[wrT] inputs
| Name | Description | Type | Default |
|---|---|---|---|
wrTrequired | Translation key. Required. | string | — |
wrTParams | Interpolation params for {{name}} tokens. | WrI18nParams | null | null |
wrTScope | Optional scope — scoped lookup first, then root fallback. | string | null | null |
Dependencies
| @angular/common/http | @angular/common/http |
|---|---|
| Built on | WrStorage |
See also
Guide TranslationsTranslate your app and ngwr's own labels, and switch the locale at runtime.Service WrStorageTyped, reactive key-value storage over localStorage or any engine, safe under SSR.Guide Setup & loadersProvide WrI18n and load your catalogs.Guide Usage in templatesRead a translation with the wrT pipe, the [wrT] directive or the WrI18n service.Guide InterpolationFill placeholders in a translation with values.Guide ScopesLoad a feature's catalog only when the feature loads.Pipe wrPluralPick the right word form for a count, in any language.