Skip to main content

Angular i18n s Transloco: príručka nastavenia a prekladu

Od inštalácie po produkciu: nakonfigurujte Transloco, spracujte tvary množného čísla syntaxou ICU, pridajte inteligentné náhradné lokalizácie a automatizujte preklady pomocou AI.

1

Nainštalujte Transloco

Transloco je najobľúbenejšia knižnica i18n od tretej strany pre Angular. Ponúka načítanie prekladov za behu, podporu formátu správ ICU, rozsahy načítavané na požiadanie a čisté rozhranie API šablón so štrukturálnymi direktívami aj filtrami.

Prečo uprednostniť Transloco pred vstavaným i18n v Angular? Vstavané riešenie Angular vyžaduje samostatné zostavenie pre každý jazyk a nepodporuje prepínanie jazykov za behu. Transloco načítava preklady za behu, takže vydáte jedno zostavenie a jazyky prepínate okamžite.
Terminal
npm install @jsverse/transloco
2

Nakonfigurujte Transloco

Zaregistrujte Transloco v konfigurácii aplikácie. Musíte zadať dostupné jazyky, nastaviť predvolený jazyk a nakonfigurovať načítavanie prekladov. Transloco podporuje samostatné komponenty (Angular 14+) aj vzory NgModule.

Samostatné komponenty (odporúčané)

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 {}
Ak sa namiesto textu „Home“ zobrazujú nespracované kľúče, ako napríklad „nav.home“, najčastejšou príčinou je, že TranslocoHttpLoader nedokáže nájsť Vaše súbory JSON. Overte, že prekladové súbory sú v src/assets/i18n/ a že pole assets v angular.json obsahuje túto cestu.

Vytvorte prekladové súbory

Vytvorte jeden súbor JSON pre každý jazyk v src/assets/i18n/. Reťazce usporiadajte podľa funkcií pomocou vnorených kľúčov. Transloco používa formát správ ICU pre tvary množného čísla a premenné.

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žívajte preklady v šablónach a službách

Transloco ponúka tri spôsoby prekladu v šablónach: štrukturálnu direktívu (*transloco), filter (| transloco) a službu (TranslocoService) pre kód TypeScript. Vo väčšine prípadov sa odporúča štrukturálna direktíva, pretože vytvorí jediné prihlásenie na odber a poskytne prekladovú funkciu celému bloku šablóny.

Preklad v šablóne

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>
Pomocou parametra read štrukturálnej direktívy obmedzte preklady na vnorený kľúč. Nemusíte tak opakovať predponu v každom volaní t() a šablóny zostanú čistejšie.

Preklad v službe (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);
  }
}
Filter transloco vytvorí nové prihlásenie na odber pri každom použití. V šablónach s mnohými preloženými reťazcami uprednostnite štrukturálnu direktívu *transloco, ktorá vytvorí jediné prihlásenie na odber pre celý blok.
4

Spracujte tvary množného čísla formátom správ ICU

Transloco používa formát správ ICU pre tvary množného čísla a výrazy select. ICU automaticky spracuje zložité pravidlá množného čísla – arabčinu (6 tvarov), ruštinu (3 tvary) aj japončinu (1 tvar) – z jediného reťazca správy. Pravidlá množného čísla definujete v prekladových súboroch a Transloco za behu vyberie správny tvar.

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 vo svojich komponentoch neimplementujte vlastnú logiku množného čísla. Jazyky majú veľmi odlišné pravidlá, ktoré už spracúva špecifikácia ICU. Nechajte pracovať Transloco a ICU – Vašou úlohou je definovať správne tvary množného čísla v prekladových súboroch.

Inteligentné náhradné lokalizácie pomocou angular-locale-chain

Keď prekladový kľúč chýba, Transloco sa predvolene vráti k Vašej predvolenej lokalizácii. Používateľ pt-BR tak namiesto úplne vhodného prekladu pt-PT uvidí angličtinu. angular-locale-chain to rieši hĺbkovým zlúčením prekladov z konfigurovateľného reťazca náhradných lokalizácií ešte pred ich odovzdaním Transloco. Vyplní sa každý kľúč – bez medzier a chýbajúcich prekladov.

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 knižnica s otvoreným zdrojovým kódom, ktorá rieši chybu Transloco č. 574 – chýbajúcu náhradu jednotlivých kľúčov pri čiastočne úplnom prekladovom súbore.

Odporúčaná štruktúra súborov

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 preklady

Po dokončení nastavenia Transloco preložte svoje lokalizačné súbory pomocou AI. Vo svojom IDE požiadajte asistenta AI o preklad zdrojového súboru JSON alebo použite CLI i18n Agent vo svojej pipeline CI/CD na plne automatizovanú lokalizáciu.

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
Prekladajte prírastkovo – po pridaní nových kľúčov do zdrojového súboru preložte iba rozdiel namiesto opätovného generovania všetkých súborov. Zachováte tak preklady skontrolované človekom a vyhnete sa zbytočným zmenám.

Automatizujte kvalitu prekladu

Pomocou i18n-validate odhaľte chýbajúce kľúče a poškodené zástupné symboly ešte pred vydaním. Kým dorazia skutočné preklady, otestujte svoje rozhranie pseudoprekladmi pomocou i18n-pseudo.

Bežné nástrahy

Preklady zobrazujú nespracované kľúče

TranslocoHttpLoader nedokáže nájsť Vaše súbory JSON. Skontrolujte, že súbory sú v src/assets/i18n/, pole assets v angular.json obsahuje túto cestu a názvy súborov sa presne zhodujú s konfiguráciou availableLangs (rozlišujú sa malé a veľké písmená).

Kľúče s rozsahom sa nevyhodnocujú

Pri použití rozsahov Transloco musia byť prekladové súbory v assets/i18n/[scope]/[lang].json, nie v koreňovom priečinku i18n. Overte tiež, že je rozsah zaregistrovaný v poli providers komponentu pomocou TRANSLOCO_SCOPE.

Upozornenia v konzole v produkcii

Pre produkčné zostavenia nastavte v konfigurácii Transloco hodnotu prodMode: true. Bez nej Transloco zapisuje do konzoly upozornenia na chýbajúce kľúče. Toto nastavenie tiež vypne vývojové kontroly, ktoré pridávajú réžiu.

Pri navigácii medzi trasami preklady bliknú

Trasy načítavané na požiadanie získajú preklady až po vykreslení komponentu, čo spôsobí krátke bliknutie nepreložených kľúčov. Na zobrazenie stavu načítavania použite vstavanú šablónu TRANSLOCO_LOADING_TEMPLATE alebo preklady vopred načítajte v ochrane trasy.

Regionálni používatelia vidia angličtinu namiesto nadradenej lokalizácie

Vstavaná náhradná lokalizácia Transloco sa aktivuje iba vtedy, keď chýba celý lokalizačný súbor, nie jednotlivé kľúče. Pomocou angular-locale-chain hĺbkovo zlúčte preklady zo súvisiacich lokalizácií (napríklad pt-BR použije pt-PT, potom pt a napokon angličtinu).

Vyskúšajte i18n Agent teraz

Potiahnite súbor na preklad sem

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

alebo kliknite a vyberte súbor

Cieľové jazyky

Bez registrácieOkamžitý odhad

Náhradná lokalizácia pomocou angular-locale-chain

Keď v regionálnej lokalizácii, ako je pt-BR, chýba prekladový kľúč, TranslocoLoader v Angular prejde priamo na predvolenú lokalizáciu namiesto toho, aby najprv skontroloval nadradenú lokalizáciu 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',
});

Úplný zoznam podporovaných frameworkov a 75 vstavaných reťazcov nájdete v našej príručke k náhradným lokalizáciám. Learn more →

Časté otázky k Angular i18n