Skip to main content

Angular i18n ar Transloco: iestatīšanas un tulkošanas ceļvedis

No instalēšanas līdz produkcijas videi: konfigurējiet Transloco, apstrādājiet daudzskaitli ar ICU sintaksi, pievienojiet viedas lokalizāciju atkāpšanās ķēdes un automatizējiet tulkošanu ar MI.

1

Instalēt Transloco

Transloco ir populārākā trešās puses i18n bibliotēka Angular. Tā nodrošina tulkojumu ielādi izpildlaikā, ICU ziņojumu formāta atbalstu, slinki ielādētas tvērumu zonas un pārskatāmu veidņu API ar strukturālām direktīvām un konveijeriem.

Kādēļ Transloco, nevis Angular iebūvētais i18n? Angular iebūvētajam risinājumam vajadzīgs atsevišķs būvējums katrai valodai un tas neatbalsta valodas pārslēgšanu izpildlaikā. Transloco ielādē tulkojumus izpildlaikā, tādēļ izlaižat vienu būvējumu un varat uzreiz pārslēgt valodas.
Terminal
npm install @jsverse/transloco
2

Konfigurēt Transloco

Reģistrējiet Transloco lietotnes konfigurācijā. Jānorāda pieejamās valodas, jāiestata noklusējuma valoda un jākonfigurē tulkojumu ielādētājs. Transloco atbalsta gan patstāvīgus komponentus (Angular 14+), gan NgModule modeļus.

Patstāvīgi komponenti (ieteicams)

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 modelis

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 {}
Ja tulkojumu vietā tiek rādītas neapstrādātas atslēgas, piemēram, „nav.home“, nevis „Sākums“, visbiežākais iemesls ir tas, ka TranslocoHttpLoader nevar atrast JSON failus. Pārbaudiet, vai tulkošanas faili atrodas src/assets/i18n/ un angular.json masīvā assets ir iekļauts šis ceļš.

Izveidot tulkošanas failus

Izveidojiet vienu JSON failu katrai valodai direktorijā src/assets/i18n/. Sakārtojiet virknes pēc funkcijas ar ligzdotām atslēgām. Transloco daudzskaitlim un mainīgajiem izmanto ICU ziņojumu formātu.

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

Izmantot tulkojumus veidnēs un pakalpojumos

Transloco piedāvā trīs tulkošanas veidus veidnēs: strukturālo direktīvu (*transloco), konveijeru (| transloco) un pakalpojumu (TranslocoService) TypeScript kodam. Vairumā gadījumu ieteicama strukturālā direktīva, jo tā izveido vienu abonementu un nodrošina tulkošanas funkciju visam veidnes blokam.

Tulkošana veidnē

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>
Izmantojiet strukturālās direktīvas parametru read, lai ierobežotu tulkojumus ar ligzdotu atslēgu. Tas ļauj neatkārtot prefiksu katrā t() izsaukumā un padara veidnes pārskatāmākas.

Tulkošana pakalpojumā (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);
  }
}
Katrā transloco konveijera lietojumā tiek izveidots jauns abonements. Veidnēs ar daudzām tulkotām virknēm izvēlieties strukturālo direktīvu *transloco, kas izveido vienu abonementu visam blokam.
4

Apstrādāt daudzskaitli ar ICU ziņojumu formātu

Transloco daudzskaitlim un izvēles izteiksmēm izmanto ICU ziņojumu formātu. ICU automātiski apstrādā sarežģītas daudzskaitļa kārtulas — arābu (6 formas), krievu (3 formas), japāņu (1 forma) — vienā ziņojuma virknē. Definējiet daudzskaitļa kārtulas tulkošanas failos, un Transloco izpildlaikā izvēlēsies pareizo 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>
Nekad neveidojiet pielāgotu daudzskaitļa loģiku komponentos. Valodu daudzskaitļa kārtulas krasi atšķiras, un ICU specifikācija tās jau apstrādā. Ļaujiet Transloco un ICU paveikt darbu — jums tikai jādefinē pareizās daudzskaitļa formas tulkošanas failos.

Viedas lokalizāciju atkāpšanās ķēdes ar angular-locale-chain

Pēc noklusējuma, ja trūkst tulkojuma atslēgas, Transloco atkāpjas uz noklusējuma lokalizāciju. pt-BR lietotājs labu pt-PT tulkojumu vietā redz angļu valodu. angular-locale-chain to novērš, pirms nodošanas Transloco dziļi sapludinot konfigurējamas atkāpšanās ķēdes tulkojumus. Tiek aizpildīta katra atslēga — bez nepilnībām un trūkstošiem tulkojumiem.

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 ir atvērtā pirmkoda bibliotēka, kas atrisina Transloco kļūdu Nr. 574 — trūkst atkāpšanās katrai atslēgai, ja tulkošanas fails ir aizpildīts tikai daļēji.

Ieteicamā failu struktūra

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

Automatizēt tulkošanu

Kad Transloco iestatīšana ir pabeigta, tulkojiet lokalizācijas failus ar MI. IDE lūdziet MI asistentam iztulkot avota JSON failu vai pilnībā automatizētai lokalizācijai izmantojiet i18n Agent CLI CI/CD konveijerā.

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
Tulkojiet pakāpeniski — pievienojot avota failam jaunas atslēgas, tulkojiet tikai izmaiņas, nevis ģenerējiet visus failus no jauna. Tas saglabā cilvēku pārskatītos tulkojumus un novērš nevajadzīgas izmaiņas.

Automatizēt tulkojumu kvalitāti

Ar i18n-validate pirms izlaišanas atrodiet trūkstošās atslēgas un bojātos vietturus. Kamēr īstie tulkojumi vēl nav gatavi, pārbaudiet UI ar i18n-pseudo pseidotulkojumiem.

Biežākās kļūdas

Tulkojumos redzamas neapstrādātas atslēgas

TranslocoHttpLoader nevar atrast JSON failus. Pārbaudiet, vai faili atrodas src/assets/i18n/, angular.json masīvā assets ir iekļauts šis ceļš un failu nosaukumi precīzi atbilst availableLangs konfigurācijai (reģistrjutīgi).

Tvēruma atslēgas netiek atrisinātas

Izmantojot Transloco tvērumus, tulkošanas failiem jāatrodas assets/i18n/[scope]/[lang].json, nevis saknes i18n mapē. Pārliecinieties arī, ka tvērums ir reģistrēts komponenta nodrošinātāju masīvā ar TRANSLOCO_SCOPE.

Konsoles brīdinājumi produkcijas vidē

Produkcijas būvējumiem Transloco konfigurācijā iestatiet prodMode: true. Bez tā Transloco konsolē reģistrē brīdinājumus par trūkstošām atslēgām. Tas arī atspējo papildu slodzi radošās izstrādes laika pārbaudes.

Pārejot uz maršrutu, īslaicīgi parādās tulkojumu atslēgas

Slinki ielādēti maršruti iegūst tulkojumus pēc komponenta atveides, tādēļ uz brīdi parādās netulkotas atslēgas. Izmantojiet Transloco iebūvēto TRANSLOCO_LOADING_TEMPLATE ielādes stāvokļa rādīšanai vai iepriekš ielādējiet tulkojumus maršruta sargā.

Reģionālie lietotāji vecāklokalizācijas vietā redz angļu valodu

Transloco iebūvētā atkāpšanās aktivizējas tikai tad, ja trūkst visa lokalizācijas faila, nevis atsevišķu atslēgu. Izmantojiet angular-locale-chain, lai dziļi sapludinātu saistītu lokalizāciju tulkojumus (piemēram, pt-BR atkāpjas uz pt-PT, tad pt un visbeidzot angļu valodu).

Izmēģiniet i18n Agent tūlīt

Nometiet tulkošanas failu šeit

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

vai noklikšķiniet, lai izvēlētos

Mērķa valodas

Reģistrācija nav vajadzīgaTūlītēja tāme

Lokalizācijas atkāpšanās ar angular-locale-chain

Ja reģionālajā lokalizācijā, piemēram, pt-BR, trūkst tulkojuma atslēgas, Angular TranslocoLoader uzreiz pāriet uz noklusējuma lokalizāciju, nevis vispirms pārbauda vecāklokalizāciju 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',
});

Pilnu atbalstīto sistēmu sarakstu un 75 iebūvētās ķēdes skatiet mūsu lokalizāciju atkāpšanās ceļvedī. Learn more →

Bieži uzdotie jautājumi par Angular i18n