@fluenti/vue 0.2.1 → 0.3.0

package/llms-migration.txt

@@ -0,0 +1,199 @@
+# Migrating to @fluenti/vue from vue-i18n
+
+> Step-by-step guide to migrate a Vue 3 app from vue-i18n (v9/v10) to Fluenti.
+
+## Overview
+
+Fluenti is a **compile-time** i18n library — translations are compiled to optimized JS at build time, resulting in zero runtime overhead and smaller bundles. vue-i18n is a runtime library that parses messages on every render.
+
+Key differences:
+- Fluenti uses ICU MessageFormat; vue-i18n uses its own syntax
+- Fluenti requires a Vite plugin for build-time compilation
+- Fluenti catalog files use PO (gettext) or JSON format, managed by the CLI
+- No runtime parser needed — messages become plain strings or template functions
+
+## Gradual Migration with @fluenti/vue-i18n-compat
+
+For large projects, use the compatibility bridge to run both libraries side by side:
+
+```bash
+pnpm add @fluenti/vue-i18n-compat @fluenti/core @fluenti/vue
+```
+
+```ts
+import { createI18n } from 'vue-i18n'
+import { createFluenti } from '@fluenti/vue'
+import { createFluentBridge } from '@fluenti/vue-i18n-compat'
+
+const i18n = createI18n({ legacy: false, locale: 'en', messages: { en: legacyMessages } })
+const fluenti = createFluenti({ locale: 'en', fallbackLocale: 'en', messages: { en: newMessages } })
+const bridge = createFluentBridge({ vueI18n: i18n, fluenti, priority: 'fluenti-first' })
+
+app.use(bridge) // installs both, syncs locale, falls through on lookups
+```
+
+Then migrate messages one at a time. When done, remove the bridge and use @fluenti/vue directly.
+
+## Step-by-step Migration (Direct)
+
+### 1. Install Fluenti packages
+
+```bash
+pnpm add @fluenti/core @fluenti/vue
+pnpm add -D @fluenti/cli
+```
+
+### 2. Update Vite config
+
+```ts
+// vite.config.ts
+import vue from '@vitejs/plugin-vue'
+import fluentiVue from '@fluenti/vue/vite-plugin'
+
+export default {
+  plugins: [vue(), fluentiVue()],
+}
+```
+
+### 3. Replace plugin setup
+
+Before (vue-i18n):
+```ts
+import { createI18n } from 'vue-i18n'
+const i18n = createI18n({ locale: 'en', messages: { en, ja } })
+app.use(i18n)
+```
+
+After (Fluenti):
+```ts
+import { createFluenti } from '@fluenti/vue'
+const fluent = createFluenti({ locale: 'en', fallbackLocale: 'en', messages: { en, ja } })
+app.use(fluent)
+```
+
+### 4. Update composable usage
+
+Before (vue-i18n):
+```ts
+import { useI18n } from 'vue-i18n'
+const { t, locale } = useI18n()
+```
+
+After (Fluenti):
+```ts
+import { useI18n } from '@fluenti/vue'
+const { t, locale, setLocale } = useI18n()
+```
+
+### 5. Convert message syntax
+
+vue-i18n named interpolation → ICU MessageFormat:
+```
+# vue-i18n
+"hello": "Hello, {name}!"
+
+# Fluenti (same for simple cases)
+"hello": "Hello, {name}!"
+```
+
+vue-i18n pluralization → ICU plural:
+```
+# vue-i18n (pipe syntax)
+"items": "no items | one item | {count} items"
+
+# Fluenti (ICU MessageFormat)
+"items": "{count, plural, =0 {no items} one {one item} other {{count} items}}"
+```
+
+vue-i18n linked messages → not supported (use message functions):
+```
+# vue-i18n
+"greeting": "@:hello, welcome!"
+
+# Fluenti — inline the full message or use code
+"greeting": "Hello, {name}, welcome!"
+```
+
+### 6. Update template syntax
+
+Before (vue-i18n):
+```vue
+<template>
+  <p>{{ $t('hello', { name: 'World' }) }}</p>
+  <i18n-t keypath="terms" tag="p">
+    <template #link><a href="/terms">terms</a></template>
+  </i18n-t>
+</template>
+```
+
+After (Fluenti):
+```vue
+<template>
+  <p>{{ t('hello', { name: 'World' }) }}</p>
+  <Trans message="Read the {0}terms{1}">
+    <template #0><a href="/terms"></template>
+    <template #1></a></template>
+  </Trans>
+  <!-- Or use v-t directive for simple text -->
+  <p v-t>Hello</p>
+</template>
+```
+
+### 7. Remove vue-i18n
+
+```bash
+pnpm remove vue-i18n
+```
+
+## API Mapping Table
+
+| vue-i18n | Fluenti |
+|----------|---------|
+| `createI18n()` | `createFluenti()` |
+| `useI18n()` | `useI18n()` |
+| `t(key, values)` | `t(key, values)` |
+| `tc(key, count)` | `t(key, { count })` (ICU plural) |
+| `te(key)` | `te(key)` |
+| `tm(key)` | `tm(key)` |
+| `d(value, format)` | `d(value, style)` |
+| `n(value, format)` | `n(value, style)` |
+| `locale.value = 'ja'` | `setLocale('ja')` |
+| `$t()` in template | `t()` in template (via useI18n) |
+| `<i18n-t>` component | `<Trans>` component |
+| `v-t` directive | `v-t` directive (same syntax) |
+| `@:key` linked messages | Not supported — inline messages |
+| Pipe plurals `a \| b \| c` | ICU `{n, plural, ...}` |
+| `numberFormats` option | `numberFormats` option |
+| `datetimeFormats` option | `dateFormats` option |
+
+## Translation File Conversion
+
+Use the Fluenti CLI to manage catalogs:
+
+```bash
+# Create config
+cat > fluenti.config.ts << 'EOF'
+export default {
+  sourceLocale: 'en',
+  locales: ['en', 'ja'],
+  catalogDir: './locales',
+  format: 'po',
+  include: ['./src/**/*.{vue,ts}'],
+  compileOutDir: './locales/compiled',
+}
+EOF
+
+# Extract messages from source
+npx fluenti extract
+
+# Compile catalogs to JS
+npx fluenti compile
+```
+
+## Key Behavioral Differences
+
+1. **No runtime parser** — messages are compiled at build time, so syntax errors are caught early
+2. **No lazy locale loading by default** — use `lazyLocaleLoading: true` with a `chunkLoader` for dynamic locale chunks
+3. **No global `$t`** — use `useI18n()` composable or `v-t` directive
+4. **ICU MessageFormat** — standard plural/select/number/date formatting, not custom vue-i18n syntax
+5. **PO file support** — compatible with professional translation tools (Poedit, Crowdin, Weblate)

package/llms.txt

@@ -0,0 +1,82 @@
+# @fluenti/vue
+
+> Vue 3 bindings for Fluenti — compile-time `t`, `v-t`, runtime-capable components, and a `useI18n()` composable.
+
+@fluenti/vue provides the Vue-side runtime for Fluenti. The recommended authoring path is:
+
+- compile-time: `import { t } from '@fluenti/vue'`
+- runtime / imperative usage: `useI18n()`
+- template authoring: `v-t`, `<Trans>`, `<Plural>`, `<Select>`
+
+## Install
+
+```bash
+pnpm add @fluenti/core @fluenti/vue @fluenti/vite-plugin
+```
+
+## Quick Start
+
+```ts
+import { createFluenti } from '@fluenti/vue'
+
+const fluent = createFluenti({
+  locale: 'en',
+  fallbackLocale: 'en',
+  messages: { en, ja },
+})
+
+app.use(fluent)
+```
+
+## Main Exports
+
+- `createFluenti(options)` — Vue plugin factory
+- `useI18n()` — composable returning the full i18n context
+- `t` — compile-time-only authoring API for tagged templates and descriptors
+- `Trans`, `Plural`, `Select`, `DateTime`, `NumberFormat` — runtime-capable components
+- `FluentiTransProps`, `FluentiPluralProps`, `FluentiSelectProps`, `FluentiDateTimeProps`, `FluentiNumberFormatProps` — component prop types
+- `msg` — lazy message descriptor helper
+- `FLUENTI_KEY` — injection key
+
+## Plugin Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `locale` | `string` | — | Active locale (required) |
+| `messages` | `Record<string, Messages>` | — | Message catalogs (required) |
+| `fallbackLocale` | `string` | — | Fallback locale |
+| `fallbackChain` | `Record<string, string[]>` | — | Locale-specific fallback chains |
+| `dateFormats` | `Record<string, DateTimeFormatOptions \| 'relative'>` | — | Named date presets |
+| `numberFormats` | `Record<string, NumberFormatOptions>` | — | Named number presets |
+| `missing` | `(locale, id) => string \| undefined` | — | Missing handler |
+| `componentPrefix` | `string` | `''` | Prefix for registered components |
+| `lazyLocaleLoading` | `boolean` | `false` | Enable async locale loading |
+| `chunkLoader` | `(locale) => Promise<Messages \| { default: Messages }>` | — | Async loader used with `lazyLocaleLoading` |
+
+## Important Boundaries
+
+- `t` imported from `@fluenti/vue` is compile-time only and requires the Fluenti plugin / loader
+- `useI18n().t()` is the full runtime API for lookup and imperative formatting
+- `<Trans>`, `<Plural>`, `<Select>`, `<DateTime>`, and `<NumberFormat>` remain runtime-capable even without the build plugin
+
+## Preferred Usage (compile-time first)
+
+1. `v-t` directive — `<p v-t>Hello {name}</p>` (Vue templates, zero runtime cost)
+2. t\`\` tagged template — t\`Hello {name}\` (primary compile-time API)
+3. `<Trans>` / `<Plural>` / `<Select>` — rich text with inline markup
+4. `msg` tagged template — outside components (route meta, stores)
+5. `useI18n().t()` — runtime fallback for dynamic keys only
+
+❌ AVOID: `t('some.key')` as the default — this is a legacy i18n pattern.
+
+## Server Subpath: `@fluenti/vue/server`
+
+Server-side utilities for SSR:
+
+- `createServerI18n(config)` — request-scoped runtime helpers for server rendering
+- Re-exports from `@fluenti/core`: `detectLocale`, `getSSRLocaleScript`, `getHydratedLocale`, `isRTL`, `getDirection`
+
+## Docs
+
+- Full docs: https://fluenti.dev
+- Source: https://github.com/usefluenti/fluenti

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluenti/vue",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "type": "module",
   "description": "Vue 3 compile-time i18n — v-t directive, Trans/Plural/Select components, useI18n composable",
   "homepage": "https://fluenti.dev",
@@ -41,6 +41,16 @@
         "default": "./dist/index.cjs"
       }
     },
+    "./server": {
+      "import": {
+        "types": "./dist/server.d.ts",
+        "default": "./dist/server.js"
+      },
+      "require": {
+        "types": "./dist/server.d.ts",
+        "default": "./dist/server.cjs"
+      }
+    },
     "./vite-plugin": {
       "import": {
         "types": "./dist/vite-plugin.d.ts",
@@ -53,7 +63,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "llms*.txt"
   ],
   "peerDependencies": {
     "vue": "^3.5",
@@ -65,8 +76,8 @@
     }
   },
   "dependencies": {
-    "@fluenti/core": "0.2.1",
-    "@fluenti/vite-plugin": "0.2.1"
+    "@fluenti/core": "0.3.0",
+    "@fluenti/vite-plugin": "0.3.0"
   },
   "devDependencies": {
     "typescript": "^5.9",
@@ -82,6 +93,7 @@
     "build": "vite build",
     "dev": "vite build --watch",
     "test": "vitest run",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "bench": "vitest bench"
   }
 }