Skip to main content

Angular i18n met Transloco: configuratie- en vertaalhandleiding

Van installatie tot productie: configureer Transloco, verwerk meervoudsvormen met ICU-syntaxis, voeg slimme terugvaltalen toe en automatiseer vertalingen met AI.

1

Transloco installeren

Transloco is de populairste externe i18n-bibliotheek voor Angular. De bibliotheek biedt het laden van vertalingen tijdens runtime, ondersteuning voor ICU-berichtindelingen, uitgesteld geladen scopes en een heldere sjabloon-API met structurele directives en pipes.

Waarom Transloco in plaats van de ingebouwde i18n van Angular? De ingebouwde oplossing van Angular vereist voor elke taal een afzonderlijke build en ondersteunt niet dat je tijdens runtime van taal wisselt. Transloco laadt vertalingen tijdens runtime, zodat je één build uitbrengt en direct van taal kunt wisselen.
Terminal
npm install @jsverse/transloco
2

Transloco configureren

Registreer Transloco in je applicatieconfiguratie. Geef de beschikbare talen op, stel een standaardtaal in en configureer de vertaallader. Transloco ondersteunt zowel zelfstandige componenten (Angular 14+) als NgModule-patronen.

Zelfstandige componenten (aanbevolen)

app.config.ts
// app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideHttpClient } from '@angular/common/http';
import {
  provideTransloco,
  TranslocoHttpLoader,
} from '@jsverse/transloco';

export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(),
    provideTransloco({
      config: {
        availableLangs: ['en', 'de', 'ja', 'es', 'fr'],
        defaultLang: 'en',
        fallbackLang: 'en',
        reRenderOnLangChange: true,
        prodMode: true,
      },
      loader: TranslocoHttpLoader,
    }),
  ],
};

NgModule-patroon

app.module.ts
// app.module.ts
import { NgModule } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import {
  TranslocoModule,
  TRANSLOCO_LOADER,
  TranslocoHttpLoader,
  provideTransloco,
} from '@jsverse/transloco';

@NgModule({
  imports: [TranslocoModule],
  providers: [
    provideTransloco({
      config: {
        availableLangs: ['en', 'de', 'ja', 'es', 'fr'],
        defaultLang: 'en',
        fallbackLang: 'en',
        reRenderOnLangChange: true,
        prodMode: true,
      },
      loader: TranslocoHttpLoader,
    }),
  ],
})
export class AppModule {}
Als vertalingen als onbewerkte sleutels zoals "nav.home" verschijnen in plaats van als "Home", kan TranslocoHttpLoader je JSON-bestanden meestal niet vinden. Controleer of je vertaalbestanden in src/assets/i18n/ staan en of de assets-array in angular.json dat pad bevat.

Vertaalbestanden maken

Maak in src/assets/i18n/ voor elke taal één JSON-bestand. Gebruik geneste sleutels om tekenreeksen per functie te ordenen. Transloco gebruikt de ICU-berichtindeling voor meervoudsvormen en variabelen.

assets/i18n/*.json
// assets/i18n/en.json
{
  "nav": {
    "home": "Home",
    "about": "About",
    "settings": "Settings"
  },
  "greeting": "Hello, {{ name }}!",
  "cart": {
    "itemCount": "{count, plural, one {# item} other {# items}}"
  }
}

// assets/i18n/de.json
{
  "nav": {
    "home": "Startseite",
    "about": "Uber uns",
    "settings": "Einstellungen"
  },
  "greeting": "Hallo, {{ name }}!",
  "cart": {
    "itemCount": "{count, plural, one {# Artikel} other {# Artikel}}"
  }
}
3

Vertalingen in sjablonen en services gebruiken

Transloco biedt drie manieren om in sjablonen te vertalen: de structurele directive (*transloco), de pipe (| transloco) en de service (TranslocoService) voor TypeScript-code. Voor de meeste toepassingen wordt de structurele directive aanbevolen, omdat deze één abonnement maakt en de vertaalfunctie aan het hele sjabloonblok beschikbaar stelt.

Vertalen in sjablonen

component.html
<!-- Using the transloco directive (recommended) -->
<ng-container *transloco="let t">
  <h1>{{ t('greeting', { name: userName }) }}</h1>
  <nav>
    <a routerLink="/">{{ t('nav.home') }}</a>
    <a routerLink="/about">{{ t('nav.about') }}</a>
  </nav>
</ng-container>

<!-- Using the transloco pipe -->
<h1>{{ 'greeting' | transloco:{ name: userName } }}</h1>

<!-- Using the structural directive with read -->
<ng-container *transloco="let t; read: 'nav'">
  <a routerLink="/">{{ t('home') }}</a>
  <a routerLink="/about">{{ t('about') }}</a>
</ng-container>
Gebruik de parameter read van de structurele directive om vertalingen tot een geneste sleutel te beperken. Zo hoef je het voorvoegsel niet in elke t()-aanroep te herhalen en blijven sjablonen overzichtelijker.

Vertalen in services (TypeScript)

notification.component.ts
import { Component, inject } from '@angular/core';
import { TranslocoService } from '@jsverse/transloco';

@Component({
  selector: 'app-notification',
  template: '<span>{{ message }}</span>',
})
export class NotificationComponent {
  private translocoService = inject(TranslocoService);
  message = '';

  showSuccess() {
    // Translate in TypeScript
    this.message = this.translocoService.translate('notifications.saved');
  }

  switchLanguage(lang: string) {
    this.translocoService.setActiveLang(lang);
  }
}
De transloco-pipe maakt bij elk gebruik een nieuw abonnement. Gebruik in sjablonen met veel vertaalde tekenreeksen bij voorkeur de structurele directive *transloco, die één abonnement voor het hele blok maakt.
4

Meervoudsvormen verwerken met de ICU-berichtindeling

Transloco gebruikt de ICU-berichtindeling voor meervouds- en select-expressies. ICU verwerkt complexe meervoudsregels automatisch — Arabisch (6 vormen), Russisch (3 vormen), Japans (1 vorm) — vanuit één berichttekenreeks. Definieer de meervoudsregels in je vertaalbestanden, waarna Transloco tijdens runtime de juiste vorm selecteert.

ICU plural syntax
// assets/i18n/en.json
{
  "cart": {
    "itemCount": "{count, plural, one {# item} other {# items}}",
    "emptyMessage": "Your cart is empty"
  },
  "notifications": {
    "unread": "{count, plural, =0 {No new notifications} one {# new notification} other {# new notifications}}"
  }
}

// assets/i18n/ar.json — Arabic has 6 plural forms
{
  "cart": {
    "itemCount": "{count, plural, zero {لا عناصر} one {عنصر واحد} two {عنصران} few {# عناصر} many {# عنصرًا} other {# عنصر}}"
  }
}

// Template usage:
// <span>{{ t('cart.itemCount', { count: cartItems.length }) }}</span>
Implementeer nooit aangepaste meervoudslogica in je componenten. Talen hebben sterk uiteenlopende meervoudsregels die al door de ICU-specificatie worden verwerkt. Laat Transloco en ICU het werk doen — jij hoeft alleen de juiste meervoudsvormen in je vertaalbestanden te definiëren.

Slimme terugvaltalen met angular-locale-chain

Transloco valt standaard terug op je standaardtaal als een vertaalsleutel ontbreekt. Een gebruiker met pt-BR ziet daardoor Engels in plaats van prima pt-PT-vertalingen. angular-locale-chain lost dit op door vertalingen uit een configureerbare terugvalketen diep samen te voegen voordat ze aan Transloco worden doorgegeven. Elke sleutel wordt ingevuld — zonder gaten of ontbrekende vertalingen.

Terminal
npm install angular-locale-chain
app.config.ts (with locale chain)
// app.config.ts — with angular-locale-chain
import { ApplicationConfig } from '@angular/core';
import { provideHttpClient } from '@angular/common/http';
import {
  provideTransloco,
  TranslocoHttpLoader,
  TRANSLOCO_LOADER,
  TRANSLOCO_FALLBACK_STRATEGY,
} from '@jsverse/transloco';
import {
  LocaleChainLoader,
  LocaleChainFallbackStrategy,
} from 'angular-locale-chain';

export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(),
    provideTransloco({
      config: {
        availableLangs: ['en', 'fr', 'fr-CA', 'pt', 'pt-BR', 'de', 'de-AT'],
        defaultLang: 'en',
        fallbackLang: 'en',
        reRenderOnLangChange: true,
        prodMode: true,
      },
    }),
    {
      provide: TRANSLOCO_LOADER,
      useFactory: () => {
        const inner = new TranslocoHttpLoader();
        return new LocaleChainLoader(inner, {
          defaultLocale: 'en',
        });
      },
    },
    {
      provide: TRANSLOCO_FALLBACK_STRATEGY,
      useFactory: () => new LocaleChainFallbackStrategy(),
    },
  ],
};
angular-locale-chain is een opensourcebibliotheek die Transloco-bug #574 oplost: het ontbreken van terugval per sleutel wanneer een vertaalbestand slechts gedeeltelijk is voltooid.

Aanbevolen bestandsstructuur

Project Structure
my-angular-app/
├── src/
│   ├── assets/
│   │   └── i18n/
│   │       ├── en.json           # Source language
│   │       ├── de.json           # German
│   │       ├── ja.json           # Japanese
│   │       ├── es.json           # Spanish
│   │       └── fr.json           # French
│   ├── app/
│   │   ├── app.config.ts         # Transloco provider config
│   │   ├── app.component.ts
│   │   └── components/
│   │       └── lang-switcher/
│   │           └── lang-switcher.component.ts
│   └── main.ts
├── angular.json
└── package.json

Vertalingen automatiseren

Nu Transloco is geconfigureerd, kun je je taalbestanden met AI vertalen. Vraag je AI-assistent in je IDE om je JSON-bronbestand te vertalen of gebruik de CLI van i18n Agent in je CI/CD-pipeline voor volledig geautomatiseerde lokalisatie.

Terminal
# In your IDE, ask your AI assistant:
> Translate src/assets/i18n/en.json to German, Japanese, and Spanish

✓ de.json created (1.2s)
✓ ja.json created (1.5s)
✓ es.json created (1.1s)

# Or use the CLI in CI/CD:
npx i18n-agent translate src/assets/i18n/en.json --lang de,ja,es
Vertaal stapsgewijs: vertaal alleen het verschil wanneer je nieuwe sleutels aan je bronbestand toevoegt, in plaats van alle bestanden opnieuw te genereren. Zo blijven door mensen gecontroleerde vertalingen behouden en voorkom je onnodige wijzigingen.

Kwaliteitscontrole van vertalingen automatiseren

Vind ontbrekende sleutels en kapotte plaatsaanduidingen vóór de release met i18n-validate. Test je gebruikersinterface met pseudovertalingen uit i18n-pseudo voordat de echte vertalingen klaar zijn.

Veelvoorkomende valkuilen

Vertalingen tonen onbewerkte sleutels

TranslocoHttpLoader kan je JSON-bestanden niet vinden. Controleer of de bestanden in src/assets/i18n/ staan of de assets-array in angular.json dat pad bevat en of de bestandsnamen exact overeenkomen met je availableLangs-configuratie (hoofdlettergevoelig).

Sleutels met een scope worden niet gevonden

Als je Transloco-scopes gebruikt, moeten vertaalbestanden in assets/i18n/[scope]/[lang].json staan en niet in de hoofdmap van i18n. Zorg ook dat de scope met TRANSLOCO_SCOPE in de providers-array van de component is geregistreerd.

Consolewaarschuwingen in productie

Stel voor productiebuilds prodMode: true in je Transloco-configuratie in. Zonder deze instelling schrijft Transloco waarschuwingen over ontbrekende sleutels naar de console. De instelling schakelt ook controles tijdens de ontwikkeling uit die extra belasting veroorzaken.

Vertalingen flitsen bij routenavigatie

Uitgesteld geladen routes halen vertalingen pas op nadat de component is weergegeven, waardoor onvertaalde sleutels kort in beeld komen. Gebruik de ingebouwde TRANSLOCO_LOADING_TEMPLATE van Transloco om een laadstatus te tonen of laad vertalingen vooraf in een routeguard.

Regionale gebruikers zien Engels in plaats van de bovenliggende taal

De ingebouwde terugval van Transloco wordt alleen geactiveerd als een volledig taalbestand ontbreekt, niet bij afzonderlijke ontbrekende sleutels. Gebruik angular-locale-chain om vertalingen uit verwante talen diep samen te voegen (pt-BR valt bijvoorbeeld terug op pt-PT, daarna op pt en vervolgens op Engels).

Probeer i18n Agent nu

Zet je vertaalbestand hier neer

JSON, YAML, PO, XML, CSV, Markdown, Properties

of klik om een bestand te selecteren

Doeltalen

Geen registratie nodigDirecte prijsindicatie

Terugvaltalen met angular-locale-chain

Als een vertaalsleutel ontbreekt in een regionale taal zoals pt-BR, schakelt TranslocoLoader van Angular direct over naar de standaardtaal in plaats van eerst de bovenliggende taal pt te controleren.

Terminal
npm install angular-locale-chain
Configuration
import { LocaleChainLoader } from 'angular-locale-chain';

new LocaleChainLoader(innerLoader, {
  fallbacks: {
    'pt-BR': ['pt', 'en'],
    'zh-Hant-HK': ['zh-Hant', 'zh', 'en'],
  },
  defaultLocale: 'en',
});

Bekijk onze handleiding voor terugvaltalen voor de volledige lijst met ondersteunde frameworks en 75 ingebouwde ketens. Learn more →

Veelgestelde vragen over Angular i18n