Skip to main content

Angular i18n su Transloco: sąrankos ir vertimo vadovas

Nuo įdiegimo iki gamybinės aplinkos: sukonfigūruokite Transloco, apdorokite daugiskaitą ICU sintakse, pridėkite išmanias atsargines lokales ir automatizuokite vertimus naudodami DI.

1

Įdiegti Transloco

Transloco yra populiariausia trečiosios šalies i18n biblioteka, skirta Angular. Ji suteikia vertimų įkėlimą vykdymo metu, ICU pranešimų formato palaikymą, tingiai įkeliamas aprėptis ir tvarkingą šablonų API su struktūrinėmis direktyvomis bei konvejeriais.

Kodėl Transloco, o ne integruotas Angular i18n? Integruotam Angular sprendimui reikia atskiro kiekvienos kalbos komponavimo ir jis nepalaiko kalbos keitimo vykdymo metu. Transloco įkelia vertimus vykdymo metu, todėl išleidžiate vieną komponavimą ir galite akimirksniu keisti kalbas.
Terminal
npm install @jsverse/transloco
2

Sukonfigūruoti Transloco

Užregistruokite Transloco programos konfigūracijoje. Turite pateikti esamas kalbas, nustatyti numatytąją kalbą ir sukonfigūruoti vertimų įkėlimo priemonę. Transloco palaiko ir savarankiškus komponentus (Angular 14+), ir NgModule šablonus.

Savarankiški komponentai (rekomenduojama)

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 šablonas

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 {}
Jei vietoje „Pradžia“ vertimuose rodomi neapdoroti raktai, pavyzdžiui, „nav.home“, dažniausia priežastis – TranslocoHttpLoader neranda JSON failų. Patikrinkite, ar vertimo failai yra src/assets/i18n/ ir ar angular.json masyve assets įtrauktas šis kelias.

Sukurti vertimo failus

Sukurkite po vieną JSON failą kiekvienai kalbai src/assets/i18n/ kataloge. Eilutes pagal funkciją tvarkykite įdėtiniais raktais. Transloco daugiskaitai ir kintamiesiems naudoja ICU pranešimų formatą.

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

Naudoti vertimus šablonuose ir paslaugose

Transloco suteikia tris vertimo šablonuose būdus: struktūrinę direktyvą (*transloco), konvejerį (| transloco) ir paslaugą (TranslocoService) TypeScript kodui. Daugeliu atvejų rekomenduojama struktūrinė direktyva, nes ji sukuria vieną prenumeratą ir suteikia vertimo funkciją visam šablono blokui.

Vertimas šablone

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>
Naudokite struktūrinės direktyvos parametrą read, kad vertimai būtų apriboti iki įdėtinio rakto. Taip nereikia kartoti prefikso kiekviename t() iškvietime, o šablonai tampa tvarkingesni.

Vertimas paslaugoje (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);
  }
}
Kiekvieną kartą panaudojus transloco konvejerį sukuriama nauja prenumerata. Daug išverstų eilučių turinčiuose šablonuose rinkitės struktūrinę direktyvą *transloco, kuri sukuria vieną prenumeratą visam blokui.
4

Apdoroti daugiskaitą ICU pranešimų formatu

Transloco daugiskaitai ir pasirinkimo išraiškoms naudoja ICU pranešimų formatą. ICU automatiškai apdoroja sudėtingas daugiskaitos taisykles – arabų (6 formos), rusų (3 formos), japonų (1 forma) – vienoje pranešimo eilutėje. Apibrėžkite daugiskaitos taisykles vertimo failuose, o vykdymo metu Transloco parinks tinkamą formą.

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>
Niekada komponentuose nekurkite pasirinktinės daugiskaitos logikos. Kalbų daugiskaitos taisyklės labai skiriasi, o ICU specifikacija jas jau apdoroja. Leiskite darbą atlikti Transloco ir ICU – jums tereikia vertimo failuose apibrėžti tinkamas daugiskaitos formas.

Išmanios atsarginės lokalės su angular-locale-chain

Pagal numatytąją nuostatą trūkstant vertimo rakto Transloco grįžta prie numatytosios lokalės. pt-BR naudotojas vietoje puikių pt-PT vertimų mato anglų kalbą. angular-locale-chain tai ištaiso prieš perduodamas vertimus Transloco giliai sujungdamas konfigūruojamos atsarginės grandinės vertimus. Užpildomas kiekvienas raktas – jokių spragų ar trūkstamų vertimų.

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 yra atvirojo kodo biblioteka, išsprendžianti Transloco klaidą Nr. 574 – nėra kiekvieno rakto atsarginio varianto, kai vertimo failas užpildytas tik iš dalies.

Rekomenduojama failų 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

Automatizuoti vertimus

Baigę Transloco sąranką išverskite lokalės failus naudodami DI. IDE paprašykite DI asistento išversti šaltinio JSON failą arba visiškai automatizuotam lokalizavimui naudokite i18n Agent CLI CI/CD konvejeryje.

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
Verskite palaipsniui – pridėję naujų raktų prie šaltinio failo išverskite tik skirtumą, o ne generuokite visus failus iš naujo. Taip išsaugomi žmonių peržiūrėti vertimai ir išvengiama nereikalingų pakeitimų.

Automatizuoti vertimo kokybę

Naudodami i18n-validate prieš išleidimą aptikite trūkstamus raktus ir sugadintus vietos rezervavimo ženklus. Kol dar nėra tikrų vertimų, patikrinkite UI su i18n-pseudo pseudoverstimais.

Dažnos klaidos

Vertimuose rodomi neapdoroti raktai

TranslocoHttpLoader neranda JSON failų. Patikrinkite, ar failai yra src/assets/i18n/, ar angular.json masyve assets įtrauktas šis kelias ir ar failų pavadinimai tiksliai atitinka availableLangs konfigūraciją (skiriamos didžiosios ir mažosios raidės).

Aprėpties raktai neišsprendžiami

Naudojant Transloco aprėptis vertimo failai turi būti assets/i18n/[scope]/[lang].json, o ne šakniniame i18n aplanke. Taip pat įsitikinkite, kad aprėptis užregistruota komponento teikėjų masyve naudojant TRANSLOCO_SCOPE.

Konsolės įspėjimai gamybinėje aplinkoje

Gamybiniams komponavimams Transloco konfigūracijoje nustatykite prodMode: true. Be jo Transloco konsolėje registruoja įspėjimus apie trūkstamus raktus. Taip pat išjungiamos papildomą naštą kuriančios kūrimo patikros.

Pereinant į maršrutą trumpam parodomi vertimo raktai

Tingiai įkeliami maršrutai gauna vertimus jau po komponento atvaizdavimo, todėl trumpam parodomi neišversti raktai. Naudokite integruotą Transloco TRANSLOCO_LOADING_TEMPLATE įkėlimo būsenai rodyti arba iš anksto įkelkite vertimus maršruto apsaugoje.

Regionų naudotojai vietoje pirminės lokalės mato anglų kalbą

Integruotas Transloco atsarginis variantas suaktyvinamas tik tada, kai nėra viso lokalės failo, o ne atskirų raktų. Naudokite angular-locale-chain susijusių lokalių vertimams giliai sujungti (pvz., pt-BR grįžta prie pt-PT, tada pt ir galiausiai anglų kalbos).

Išbandykite i18n Agent dabar

Nuvilkite vertimo failą čia

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

arba spustelėkite norėdami pasirinkti

Tikslinės kalbos

Registruotis nereikiaMomentinis įvertis

Atsarginė lokalė su angular-locale-chain

Kai regioninėje lokalėje, pavyzdžiui, pt-BR, trūksta vertimo rakto, Angular TranslocoLoader iškart pereina prie numatytosios lokalės, užuot pirmiausia patikrinęs pirminę lokalę 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',
});

Visą palaikomų sistemų sąrašą ir 75 integruotas grandines rasite mūsų atsarginių lokalių vadove. Learn more →

DUK apie Angular i18n