Skip to main content

Angular i18n s Transloco: Nastavení a průvodce překladem

Od instalace po produkci: nakonfigurujte Transloco, řešte plurály pomocí ICU syntaxe, přidejte chytré fallbacky locale a automatizujte překlady s AI.

1

Nainstalujte Transloco

Transloco je nejoblíbenější i18n knihovna třetí strany pro Angular. Nabízí načítání překladů za běhu, podporu formátu zpráv ICU, lazy-loadované scopes a čisté šablonové API se strukturálními direktivami i pipes.

Proč zvolit Transloco místo vestavěného i18n v Angularu? Vestavěné řešení vyžaduje samostatný build pro každý jazyk a nepodporuje přepínání jazyka za běhu. Transloco načítá překlady za běhu, takže nasazujete jeden build a jazyky přepínáte za chodu.
Terminal
npm install @jsverse/transloco
2

Nakonfigurujte Transloco

Zaregistrujte Transloco v konfiguraci aplikace. Je potřeba zadat dostupné jazyky, nastavit výchozí jazyk a nakonfigurovat loader překladů. Transloco podporuje jak standalone komponenty (Angular 14+), tak vzor NgModule.

Standalone komponenty (doporučeno)

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,
    }),
  ],
};

Vzor NgModule

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 {}
Pokud se překlady zobrazují jako surové klíče typu „nav.home“ místo „Home“, nejčastější příčinou je, že TranslocoHttpLoader nemůže najít Vaše JSON soubory. Ověřte, že překladové soubory jsou v src/assets/i18n/ a že pole assets v angular.json obsahuje tuto cestu.

Vytvořte překladové soubory

Vytvořte jeden JSON soubor pro každý jazyk v src/assets/i18n/. Používejte vnořené klíče pro organizaci řetězců podle funkcionality. Transloco používá pro plurály a proměnné formát zpráv ICU.

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

Používejte překlady v šablonách a službách

Transloco nabízí tři způsoby překladu v šablonách: strukturální direktivu (*transloco), pipe (| transloco) a službu (TranslocoService) pro TypeScript kód. Pro většinu případů použití se doporučuje strukturální direktiva, protože vytvoří jedinou subscription a poskytne překladovou funkci celému bloku šablony.

Překlad v šabloně

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>
Použijte parametr read u strukturální direktivy, abyste omezili překlady na vnořený klíč. Vyhnete se tak opakování prefixu v každém volání t() a šablony budou přehlednější.

Překlad ve službě (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);
  }
}
Pipe transloco vytváří novou subscription pro každé použití. V šablonách s mnoha překládanými řetězci upřednostněte strukturální direktivu *transloco, která vytvoří jednu subscription pro celý blok.
4

Řešte plurály pomocí ICU message formátu

Transloco používá formát zpráv ICU pro plurály a select výrazy. ICU automaticky zpracuje složitá pravidla plurálů — arabština (6 forem), ruština (3 formy), japonština (1 forma) — a to vše z jediného message řetězce. Definujte plural pravidla v překladových souborech a Transloco za běhu vybere správnou formu.

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>
Nikdy neimplementujte vlastní plural logiku v komponentách. Jazyky mají dramaticky odlišná pravidla plurálů, která specifikace ICU už řeší. Nechte to na Transloco a ICU — Vaším úkolem je definovat správné plural formy v překladových souborech.

Chytré fallbacky locale s angular-locale-chain

Ve výchozím nastavení Transloco při chybějícím klíči přepne na Vaše výchozí locale. Uživatel pt-BR tak uvidí angličtinu místo naprosto použitelných překladů pt-PT. angular-locale-chain to řeší tím, že před předáním do Transloco provede deep-merge překladů z konfigurovatelného fallback řetězce. Každý klíč se doplní — žádné mezery, žádné chybějící překlady.

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 je open-source knihovna, která řeší bug #574 v Transloco — chybějící per-key fallback, když je překladový soubor jen částečně kompletní.

Doporučená struktura souborů

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

Automatizujte překlady

Jakmile máte Transloco nastavené, přeložte své locale soubory pomocí AI. V IDE požádejte svého AI asistenta o překlad zdrojového JSON souboru, nebo použijte i18n Agent CLI ve Vašem CI/CD pipeline pro plně automatizovanou lokalizaci.

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
Překládejte inkrementálně — když přidáte nové klíče do zdrojového souboru, přeložte jen diff místo regenerování všech souborů. Zachováte tím překlady zkontrolované člověkem a vyhnete se zbytečnému churnu.

Automatizujte kvalitu překladů

Zachyťte chybějící klíče a rozbité zástupné značky ještě před nasazením pomocí i18n-validate. Otestujte své UI pomocí pseudo-překladů přes i18n-pseudo dříve, než dorazí skutečné překlady.

Běžné nástrahy

Překlady se zobrazují jako surové klíče

TranslocoHttpLoader nemůže najít Vaše JSON soubory. Zkontrolujte, že soubory jsou v src/assets/i18n/, že pole assets v angular.json obsahuje tuto cestu a že názvy souborů přesně odpovídají konfiguraci availableLangs (rozlišuje se velikost písmen).

Scoped klíče se nevyhodnocují

Při použití Transloco scopes musí být překladové soubory v assets/i18n/[scope]/[lang].json, ne v kořenové složce i18n. Také se ujistěte, že je scope zaregistrovaný v poli providers komponenty pomocí TRANSLOCO_SCOPE.

Varování v konzoli v produkci

Pro produkční buildy nastavte v konfiguraci Transloco prodMode: true. Bez toho Transloco zapisuje do konzole varování o chybějících klíčích. Zároveň se tím vypnou kontroly určené pro vývoj, které přidávají režii.

Překlady při navigaci mezi routami probliknou

Lazy-loadované routy načítají překlady až po vykreslení komponenty, což způsobí krátké probliknutí nepřeložených klíčů. Použijte vestavěnou TRANSLOCO_LOADING_TEMPLATE pro zobrazení stavu načítání, nebo přednačtěte překlady v route guardu.

Regionální uživatelé vidí angličtinu místo nadřazeného locale

Vestavěný fallback v Transloco se spustí jen tehdy, když chybí celý locale soubor, ne při chybějících jednotlivých klíčích. Použijte angular-locale-chain pro deep-merge překladů z příbuzných locale (např. pt-BR → pt-PT → pt → English).

Vyzkoušejte i18n Agent nyní

Sem přetáhněte svůj překladový soubor

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

nebo klikněte a vyberte soubor

Cílové jazyky

Bez registraceOkamžitý odhad

Fallback lokalizací s angular-locale-chain

Když v regionální lokalizaci, jako je pt-BR, chybí překladový klíč, Angular TranslocoLoader skočí rovnou na výchozí lokalizaci, místo aby nejdřív zkontroloval nadřazenou lokalizaci pt.

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',
});

Podívejte se do našeho průvodce Locale Fallback, kde najdete úplný seznam podporovaných frameworků a 75 vestavěných řetězců. Learn more →

Angular i18n – FAQ