How It Works

Pipeline Overview

Source Code → Extract → Catalog → Compile → Bundle
     ↓           ↓         ↓          ↓         ↓
  .vue/.tsx   fluenti    .po       .js module   Vite
              extract    catalog   per locale   build

v-t Directive Compilation

The v-t directive is a compile-time nodeTransform, not a runtime directive.

Input:  <p v-t>Hello {{ name }}</p>
   ↓ (Vue compiler nodeTransform)
Output: <p>{{ $t('Hello {{ name }}') }}</p>

t“ Tagged Template Compilation

Direct-import t is Fluenti’s compile-time surface. The Vite plugin and Next loader use AST scope analysis to detect it and transform it at build time:

Input:  import { t } from '@fluenti/react'
        const greeting = t`Hello ${name}`
   ↓ (Vite transform hook — scope-aware AST)
Output: const greeting = t('Hello {name}', { name: name })

Only Fluenti’s imported t inside supported scopes is transformed. Other variables named t are left untouched.

Message Extraction

fluenti extract scans source files for all translatable patterns and outputs a catalog:

{
  "Hello {name}": {
    "message": "Hello {name}",
    "origin": { "file": "src/App.vue", "line": 5 }
  }
}

Message Compilation

fluenti compile converts ICU messages into optimized JavaScript:

// @fluenti/compiled v1
/* @__PURE__ */ export const _a1b2c3 = (v) => `Hello ${v.name}`
/* @__PURE__ */ export const _d4e5f6 = 'Welcome to Fluenti'

export default {
  'Hello {name}': _a1b2c3,
  'Welcome to Fluenti': _d4e5f6,
}

Every compiled file starts with a // @fluenti/compiled v1 version marker (CATALOG_VERSION). Static messages become plain strings (zero overhead). Dynamic messages become small functions. The @__PURE__ annotations enable tree-shaking — unused messages are eliminated from the production bundle. The export default re-export allows catalog imports by message ID key.

ICU Parser

The core uses a hand-written recursive descent parser for ICU MessageFormat. It handles variables, plurals, selects, nested messages, number/date functions, and quote escaping.