Skip to main content

Angular i18n Translocóval: beállítási és fordítási útmutató

A telepítéstől az éles környezetig: állítsa be a Translocót, kezelje a többes számot ICU-szintaxissal, adjon intelligens területi tartalékokat, és automatizálja a fordítást mesterséges intelligenciával.

1

A Transloco telepítése

A Transloco az Angular legnépszerűbb külső i18n-könyvtára. Futásidejű fordításbetöltést, ICU-üzenetformátum-támogatást, lusta betöltésű hatóköröket, valamint strukturális direktívákat és pipe-okat kínáló letisztult sablon-API-t biztosít.

Miért Transloco az Angular beépített i18n-megoldása helyett? Az Angular beépített megoldása nyelvenként külön buildet igényel, és nem támogatja a futásidejű nyelvváltást. A Transloco futásidőben tölti be a fordításokat, így egyetlen buildet szállít, és menet közben válthat nyelvet.
Terminal
npm install @jsverse/transloco
2

A Transloco beállítása

Regisztrálja a Translocót az alkalmazás konfigurációjában. Meg kell adnia az elérhető nyelveket, be kell állítania az alapértelmezett nyelvet és a fordításbetöltőt. A Transloco az önálló komponenseket (Angular 14+) és az NgModule-mintákat is támogatja.

Önálló komponensek (ajánlott)

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-minta

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 {}
Ha a fordítások „Home” helyett nyers kulcsként, például „nav.home” formában jelennek meg, a leggyakoribb ok, hogy a TranslocoHttpLoader nem találja a JSON-fájlokat. Ellenőrizze, hogy a fordításfájlok a src/assets/i18n/ könyvtárban vannak-e, és az angular.json assets tömbje tartalmazza-e ezt az útvonalat.

Fordítási fájlok létrehozása

Hozzon létre nyelvenként egy JSON-fájlt a src/assets/i18n/ könyvtárban. A karakterláncokat funkciónként egymásba ágyazott kulcsokkal rendezze. A Transloco ICU-üzenetformátumot használ a többes számokhoz és változókhoz.

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

Fordítások használata sablonokban és szolgáltatásokban

A Transloco háromféle fordítási módot kínál sablonokban: strukturális direktívát (*transloco), pipe-ot (| transloco) és TypeScript-kódhoz szolgáltatást (TranslocoService). A legtöbb esetben a strukturális direktíva ajánlott, mert egyetlen előfizetést hoz létre, és a teljes sablonblokk számára elérhetővé teszi a fordítási függvényt.

Sablonfordítás

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>
A fordítások egymásba ágyazott kulcsra szűkítéséhez használja a strukturális direktíva read paraméterét. Így nem kell minden t() hívásban megismételni az előtagot, és tisztább lesz a sablon.

Szolgáltatásalapú fordítás (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);
  }
}
A transloco pipe minden használatnál új előfizetést hoz létre. Sok fordított karakterláncot tartalmazó sablonokban részesítse előnyben a *transloco strukturális direktívát, amely a teljes blokkhoz egyetlen előfizetést hoz létre.
4

Többes szám kezelése ICU-üzenetformátummal

A Transloco ICU-üzenetformátumot használ a többes számokhoz és select kifejezésekhez. Az ICU automatikusan kezeli az összetett többesszám-szabályokat — arab (6 alak), orosz (3 alak), japán (1 alak) — egyetlen üzenetkarakterláncból. Határozza meg a többesszám-szabályokat a fordításfájlokban, és a Transloco futásidőben kiválasztja a megfelelő alakot.

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>
Soha ne valósítson meg egyéni többesszám-logikát a komponensekben. A nyelvek többesszám-szabályai rendkívül eltérők, ezeket az ICU-specifikáció már kezeli. Bízza a munkát a Translocóra és az ICU-ra — Önnek csak a megfelelő többes számú alakokat kell meghatároznia a fordításfájlokban.

Intelligens területi tartalékok angular-locale-chain használatával

Alapértelmezés szerint hiányzó fordítási kulcsnál a Transloco az alapértelmezett területre vált. Egy pt-BR felhasználó angolt lát a megfelelő pt-PT fordítás helyett. Az angular-locale-chain ezt úgy javítja, hogy a fordításokat egy beállítható tartalékláncból mélyen egyesíti, mielőtt átadná a Translocónak. Minden kulcs kitöltődik — nincsenek hézagok vagy hiányzó fordítások.

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(),
    },
  ],
};
Az angular-locale-chain egy nyílt forráskódú könyvtár, amely megoldja a Transloco 574-es hibáját — a kulcsonkénti tartalék hiányát részlegesen elkészült fordításfájl esetén.

Ajánlott fájlszerkezet

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

Fordítások automatizálása

A Transloco beállítása után fordítsa le területifájljait mesterséges intelligenciával. Kérje meg az IDE MI-alapú segédét a forrás JSON-fájl lefordítására, vagy használja az i18n Agent parancssori eszközét a CI/CD-folyamatban a teljesen automatizált lokalizációhoz.

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
Fordítson fokozatosan — amikor új kulcsokat ad a forrásfájlhoz, csak a különbséget fordítsa le az összes fájl újragenerálása helyett. Így megmaradnak az ember által ellenőrzött fordítások, és elkerülhető a szükségtelen változtatási zaj.

A fordítási minőség automatizálása

Az i18n-validate segítségével még kiadás előtt találja meg a hiányzó kulcsokat és hibás helyőrzőket. Az i18n-pseudo használatával valódi fordítások beérkezése előtt tesztelje a felületet pszeudofordításokkal.

Gyakori buktatók

A fordítások nyers kulcsokat jelenítenek meg

A TranslocoHttpLoader nem találja a JSON-fájlokat. Ellenőrizze, hogy a fájlok a src/assets/i18n/ könyvtárban vannak-e, az angular.json assets tömbje tartalmazza-e ezt az útvonalat, és a fájlnevek betűérzékenyen egyeznek-e az availableLangs beállítással.

A hatókörös kulcsok nem oldódnak fel

Transloco-hatókörök használatakor a fordításfájloknak az assets/i18n/[scope]/[lang].json útvonalon kell lenniük, nem a gyökér i18n-mappában. Gondoskodjon arról is, hogy a hatókör TRANSLOCO_SCOPE használatával regisztrálva legyen a komponens providers tömbjében.

Konzolfigyelmeztetések éles környezetben

Éles buildeknél állítsa prodMode: true értékre a Transloco konfigurációját. Enélkül a Transloco a konzolra írja a hiányzó kulcsok figyelmeztetéseit. A beállítás a többletterhet jelentő fejlesztésidejű ellenőrzéseket is kikapcsolja.

A fordítások felvillannak útvonalváltáskor

A lusta betöltésű útvonalak a komponens renderelése után kérik le a fordításokat, ezért rövid időre lefordítatlan kulcsok villannak fel. Használja a Transloco beépített TRANSLOCO_LOADING_TEMPLATE elemét betöltési állapot megjelenítéséhez, vagy töltesse elő a fordításokat útvonalőrrel.

A regionális felhasználók a szülőterület helyett angol szöveget látnak

A Transloco beépített tartaléka csak akkor aktiválódik, ha egy teljes területifájl hiányzik, egyes hiányzó kulcsoknál nem. Az angular-locale-chain segítségével mélyen egyesítse a kapcsolódó területek fordításait (például a pt-BR előbb pt-PT, majd pt, végül angol változatra vált).

Try i18n Agent Now

Drop your translation file here

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

or click to browse

Target languages

No signup requiredInstant estimate

Területi tartalék angular-locale-chain használatával

Ha egy fordítási kulcs hiányzik egy regionális területi beállításból, például a pt-BR változatból, az Angular TranslocoLoadere a pt szülőterület ellenőrzése helyett közvetlenül az alapértelmezett területre vált.

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

A támogatott keretrendszerek és a 75 beépített lánc teljes listájáért tekintse meg Területi tartalék útmutatónkat. Learn more →

Angular i18n – gyakori kérdések