Skip to main content

Angular i18n gamit ang Transloco: Gabay sa Setup at Pagsasalin

Mula installation hanggang production: i-configure ang Transloco, pangasiwaan ang plural gamit ang ICU syntax, magdagdag ng smart locale fallback, at i-automate ang pagsasalin gamit ang AI.

1

I-install ang Transloco

Ang Transloco ang pinakapopular na third-party i18n library para sa Angular. Nagbibigay ito ng runtime translation loading, suporta sa ICU message format, lazy-loaded scope, at malinis na template API na may parehong structural directive at pipe.

Bakit Transloco sa halip na built-in na i18n ng Angular? Nangangailangan ang built-in na solusyon ng Angular ng hiwalay na build para sa bawat wika at hindi ito sumusuporta sa pagpapalit ng wika sa runtime. Naglo-load ang Transloco ng mga pagsasalin sa runtime, kaya isang build lang ang ise-ship ninyo at makakapagpalit kayo ng wika on the fly.
Terminal
npm install @jsverse/transloco
2

I-configure ang Transloco

Irehistro ang Transloco sa application config ninyo. Kailangan ninyong ibigay ang mga available na wika, magtakda ng default na wika, at i-configure ang translation loader. Sinusuportahan ng Transloco ang parehong standalone components (Angular 14+) at NgModule patterns.

Standalone Components (Inirerekomenda)

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

Pattern ng 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 {}
Kung lumalabas ang mga pagsasalin bilang raw key tulad ng "nav.home" sa halip na "Home", ang pinakakaraniwang sanhi ay hindi mahanap ng TranslocoHttpLoader ang inyong mga JSON file. Suriin kung nasa src/assets/i18n/ ang mga translation file at kung kasama ang path na iyon sa assets array ng angular.json.

Gumawa ng Mga Translation File

Gumawa ng isang JSON file para sa bawat wika sa src/assets/i18n/. Gumamit ng nested key para ayusin ang mga string ayon sa feature. Gumagamit ang Transloco ng ICU message format para sa plural at variable.

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

Gamitin ang Mga Pagsasalin sa Templates at Services

Nagbibigay ang Transloco ng tatlong paraan para magsalin sa templates: ang structural directive (*transloco), ang pipe (| transloco), at ang service (TranslocoService) para sa TypeScript code. Inirerekomenda ang structural directive para sa karamihan ng use case dahil lumilikha ito ng iisang subscription at ibinibigay ang translate function sa buong template block.

Pagsasalin sa Template

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>
Gamitin ang read parameter sa structural directive para i-scope ang mga pagsasalin sa isang nested key. Iniiwasan nito ang pag-uulit ng prefix sa bawat t() call at ginagawang mas malinis ang mga template.

Pagsasalin sa Service (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);
  }
}
Lumilikha ang transloco pipe ng bagong subscription sa bawat paggamit. Sa mga template na maraming isinasaling string, mas piliin ang *transloco structural directive na lumilikha ng iisang subscription para sa buong block.
4

Pangasiwaan ang Plural gamit ang ICU Message Format

Gumagamit ang Transloco ng ICU message format para sa plural at select expression. Awtomatikong hinahandle ng ICU ang mga kumplikadong plural rule — Arabic (6 forms), Russian (3 forms), Japanese (1 form) — mula sa iisang message string. Idefine ang inyong mga plural rule sa translation files at pipiliin ng Transloco ang tamang anyo sa runtime.

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>
Huwag kailanman mag-implement ng custom plural logic sa inyong mga component. Malaki ang pagkakaiba-iba ng mga plural rule sa iba’t ibang wika, at hinahandle na ito ng ICU specification. Hayaan ang Transloco at ICU ang gumawa ng trabaho — ang sa inyo ay idefine ang tamang plural form sa inyong translation files.

Smart Locale Fallbacks gamit ang angular-locale-chain

Bilang default, nagfa-fallback ang Transloco sa default locale ninyo kapag may nawawalang translation key. Dahil dito, nakakakita ang isang pt-BR user ng English sa halip na magagamit na pt-PT translations. Inaayos ito ng angular-locale-chain sa pamamagitan ng pag-deep-merge ng mga pagsasalin mula sa configurable fallback chain bago ibigay ang mga ito sa Transloco. Napupunan ang bawat key — walang gap, walang nawawalang pagsasalin.

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(),
    },
  ],
};
Ang angular-locale-chain ay isang open-source library na lumulutas sa Transloco bug #574 — nawawalang per-key fallback kapag bahagyang kumpleto ang translation file.

Inirerekomendang File Structure

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

I-automate ang Pagsasalin

Kapag kumpleto na ang Transloco setup ninyo, isalin ang inyong mga locale file gamit ang AI. Sa inyong IDE, hilingin sa inyong AI assistant na isalin ang source JSON file ninyo, o gamitin ang i18n Agent CLI sa inyong CI/CD pipeline para sa ganap na automated localization.

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
Isalin nang paunti-unti — kapag nagdagdag kayo ng bagong key sa source file, isalin lamang ang diff sa halip na i-regenerate ang lahat ng file. Pinapanatili nito ang anumang human-reviewed na pagsasalin at iniiwasan ang hindi kinakailangang churn.

I-automate ang Kalidad ng Pagsasalin

Matukoy ang mga nawawalang key at sirang placeholder bago ma-ship gamit ang i18n-validate. Subukan ang UI ninyo gamit ang pseudo-translation sa i18n-pseudo bago dumating ang totoong pagsasalin.

Karaniwang Pitfalls

Nagpapakita ang Mga Pagsasalin ng Raw Keys

Hindi mahanap ng TranslocoHttpLoader ang inyong mga JSON file. Tingnan kung nasa src/assets/i18n/ ang mga file, kung kasama ang path na iyon sa assets array ng angular.json, at kung eksaktong tumutugma (case-sensitive) ang mga filename sa inyong availableLangs configuration.

Hindi Nare-resolve ang Scoped Keys

Kapag gumagamit ng Transloco scope, dapat nasa assets/i18n/[scope]/[lang].json ang mga translation file, hindi sa root i18n folder. Tiyakin ding nakarehistro ang scope sa providers array ng component gamit ang TRANSLOCO_SCOPE.

Mga Console Warning sa Production

Itakda ang prodMode: true sa inyong Transloco config para sa production builds. Kapag wala ito, naglo-log ang Transloco ng mga warning para sa missing key sa console. Dina-disable rin nito ang mga development-time check na nagdaragdag ng overhead.

Nagpa-flash ang Mga Pagsasalin sa Route Navigation

Kinukuha ng lazy-loaded route ang mga pagsasalin matapos mag-render ang component, kaya nagkakaroon ng panandaliang flash ng untranslated key. Gamitin ang built-in na TRANSLOCO_LOADING_TEMPLATE ng Transloco para magpakita ng loading state, o i-pre-load ang mga pagsasalin sa isang route guard.

Nakakakita ang Mga Regional User ng English sa Halip na Parent Locale

Nagti-trigger lang ang built-in fallback ng Transloco kapag nawawala ang buong locale file, hindi kapag may indibidwal na nawawalang key. Gamitin ang angular-locale-chain para i-deep-merge ang mga pagsasalin mula sa magkakaugnay na locale (hal., pt-BR magfa-fallback sa pt-PT, pagkatapos pt, pagkatapos English).

Subukan ang i18n Agent Ngayon

I-drop dito ang inyong translation file

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

o i-click para mag-browse

Mga target language

Hindi kailangan ang signupInstant na estimate

Locale Fallback gamit ang angular-locale-chain

Kapag may nawawalang translation key sa isang regional locale tulad ng pt-BR, dumidiretso ang Angular TranslocoLoader sa default locale sa halip na tingnan muna ang parent locale na 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',
});

Tingnan ang aming Locale Fallback Guide para sa kumpletong listahan ng sinusuportahang framework at 75 built-in chain. Learn more →

FAQ sa Angular i18n