Introduction

Fluenti is a compile-time internationalization library for modern frameworks. It supports Vue, React, and SolidJS, with Svelte planned. It eliminates the three biggest pain points of traditional i18n: manual key management, runtime parsing overhead, and clunky rich text APIs.

Why Fluenti exists

The key management tax

Every i18n library asks you to invent a key for every string:

// en.json — you maintain this by hand
{
  "pages.home.hero.title": "Welcome to our app",
  "pages.home.hero.subtitle": "The best tool for ...",
  "pages.home.cta": "Get started"
}

Keys drift out of sync. Unused keys pile up. Developers spend time naming things instead of building features.

Fluenti’s answer: the source text is the key. Write <h1 v-t>Welcome to our app</h1> and extraction happens automatically. No JSON file to maintain.

Runtime parsing overhead

Traditional libraries ship a full ICU parser to the browser, parsing message strings on every render. For a page with 50 translated strings, that’s 50 parse calls before the user sees anything.

Fluenti’s answer: the v-t directive is a Vue nodeTransform — it rewrites your template at build time. The compiled render function contains the translated string directly. At runtime, there is nothing left to parse.

Clunky rich text

Need a link inside a translated sentence? Most libraries force you into one of these:

v-html (XSS risk)

<!-- vue-i18n: raw HTML injection -->
<p v-html="$t('click_here', { link: '<a href=\'/docs\'>here</a>' })" />

Indexed slots

{/* Lingui: numbered placeholders */}
<Trans>Click <0>here</0> to continue</Trans>
{/* Translators see: Click {0} to continue */}

Fluenti

<!-- Real HTML elements — no indices, no XSS -->
<Trans>Click <a href="/docs">here</a> to continue</Trans>

Fluenti preserves your actual markup. Translators see HTML they already understand, and there is no XSS vector.

How Fluenti compares

Feature	vue-i18n	Lingui	Fluenti
Keys	Manual key strings	Auto-generated IDs	Source text = key
Rich text	v-html (XSS risk)	<0>indexed</0> placeholders	Native <a>, <strong>, etc.
Runtime cost	Full parser in bundle	Compiled messages	Compiled + v-t zero-cost
Code splitting	Manual	Manual	Built-in locale chunks
Catalog format	JSON only	PO / JSON	PO / JSON
SSR	Plugin config required	Custom setup	Built-in locale detection
Frameworks	Vue only	React only	Vue, React, Solid
ICU MessageFormat	Partial support	Full	Full
Formatters	Separate @intlify/core	External packages	Built-in d() / n()

Architecture overview

Fluenti’s pipeline turns your source text into optimized, per-locale bundles at build time:

  Source code          Extract           Catalog          Translate
 ┌──────────┐      ┌──────────┐      ┌──────────┐      ┌──────────┐
 │ <h1 v-t> │ ───► │ fluenti  │ ───► │  .po     │ ───► │ Poedit / │
 │ Hello!   │      │ extract  │      │ catalog  │      │ Crowdin  │
 │ </h1>    │      └──────────┘      └──────────┘      └──────────┘
 └──────────┘                                                │
                                                             ▼
  Ship                Compile                          Translated
 ┌──────────┐      ┌──────────┐      ┌──────────────────────────┐
 │  Vite    │ ◄─── │ fluenti  │ ◄─── │ .po catalog with target  │
 │  bundle  │      │ compile  │      │ language strings filled   │
 └──────────┘      └──────────┘      └──────────────────────────┘

1. Write source text directly in your templates: <h1 v-t>Welcome</h1> or t`Hello!`

2. Extract messages with fluenti extract — scans Vue SFCs and TSX files, generates PO catalogs

3. Translate using any gettext-compatible tool (Poedit, Crowdin, Weblate) or translate the PO files by hand

4. Compile with fluenti compile — generates optimized JS modules, one per locale, ready for code splitting

5. Ship — Vite bundles compiled translations automatically via @fluenti/vite-plugin, with static or dynamic locale loading

Performance

Fluenti’s compile-time architecture provides fundamental performance advantages over runtime i18n libraries:

Aspect	Runtime libraries	Fluenti
Bundle size	Ship ICU parser + runtime (15-40 KB)	No parser shipped — compiled messages are plain functions
Parse cost	Parse every message on render	Zero parse cost — messages are pre-compiled strings/functions
Rich text	Runtime DOM manipulation or v-html	Compiled at build time into static render instructions
Code splitting	Manual per-locale setup	Built-in splitting: 'dynamic' with automatic chunk loading

The v-t directive in Vue is a nodeTransform — it rewrites your template during compilation, so the translated string appears directly in the render function. There is literally nothing left to execute at runtime for static translations.

For dynamic messages (with variables, plurals, or selects), Fluenti compiles ICU patterns into small functions that perform string concatenation — no parsing, no AST traversal, just direct value interpolation.

Packages

Package	Description
@fluenti/core	Framework-agnostic ICU parser, compiler, interpolation, plural/select, and formatters
@fluenti/vue	Vue 3 plugin: v-t directive, <Trans>, <Plural>, <Select>, useI18n() composable
@fluenti/react	React integration: I18nProvider, <Trans>, <Plural>, <Select>, useI18n() hook
@fluenti/solid	SolidJS integration: I18nProvider, <Trans>, <Plural>, <Select>, useI18n() hook
@fluenti/cli	Message extraction (Vue SFC + TSX), PO/JSON catalog format, compilation
@fluenti/vue/vite-plugin	Vite plugin for Vue: build-time v-t transforms, compile-time `t“ optimization, and locale chunk loading
@fluenti/react/vite-plugin	Vite plugin for React: compile-time `t“ optimization and locale chunk loading
@fluenti/solid/vite-plugin	Vite plugin for SolidJS: compile-time `t“ optimization and locale chunk loading
@fluenti/nuxt	Nuxt module: locale-prefixed routing (4 strategies), SEO helpers, composables
@fluenti/vue-i18n-compat	Progressive migration bridge — run vue-i18n and Fluenti side by side

Installation

Vue

pnpm

pnpm add @fluenti/core @fluenti/vue
pnpm add -D @fluenti/cli

npm

npm install @fluenti/core @fluenti/vue
npm install -D @fluenti/cli

React

pnpm

pnpm add @fluenti/core @fluenti/react
pnpm add -D @fluenti/cli

npm

npm install @fluenti/core @fluenti/react
npm install -D @fluenti/cli

SolidJS

pnpm

pnpm add @fluenti/core @fluenti/solid
pnpm add -D @fluenti/cli

npm

npm install @fluenti/core @fluenti/solid
npm install -D @fluenti/cli

Nuxt

pnpm

pnpm add @fluenti/nuxt @fluenti/core @fluenti/vue
pnpm add -D @fluenti/cli

npm

npm install @fluenti/nuxt @fluenti/core @fluenti/vue
npm install -D @fluenti/cli

Requirements

• Node.js >= 18
• Vue >= 3.4 (for Vue bindings)
• React >= 18 (for React bindings)
• SolidJS >= 1.8 (for Solid bindings)
• Vite >= 5 (for Vite plugin)
• Nuxt >= 3 (for Nuxt module)

Next steps

• Quick Start — build your first translated app
• How It Works — understand the compile-time pipeline
• Translating Content — v-t, t“, Trans, Plural, Select
• vue-i18n bridge — gradual migration from vue-i18n