Skip to main content

Angular i18n uz Transloco: vodič za postavljanje i prevođenje

Od instalacije do produkcije: postavite Transloco, obradite množinu sintaksom ICU, dodajte pametne zamjenske lokalne postavke i automatizirajte prevođenje s pomoću AI-ja.

1

Instalirajte Transloco

Transloco je najpopularnija i18n biblioteka treće strane za Angular. Omogućuje učitavanje prijevoda tijekom izvođenja, podržava format poruka ICU, opsege s odgođenim učitavanjem te pregledan API za predloške sa strukturnim direktivama i cijevima.

Zašto odabrati Transloco umjesto ugrađenog Angularova rješenja za i18n? Ugrađeno rješenje zahtijeva zasebnu međuverziju za svaki jezik i ne podržava promjenu jezika tijekom izvođenja. Transloco učitava prijevode tijekom izvođenja, pa isporučujete jednu međuverziju i jezike mijenjate u hodu.
Terminal
npm install @jsverse/transloco
2

Konfigurirajte Transloco

Registrirajte Transloco u konfiguraciji aplikacije. Navedite dostupne jezike, postavite zadani jezik i konfigurirajte učitavač prijevoda. Transloco podržava samostalne komponente (Angular 14+) i obrazac NgModule.

Samostalne komponente (preporuč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,
    }),
  ],
};

Obrazac 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 {}
Ako se umjesto prijevoda prikazuju neobrađeni ključevi poput "nav.home" umjesto "Home", najčešći je uzrok to što TranslocoHttpLoader ne može pronaći Vaše JSON datoteke. Provjerite nalaze li se datoteke prijevoda u src/assets/i18n/ i uključuje li polje assets u datoteci angular.json tu putanju.

Izradite datoteke prijevoda

Izradite po jednu JSON datoteku za svaki jezik u src/assets/i18n/. Ugniježđenim ključevima organizirajte tekstove prema funkcionalnostima. Transloco za množinu i varijable upotrebljava format poruka 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

Upotrebljavajte prijevode u predlošcima i servisima

Transloco nudi tri načina prevođenja u predlošcima: strukturnu direktivu (*transloco), cijev (| transloco) i servis (TranslocoService) za TypeScript kôd. Strukturna direktiva preporučuje se u većini slučajeva jer stvara jednu pretplatu i funkciju za prevođenje čini dostupnom cijelom bloku predloška.

Prevođenje u predlošku

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>
Parametrom read na strukturnoj direktivi ograničite prijevode na ugniježđeni ključ. Tako ne morate ponavljati prefiks u svakom pozivu t(), a predlošci ostaju pregledniji.

Prevođenje u servisu (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);
  }
}
Cijev transloco stvara novu pretplatu pri svakoj uporabi. U predlošcima s mnogo prevedenih tekstova radije upotrijebite strukturnu direktivu *transloco, koja stvara jednu pretplatu za cijeli blok.
4

Obradite množinu formatom poruka ICU

Transloco upotrebljava format poruka ICU za množinu i izraze select. ICU automatski obrađuje složena pravila množine — arapski (6 oblika), ruski (3 oblika), japanski (1 oblik) — iz samo jednog niza poruke. Pravila množine definirajte u datotekama prijevoda, a Transloco će tijekom izvođenja odabrati ispravan oblik.

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>
Nikada nemojte implementirati vlastitu logiku množine u komponentama. Pravila se među jezicima znatno razlikuju, a specifikacija ICU već ih obrađuje. Prepustite taj posao alatima Transloco i ICU — Vi trebate definirati ispravne oblike množine u datotekama prijevoda.

Pametne zamjenske lokalne postavke uz angular-locale-chain

Kada nedostaje ključ prijevoda, Transloco se prema zadanim postavkama vraća na Vašu zadanu lokalnu postavku. Korisnik s postavkom pt-BR zato vidi engleski umjesto valjanih prijevoda za pt-PT. angular-locale-chain to rješava dubinskim spajanjem prijevoda iz podesivog zamjenskog lanca prije predaje alatu Transloco. Svaki je ključ popunjen — bez praznina i nedostajućih prijevoda.

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 biblioteka je otvorenog kôda koja rješava pogrešku Transloco #574 — izostanak zamjene po ključu kada je datoteka prijevoda samo djelomično dovršena.

Preporučena struktura datoteka

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

Automatizirajte prevođenje

Nakon što dovršite postavljanje alata Transloco, prevedite datoteke lokalnih postavki s pomoću AI-ja. U svojem IDE-u zatražite od AI pomoćnika da prevede izvornu JSON datoteku ili upotrijebite i18n Agent CLI u svojem CI/CD pipelineu za potpuno automatiziranu lokalizaciju.

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
Prevodite postupno — kada u izvornu datoteku dodate nove ključeve, prevedite samo razliku umjesto ponovnog generiranja svih datoteka. Tako ćete sačuvati prijevode koje su pregledali ljudi i izbjeći nepotrebne izmjene.

Automatizirajte provjeru kvalitete prijevoda

Alatom i18n-validate otkrijte ključeve koji nedostaju i neispravna rezervirana mjesta prije objave. Korisničko sučelje testirajte pseudoprijevodima uz i18n-pseudo prije nego što stignu stvarni prijevodi.

Uobičajene zamke

Prijevodi prikazuju neobrađene ključeve

TranslocoHttpLoader ne može pronaći Vaše JSON datoteke. Provjerite nalaze li se datoteke u src/assets/i18n/, uključuje li polje assets u datoteci angular.json tu putanju i podudaraju li se nazivi datoteka točno s konfiguracijom availableLangs, uz razlikovanje velikih i malih slova.

Ključevi opsega ne razrješavaju se

Pri uporabi opsega Transloco datoteke prijevoda moraju biti u assets/i18n/[scope]/[lang].json, a ne u korijenskoj mapi i18n. Provjerite i je li opseg registriran u polju providers komponente s pomoću TRANSLOCO_SCOPE.

Upozorenja u konzoli u produkciji

Za produkcijske međuverzije postavite prodMode: true u konfiguraciji alata Transloco. Bez toga Transloco u konzolu zapisuje upozorenja o ključevima koji nedostaju. Time se isključuju i razvojne provjere koje stvaraju dodatno opterećenje.

Prijevodi nakratko zatrepere pri navigaciji rutama

Rute s odgođenim učitavanjem dohvaćaju prijevode nakon iscrtavanja komponente, pa se nakratko prikažu neprevedeni ključevi. Ugrađenim predloškom TRANSLOCO_LOADING_TEMPLATE prikažite stanje učitavanja ili unaprijed učitajte prijevode u čuvaru rute.

Regionalni korisnici vide engleski umjesto nadređene lokalne postavke

Ugrađena zamjena alata Transloco aktivira se samo kada nedostaje cijela datoteka lokalne postavke, a ne pojedinačni ključevi. Upotrijebite angular-locale-chain za dubinsko spajanje prijevoda srodnih postavki (npr. pt-BR prelazi na pt-PT, zatim pt pa engleski).

Isprobajte i18n Agent odmah

Povucite datoteku za prijevod ovdje

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

ili kliknite za odabir

Ciljni jezici

Registracija nije potrebnaProcjena odmah

Zamjenske lokalne postavke uz angular-locale-chain

Kada u regionalnoj lokalnoj postavci poput pt-BR nedostaje ključ prijevoda, Angularov TranslocoLoader odmah prelazi na zadanu postavku umjesto da prvo provjeri nadređenu postavku 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',
});

U našem vodiču za zamjenske lokalne postavke pogledajte cjelovit popis podržanih razvojnih okvira i 75 ugrađenih lanaca. Learn more →

Česta pitanja o Angular i18n-u