Getting Started

Set up @angular-translation-service/core in your Angular v19+ project in 3 minutes.

1. Install

npm install @angular-translation-service/core

2. Create Translation Files

For httpLoader('/i18n'), put JSON under public/i18n/. Angular serves public/ at the site root, so public/i18n/en/common.json is available at /i18n/en/common.json. CLI tools default to src/i18n/ — keep a matching tree there, or pass -i/--i18n. Loader pattern: basePath/lang/namespace.json:

public/i18n/en/common.json

{
  "nav": {
    "home": "Home",
    "about": "About"
  },
  "greeting": "Hello, {name}!"
}

3. Configure the Provider

app.config.ts

import { provideTranslation, httpLoader } from '@angular-translation-service/core';

export const appConfig = {
  providers: [
    provideTranslation({
      defaultLang: 'en',
      supportedLangs: ['en', 'pt-BR'],
      coreNamespaces: ['common'],
      loader: httpLoader('/i18n'),
    }),
  ],
};

4. Use in Components

Use select() to get a namespace signal. Optional chaining keeps the DOM stable while the namespace loads; the recursive proxy prevents template crashes.

my-component.ts

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

@Component({
  template: `
    @let t = common();
    <h1>{{ t?.nav?.home }}</h1>
    <p>{{ t?.greeting }}</p>
  `,
})
export class MyComponent {
  private readonly i18n = inject(TranslationService);
  protected readonly common = this.i18n.select('common');
}

5. Alternative: Use the Pipe

For simpler cases, use TranslatePipe instead of select(). Keys always use namespace:path (default separator :):

my-component.ts

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

@Component({
  imports: [TranslatePipe],
  template: `
    <h1>{{ 'common:nav.home' | translate }}</h1>
    <p>{{ 'common:greeting' | translate:{ name: 'Igor' } }}</p>
  `,
})

6. Switch Language

Call setLang() (not use()). Persist with storageKey and enable browser detection with detectLanguage: true on the provider.

language-switcher.ts

protected readonly i18n = inject(TranslationService);
protected readonly languages = this.i18n.supportedLangs;

async switchTo(lang: string) {
  await this.i18n.setLang(lang);
}

7. Optional: Generate Typed Keys

Install the CLI and run ats generate when you want compile-time checking for service calls. The generated file registers its keys with @angular-translation-service/core, so typo'd keys and namespace paths fail TypeScript before they ship.

terminal

npx @angular-translation-service/cli generate \
  -i src/i18n/en \
  -o src/app/i18n.generated.ts

my-component.ts

this.i18n.translate('common:nav.home'); // typed
this.i18n.translate('common:nav.hmoe'); // TypeScript catches the typo

What's Next?

API Reference →Guides (troubleshooting & migration) →View Source on GitHub ↗