angular-locale-chain

March 16, 2026 ยท View on GitHub

npm version license

Smart locale fallback chains for Angular + Transloco -- because pt-BR users deserve pt-PT, not English.

The Problem

Transloco has bug #574: when a translation key is missing in the active locale's loaded file, it does not fall through to the next locale in the fallback chain on a per-key basis. Transloco's built-in TRANSLOCO_FALLBACK_STRATEGY only kicks in when the entire locale file fails to load -- it does not help with individual missing keys.

Example: Your app has pt-PT translations but no pt-BR messages file. A Brazilian Portuguese user sees English (or whatever your fallback locale is) instead of the perfectly good pt-PT translations.

The same thing happens with es-MX -> es, fr-CA -> fr, de-AT -> de, and every other regional variant. Your users see English when a perfectly good translation exists in a sibling locale.

The Solution

Drop-in TranslocoLoader replacement. Zero changes to your existing Transloco templates.

LocaleChainLoader wraps your existing loader and deep-merges translations from a configurable fallback chain before handing them to Transloco. Every key is filled in -- no gaps, no missing translations.

Installation

npm install angular-locale-chain @jsverse/transloco

Quick Start

NgModule setup

// app.module.ts
import { NgModule } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import {
  TranslocoModule,
  TRANSLOCO_LOADER,
  TRANSLOCO_FALLBACK_STRATEGY,
  TranslocoHttpLoader,
} from '@jsverse/transloco';
import { LocaleChainLoader, LocaleChainFallbackStrategy } from 'angular-locale-chain';

@NgModule({
  imports: [TranslocoModule],
  providers: [
    {
      provide: TRANSLOCO_LOADER,
      useFactory: (http: HttpClient) => {
        const inner = new TranslocoHttpLoader(http);
        return new LocaleChainLoader(inner, {
          defaultLocale: 'en',
        });
      },
      deps: [HttpClient],
    },
    {
      provide: TRANSLOCO_FALLBACK_STRATEGY,
      useFactory: () => new LocaleChainFallbackStrategy(),
    },
  ],
})
export class AppModule {}

Standalone component setup

// app.config.ts
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(),
    },
  ],
};

All default fallback chains are active. A pt-BR user will now see pt-PT translations when pt-BR keys are missing.

Custom Configuration

Default (zero config)

const loader = new LocaleChainLoader(innerLoader, {
  defaultLocale: 'en',
});

Uses all built-in fallback chains. Covers Chinese, Portuguese, Spanish, French, German, Italian, Dutch, English, Arabic, Norwegian, and Malay regional variants.

With overrides (merge with defaults)

// Override specific chains while keeping all defaults
const loader = new LocaleChainLoader(innerLoader, {
  defaultLocale: 'en',
  fallbacks: { 'pt-BR': ['pt'] }, // skip pt-PT, go straight to pt
});

Your overrides replace matching keys in the default map. All other defaults remain.

Full custom (replace defaults)

// Full control -- only use your chains
const loader = new LocaleChainLoader(innerLoader, {
  defaultLocale: 'en',
  fallbacks: {
    'pt-BR': ['pt-PT', 'pt'],
    'es-MX': ['es-419', 'es'],
  },
  mergeDefaults: false,
});

Only the chains you specify will be active. No defaults.

API Reference

LocaleChainLoader

A TranslocoLoader that wraps your existing loader and deep-merges translations across the full fallback chain.

new LocaleChainLoader(innerLoader: TranslocoLoader, options?: LocaleChainLoaderOptions)

Options:

OptionTypeDefaultDescription
defaultLocalestringundefinedBase locale loaded first (lowest priority)
fallbacksFallbackMapundefinedCustom fallback chains to use or merge with defaults
mergeDefaultsbooleantrueWhether to merge custom fallbacks with built-in defaults

LocaleChainFallbackStrategy

A TranslocoFallbackStrategy that returns the correct fallback chain when an entire locale file fails to load. Use alongside LocaleChainLoader for complete coverage.

new LocaleChainFallbackStrategy(options?: LocaleChainFallbackStrategyOptions)

Options:

OptionTypeDefaultDescription
fallbacksFallbackMapundefinedCustom fallback chains
mergeDefaultsbooleantrueWhether to merge with built-in defaults

defaultFallbacks

The built-in FallbackMap constant containing all default locale chains. Can be inspected or spread into custom configurations.

mergeFallbacks(defaults, overrides)

Utility function that merges two FallbackMap objects. Overrides replace matching keys from defaults.

Default Fallback Map

Chinese

LocaleFallback Chain
zh-Hant-HKzh-Hant-TW -> zh-Hant -> (default locale)
zh-Hant-MOzh-Hant-HK -> zh-Hant-TW -> zh-Hant -> (default locale)
zh-Hant-TWzh-Hant -> (default locale)
zh-Hans-SGzh-Hans -> (default locale)
zh-Hans-MYzh-Hans -> (default locale)

Portuguese

LocaleFallback Chain
pt-BRpt-PT -> pt -> (default locale)
pt-PTpt -> (default locale)
pt-AOpt-PT -> pt -> (default locale)
pt-MZpt-PT -> pt -> (default locale)

Spanish

LocaleFallback Chain
es-419es -> (default locale)
es-MXes-419 -> es -> (default locale)
es-ARes-419 -> es -> (default locale)
es-COes-419 -> es -> (default locale)
es-CLes-419 -> es -> (default locale)
es-PEes-419 -> es -> (default locale)
es-VEes-419 -> es -> (default locale)
es-ECes-419 -> es -> (default locale)
es-GTes-419 -> es -> (default locale)
es-CUes-419 -> es -> (default locale)
es-BOes-419 -> es -> (default locale)
es-DOes-419 -> es -> (default locale)
es-HNes-419 -> es -> (default locale)
es-PYes-419 -> es -> (default locale)
es-SVes-419 -> es -> (default locale)
es-NIes-419 -> es -> (default locale)
es-CRes-419 -> es -> (default locale)
es-PAes-419 -> es -> (default locale)
es-UYes-419 -> es -> (default locale)
es-PRes-419 -> es -> (default locale)

French

LocaleFallback Chain
fr-CAfr -> (default locale)
fr-BEfr -> (default locale)
fr-CHfr -> (default locale)
fr-LUfr -> (default locale)
fr-MCfr -> (default locale)
fr-SNfr -> (default locale)
fr-CIfr -> (default locale)
fr-MLfr -> (default locale)
fr-CMfr -> (default locale)
fr-MGfr -> (default locale)
fr-CDfr -> (default locale)

German

LocaleFallback Chain
de-ATde -> (default locale)
de-CHde -> (default locale)
de-LUde -> (default locale)
de-LIde -> (default locale)

Italian

LocaleFallback Chain
it-CHit -> (default locale)

Dutch

LocaleFallback Chain
nl-BEnl -> (default locale)

English

LocaleFallback Chain
en-GBen -> (default locale)
en-AUen-GB -> en -> (default locale)
en-NZen-AU -> en-GB -> en -> (default locale)
en-INen-GB -> en -> (default locale)
en-CAen -> (default locale)
en-ZAen-GB -> en -> (default locale)
en-IEen-GB -> en -> (default locale)
en-SGen-GB -> en -> (default locale)

Arabic

LocaleFallback Chain
ar-SAar -> (default locale)
ar-EGar -> (default locale)
ar-AEar -> (default locale)
ar-MAar -> (default locale)
ar-DZar -> (default locale)
ar-IQar -> (default locale)
ar-KWar -> (default locale)
ar-QAar -> (default locale)
ar-BHar -> (default locale)
ar-OMar -> (default locale)
ar-JOar -> (default locale)
ar-LBar -> (default locale)
ar-TNar -> (default locale)
ar-LYar -> (default locale)
ar-SDar -> (default locale)
ar-YEar -> (default locale)

Norwegian

LocaleFallback Chain
nbno -> (default locale)
nnnb -> no -> (default locale)

Malay

LocaleFallback Chain
ms-MYms -> (default locale)
ms-SGms -> (default locale)
ms-BNms -> (default locale)

How It Works

  1. LocaleChainLoader wraps your existing TranslocoLoader (e.g., TranslocoHttpLoader).
  2. When Transloco requests translations for a locale, the loader resolves the fallback chain.
  3. It calls the inner loader for each locale in the chain.
  4. Messages are deep-merged in priority order: default locale (base) -> chain locales -> requested locale (highest priority).
  5. If the inner loader throws for any chain locale (e.g., file doesn't exist), it silently skips that locale and continues.
  6. The fully merged translation object is returned to Transloco. Your templates see a complete set of keys with no gaps.

LocaleChainFallbackStrategy complements this by providing Transloco with the correct fallback sequence when an entire locale file fails to load.

FAQ

Why do I need both LocaleChainLoader and LocaleChainFallbackStrategy? They solve different problems. The loader handles per-key deep merge (bug #574). The strategy handles locale-level fallback when an entire translation file is missing. Together they provide complete coverage.

Performance impact? Minimal. The fallback map is resolved once at construction time. Message loading happens per locale change, but only for locales in the chain. Deep merge is fast for typical message objects.

Does it work with nested message keys? Yes. Deep merge is recursive -- it walks all nesting levels. If pt-BR has common.save but not common.cancel, common.cancel will be filled from the next locale in the chain.

Does it work with Transloco scopes? Yes. Scoped translations go through the same loader, so each scope gets the same fallback chain treatment.

Can I use a custom inner loader? Yes. Any class implementing TranslocoLoader works as the inner loader -- TranslocoHttpLoader, a custom loader that fetches from a CMS, or any other implementation.

What if my inner loader returns Observables? Fully supported. The inner loader can return either Observable<Translation> or Promise<Translation>. Both are handled transparently.

What if a chain locale doesn't have a messages file? It's silently skipped. The chain continues to the next locale. This is by design -- you don't need message files for every locale in every chain.

Transloco version compatibility? Works with @jsverse/transloco v5+ (including v6 and v7).

Angular version compatibility? Compatible with Angular 14+ (both NgModule and standalone component patterns).

Contributing

  • Open issues for bugs or feature requests.
  • PRs welcome, especially for adding new locale fallback chains.
  • Run npm test before submitting.

Example

A minimal Angular + Transloco example app is included in the example/ directory. It demonstrates the locale chain resolving three keys for pt-BR, showing fallback from pt-BR -> pt -> en.

cd example && pnpm install && pnpm start

See example/README.md for full setup instructions.

License

MIT License - see LICENSE file.

Built by i18nagent.ai