WrI18n

Translate strings at runtime and switch the locale without a reload.

Installation

Import the class. This entry point has no stylesheet.

import { Component } from '@angular/core';
import { WrI18n, WrTDirective, WrTPipe } from 'ngwr/i18n';

@Component({ imports: [WrTDirective, WrTPipe] })
export class MyComponent {}

Live demo

Switch the locale; every wrT binding updates.

Active locale:en

Pipe: ngwr i18n demo — Hello, Ada!

Directive:Hello, Ada!

Common keys:Save / Cancel / Loading…

Reading a key from TypeScript

The use… and read… helpers need an injection context; t() and translate() work anywhere.

CallReturnsRuns inUse it for
useI18nText(input, key, fallback)Signal<string>Injection contextA string with an override input
readI18nText(key, fallback)Signal<string>Injection contextA string with no override input
useI18nFormatter(key, fallback)(params) => stringInjection contextA label with params per row
i18n.translate(key, params?)Signal<string>AnywhereA reactive string, created later
i18n.t(key, params?)stringAnywhereA 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

NameDescriptionTypeDefault
WrI18nInjectable service.service—
localeActive 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.

NameDescriptionTypeDefault
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

NameDescriptionTypeDefault
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

NameDescriptionTypeDefault
wrTrequiredTranslation key. Required.string—
wrTParamsInterpolation params for {{name}} tokens.WrI18nParams | nullnull
wrTScopeOptional scope — scoped lookup first, then root fallback.string | nullnull

Dependencies

@angular/common/http@angular/common/http
Built onWrStorage

See also