Skip to main content

Angular i18n s Transloco: vodnik za nastavitev in prevajanje

Od namestitve do produkcije: nastavite Transloco, obravnavajte množinske oblike s skladnjo ICU, dodajte pametne nadomestne področne nastavitve in avtomatizirajte prevajanje z umetno inteligenco.

1

Namestite Transloco

Transloco je najbolj priljubljena zunanja knjižnica za internacionalizacijo aplikacij Angular. Omogoča nalaganje prevodov med izvajanjem, podporo za obliko sporočil ICU, obsege z odloženim nalaganjem ter pregleden API za predloge s strukturnimi direktivami in cevmi.

Zakaj izbrati Transloco namesto vgrajene internacionalizacije Angular? Vgrajena rešitev Angular zahteva ločeno graditev za vsak jezik in ne podpira preklapljanja jezika med izvajanjem. Transloco prevode naloži med izvajanjem, zato lahko objavite eno graditev in sproti preklapljate med jeziki.
Terminal
npm install @jsverse/transloco
2

Nastavite Transloco

Registrirajte Transloco v konfiguraciji aplikacije. Navesti morate razpoložljive jezike, določiti privzeti jezik in nastaviti nalagalnik prevodov. Transloco podpira samostojne komponente (Angular 14+) in vzorce NgModule.

Samostojne komponente (priporočeno)

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

Vzorec NgModule

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 {}
Če so namesto besedila »Domov« prikazani neobdelani ključi, kot je "nav.home", TranslocoHttpLoader najverjetneje ne more najti Vaših datotek JSON. Preverite, ali so prevodne datoteke v src/assets/i18n/ in ali polje assets v angular.json vključuje to pot.

Ustvarite prevodne datoteke

V src/assets/i18n/ ustvarite po eno datoteko JSON za vsak jezik. Nize razvrstite po funkcionalnostih z ugnezdenimi ključi. Transloco za množinske oblike in spremenljivke uporablja obliko sporočil ICU.

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

Uporabite prevode v predlogah in storitvah

Transloco omogoča tri načine prevajanja v predlogah: strukturno direktivo (*transloco), cev (| transloco) in storitev (TranslocoService) za kodo TypeScript. Za večino primerov uporabe je priporočljiva strukturna direktiva, saj ustvari eno samo naročnino in zagotovi funkcijo za prevajanje celotnemu bloku predloge.

Prevajanje v predlogi

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>
S parametrom read strukturne direktive omejite prevode na ugnezdeni ključ. Tako Vam ni treba ponavljati predpone v vsakem klicu t(), predloge pa so preglednejše.

Prevajanje v storitvi (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);
  }
}
Cev transloco ob vsaki uporabi ustvari novo naročnino. V predlogah z veliko prevedenimi nizi raje uporabite strukturno direktivo *transloco, ki ustvari eno samo naročnino za celoten blok.
4

Obravnavajte množinske oblike z obliko sporočil ICU

Transloco za množinske oblike in izbirne izraze uporablja obliko sporočil ICU. ICU samodejno obravnava zapletena pravila za množinske oblike — arabščina (6 oblik), ruščina (3 oblike), japonščina (1 oblika) — vse iz enega niza sporočila. Pravila za množinske oblike določite v prevodnih datotekah, Transloco pa med izvajanjem izbere ustrezno obliko.

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>
V komponentah nikoli ne izvajajte lastne logike za množinske oblike. Jeziki imajo zelo različna pravila, ki jih specifikacija ICU že obravnava. Delo prepustite Transloco in ICU — Vaša naloga je, da v prevodnih datotekah določite pravilne množinske oblike.

Pametne nadomestne področne nastavitve z angular-locale-chain

Transloco privzeto uporabi Vaše privzete področne nastavitve, kadar prevodni ključ manjka. Uporabniku različice pt-BR se tako namesto povsem ustreznega prevoda pt-PT prikaže angleščina. angular-locale-chain to odpravi z globokim združevanjem prevodov iz nastavljive nadomestne verige, preden jih preda Transloco. Zapolnjen je vsak ključ — brez vrzeli in manjkajočih prevodov.

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 je odprtokodna knjižnica, ki odpravlja napako Transloco #574 — manjkajočo nadomestno vrednost za posamezne ključe, kadar je prevodna datoteka le delno dokončana.

Priporočena struktura datotek

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

Avtomatizirajte prevajanje

Ko dokončate nastavitev Transloco, prevedite datoteke področnih nastavitev z umetno inteligenco. V svojem razvojnem okolju prosite pomočnika z umetno inteligenco, naj prevede izvorno datoteko JSON, ali pa v cevovodu CI/CD uporabite i18n Agent CLI za povsem avtomatizirano lokalizacijo.

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
Prevajajte postopoma — ko v izvorno datoteko dodate nove ključe, prevedite le razliko, namesto da bi znova ustvarili vse datoteke. Tako ohranite človeško pregledane prevode in se izognete nepotrebnim spremembam.

Avtomatizirajte zagotavljanje kakovosti prevodov

Z i18n-validate odkrijte manjkajoče ključe in poškodovane označbe mest, preden pridejo v produkcijo. Preden so pravi prevodi pripravljeni, uporabniški vmesnik preizkusite s psevdoprevodi z i18n-pseudo.

Pogoste težave

Pri prevodih so prikazani neobdelani ključi

TranslocoHttpLoader ne more najti Vaših datotek JSON. Preverite, ali so datoteke v src/assets/i18n/ in ali polje assets v angular.json vključuje to pot ter ali se imena datotek povsem ujemajo z Vašo konfiguracijo availableLangs (z upoštevanjem velikosti črk).

Ključev z določenim obsegom ni mogoče razrešiti

Pri uporabi obsegov Transloco morajo biti prevodne datoteke v assets/i18n/[scope]/[lang].json in ne v korenski mapi i18n. Poskrbite tudi, da je obseg registriran v polju providers komponente z uporabo TRANSLOCO_SCOPE.

Opozorila v konzoli v produkciji

Za produkcijske graditve v konfiguraciji Transloco nastavite prodMode: true. Brez te nastavitve Transloco v konzolo zapisuje opozorila o manjkajočih ključih. Nastavitev onemogoči tudi preverjanja med razvojem, ki povzročajo dodatno obremenitev.

Ob krmarjenju med potmi za hip utripnejo prevodi

Poti z odloženim nalaganjem pridobijo prevode po izrisu komponente, zato se za hip prikažejo neprevedeni ključi. Z vgrajenim TRANSLOCO_LOADING_TEMPLATE knjižnice Transloco prikažite stanje nalaganja ali pa prevode vnaprej naložite v varovalu poti.

Regionalnim uporabnikom se namesto nadrejenega jezika prikaže angleščina

Vgrajeni nadomestni mehanizem Transloco se sproži le, kadar manjka celotna datoteka področnih nastavitev, ne pa pri posameznih manjkajočih ključih. Z angular-locale-chain globoko združite prevode iz sorodnih področnih nastavitev (npr. pt-BR uporabi pt-PT, nato pt in nazadnje angleščino).

Preizkusite i18n Agent zdaj

Spustite prevajalsko datoteko sem

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

ali kliknite za izbiro

Ciljni jeziki

Registracija ni potrebnaTakojšnja ocena

Nadomestne področne nastavitve z angular-locale-chain

Ko v regionalnih področnih nastavitvah, kot je pt-BR, manjka prevodni ključ, Angularjev TranslocoLoader takoj uporabi privzete področne nastavitve, namesto da bi najprej preveril nadrejene področne nastavitve 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',
});

V našem vodniku po nadomestnih področnih nastavitvah si oglejte celoten seznam podprtih ogrodij in 75 vgrajenih verig. Learn more →

Pogosta vprašanja o Angular i18n