Skip to main content

Angular i18n Transloco'ga: seadistus- ja tõlkejuhend

Paigaldamisest tootmiskeskkonnani: seadista Transloco, töötle mitmusevorme ICU süntaksiga, lisa nutikad varulokaadid ja automatiseeri tõlked tehisintellektiga.

1

Paigalda Transloco

Transloco on Angular'i populaarseim kolmanda osapoole i18n-teek. See pakub tõlgete käitusaegset laadimist, ICU sõnumivormingu tuge, laisalt laaditavaid skoope ning puhast malli API-t nii struktuuridirektiivide kui ka pipe'idega.

Miks Transloco, mitte Angular'i sisseehitatud i18n? Angular'i sisseehitatud lahendus nõuab iga keele jaoks eraldi ehitust ega toeta käitusaegset keelevahetust. Transloco laadib tõlked käitusajal, nii et avaldad ühe ehituse ja vahetad keelt lennult.
Terminal
npm install @jsverse/transloco
2

Seadista Transloco

Registreeri Transloco rakenduse seadistuses. Määra saadaolevad keeled, vaikekeel ja tõlkelaadur. Transloco toetab nii eraldiseisvaid komponente (Angular 14+) kui ka NgModule'i mustreid.

Eraldiseisvad komponendid (soovitatud)

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'i muster

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 {}
Kui tõlgete asemel kuvatakse "Home" asemel töötlemata võtmeid, näiteks "nav.home", ei leia TranslocoHttpLoader tõenäoliselt sinu JSON-faile. Veendu, et tõlkefailid asuksid kataloogis src/assets/i18n/ ning faili angular.json massiiv assets sisaldaks seda rada.

Loo tõlkefailid

Loo iga keele jaoks üks JSON-fail kataloogi src/assets/i18n/. Korrasta stringid funktsioonide järgi pesastatud võtmetega. Transloco kasutab mitmusevormide ja muutujate jaoks ICU sõnumivormingut.

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

Kasuta tõlkeid mallides ja teenustes

Transloco pakub mallides tõlkimiseks kolme viisi: struktuuridirektiiv (*transloco), pipe (| transloco) ja TypeScript'i koodi teenus (TranslocoService). Struktuuridirektiiv on enamiku juhtude jaoks soovitatav, sest see loob ühe tellimuse ja annab tõlkefunktsiooni kogu malliplokile.

Tõlge mallis

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>
Piira tõlked struktuuridirektiivi parameetriga read pesastatud võtmele. Nii ei pea igas t()-kutses eesliidet kordama ja mallid jäävad puhtamaks.

Tõlge teenuses (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);
  }
}
transloco pipe loob iga kasutuskorra jaoks uue tellimuse. Paljude tõlgitud stringidega mallides eelista *transloco struktuuridirektiivi, mis loob kogu ploki jaoks ühe tellimuse.
4

Töötle mitmusevorme ICU sõnumivorminguga

Transloco kasutab mitmusevormide ja select-avaldiste jaoks ICU sõnumivormingut. ICU töötleb keerukaid mitmusereegleid automaatselt — araabia keel (kuus vormi), vene keel (kolm vormi), jaapani keel (üks vorm) — kõik ühes sõnumistringis. Määra mitmusereeglid tõlkefailides ning Transloco valib käitusajal õige vormi.

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>
Ära kunagi rakenda komponentides kohandatud mitmuseloogikat. Keelte mitmusereeglid erinevad tohutult ning ICU spetsifikatsioon juba haldab neid. Lase Translocal ja ICU-l töö teha — sinu ülesanne on määrata tõlkefailides õiged mitmusevormid.

Nutikad varulokaadid angular-locale-chainiga

Vaikimisi lülitub Transloco puuduva tõlkevõtme korral vaikelokaadile. pt-BR kasutaja näeb täiesti sobivate pt-PT tõlgete asemel inglise keelt. angular-locale-chain parandab selle, süvaühendades seadistatava varulokaadiahela tõlked enne nende Transloco'le andmist. Iga võti täidetakse — lünki ega puuduvaid tõlkeid pole.

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 on avatud lähtekoodiga teek, mis lahendab Transloco vea #574 — võtmekohane varulokaat puudub, kui tõlkefail on ainult osaliselt valmis.

Soovituslik failistruktuur

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

Automatiseeri tõlked

Kui Transloco on seadistatud, tõlgi lokaadifailid tehisintellektiga. Palu IDE-s oma tehisintellekti abilisel JSON-lähtefail tõlkida või kasuta täielikult automatiseeritud lokaliseerimiseks CI/CD-konveieris i18n Agent'i CLI-d.

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
Tõlgi järk-järgult — kui lisad lähtefaili uusi võtmeid, tõlgi kõigi failide uuesti loomise asemel ainult diff. Nii säilivad inimeste ülevaadatud tõlked ja väldid tarbetuid muudatusi.

Automatiseeri tõlkekvaliteet

Leia i18n-validate'i abil puuduvad võtmed ja katkised kohatäitjad enne avaldamist. Testi kasutajaliidest i18n-pseudo abil pseudotõlgetega enne päris tõlgete saabumist.

Levinud komistuskivid

Tõlgetes kuvatakse töötlemata võtmed

TranslocoHttpLoader ei leia sinu JSON-faile. Kontrolli, et failid asuksid kataloogis src/assets/i18n/, faili angular.json massiiv assets sisaldaks seda rada ning failinimed vastaksid täpselt ja tõstutundlikult availableLangs-seadistusele.

Skoobitud võtmeid ei lahendata

Transloco skoopide kasutamisel peavad tõlkefailid asuma rajal assets/i18n/[scope]/[lang].json, mitte i18n-i juurkaustas. Veendu ka, et skoop oleks registreeritud komponendi providers-massiivis väärtusega TRANSLOCO_SCOPE.

Konsoolihoiatused tootmiskeskkonnas

Määra tootmisehituste Transloco seadistuses prodMode: true. Ilma selleta logib Transloco puuduvate võtmete hoiatused konsooli. See lülitab välja ka arendusaegsed lisakoormust tekitavad kontrollid.

Tõlked vilguvad marsruudil liikumisel

Laisalt laaditavad marsruudid hangivad tõlked pärast komponendi renderdamist, põhjustades tõlkimata võtmete lühikese vilgatuse. Näita laadimisolekut Transloco sisseehitatud TRANSLOCO_LOADING_TEMPLATE abil või eellaadi tõlked marsruudivalvuris.

Piirkondlikud kasutajad näevad põhilokaadi asemel inglise keelt

Transloco sisseehitatud varulokaat käivitub ainult terve lokaadifaili puudumisel, mitte üksikute puuduvate võtmete puhul. Süvaühenda seotud lokaatide tõlked angular-locale-chainiga (nt pt-BR taandub pt-PT-le, siis pt-le ja lõpuks inglise keelele).

Proovi i18n Agent'i kohe

Kukuta tõlkefail siia

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

või klõpsa faili valimiseks

Sihtkeeled

Registreerumine pole vajalikKohene hinnang

Varulokaat angular-locale-chainiga

Kui piirkondlikust lokaadist, näiteks pt-BR-st, puudub tõlkevõti, liigub Angular'i TranslocoLoader otse vaikelokaadile ega kontrolli esmalt põhilokaati 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',
});

Vaata meie varulokaadi juhendist kõigi toetatud raamistike ja 75 sisseehitatud ahela loendit. Learn more →

Angular i18n-i KKK