@ngx-runtime-i18n/angular

Install

Install angular alongside core — the Angular package expects a matching core version as a peer dependency:

npm i @ngx-runtime-i18n/angular @ngx-runtime-i18n/core

Peer support: @angular/common, @angular/core, and @angular/platform-browser at >=16 <23.

Directory layout

your-app/
  src/
    public/
      i18n/
        en.json
        hi.json
        de.json

At runtime, catalogs are fetched from /i18n/<lang>.json by default in the examples on this page — the exact path is whatever your fetchCatalog function requests.

Register provideRuntimeI18n()

// app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideRouter } from '@angular/router';
import { provideRuntimeI18n } from '@ngx-runtime-i18n/angular';
import { appRoutes } from './app.routes';
 
export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(appRoutes),
    provideRuntimeI18n(
      {
        defaultLang: 'en',
        supported: ['en', 'hi', 'de'],
        fallbacks: ['de'],
        fetchCatalog: (lang, signal, scope) =>
          fetch(scope ? `/i18n/${scope}/${lang}.json` : `/i18n/${lang}.json`, { signal }).then((r) => {
            if (!r.ok) throw new Error(`Failed to load catalog: ${lang}`);
            return r.json();
          }),
        onMissingKey: (k) => k,
      },
      {
        localeLoaders: {
          en: () => import('@angular/common/locales/global/en'),
          hi: () => import('@angular/common/locales/global/hi'),
          de: () => import('@angular/common/locales/global/de'),
        },
        options: {
          autoDetect: true,
          storageKey: '@ngx-runtime-i18n:lang',
          cacheMode: 'storage',
          cacheKeyPrefix: '@ngx-runtime-i18n:catalog:',
          preferNavigatorBase: true,
        },
      },
    ),
  ],
};

provideRuntimeI18n(config, { localeLoaders?, options?, stateKeyPrefix? })

config

Second argument

I18nService

Signals-first service, injected with inject(I18nService).

Signals

Methods

const i18n = inject(I18nService);
 
// Disable the switcher while the next catalog downloads.
const onSwitch = (lang: string) => {
  if (i18n.switching()) return;
  i18n.setLang(lang);
};
 
// Warm caches for languages the user is likely to pick.
await i18n.preloadLangs(['de', 'hi']);

I18nPipe

<h1>{{ 'hello.user' | i18n:{ name: username } }}</h1>
<p>{{ 'cart.items' | i18n:{ count: items().length } }}</p>

Impure (pure: false) but listens only to lang, so it only recomputes when the language changes, not on every change-detection cycle.

I18nCompatService

RxJS equivalent of I18nService for codebases not yet on signals: lang$, ready$, and t().

t$() signal helper

I18nService.t$() returns a Signal<string> that recomputes only when the active language or the params change — useful in signal-heavy templates where the impure pipe's per-cycle check adds up.

@Component({
  template: `{{ greeting() }}`,
})
export class MyComponent {
  private i18n = inject(I18nService);
 
  // Static params — recomputes only on lang change.
  readonly greeting = this.i18n.t$('hello.user', { name: 'Ashwin' });
 
  // Reactive params — recomputes when either lang or params signal changes.
  private username = signal('Ashwin');
  readonly dynamicGreeting = this.i18n.t$('hello.user', this.username as unknown as Signal<Record<string, unknown>>);
}

Route-scoped catalogs with withI18nScope()

Load a feature-specific catalog only when a route activates, and unload it when the route is destroyed:

import { withI18nScope } from '@ngx-runtime-i18n/angular';
 
export const routes: Routes = [
  {
    path: 'checkout',
    loadComponent: () => import('./checkout/checkout.component'),
    providers: [withI18nScope('checkout')],
  },
];

Activating the checkout scope calls fetchCatalog(lang, signal, 'checkout') — the same fetchCatalog used for the global catalog, with the third argument set. Your implementation decides the URL shape, e.g. scope ? `/i18n/${scope}/${lang}.json` : `/i18n/${lang}.json`.

Resolution order: scope catalogs (most recently loaded scope wins) → global catalog → fallback chain → onMissingKey.

Scope catalogs are cleaned up automatically via DestroyRef when the route's environment injector is destroyed.

SSR and hydration

provideRuntimeI18nSsr() seeds Angular's TransferState on the server with the keys provideRuntimeI18n() reads on the client, so the first client render matches the server-rendered markup. See SSR and hydration for the full setup, including the requirement to put provideRuntimeI18nSsr()'s return value directly into providers — it's an opaque EnvironmentProviders value, and spreading it breaks.

Type safety

Declare a catalog schema via module augmentation to get compile-time checked keys and interpolation params on t(), I18nPipe, and I18nCompatService.t(). See type safety.

Pitfalls and gotchas

• Angular pipes not localizing: check that localeLoaders includes an entry for the language under test.
• Hydration mismatch: seed TransferState on SSR. The wrapper is hydration-safe when the first paint uses server data.
• 404 for catalogs: place catalog files under src/public/i18n so they serve as /i18n/*.json in both dev and prod.
• Rapid language toggles: supported. The wrapper cancels in-flight fetches when setLang() is called again before the previous switch resolves; your fetchCatalog must respect the passed AbortSignal for this to work.

Versioning and support

• Angular: >=16 <23
• Node: latest LTS recommended
• SemVer: breaking changes bump the major version.