CLI Usage

The @fluenti/cli provides commands for the extract → translate → compile workflow.

`fluenti extract`

Scan source files and update translation catalogs:

npx fluenti extract

Supports:

t() and t` ` calls
<Trans> component children
<Plural> components
v-t directive (Vue)
msg tagged template

The command reads fluenti.config.ts for include, exclude, catalogDir, and format settings.

Flags

Flag	Type	Default	Description
`--config`	`string`	—	Path to config file
`--clean`	`boolean`	`false`	Remove obsolete messages from catalogs
`--no-fuzzy`	`boolean`	`false`	Skip fuzzy matching for similar messages
`--no-cache`	`boolean`	`false`	Disable incremental extraction cache

`fluenti compile`

Compile message catalogs to optimized JavaScript modules:

npx fluenti compile

Input: JSON or PO catalog files from catalogDir
Output: ES modules with string literals and template functions in compileOutDir
Each message becomes a /* @__PURE__ */ annotated named export for tree-shaking
Static messages compile to plain strings (zero overhead)
Dynamic messages compile to small functions

Flags

Flag	Type	Default	Description
`--config`	`string`	—	Path to config file
`--skip-fuzzy`	`boolean`	`false`	Exclude fuzzy-marked translations from output
`--no-cache`	`boolean`	`false`	Disable compilation cache
`--parallel`	`boolean`	`false`	Enable parallel compilation using worker threads
`--concurrency`	`number`	auto	Max number of worker threads

`fluenti stats`

Show translation progress:

npx fluenti stats

Locale    Total   Translated   %
──────    ─────   ──────────   ──────
en        142     142          100%
ja        142     128           90%
zh-CN     142      97           68%

To enforce a minimum translation percentage, set strictThreshold in your fluenti.config.ts:

export default defineConfig({
  strictThreshold: 90, // fail if any locale is below 90%
})

`fluenti lint`

Check translation quality — missing translations, inconsistent placeholders, fuzzy entries:

npx fluenti lint
npx fluenti lint --strict          # Treat warnings as errors
npx fluenti lint --locale ja       # Lint a single locale

Flags

Flag	Type	Default	Description
`--config`	`string`	—	Path to config file
`--strict`	`boolean`	`false`	Treat warnings as errors (non-zero exit code)
`--locale`	`string`	—	Lint a specific locale only

`fluenti check`

Check translation coverage — designed for CI pipelines:

npx fluenti check --min-coverage 90
npx fluenti check --ci                 # GitHub Actions annotations
npx fluenti check --format json        # Machine-readable output
npx fluenti check --locale ja          # Check a single locale

Flags

Flag	Type	Default	Description
`--config`	`string`	—	Path to config file
`--min-coverage`	`number`	`100`	Minimum coverage percentage (0–100)
`--format`	`'text' \| 'json' \| 'github'`	`'text'`	Output format
`--ci`	`boolean`	`false`	Alias for `--format github`
`--locale`	`string`	—	Check a specific locale only

The github format outputs ::error and ::warning annotations that GitHub Actions renders inline on PRs.

`fluenti init`

Interactive project setup:

npx fluenti init

Detects your framework from package.json dependencies and prompts for:

Source locale (default: en)
Target locales (e.g. ja, zh-CN)
Catalog format (po or json)

Generates:

fluenti.config.ts with your chosen settings
Updates .gitignore to exclude compiled output
Adds i18n:extract and i18n:compile scripts to package.json

Supported frameworks: Vue, React, SolidJS, Next.js, Nuxt, SolidStart.

`fluenti translate`

AI-powered translation using Claude or Codex CLI:

npx fluenti translate --locale ja
npx fluenti translate --locale zh-CN --provider codex --batch-size 100

Flag	Type	Default	Description
`--provider`	`'claude' \| 'codex'`	`'claude'`	AI provider to use
`--locale`	`string`	—	Target locale to translate
`--batch-size`	`number`	`50`	Messages per AI request
`--dry-run`	`boolean`	`false`	Preview translations without writing files
`--context`	`string`	—	Project context description to improve translation quality
`--config`	`string`	—	Path to config file

The command batches untranslated messages from your catalogs and sends them to the AI provider. Existing translations are preserved.

`fluenti migrate`

AI-assisted migration from another i18n library:

npx fluenti migrate --from vue-i18n
npx fluenti migrate --from react-i18next --provider codex --write

Flag	Type	Default	Description
`--from`	`string`	—	Source library (required)
`--provider`	`'claude' \| 'codex'`	`'claude'`	AI provider
`--write`	`boolean`	`false`	Write changes to disk (default: dry-run preview)

Supported source libraries: vue-i18n, nuxt-i18n, react-i18next, next-intl, next-i18next, lingui.

The command scans your project for the existing library’s config files, locale files, and source patterns, then generates a migration plan including fluenti.config.ts, converted PO catalogs, and step-by-step migration instructions.

Workflow

┌─────────────────────────────────────────┐
│  0. fluenti init                        │
│     Set up config and scripts           │
│                                         │
│  1. fluenti extract [--no-cache]        │
│     Scan source → update PO/JSON files  │
│                                         │
│  2. Translate                           │
│     Translators edit PO files           │
│     (or use fluenti translate for AI)   │
│                                         │
│  3. fluenti check                       │
│     Verify coverage meets threshold     │
│                                         │
│  4. fluenti compile [--parallel]        │
│     PO → optimised JS modules           │
└─────────────────────────────────────────┘

Programmatic API

For custom tooling, the CLI exports its internals:

import { extractFromVue } from '@fluenti/cli/vue-extractor'
import { extractFromTsx } from '@fluenti/cli'
import { updateCatalog, compileCatalog } from '@fluenti/cli'
import { readPoCatalog, writePoCatalog } from '@fluenti/cli'
import { runExtract, runCompile, loadConfig } from '@fluenti/cli'

For the full programmatic API reference, see @fluenti/cli API.