fluent-transpiler

Transpile Fluent (ftl) files into optimized, tree-shakable, JavaScript EcmaScript Modules (esm).


GitHub Actions unit test status GitHub Actions dast test status GitHub Actions perf test status GitHub Actions SAST test status GitHub Actions lint test status
npm version npm install size npm weekly downloads npm provenance
Open Source Security Foundation (OpenSSF) Scorecard SLSA 3 Checked with Biome Conventional Commits code coverage

## Install ```bash npm i -D fluent-transpiler ``` ## CLI ```bash Usage: ftl [options] Compile Fluent (.ftl) files to JavaScript (.js or .mjs) Arguments: inputs Paths to the Fluent file(s) to compile. Multiple files are joined in order; ids must be unique across the set. Options: --locale What locale(s) to be used. Multiple can be set to allow for fallback. i.e. en-CA --comments Include comments in output file. --include-key Allowed messages to be included. Default to include all. --exclude-key Ignored messages to be excluded. Default to exclude none. --exclude-value Set message to an empty string when it contains this value. --variable-notation What variable notation to use with exports (choices: "camelCase", "pascalCase", "constantCase", "snakeCase", default: "camelCase") --disable-minify If disabled, all exported messages will have the same interface `(params) => ({value, attributes})`. --use-isolating Wrap placeable with \u2068 and \u2069. -o, --output Path to store the resulting JavaScript file. Will be in ESM. -h, --help display help for command ``` ## NodeJS | Option | Description | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | locale | What locale(s) to be used. Multiple can be set to allow for fallback. i.e. `en-CA` | | comments | Include comments in output file. Default: `true` | | includeKey | Array of message keys to include. Default: `[]` (include all) | | excludeKey | Array of message keys to exclude. Default: `[]` (exclude none) | | excludeValue | Set message to an empty string when it contains this value. Default: `undefined` | | disableMinify | If disabled, all exported messages will have the same interface `(params) => ({value, attributes})`. Default: each exported message could be a different type based on what is needed to generate the message (`string`, `object`, `() => ''`, `() => ({})`) | | errorOnJunk | Throw error when `Junk` is parsed. Default: `true` | | variableNotation | What variable notation to use with exports. Choices: `camelCase`, `pascalCase`, `snakeCase`, `constantCase`. Default: `camelCase` | | useIsolating | Wrap placeable with \u2068 and \u2069. Default: `false` | | exportDefault | Allows the overwriting of the `export default` to allow for custom uses. Default: See code | ```javascript import { readFile, writeFile } from 'node:fs/promises' import fluentTranspiler from 'fluent-transpiler' const ftl = await readFile('./path/to/en.ftl', { encoding: 'utf8' }) const js = fluentTranspiler(ftl, { locale: 'en-CA' }) await writeFile('./path/to/en.mjs', js, 'utf8') ``` ### Joining multiple files `compile` also accepts an array of source strings, and `compileFiles` reads and joins files from disk. Sources are concatenated in the order supplied; top-level message and term ids must be unique across the set. ```javascript import { writeFile } from 'node:fs/promises' import { compileFiles } from 'fluent-transpiler' const js = await compileFiles( ['./common.ftl', './brand.ftl', './app.ftl'], { locale: 'en-CA' }, ) await writeFile('./en.mjs', js, 'utf8') ```