API Reference

select<N extends TranslationNamespace>(scope: N): Signal<TranslationNamespaces[N] | undefined>

Returns a scope signal for template access. Automatically triggers lazy loading for the namespace. Data is undefined until the namespace loads, then returns a proxy-wrapped dictionary for safe deep property access. When generated types are registered, the namespace name and returned schema are typed.

protected readonly common = this.i18n.select('common');
// template: @let t = common(); {{ t?.nav?.title }}

translate<K extends TranslationKey>(key: K, params?: TranslationParams<K>): Signal<string>

Returns a cached signal for a single translation key. Automatically triggers namespace loading and re-runs when the active language changes. Key format: namespace:dotted.path. When generated types are registered, invalid keys become TypeScript errors.

protected readonly title = this.i18n.translate('common:nav.title');
protected readonly greeting = this.i18n.translate('common:greeting', { name: 'Igor' });

instant<K extends TranslationKey>(key: K, params?: TranslationParams<K>): string

Returns the translation synchronously. It is non-reactive: values read with instant() do not update after setLang(). If called before a lazy namespace has ever been requested, dev mode warns once and starts loading that namespace; the current synchronous call still returns ''. Use ensureNamespaces() first or prefer translate() for reactive UI state.

setLang(lang: string): Promise<void>

Switches the active language. Reloads all previously requested namespaces for the new language and persists the preference to localStorage (if storageKey is configured). Logs a warning and returns early if the language is not in supportedLangs.

ensureNamespaces(ns: string[]): Promise<void>

Pre-loads additional namespaces. Deduplicates concurrent loads automatically. Useful for route guards or resolvers.

lang: WritableSignal<string>

The current language signal. Read in templates to show the active language.

supportedLangs: readonly string[]

Read-only array of all supported language codes from the configuration. Useful for building language switchers.

// Build a language switcher
protected readonly languages = this.i18n.supportedLangs;
// template: @for (lang of languages; track lang) { ... }

ready: Signal<boolean>

True when all coreNamespaces have been loaded for the current language.

Generated registry

export interface I18nTypes {
  common: {
    nav: {
      home: string;
    };
  };
}

declare module '@angular-translation-service/core' {
  interface TranslationKeyRegistry {
    keys: I18nTranslationKey;
    namespaces: I18nTypes;
  }
}

What TypeScript catches

Static TypeScript call sites get checked end-to-end. The pipe still accepts template strings because Angular template expressions cannot expose the same module augmentation contract.

this.i18n.translate('common:nav.home'); // OK
this.i18n.translate('common:nav.hmoe'); // TypeScript error

const common = this.i18n.select('common');
common()?.nav.home; // typed namespace schema

Canonical form

Single braces match the translate(key, { name }) mental model and avoid visual collision with Angular template interpolation.

{
  "greeting": "Hello, {name}!"
}

this.i18n.translate('common:greeting', { name: 'Igor' });

Angular pipe params gotcha

When passing an object literal to the pipe inside Angular interpolation, leave a space between the object closing brace and Angular's closing braces. Without the space, Angular may parse the braces together.

<!-- Avoid: object brace touches Angular's closing braces -->
<p>{{ 'common:greeting' | translate:{ name: userName()}}}</p>

<!-- Prefer: keep a space before the interpolation closes -->
<p>{{ 'common:greeting' | translate:{ name: userName() } }}</p>

Setup

Import TranslatePipe in your component's imports array:

import { TranslatePipe } from '@angular-translation-service/core';

@Component({
  imports: [TranslatePipe],
  template: `...`,
})

Usage

<!-- Basic -->
<h1>{{ 'common:nav.title' | translate }}</h1>

<!-- With params -->
<p>{{ 'common:greeting' | translate:{ name: 'Igor' } }}</p>

httpLoader(basePath: string): TranslationLoader

Creates a fetch-based loader. Loads JSON from: basePath/lang/namespace.json. Place your JSON files in the Angular project's public/ directory (files in public/ are served at the root URL).

// Files at: public/i18n/en/common.json → served at /i18n/en/common.json
loader: httpLoader('/i18n')

importLoader(factory: (lang, ns) => Promise<{ default: Record }>): TranslationLoader

Creates a loader using dynamic imports. The factory callback must return a module with a default export containing the translation dictionary. The bundler can statically analyze import paths for tree-shaking and code splitting.

loader: importLoader((lang, ns) =>
  import(`./i18n/${lang}/${ns}.json`)
)

TRANSLATION_CONFIG: InjectionToken<TranslationConfig>

Injection token for the translation configuration. Automatically provided by provideTranslation(). Useful for custom providers that need access to the configuration.

CURRENT_LANGUAGE: InjectionToken<string>

Injection token for server-side language detection. Provided by provideTranslationSSR() on the server to inject the language from the HTTP request. On the client, language is resolved from TransferState or local detection.

Behavior

provideTranslationSSR(config: TranslationSSRConfig): EnvironmentProviders

Add to your server application config. On the server, it provides CURRENT_LANGUAGE from the HTTP request and snapshots all loaded translations into TransferState. On the client, it hydrates translations synchronously — no HTTP requests needed for the initial render.

// app.config.server.ts
import { provideTranslationSSR } from '@angular-translation-service/core/ssr';

export const serverConfig = {
  providers: [
    provideTranslationSSR({
      langFromRequest: (req) => {
        const accept = (req as Request).headers.get('accept-language') ?? 'en';
        return accept.split(',')[0].split('-')[0];
      },
    }),
  ],
};

How it works

TranslationSSRConfig