# @fluenti/cli

> CLI tool for the Fluenti i18n framework. Extracts translatable messages from Vue SFC and TSX/JSX source files, compiles PO/JSON catalogs to optimized ES modules with tree-shaking support, shows translation progress stats, and provides AI-powered translation via Claude Code or Codex CLI.

- Package: `@fluenti/cli`
- Binary: `fluenti`
- Docs: https://fluenti.dev
- Repository: https://github.com/usefluenti/fluenti/tree/main/packages/cli
- License: MIT

## Installation

```bash
pnpm add -D @fluenti/cli
```

## Configuration

Create `fluenti.config.ts` (or `.js` / `.mjs`) in your project root:

```ts
export default {
  sourceLocale: 'en',
  locales: ['en', 'ja', 'zh-CN'],
  catalogDir: './locales',
  format: 'po' as const,              // 'po' or 'json'
  include: ['./src/**/*.{vue,tsx,jsx,ts,js}'],
  compileOutDir: './src/locales/compiled',
}
```

| Property | Type | Default | Description |
|---|---|---|---|
| `sourceLocale` | `string` | `'en'` | Source language for extraction |
| `locales` | `string[]` | `['en']` | All supported locales |
| `catalogDir` | `string` | `'./locales'` | Directory for PO/JSON catalog files |
| `format` | `'po' \| 'json'` | `'po'` | Catalog format (PO is gettext-compatible; JSON is simple key-value) |
| `include` | `string[]` | `['./src/**/*.{vue,tsx,jsx,ts,js}']` | Glob patterns for source files to scan |
| `compileOutDir` | `string` | `'./locales/compiled'` | Output directory for compiled JS modules |

Config is loaded via `jiti` with fallback to defaults. Searched paths: `fluenti.config.ts`, `fluenti.config.js`, `fluenti.config.mjs`.

## Commands

- `fluenti extract [--config path]`: Scan source files for translatable messages and update catalog files. Extracts from Vue SFC (`v-t`, `<Trans>`, `<Plural>`, `<Select>`, direct-import `t`, runtime `t` bindings) and TSX/JSX (`<Trans>`, `<Plural>`, `<Select>`, direct-import `t`, runtime `t` bindings). Reports added, unchanged, and obsolete counts per locale.
- `fluenti compile [--config path]`: Compile catalogs to optimized ES modules. Output: `.js` files with tree-shakeable named exports and `@__PURE__` annotations, plus a `export default { ... }` re-export with message ID keys. Also generates an `index.js` with locale list and lazy loaders.
- `fluenti stats [--config path]`: Display a table of translation progress per locale (total messages, translated count, completion percentage). Excludes obsolete entries.
- `fluenti translate [--config path] [--provider claude|codex] [--locale xx] [--batch-size N]`: AI-powered translation of untranslated messages using local CLI tools. Default provider: `claude` (Claude Code CLI). Default batch size: `50`. Preserves ICU MessageFormat placeholders and HTML tags. Translates all non-source locales by default, or a specific locale with `--locale`.

## Workflow

```bash
fluenti extract          # 1. Extract messages from source
fluenti translate        # 2. AI-translate untranslated messages
fluenti compile          # 3. Compile to tree-shakeable ES modules
fluenti stats            # 4. Check translation progress
```

## Programmatic API

All CLI commands are also available as importable functions from `@fluenti/cli`:

- `extractFromTsx(code, options?)`: Extract translatable messages from TSX/JSX source code
- `updateCatalog(catalog, extracted, options?)`: Merge extracted messages into an existing catalog, returning added/unchanged/obsolete counts
- `readJsonCatalog(path)` / `writeJsonCatalog(path, catalog)`: Read/write JSON format catalogs
- `readPoCatalog(path)` / `writePoCatalog(path, catalog)`: Read/write PO (gettext) format catalogs
- `compileCatalog(catalog, locale)`: Compile a catalog into an optimized ES module string
- `compileIndex(locales)`: Generate the `index.js` barrel with locale list and lazy loaders
- `collectAllIds(catalogs)`: Collect all unique message IDs across multiple catalogs
- `runExtract(options)`: Programmatic equivalent of `fluenti extract`
- `runCompile(options)`: Programmatic equivalent of `fluenti compile`
- `defineConfig(config)`: Type-safe config helper (identity function)
- `loadConfig(configPath?)`: Load and resolve `fluenti.config.ts` (uses jiti)
- `hashMessage(message, context?)`: Re-export of FNV-1a hash from `@fluenti/core`

### Key Types

- `CatalogData`, `CatalogEntry`, `UpdateResult` — catalog data structures
- `CompileStats` — compilation statistics
- `RunCompileOptions`, `RunExtractOptions` — options for programmatic runners
- `FluentiBuildConfig` — re-exported from `@fluenti/core`

## Documentation

- Full docs: [fluenti.dev](https://fluenti.dev)
- Repository: [GitHub](https://github.com/usefluenti/fluenti)
