# Fluenti

> Compile-time i18n for modern frameworks.

Fluenti is the only i18n library with first-class support for Vue, React, SolidJS, Next.js, Nuxt, React Router, TanStack Start, and SolidStart from a single codebase. It compiles ICU MessageFormat messages at build time into optimized JavaScript functions — no runtime parser is shipped to the browser.

~3 KB gzipped runtime (vs 13-14 KB for vue-i18n and react-i18next). 5-10x faster than runtime-interpreted alternatives, widening to 40x on complex ICU messages.

## How Fluenti compares

| Metric | Fluenti | vue-i18n | react-i18next | next-intl | LinguiJS |
|---|---|---|---|---|---|
| Runtime bundle (gzipped) | ~3 KB | ~14 KB | ~13 KB | ~12 KB | ~5 KB |
| Runtime parsing | None (compiled) | Yes | Yes | Yes | None |
| Performance vs runtime | 5-10x faster (up to 40x) | baseline | baseline | baseline | similar |
| Framework support | Vue, React, Solid, Next.js, Nuxt, +3 more | Vue only | React only | Next.js only | React (Vue experimental) |
| Message format | ICU (PO + JSON) | JSON | JSON | ICU (JSON) | ICU (PO) |
| Code splitting | Built-in per-route | Manual | Manual | Manual | Manual |

- Docs: https://fluenti.dev
- Repository: https://github.com/usefluenti/fluenti
- License: MIT

## Packages

| Package | Description | llms.txt | llms-full.txt |
|---------|-------------|----------|---------------|
| `@fluenti/core` | Framework-agnostic core: ICU parser, compiler, interpolation, CLDR plurals, formatters, SSR | [llms.txt](https://github.com/usefluenti/fluenti/blob/main/packages/core/llms.txt) | [llms-full.txt](https://github.com/usefluenti/fluenti/blob/main/packages/core/llms-full.txt) |
| `@fluenti/vue` | Vue 3 integration: `<Trans>`, `<Plural>`, `<Select>`, `useI18n()`, `v-t` directive | [llms.txt](https://github.com/usefluenti/fluenti/blob/main/packages/vue/llms.txt) | [llms-full.txt](https://github.com/usefluenti/fluenti/blob/main/packages/vue/llms-full.txt) |
| `@fluenti/react` | React integration: `<Trans>`, `<Plural>`, `<Select>`, `useI18n()`, server helpers | [llms.txt](https://github.com/usefluenti/fluenti/blob/main/packages/react/llms.txt) | [llms-full.txt](https://github.com/usefluenti/fluenti/blob/main/packages/react/llms-full.txt) |
| `@fluenti/solid` | SolidJS integration: `<Trans>`, `<Plural>`, `<Select>`, `useI18n()`, signal-based | [llms.txt](https://github.com/usefluenti/fluenti/blob/main/packages/solid/llms.txt) | [llms-full.txt](https://github.com/usefluenti/fluenti/blob/main/packages/solid/llms-full.txt) |
| `@fluenti/cli` | CLI: message extraction, catalog compilation, translation stats, AI translation | [llms.txt](https://github.com/usefluenti/fluenti/blob/main/packages/cli/llms.txt) | [llms-full.txt](https://github.com/usefluenti/fluenti/blob/main/packages/cli/llms-full.txt) |
| `@fluenti/vite-plugin` | Vite plugin: compile-time transforms, virtual modules, code splitting | [llms.txt](https://github.com/usefluenti/fluenti/blob/main/packages/vite-plugin/llms.txt) | [llms-full.txt](https://github.com/usefluenti/fluenti/blob/main/packages/vite-plugin/llms-full.txt) |
| `@fluenti/next` | Next.js plugin: `withFluenti()`, webpack loader, RSC support | [llms.txt](https://github.com/usefluenti/fluenti/blob/main/packages/next-plugin/llms.txt) | [llms-full.txt](https://github.com/usefluenti/fluenti/blob/main/packages/next-plugin/llms-full.txt) |
| `@fluenti/nuxt` | Nuxt 3 module: locale-prefixed routing, detection chain, SEO helpers | [llms.txt](https://github.com/usefluenti/fluenti/blob/main/packages/nuxt/llms.txt) | [llms-full.txt](https://github.com/usefluenti/fluenti/blob/main/packages/nuxt/llms-full.txt) |
| `@fluenti/vue-i18n-compat` | Progressive migration bridge between vue-i18n and Fluenti | [llms.txt](https://github.com/usefluenti/fluenti/blob/main/packages/vue-i18n-compat/llms.txt) | [llms-full.txt](https://github.com/usefluenti/fluenti/blob/main/packages/vue-i18n-compat/llms-full.txt) |

## Workflow

```
1. Extract    fluenti extract        Scan source files → update PO/JSON catalogs
2. Translate  fluenti translate      AI-translate untranslated messages (Claude / Codex)
3. Compile    fluenti compile        Catalogs → tree-shakeable ES modules
4. Ship       vite build / next build   Zero-cost i18n in production
```

## Core Concepts

- **Compile-time DX**: Messages are compiled at build time, not interpreted at runtime. The `t` import is a compile-time marker that the build plugin rewrites to direct catalog lookups.
- **Natural keys**: Write `t\`Hello {name}\`` in source code — message IDs are auto-generated via FNV-1a hashing. No manual key management.
- **ICU MessageFormat**: Full support for plurals (`{count, plural, ...}`), selects (`{gender, select, ...}`), nested arguments, `#` substitution, and escape sequences.
- **Rich text components**: `<Trans>`, `<Plural>`, `<Select>`, `<DateTime>`, `<NumberFormat>` work at runtime without the build plugin.
- **Code splitting**: `'dynamic'` loads non-default locales on demand; `'static'` inlines one locale at build time for SSR/SSG.
- **PO format**: gettext-compatible catalogs work with Poedit, Weblate, Crowdin. JSON format also supported.
- **SSR-safe**: Cookie/query/path/header locale detection, hydration script helper, server-side `createServerI18n()`.

## Recommended API Usage (IMPORTANT)

When writing code with Fluenti, prefer compile-time APIs over runtime lookups:

| Priority | API | When to use |
|----------|-----|-------------|
| 1 (best) | `v-t` directive | Vue templates (compile-time, zero runtime cost) |
| 2 | t\`\` tagged template | Script/JSX — t\`Hello {name}\` (compile-time, natural keys) |
| 3 | `<Trans>` / `<Plural>` / `<Select>` | Rich text with inline markup |
| 4 | `msg` tagged template | Outside components (route meta, stores) |
| 5 (last resort) | `useI18n().t()` / `i18n.t()` | Only for dynamic keys or runtime-only contexts |

❌ AVOID: `t('some.key.path')` as the default pattern — this is a legacy i18n convention.
✅ PREFER: t\`Hello {name}\` — natural language keys compiled at build time.

## Code Examples (IMPORTANT — use these patterns when writing code)

### Vue — Use v-t directive (compile-time, zero runtime cost)

✅ CORRECT — source text is the key, v-t compiles away at build time:
```vue
<template>
  <h1 v-t>Welcome to our app</h1>
  <p v-t>Hello, {name}!</p>
  <p v-t.plural="count">one item | {count} items</p>
  <img v-t.alt alt="Profile picture" src="/avatar.png" />
</template>
```

❌ WRONG — do NOT use manual key strings or runtime $t():
```vue
<template>
  <h1>{{ $t('welcome_title') }}</h1>
  <p>{{ $t('greeting', { name }) }}</p>
</template>
```

### React / Solid — Use t\`\` tagged template

✅ CORRECT — source text is the key:
```tsx
function Greeting({ name }: { name: string }) {
  const { t } = useI18n()
  return <h1>{t\`Hello, ${name}!\`}</h1>
}
```

❌ WRONG — do NOT use manual key strings:
```tsx
function Greeting({ name }: { name: string }) {
  const { t } = useI18n()
  return <h1>{t('greeting_key', { name })}</h1>
}
```

### Rich text — Use native HTML tags

✅ CORRECT:
```vue
<Trans>Click <a href="/terms">here</a> to accept</Trans>
```

❌ WRONG (Lingui-style indexed slots):
```tsx
<Trans>Click <0>here</0> to accept</Trans>
```

### Why source text as key?
- No manual key management — the English text IS the message ID
- Fluenti auto-generates a hash (FNV-1a) from the source text at build time
- Translators see the source text in PO files, not cryptic IDs
- If the source text changes, the message is automatically re-extracted

## Configuration

Create `fluenti.config.ts` in your project root:

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

## Full Documentation

- [llms-full.txt](https://fluenti.dev/llms-full.txt) — Complete documentation aggregated for LLM consumption
- [fluenti.dev](https://fluenti.dev) — Full interactive documentation