Angular i18n with Transloco: Setup & Translation Guide
From installation to production: configure Transloco, handle plurals with ICU syntax, add smart locale fallbacks, and automate translations with AI.
Install Transloco
Transloco is the most popular third-party i18n library for Angular. It provides runtime translation loading, ICU message format support, lazy-loaded scopes, and a clean template API with both structural directives and pipes.
npm install @jsverse/translocoConfigure Transloco
Register Transloco in your application config. You need to provide the available languages, set a default language, and configure the translation loader. Transloco supports both standalone components (Angular 14+) and NgModule patterns.
Standalone Components (Recommended)
// 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 Pattern
// 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 {}Create Translation Files
Create one JSON file per language in src/assets/i18n/. Use nested keys to organize strings by feature. Transloco uses the ICU message format for plurals and variables.
// 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}}"
}
}Use Translations in Templates and Services
Transloco provides three ways to translate in templates: the structural directive (*transloco), the pipe (| transloco), and the service (TranslocoService) for TypeScript code. The structural directive is recommended for most use cases because it creates a single subscription and provides the translate function to the entire template block.
Template Translation
<!-- 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>Service Translation (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);
}
}Handle Plurals with ICU Message Format
Transloco uses the ICU message format for plurals and select expressions. ICU handles complex plural rules automatically — Arabic (6 forms), Russian (3 forms), Japanese (1 form) — all from a single message string. Define your plural rules in the translation files and Transloco selects the correct form at runtime.
// 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>Smart Locale Fallbacks with angular-locale-chain
By default, Transloco falls back to your default locale when a translation key is missing. A pt-BR user sees English instead of perfectly good pt-PT translations. angular-locale-chain fixes this by deep-merging translations from a configurable fallback chain before handing them to Transloco. Every key is filled in — no gaps, no missing translations.
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(),
},
],
};Recommended File 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.jsonAutomate Translations
With your Transloco setup complete, translate your locale files using AI. In your IDE, ask your AI assistant to translate your source JSON file, or use the i18n Agent CLI in your CI/CD pipeline for fully automated localization.
# 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,esAutomate Translation Quality
Common Pitfalls
Translations Show Raw Keys
Scoped Keys Not Resolving
Console Warnings in Production
Translations Flash on Route Navigation
Regional Users See English Instead of Parent Locale
Try i18n Agent Now
Drop your translation file here
JSON, YAML, PO, XML, CSV, Markdown, Properties
or click to browse
Target languages
Locale Fallback with angular-locale-chain
When a translation key is missing in a regional locale like pt-BR, Angular's TranslocoLoader jumps straight to the default locale instead of checking the parent locale pt first.
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',
'}')See our Locale Fallback Guide for the full list of supported frameworks and 75 built-in chains. Learn more →