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.
Į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.
npm install @jsverse/translocoSukonfigū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
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
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 {}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/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}}"
}
}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
<!-- 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>Vertimas paslaugoje (TypeScript)
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);
}
}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ą.
// 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>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ų.
npm install angular-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(),
},
],
};Rekomenduojama failų struktūra
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.jsonAutomatizuoti 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.
# 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,esAutomatizuoti vertimo kokybę
Dažnos klaidos
Vertimuose rodomi neapdoroti raktai
Aprėpties raktai neišsprendžiami
Konsolės įspėjimai gamybinėje aplinkoje
Pereinant į maršrutą trumpam parodomi vertimo raktai
Regionų naudotojai vietoje pirminės lokalės mato anglų kalbą
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
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.
npm install angular-locale-chainimport { 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 →