Fluent Impl Locale Loading

fluent-impl-locale-loading

Quick Reference

Loading Pipeline

File Organization Patterns

Key Dependencies

Critical Warnings

NEVER create a new FluentResource() for each individual message. ALWAYS batch all messages from an FTL file into a single FluentResource. Creating one resource per message adds unnecessary parser overhead.

NEVER ignore the error array returned by bundle.addResource(). ALWAYS log errors to detect malformed FTL before it causes silent translation failures in production.

NEVER block initial render by synchronously loading FTL files. ALWAYS load translations asynchronously and show a loading state until bundles are ready.

ALWAYS pass an errors array to bundle.addResource() and log the results. Without this, parse errors are silently swallowed and translations fail without explanation.

ALWAYS use CachedSyncIterable (or ReactLocalization which wraps it automatically) when using generator-based bundle creation. Without caching, the generator is consumed on first iteration and subsequent lookups return nothing.

Decision Tree: File Organization

How many translation messages does your app have?
├─ < 50 messages
│  └─ USE flat files: /locales/en-US.ftl, /locales/fr.ftl
│     One file per locale, all messages together
│
├─ 50-200 messages
│  └─ USE directory per locale: /locales/en-US/messages.ftl
│     Single file per locale in its own directory
│     Room to split later without changing paths
│
└─ > 200 messages OR need code-splitting
   └─ USE feature-split: /locales/en-US/main.ftl, settings.ftl, errors.ftl
      ├─ Split by page or feature
      ├─ Load only what the current route needs
      └─ Multiple addResource() calls per bundle

Decision Tree: Loading Strategy

When do you need translations available?
├─ At app startup (all locales needed immediately)
│  └─ USE eager loading with Promise.all()
│     Fetch all negotiated locales in parallel
│     Wait for all before rendering
│
├─ At app startup (only primary locale needed immediately)
│  └─ USE lazy generator with CachedSyncIterable
│     Primary locale loaded eagerly
│     Fallback locales loaded on demand when a message is missing
│
└─ On route change (different pages need different translations)
   └─ USE feature-split loading
      Load FTL file matching current route
      Add to existing bundle via addResource()
      Cache loaded resources in a Map

Core Pattern: Async FTL Loading

import { FluentBundle, FluentResource } from "@fluent/bundle";

async function fetchMessages(locale: string): Promise<string> {
  const response = await fetch(`/locales/${locale}/messages.ftl`);
  if (!response.ok) {
    throw new Error(`Failed to fetch FTL for ${locale}: ${response.status}`);
  }
  return response.text();
}

function createBundle(locale: string, ftlText: string): FluentBundle {
  const bundle = new FluentBundle(locale);
  const resource = new FluentResource(ftlText);
  const errors = bundle.addResource(resource);
  if (errors.length > 0) {
    errors.forEach((e) => console.warn(`FTL error in ${locale}:`, e));
  }
  return bundle;
}

async function loadBundles(locales: string[]): Promise<FluentBundle[]> {
  return Promise.all(
    locales.map(async (locale) => {
      const ftlText = await fetchMessages(locale);
      return createBundle(locale, ftlText);
    })
  );
}

Core Pattern: Lazy Generator with CachedSyncIterable

import { FluentBundle, FluentResource } from "@fluent/bundle";
import { ReactLocalization } from "@fluent/react";

function* generateBundles(
  locales: string[],
  ftlCache: Map<string, string>
): Generator<FluentBundle> {
  for (const locale of locales) {
    const ftlText = ftlCache.get(locale);
    if (!ftlText) continue;

    const bundle = new FluentBundle(locale);
    const resource = new FluentResource(ftlText);
    const errors = bundle.addResource(resource);
    if (errors.length > 0) {
      errors.forEach((e) => console.warn(`FTL error in ${locale}:`, e));
    }
    yield bundle;
  }
}

// ReactLocalization wraps the generator in CachedSyncIterable automatically
const l10n = new ReactLocalization(generateBundles(locales, cache));

The generator pattern is preferable for large locale sets because fallback bundles are only created when needed. ReactLocalization wraps any iterable in CachedSyncIterable.from() internally, so the generator is iterated once and then cached.

Core Pattern: Multiple FTL Files Per Locale

async function loadMultipleFiles(
  locale: string,
  files: string[]
): Promise<FluentBundle> {
  const bundle = new FluentBundle(locale);

  for (const file of files) {
    const response = await fetch(`/locales/${locale}/${file}`);
    const ftlText = await response.text();
    const resource = new FluentResource(ftlText);
    const errors = bundle.addResource(resource);
    if (errors.length > 0) {
      errors.forEach((e) => console.warn(`FTL error in ${locale}/${file}:`, e));
    }
  }

  return bundle;
}

// Usage: one bundle holds multiple resources
const bundle = await loadMultipleFiles("en-US", [
  "main.ftl",
  "errors.ftl",
  "settings.ftl",
]);

A single FluentBundle accepts multiple FluentResource instances via repeated addResource() calls. All messages from all resources become available in the same bundle.

File Organization Convention

Feature-Split Structure

public/
└── locales/
    ├── en-US/
    │   ├── main.ftl          # Core UI: navigation, common buttons
    │   ├── auth.ftl           # Login, registration, password reset
    │   ├── settings.ftl       # Settings page
    │   ├── errors.ftl         # Error messages
    │   └── dashboard.ftl      # Dashboard-specific messages
    ├── fr/
    │   ├── main.ftl
    │   ├── auth.ftl
    │   ├── settings.ftl
    │   ├── errors.ftl
    │   └── dashboard.ftl
    └── de/
        ├── main.ftl
        ├── auth.ftl
        ├── settings.ftl
        ├── errors.ftl
        └── dashboard.ftl

FTL File Naming Rules

• ALWAYS use lowercase filenames: main.ftl, not Main.ftl
• ALWAYS use BCP 47 locale identifiers for directory names: en-US, fr-CA, zh-Hans
• ALWAYS keep the same file names across all locales — every locale directory MUST mirror the same set of .ftl files
• NEVER mix messages from different features in one FTL file when using feature-split

Bundle Caching Strategy

const bundleCache = new Map<string, FluentBundle>();

async function getOrCreateBundle(locale: string): Promise<FluentBundle> {
  if (bundleCache.has(locale)) {
    return bundleCache.get(locale)!;
  }

  const ftlText = await fetchMessages(locale);
  const bundle = createBundle(locale, ftlText);
  bundleCache.set(locale, bundle);
  return bundle;
}

ALWAYS cache FluentBundle instances in a Map<string, FluentBundle> when locales may be re-requested (e.g., locale switching). Creating bundles and parsing FTL is not free — avoid repeated parsing of the same content.

Reference Links

• references/methods.md -- API methods for fetch, FluentResource, addResource, and bundle creation
• references/examples.md -- Complete working examples for async loading, lazy generators, caching, and feature-split loading
• references/anti-patterns.md -- What NOT to do when loading FTL files

Official Sources

• https://github.com/projectfluent/fluent.js/wiki/React-Tutorial
• https://github.com/projectfluent/fluent.js/wiki/ReactLocalization
• https://github.com/projectfluent/fluent.js/blob/main/fluent-bundle/src/bundle.ts
• https://github.com/projectfluent/fluent.js/blob/main/fluent-react/src/localization.ts