API Reference

select<K extends string>(scope: K): Signal<Record<string, unknown> | 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.

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

translate(key: string, params?: Record<string, string | number>): Signal<string>

Returns a cached signal for a single translation key. Automatically triggers namespace loading. Key format: namespace:dotted.path.

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

instant(key: string, params?: Record<string, string | number>): string

Returns the translation synchronously. Non-reactive and does not trigger lazy loading — use only for imperative code (toasts, logs) when the namespace is already loaded.

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.

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