@fluenti/solid 0.2.0 → 0.3.0

package/llms-migration.txt

@@ -0,0 +1,176 @@
+# Migrating to @fluenti/solid from @solid-primitives/i18n
+
+> Step-by-step guide to migrate a SolidJS app from @solid-primitives/i18n (or manual i18n) to Fluenti.
+
+## Overview
+
+Fluenti is a **compile-time** i18n library — translations are compiled to optimized JS at build time. @solid-primitives/i18n provides a runtime dictionary-based approach. Fluenti offers ICU MessageFormat support, PO/JSON catalog management, and zero runtime overhead.
+
+Key differences:
+- Compile-time compilation vs runtime dictionary lookup
+- ICU MessageFormat (plurals, selects, date/number formatting) vs flat key-value strings
+- CLI-managed extraction and catalog workflow
+- Vite plugin for build-time transforms
+
+## Step-by-step Migration
+
+### 1. Install Fluenti
+
+```bash
+pnpm add @fluenti/core @fluenti/solid
+pnpm add -D @fluenti/cli
+```
+
+### 2. Replace provider setup
+
+Before (@solid-primitives/i18n):
+```tsx
+import { I18nContext, createFluenti } from '@solid-primitives/i18n'
+
+const dict = { en: { hello: 'Hello!' }, ja: { hello: 'こんにちは！' } }
+const value = createFluenti(dict, 'en')
+
+<I18nContext.Provider value={value}>
+  <App />
+</I18nContext.Provider>
+```
+
+After (Fluenti):
+```tsx
+import { I18nProvider } from '@fluenti/solid'
+import en from './locales/compiled/en'
+import ja from './locales/compiled/ja'
+
+<I18nProvider locale="en" fallbackLocale="en" messages={{ en, ja }}>
+  <App />
+</I18nProvider>
+```
+
+### 3. Update translation usage
+
+Before (@solid-primitives/i18n):
+```tsx
+import { useI18n } from '@solid-primitives/i18n'
+const [t, { locale, add }] = useI18n()
+t('hello')
+locale('ja') // switch locale
+```
+
+After (Fluenti):
+```tsx
+import { useI18n } from '@fluenti/solid'
+const { i18n, locale, setLocale } = useI18n()
+i18n.t('hello')
+setLocale('ja')
+```
+
+### 4. Add rich formatting
+
+@solid-primitives/i18n only supports flat strings. Fluenti adds ICU MessageFormat:
+
+```tsx
+// Pluralization
+<Plural value={count} one="# item" other="# items" />
+
+// Gender select
+<Select value={gender} male="He" female="She" other="They" />
+
+// Date/number formatting
+<DateTime value={new Date()} style="long" />
+<NumberFormat value={1234.5} style="currency" />
+
+// Rich text
+<Trans message="Read the {0}docs{1}">
+  {(text) => <a href="/docs">{text}</a>}
+</Trans>
+```
+
+### 5. Set up Vite plugin
+
+```ts
+// vite.config.ts
+import solid from 'vite-plugin-solid'
+import fluentiSolid from '@fluenti/solid/vite-plugin'
+
+export default {
+  plugins: [solid(), fluentiSolid()],
+}
+```
+
+### 6. Set up CLI config and catalogs
+
+```ts
+// fluenti.config.ts
+export default {
+  sourceLocale: 'en',
+  locales: ['en', 'ja'],
+  catalogDir: './locales',
+  format: 'po',
+  include: ['./src/**/*.{tsx,jsx,ts,js}'],
+  compileOutDir: './locales/compiled',
+}
+```
+
+```bash
+npx fluenti extract    # Extract messages from source
+npx fluenti compile    # Compile to JS modules
+```
+
+### 7. Remove old library
+
+```bash
+pnpm remove @solid-primitives/i18n
+```
+
+## API Mapping Table
+
+| @solid-primitives/i18n | Fluenti |
+|------------------------|---------|
+| `createFluenti(dict, locale)` | `createFluenti(config)` or `<I18nProvider>` |
+| `I18nContext.Provider` | `I18nProvider` |
+| `useI18n()` → `[t, { locale, add }]` | `useI18n()` → `{ i18n, locale, setLocale, isLoading }` |
+| `t('key')` | `i18n.t('key')` |
+| `t('key', { name: 'X' })` | `i18n.t('key', { name: 'X' })` |
+| `locale('ja')` (setter) | `setLocale('ja')` |
+| `locale()` (getter) | `locale` (signal) |
+| `add(locale, dict)` | `loadMessages` callback on provider |
+| N/A | `<Trans>` component |
+| N/A | `<Plural>` component |
+| N/A | `<Select>` component |
+| N/A | `<DateTime>` component |
+| N/A | `<NumberFormat>` component |
+| N/A | `i18n.d(date, style)` — date formatting |
+| N/A | `i18n.n(number, style)` — number formatting |
+| N/A | `msg()` — lazy message descriptor |
+
+## Message Format Conversion
+
+@solid-primitives/i18n uses flat key-value dictionaries:
+```ts
+// Before: flat dictionary
+const dict = {
+  en: {
+    hello: 'Hello, {{name}}!',
+    items: '{{count}} items',
+  }
+}
+```
+
+Fluenti uses ICU MessageFormat in PO or JSON catalogs:
+```
+# PO format (locales/en.po)
+msgid "hello"
+msgstr "Hello, {name}!"
+
+msgid "items"
+msgstr "{count, plural, one {{count} item} other {{count} items}}"
+```
+
+## Key Behavioral Differences
+
+1. **Compile-time** — messages compiled to JS functions at build time, no runtime parser
+2. **ICU MessageFormat** — standard format for plurals, selects, date/number formatting
+3. **CLI workflow** — extract → translate → compile pipeline
+4. **Signals-based reactivity** — Fluenti uses SolidJS signals internally for locale state
+5. **PO file support** — compatible with professional translation tools (Poedit, Crowdin, Weblate)
+6. **AI translation** — `npx fluenti translate --provider claude` for automated translation

package/llms.txt

@@ -0,0 +1,64 @@
+# @fluenti/solid
+
+> SolidJS bindings for Fluenti — compile-time `t`, runtime-capable components, and signal-based locale switching.
+
+@fluenti/solid provides Solid-specific runtime APIs for Fluenti. The recommended public path is:
+
+- compile-time authoring: `import { t } from '@fluenti/solid'`
+- runtime / imperative access: `useI18n()`
+- runtime-capable components: `Trans`, `Plural`, `Select`, `DateTime`, `NumberFormat`
+
+## Install
+
+```bash
+pnpm add @fluenti/core @fluenti/solid @fluenti/vite-plugin
+```
+
+## Main Exports
+
+- `createFluentiContext(config)` — context factory (creates a reactive i18n context)
+- `I18nProvider` — provider component
+- `useI18n()` — access the nearest `<I18nProvider>` context
+- `t` — compile-time-only authoring API
+- `Trans`, `Plural`, `Select`, `DateTime`, `NumberFormat`
+- `msg`
+
+### Type Exports
+
+- `FluentiContext`, `FluentiConfig` — context value and config types
+- `FluentiTransProps`, `FluentiPluralProps`, `FluentiSelectProps` — component prop types
+
+## FluentiContext Methods
+
+The context returned by `useI18n()` provides:
+
+- `locale()`, `setLocale(locale)`, `t(id, values?)`, `d(value, style?)`, `n(value, style?)`
+- `format(message, values?)`, `loadMessages(locale, messages)`, `getLocales()`
+- `te(key, locale?)` — check if a translation key exists
+- `tm(key, locale?)` — get the raw compiled message without interpolation
+- `isLoading()`, `loadedLocales()`, `preloadLocale(locale)`
+
+## Config Extensions
+
+- `lazyLocaleLoading?: boolean`
+- `chunkLoader?: (locale) => Promise<Messages | { default: Messages }>`
+
+## Important Boundaries
+
+- imported `t` is compile-time only and requires the Fluenti Vite plugin
+- `useI18n().t()` is the full runtime API
+- `Trans / Plural / Select / DateTime / NumberFormat` remain runtime-capable without the build plugin
+
+## Preferred Usage (compile-time first)
+
+1. t\`\` tagged template — t\`Hello {name}\` (primary compile-time API)
+2. `<Trans>` / `<Plural>` / `<Select>` — rich text with inline markup
+3. `msg` tagged template — outside components (route meta, stores)
+4. `useI18n().t()` — runtime fallback for dynamic keys only
+
+❌ AVOID: `t('some.key')` as the default — this is a legacy i18n pattern.
+
+## Docs
+
+- Full docs: https://fluenti.dev
+- Source: https://github.com/usefluenti/fluenti

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluenti/solid",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "SolidJS compile-time i18n — Trans/Plural/Select components, I18nProvider, useI18n",
   "homepage": "https://fluenti.dev",
@@ -44,6 +44,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",
@@ -57,7 +67,8 @@
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "llms*.txt"
   ],
   "peerDependencies": {
     "solid-js": "^1.8",
@@ -69,8 +80,8 @@
     }
   },
   "dependencies": {
-    "@fluenti/core": "0.2.0",
-    "@fluenti/vite-plugin": "0.2.0"
+    "@fluenti/core": "0.3.0",
+    "@fluenti/vite-plugin": "0.3.0"
   },
   "devDependencies": {
     "@solidjs/testing-library": "^0.8",
@@ -87,6 +98,7 @@
     "build": "vite build",
     "dev": "vite build --watch",
     "test": "vitest run",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "bench": "vitest bench"
   }
 }

package/src/context.ts

@@ -1,6 +1,7 @@
-import { createSignal, createRoot, type Accessor } from 'solid-js'
-import { formatDate, formatNumber, interpolate as coreInterpolate, buildICUMessage, resolveDescriptorId } from '@fluenti/core'
-import type { FluentConfig, Locale, Messages, CompiledMessage, MessageDescriptor, DateFormatOptions, NumberFormatOptions } from '@fluenti/core'
+import { createSignal, type Accessor } from 'solid-js'
+import { createDiagnostics, formatDate, formatNumber } from '@fluenti/core'
+import type { FluentiCoreConfig, Locale, LocalizedString, Messages, CompiledMessage, MessageDescriptor, DateFormatOptions, NumberFormatOptions, DiagnosticsConfig } from '@fluenti/core'
+import { interpolate as coreInterpolate, buildICUMessage, resolveDescriptorId } from '@fluenti/core/internal'
 
 /** Chunk loader for lazy locale loading */
 export type ChunkLoader = (
@@ -12,7 +13,7 @@ interface SplitRuntimeModule {
   __preloadLocale?: (locale: string) => Promise<void>
 }
 
-const SPLIT_RUNTIME_KEY = Symbol.for('fluenti.runtime.solid')
+const SPLIT_RUNTIME_KEY = Symbol.for('fluenti.runtime.solid.v1')
 
 function getSplitRuntimeModule(): SplitRuntimeModule | null {
   const runtime = (globalThis as Record<PropertyKey, unknown>)[SPLIT_RUNTIME_KEY]
@@ -30,7 +31,7 @@ function resolveChunkMessages(
 }
 
 /** Extended config with lazy locale loading support */
-export interface I18nConfig extends FluentConfig {
+export interface FluentiConfig extends FluentiCoreConfig {
   /** Async chunk loader for lazy locale loading */
   chunkLoader?: ChunkLoader
   /** Enable lazy locale loading through chunkLoader */
@@ -41,34 +42,40 @@ export interface I18nConfig extends FluentConfig {
   dateFormats?: DateFormatOptions
   /** Named number format styles */
   numberFormats?: NumberFormatOptions
+  /** Runtime diagnostics configuration */
+  diagnostics?: DiagnosticsConfig
 }
 
 /** Reactive i18n context holding locale signal and translation utilities */
-export interface I18nContext {
+export interface FluentiContext {
   /** Reactive accessor for the current locale */
   locale(): Locale
   /** Set the active locale (async when lazy locale loading is enabled) */
   setLocale(locale: Locale): Promise<void>
   /** Translate a message by id with optional interpolation values */
-  t(id: string | MessageDescriptor, values?: Record<string, unknown>): string
+  t(id: string | MessageDescriptor, values?: Record<string, unknown>): LocalizedString
   /** Tagged template form: t`Hello ${name}` */
-  t(strings: TemplateStringsArray, ...exprs: unknown[]): string
+  t(strings: TemplateStringsArray, ...exprs: unknown[]): LocalizedString
   /** Merge additional messages into a locale catalog at runtime */
   loadMessages(locale: Locale, messages: Messages): void
   /** Return all locale codes that have loaded messages */
   getLocales(): Locale[]
   /** Format a date value for the current locale */
-  d(value: Date | number, style?: string): string
+  d(value: Date | number, style?: string): LocalizedString
   /** Format a number value for the current locale */
-  n(value: number, style?: string): string
+  n(value: number, style?: string): LocalizedString
   /** Format an ICU message string directly (no catalog lookup) */
-  format(message: string, values?: Record<string, unknown>): string
+  format(message: string, values?: Record<string, unknown>): LocalizedString
   /** Whether a locale chunk is currently being loaded */
   isLoading: Accessor<boolean>
   /** Set of locales whose messages have been loaded */
   loadedLocales: Accessor<Set<string>>
   /** Preload a locale in the background without switching to it */
   preloadLocale(locale: string): void
+  /** Check if a translation key exists for the given or current locale */
+  te(key: string, loc?: string): boolean
+  /** Get the raw compiled message for a key without interpolation */
+  tm(key: string, loc?: string): CompiledMessage | undefined
 }
 
 /**
@@ -77,22 +84,23 @@ export interface I18nContext {
  * The returned `t()` reads the internal `locale()` signal, so any
  * Solid computation that calls `t()` will re-run when the locale changes.
  */
-export function createI18nContext(config: FluentConfig | I18nConfig): I18nContext {
+export function createFluentiContext(config: FluentiCoreConfig | FluentiConfig): FluentiContext {
   const [locale, setLocaleSignal] = createSignal<Locale>(config.locale)
   const [isLoading, setIsLoading] = createSignal(false)
   const loadedLocalesSet = new Set<string>([config.locale])
   const [loadedLocales, setLoadedLocales] = createSignal(new Set(loadedLocalesSet))
   const messages: Record<string, Messages> = { ...config.messages }
-  const i18nConfig = config as I18nConfig
+  const i18nConfig = config as FluentiConfig
+  const diagnostics = i18nConfig.diagnostics ? createDiagnostics(i18nConfig.diagnostics) : undefined
   const lazyLocaleLoading = i18nConfig.lazyLocaleLoading
-    ?? (config as I18nConfig & { splitting?: boolean }).splitting
+    ?? (config as FluentiConfig & { splitting?: boolean }).splitting
     ?? false
 
   function lookupCatalog(
     id: string,
     loc: Locale,
     values?: Record<string, unknown>,
-  ): string | undefined {
+  ): LocalizedString | undefined {
     const catalog = messages[loc]
     if (!catalog) {
       return undefined
@@ -104,21 +112,21 @@ export function createI18nContext(config: FluentConfig | I18nConfig): I18nContex
     }
 
     if (typeof msg === 'function') {
-      return msg(values)
+      return msg(values) as LocalizedString
     }
 
     if (typeof msg === 'string' && values) {
-      return coreInterpolate(msg, values, loc)
+      return coreInterpolate(msg, values, loc) as LocalizedString
     }
 
-    return String(msg)
+    return String(msg) as LocalizedString
   }
 
   function lookupWithFallbacks(
     id: string,
     loc: Locale,
     values?: Record<string, unknown>,
-  ): string | undefined {
+  ): LocalizedString | undefined {
     const localesToTry: Locale[] = [loc]
     const seen = new Set(localesToTry)
 
@@ -140,6 +148,9 @@ export function createI18nContext(config: FluentConfig | I18nConfig): I18nContex
     for (const targetLocale of localesToTry) {
       const result = lookupCatalog(id, targetLocale, values)
       if (result !== undefined) {
+        if (targetLocale !== loc) {
+          diagnostics?.fallbackUsed(loc, targetLocale, id)
+        }
         return result
       }
     }
@@ -150,14 +161,14 @@ export function createI18nContext(config: FluentConfig | I18nConfig): I18nContex
   function resolveMissing(
     id: string,
     loc: Locale,
-  ): string | undefined {
+  ): LocalizedString | undefined {
     if (!config.missing) {
       return undefined
     }
 
     const result = config.missing(loc, id)
     if (result !== undefined) {
-      return result
+      return result as LocalizedString
     }
     return undefined
   }
@@ -166,27 +177,29 @@ export function createI18nContext(config: FluentConfig | I18nConfig): I18nContex
     id: string,
     loc: Locale,
     values?: Record<string, unknown>,
-  ): string {
+  ): LocalizedString {
     const catalogResult = lookupWithFallbacks(id, loc, values)
     if (catalogResult !== undefined) {
       return catalogResult
     }
 
+    diagnostics?.missingKey(loc, id)
+
     const missingResult = resolveMissing(id, loc)
     if (missingResult !== undefined) {
       return missingResult
     }
 
     if (id.includes('{')) {
-      return coreInterpolate(id, values, loc)
+      return coreInterpolate(id, values, loc) as LocalizedString
     }
 
-    return id
+    return id as LocalizedString
   }
 
-  function t(strings: TemplateStringsArray, ...exprs: unknown[]): string
-  function t(id: string | MessageDescriptor, values?: Record<string, unknown>): string
-  function t(idOrStrings: string | MessageDescriptor | TemplateStringsArray, ...rest: unknown[]): string {
+  function t(strings: TemplateStringsArray, ...exprs: unknown[]): LocalizedString
+  function t(id: string | MessageDescriptor, values?: Record<string, unknown>): LocalizedString
+  function t(idOrStrings: string | MessageDescriptor | TemplateStringsArray, ...rest: unknown[]): LocalizedString {
     // Tagged template form: t`Hello ${name}`
     if (Array.isArray(idOrStrings) && 'raw' in idOrStrings) {
       const strings = idOrStrings as TemplateStringsArray
@@ -213,10 +226,10 @@ export function createI18nContext(config: FluentConfig | I18nConfig): I18nContex
       }
 
       if (id.message !== undefined) {
-        return coreInterpolate(id.message, values, currentLocale)
+        return coreInterpolate(id.message, values, currentLocale) as LocalizedString
       }
 
-      return messageId ?? ''
+      return (messageId ?? '') as LocalizedString
     }
 
     return resolveMessage(id, currentLocale, values)
@@ -280,59 +293,25 @@ export function createI18nContext(config: FluentConfig | I18nConfig): I18nContex
 
   const getLocales = (): Locale[] => Object.keys(messages)
 
-  const d = (value: Date | number, style?: string): string =>
-    formatDate(value, locale(), style, i18nConfig.dateFormats)
+  const d = (value: Date | number, style?: string): LocalizedString =>
+    formatDate(value, locale(), style, i18nConfig.dateFormats) as LocalizedString
 
-  const n = (value: number, style?: string): string =>
-    formatNumber(value, locale(), style, i18nConfig.numberFormats)
+  const n = (value: number, style?: string): LocalizedString =>
+    formatNumber(value, locale(), style, i18nConfig.numberFormats) as LocalizedString
 
-  const format = (message: string, values?: Record<string, unknown>): string => {
-    return coreInterpolate(message, values, locale())
+  const format = (message: string, values?: Record<string, unknown>): LocalizedString => {
+    return coreInterpolate(message, values, locale()) as LocalizedString
   }
 
-  return { locale, setLocale, t, loadMessages, getLocales, d, n, format, isLoading, loadedLocales, preloadLocale }
-}
-
-// ─── Module-level singleton ─────────────────────────────────────────────────
-
-let globalCtx: I18nContext | undefined
-
-/**
- * Initialize the global i18n singleton.
- *
- * Call once at app startup (e.g. in your entry file) before any `useI18n()`.
- * Signals are created inside a `createRoot` so they outlive any component scope.
- *
- * Returns the context for convenience, but `useI18n()` will also find it.
- */
-export function createI18n(config: FluentConfig | I18nConfig): I18nContext {
-  const ctx = createRoot(() => createI18nContext(config))
-
-  // Only set global singleton in browser (client-side).
-  // In SSR, each request should use <I18nProvider> for per-request isolation.
-  if (typeof window !== 'undefined') {
-    globalCtx = ctx
-  } else {
-    console.warn(
-      '[fluenti] createI18n() detected SSR environment. ' +
-      'Use <I18nProvider> for per-request isolation in SSR.',
-    )
+  const te = (key: string, loc?: string): boolean => {
+    const msgs = messages[loc ?? locale()]
+    return msgs !== undefined && key in msgs
   }
 
-  return ctx
-}
-
-/** @internal — used by useI18n and I18nProvider */
-export function getGlobalI18nContext(): I18nContext | undefined {
-  return globalCtx
-}
-
-/** @internal — used by I18nProvider to set context without createRoot wrapper */
-export function setGlobalI18nContext(ctx: I18nContext): void {
-  globalCtx = ctx
-}
+  const tm = (key: string, loc?: string): CompiledMessage | undefined => {
+    const msgs = messages[loc ?? locale()]
+    return msgs ? msgs[key] : undefined
+  }
 
-/** @internal — reset the global singleton (for testing only) */
-export function resetGlobalI18nContext(): void {
-  globalCtx = undefined
+  return { locale, setLocale, t, loadMessages, getLocales, d, n, format, isLoading, loadedLocales, preloadLocale, te, tm }
 }

package/src/hooks/__useI18n.ts

@@ -1,5 +1,5 @@
 import { useI18n } from '../use-i18n'
-import type { I18nContext } from '../types'
+import type { FluentiContext } from '../types'
 
 /**
  * Internal hook used by the Vite plugin's compiled output.
@@ -10,6 +10,6 @@ import type { I18nContext } from '../types'
  *
  * @internal
  */
-export function __useI18n(): I18nContext {
+export function __useI18n(): FluentiContext {
   return useI18n()
 }

package/src/index.ts

@@ -1,14 +1,14 @@
-export { createI18nContext, createI18n } from './context'
-export type { I18nContext, I18nConfig } from './context'
-export { I18nProvider, I18nCtx } from './provider'
+export { createFluentiContext } from './context'
+export type { FluentiContext, FluentiConfig } from './context'
+export { I18nProvider } from './provider'
 export { useI18n } from './use-i18n'
 export { t } from './compile-time-t'
 export { Trans } from './trans'
-export type { TransProps } from './trans'
+export type { FluentiTransProps } from './trans'
 export { Plural } from './plural'
-export type { PluralProps } from './plural'
+export type { FluentiPluralProps } from './plural'
 export { SelectComp as Select } from './select'
-export type { SelectProps } from './select'
+export type { FluentiSelectProps } from './select'
 export { msg } from './msg'
 export { DateTime } from './components/DateTime'
 export { NumberFormat } from './components/NumberFormat'