fluent.js

The DOMLocalization class is designed for full-fallback ready message formatting within the DOM. It works by identifying localizable elements via the data-l10n-id attribute.

Key workflow:

1. Initialize DOMLocalization with a list of FTL resource paths and a generateBundles generator function.
2. Call connectRoot(root) to specify the starting point in the DOM.
3. Call translateRoots() to perform the initial translation of the DOM tree.
4. Use setAttributes(element, id, args) to update specific elements. This method sets data-l10n-id and data-l10n-args on the element, which triggers an internal MutationObserver to automatically translate the element.

import { DOMLocalization } from "@fluent/dom";

const l10n = new DOMLocalization(
  ["/browser/main.ftl", "/toolkit/menu.ftl"],
  generateBundles
);

l10n.connectRoot(document.documentElement);
l10n.translateRoots();

const h1 = document.querySelector("h1");

// Sets `data-l10n-id` and `data-l10n-args` which triggers
// the `MutationObserver` from `DOMLocalization` and translates the
// element.
l10n.setAttributes(h1, "welcome", { user: "Anna" });

The negotiateLanguages API supports three different strategies via the strategy option. Choose the one that best fits your application's requirements for how many locales should be returned:

1. filtering (default): Tries to match as many available locales as possible for each requested locale.
   • Example: If requested ['de-DE', 'fr-FR'] and available ['de', 'fr'], it returns ['de', 'fr'].
2. matching: Looks for the single best matching available locale for each requested locale.
   • Example: If requested ['de-DE', 'fr-FR'] and available ['de', 'fr'], it returns ['de', 'fr'] (but focuses on the best match per request).
3. lookup: Tries to find the single best locale for the entire requested locale list among the available locales.
   • Example: If requested ['de-DE', 'fr-FR'] and available ['de-DE', 'fr'], it returns only the single best match, e.g., ['de-DE'].

let supported = negotiateLanguages(requested, available, {
  strategy: "matching",
});

Use the test.js script to measure the performance impact of changes to the fluent.js codebase. The script measures the speed of parsing, compilation, and entity retrieval using a resource file containing approximately 500 entities (imitating a real-world scenario like Firefox OS's settings localization). Execution time is reported in milliseconds (ms).

To ensure reliable measurements and avoid JIT (Just-In-Time) compilation bias, the script spawns the target command via child_process.exec for a large sample of runs. If no command is provided, it is automatically determined based on the selected --engine.

# Run with default settings
./test.js

# Run using a specific engine (node, jsshell, or d8)
./test.js --engine jsshell

# Run with a large sample size and show progress
./test.js --sample 1000 --progress

# Run a specific custom command
./test.js "~/src/jsshell/js benchmark.jsshell.js"

To format translations, use the FluentBundle constructor to create a bundle for a specific locale, add a FluentResource containing FTL (Fluent Translation Language) content, and then use getMessage and formatPattern to resolve messages with provided arguments.

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

// 1. Define your FTL resource
let resource = new FluentResource(`
-brand-name = Foo 3000
welcome = Welcome, {$name}, to {-brand-name}!
`);

// 2. Create a bundle for a specific locale
let bundle = new FluentBundle("en-US");

// 3. Add the resource and check for syntax errors
let errors = bundle.addResource(resource);
if (errors.length) {
  // Handle syntax errors (errors are per-message)
}

// 4. Retrieve and format a message
let welcome = bundle.getMessage("welcome");
if (welcome.value) {
  let result = bundle.formatPattern(welcome.value, { name: "Anna" });
  // result → "Welcome, Anna, to Foo 3000!"
}