fluent-transpiler

0.4.1 verified Fri May 01 auth: no javascript

fluent-transpiler is a build-time tool that compiles Fluent (.ftl) localization files into optimized, tree-shakable JavaScript ES modules. Current stable version is 0.4.1. It supports single and multiple locales, allows selective message inclusion/exclusion, and offers variable naming conventions (camelCase, PascalCase, etc.). Unlike runtime i18n libraries like @fluent/react or react-intl, fluent-transpiler produces zero-runtime code, ideal for modern bundlers with tree shaking. Requires Node >=24 and ships TypeScript definitions.

Common errors

error Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'fluent-transpiler' ↓

cause Using CommonJS require() in a Node.js version that doesn't support ESM, or the package is installed as devDependency but not available at runtime.

fix

Use ES modules (import) and ensure the package is installed as a dependency (npm i -D is for devDependencies; if needed at runtime, use npm i).

error SyntaxError: The requested module 'fluent-transpiler' does not provide an export named 'default' ↓

cause Attempting a default import when the package only exports named exports.

fix

Change to named import: import { compile } from 'fluent-transpiler'.

error TypeError: ftlContent is not a string ↓

cause Passing a file path instead of the actual FTL content string to compile().

fix

Read the .ftl file content first: const ftlContent = readFileSync('file.ftl', 'utf8'); then compile(ftlContent, options).

Warnings

gotcha By default, comments in FTL files are omitted from the output. Use --comments or the comments option to include them. ↓

fix Pass { comments: true } in options or use CLI flag --comments.

gotcha The output includes only messages that are not excluded. If --include-key is used, only those keys are included. If --exclude-key is used, specified keys are removed. ↓

fix Review include/exclude options to ensure the desired messages are present in the output.

gotcha Variable names are converted to camelCase by default. This may conflict with original FTL variable names. Use --variable-notation to change. ↓

fix Set variableNotation option to an appropriate value (e.g., 'snakeCase') to match your naming conventions.

deprecated SLSA 3 and OpenSSF Scorecard badges are present; no known security incidents. Package uses npm provenance. ↓

fix No action needed; these are positive indicators.

Install

npm install fluent-transpiler

yarn add fluent-transpiler

pnpm add fluent-transpiler

Imports

fluentTranspiler
wrong
```
const fluentTranspiler = require('fluent-transpiler')
```
correct
```
import { fluentTranspiler } from 'fluent-transpiler'
```
Package is ESM-only; CommonJS require will fail. The default export does not exist; use named import.
compile
```
import { compile } from 'fluent-transpiler/compile'
```
The compile function is available as a named export from the main entry point, but may also be accessed from a subpath export in future versions. Use import { compile } from 'fluent-transpiler'.
FluentTranspiler
wrong
```
import FluentTranspiler from 'fluent-transpiler'
```
correct
```
import { FluentTranspiler } from 'fluent-transpiler'
```
The class is a named export, not a default export. TypeScript users should import the type directly: import type { FluentTranspiler } from 'fluent-transpiler'.
Type imports
```
import type { FluentTranspilerOptions } from 'fluent-transpiler'
```
For TypeScript, use import type for options interfaces; they are re-exported from the package.

Quickstart

Reads an FTL file, compiles it to a JS module using fluent-transpiler, and writes the output.

import { readFileSync, writeFileSync } from 'node:fs';
import { compile } from 'fluent-transpiler';

const ftlContent = readFileSync('messages/en-CA.ftl', 'utf8');
const jsCode = compile(ftlContent, {
  locale: 'en-CA',
  variableNotation: 'camelCase'
});
writeFileSync('messages/en-CA.js', jsCode, 'utf8');
console.log('Transpilation complete.');