@astroscope/i18n 0.2.4 → 0.3.1

package/README.md

@@ -21,11 +21,12 @@ i18n for Astro + React islands — automatic tree-shaking, parallel loading, any
 ## Features
 
 - **Per-chunk translation loading** — each island gets only its translations
-- **ICU MessageFormat** support via `@messageformat/core`
+- **Unicode MessageFormat 2** (MF2) support via `messageformat` v4
+- **Built-in formatters** — `:number`, `:integer`, `:percent`, `:currency`, `:date`, `:time`, `:datetime`, `:unit`
 - **Babel-based extraction** — robust AST parsing, source maps, production stripping
 - **Manifest fallbacks** — missing translations automatically use extracted fallbacks
 - **Full TypeScript support**
-- **Tiny client runtime** — no heavy i18n framework
+- **Tiny client runtime** — ~8KB gzipped for translations
 
 ## Installation
 
@@ -51,6 +52,20 @@ export default defineConfig({
 });
 ```
 
+#### Consistency checking
+
+The integration checks for translation key consistency — when the same key is used in multiple files with different fallbacks, variables, or descriptions.
+
+```ts
+i18n({
+  consistency: 'warn',  // 'warn' (default) | 'error' | 'off'
+})
+```
+
+- **`'warn'`** — Log a warning but continue (default)
+- **`'error'`** — Fail the build
+- **`'off'`** — Disable consistency checking
+
 ### 2. Configure i18n in your boot file
 
 **VERY IMPORTANT:** `i18n.configure` must be awaited during boot before handling any requests!
@@ -123,7 +138,7 @@ Inject translations into the page for hydrated components:
 
 ```astro
 ---
-import { I18nScript } from '@astroscope/i18n/components';
+import { I18nScript } from '@astroscope/i18n/astro';
 ---
 <html>
   <head>
@@ -140,25 +155,27 @@ import { I18nScript } from '@astroscope/i18n/components';
 ```astro
 ---
 // In .astro files
-import { t } from '@astroscope/i18n/t';
+import { t } from '@astroscope/i18n/translate';
 ---
 <h1>{t('checkout.title', 'Order Summary')}</h1>
 ```
 
 ```tsx
 // In React components
-import { t } from '@astroscope/i18n/t';
+import { t } from '@astroscope/i18n/translate';
 
 export function CheckoutSummary() {
   return (
     <div>
       <h1>{t('checkout.title', 'Order Summary')}</h1>
-      <p>{t('checkout.tax', 'Includes {tax} VAT', { tax: '19%' })}</p>
+      <p>{t('checkout.tax', 'Includes {$tax} VAT', { tax: '19%' })}</p>
     </div>
   );
 }
 ```
 
+> **Note:** Variables use `{$name}` syntax (with `$` prefix) per MessageFormat 2 specification.
+
 ### 6. Use i18n-aware client directives
 
 **The problem:** With standard `client:*` directives, the translation chunk loads *after* the component module. This delays hydration while translations are fetched sequentially.
@@ -179,28 +196,90 @@ import Cart from '../components/Cart';
 
 ### `t(key, fallback, values?)`
 
-Translate a key with optional interpolation values.
+Translate a key with optional interpolation values. The fallback is used when a translation is missing and also serves as an example for translators. Uses [MessageFormat 2](https://github.com/unicode-org/message-format-wg) syntax.
 
 ```ts
-// simple
+// simple text
 t('checkout.title', 'Order Summary')
 
-// with variables
-t('checkout.tax', 'Includes {tax} VAT', { tax: '19%' })
+// with variables (note the $ prefix)
+t('checkout.tax', 'Includes {$tax} VAT', { tax: '19%' })
+
+// with pluralization (MF2 syntax)
+t('cart.items', `.input {$count :number}
+.match $count
+one {{{$count} item}}
+* {{{$count} items}}`, { count: 5 })
+
+// with number formatting
+t('stats.value', '{$value :number minimumFractionDigits=2}', { value: 1234.5 })
+
+// with percentage
+t('stats.ratio', '{$value :percent}', { value: 0.856 })
+
+// with date/time formatting
+t('event.date', '{$date :date style=long}', { date: new Date() })
+t('event.time', '{$time :time style=short}', { time: new Date() })
 
-// with pluralization (ICU MessageFormat)
-t('cart.items', '{count, plural, one {# item} other {# items}}', { count: 5 })
+// with currency (translator controls currency)
+t('product.price', '{$price :currency currency=EUR}', { price: 99.99 })
+
+// with currency (code controls currency via wrapped value)
+t('product.price', '{$price :currency}', {
+  price: { valueOf: () => 99.99, options: { currency: 'EUR' } }
+})
+
+// with units
+t('distance', '{$value :unit unit=kilometer}', { value: 42 })
 
 // with metadata object (for extraction tooling)
 t('cart.total', {
-  fallback: 'Total: {amount}',
+  example: 'Total: {$amount}',
   description: 'Cart total price',
   variables: {
-    amount: { fallback: '$0.00', description: 'Formatted price' }
+    amount: { example: '$0.00', description: 'Formatted price' }
   }
 }, { amount: '$49.99' })
 ```
 
+### `rich(key, fallback, components, values?)`
+
+Translate with embedded components using MF2 markup syntax. Returns an array of strings and JSX elements that can be rendered directly.
+
+```tsx
+import { rich } from '@astroscope/i18n/translate';
+
+// basic link
+rich('tos', 'Read our {#link}Terms of Service{/link}', {
+  link: (children) => <a href="/tos">{children}</a>
+})
+// Returns: ['Read our ', <a href="/tos">Terms of Service</a>]
+
+// multiple tags
+rich('legal', 'Read our {#tos}Terms{/tos} and {#privacy}Privacy Policy{/privacy}', {
+  tos: (children) => <a href="/tos">{children}</a>,
+  privacy: (children) => <a href="/privacy">{children}</a>,
+})
+
+// with variables
+rich('greeting', 'Hello {$name}, check your {#inbox}messages{/inbox}', {
+  inbox: (children) => <a href="/inbox">{children}</a>,
+}, { name: 'Alice' })
+
+// nested tags
+rich('highlight', 'This is {#bold}very {#em}important{/em}{/bold}', {
+  bold: (children) => <strong>{children}</strong>,
+  em: (children) => <em>{children}</em>,
+})
+
+// standalone (self-closing) tags
+rich('install', 'Click {#icon/} to install', {
+  icon: () => <DownloadIcon />,
+})
+```
+
+The same code works in both Astro templates and React islands — `rich()` is JSX-runtime agnostic.
+
 ### `i18n` singleton
 
 ```ts
@@ -256,11 +335,74 @@ export function App() {
 3. **SSR** — Middleware provides translations to `t()`, merging manifest fallbacks for missing keys
 4. **Client** — Custom directives load only the translations needed by each chunk
 
-The same `import { t } from '@astroscope/i18n/t'` works everywhere — bundler picks the correct implementation via conditional exports (`browser` vs `default`).
+The same `import { t } from '@astroscope/i18n/translate'` works everywhere — bundler picks the correct implementation via conditional exports (`browser` vs `default`).
 
 ### Client bundle
 
-Translation chunks are served as raw ICU MessageFormat strings and compiled on the browser on first use. This keeps chunk sizes minimal but includes `@messageformat/core` (~15KB gzipped) in your client bundle. Compiled messages are cached for subsequent renders.
+Translation chunks are served as raw MessageFormat 2 strings and compiled on the browser on first use. This keeps chunk sizes minimal — the `messageformat` runtime is ~8KB gzipped. Compiled messages are cached for subsequent renders.
+
+> **Future:** Once browsers ship native `Intl.MessageFormat`, this 8KB runtime will be replaced by the built-in API with zero bundle cost.
+
+## MessageFormat 2 Syntax
+
+This library uses [Unicode MessageFormat 2](https://github.com/unicode-org/message-format-wg) (MF2), the modern standard for internationalization.
+
+### Basic syntax
+
+```
+Simple text
+Hello {$name}
+```
+
+### Pluralization
+
+```
+.input {$count :number}
+.match $count
+one {{{$count} item}}
+* {{{$count} items}}
+```
+
+### Selection (gender, etc.)
+
+```
+.input {$gender :string}
+.match $gender
+male {{He liked it}}
+female {{She liked it}}
+* {{They liked it}}
+```
+
+### Built-in formatters
+
+| Formatter | Description | Example |
+|-----------|-------------|---------|
+| `:number` | Locale-aware number | `{$n :number}` → "1,234.56" |
+| `:integer` | Integer (no decimals) | `{$n :integer}` → "1,235" |
+| `:percent` | Percentage | `{$n :percent}` → "85.6%" |
+| `:currency` | Currency | `{$n :currency currency=EUR}` → "€99.99" |
+| `:date` | Date | `{$d :date style=long}` → "January 26, 2026" |
+| `:time` | Time | `{$d :time style=short}` → "3:45 PM" |
+| `:datetime` | Date + time | `{$d :datetime dateStyle=medium timeStyle=short}` |
+| `:unit` | Units | `{$n :unit unit=kilometer}` → "42 km" |
+
+### Currency and unit options
+
+For `:currency` and `:unit`, the required option (`currency` or `unit`) can be:
+
+1. **Hardcoded in translation** (translator controls):
+   ```
+   {$price :currency currency=EUR}
+   ```
+   Code passes plain number: `{ price: 99.99 }`
+
+2. **Provided by code** (for dynamic currency/unit):
+   ```
+   {$price :currency}
+   ```
+   Code passes wrapped value: `{ price: { valueOf: () => 99.99, options: { currency: 'EUR' } } }`
+
+> **Note:** If both translation and code specify the option, **translation wins**.
 
 ## Configuration
 

package/dist/chunk-33JVAFGQ.js

@@ -0,0 +1,44 @@
+// src/shared/compiler.ts
+import { MessageFormat } from "messageformat";
+import { DraftFunctions } from "messageformat/functions";
+var mfOptions = { functions: DraftFunctions };
+var cache = /* @__PURE__ */ new Map();
+function getOrCreateMessageFormat(locale, message) {
+  const cacheKey = `${locale}:${message}`;
+  const cached = cache.get(cacheKey);
+  if (cached) {
+    return cached;
+  }
+  const mf = new MessageFormat(locale, message, mfOptions);
+  cache.set(cacheKey, mf);
+  return mf;
+}
+function compileMessage(locale, message) {
+  try {
+    const mf = getOrCreateMessageFormat(locale, message);
+    return (values) => mf.format(values);
+  } catch {
+    return () => message;
+  }
+}
+function formatMessageToParts(locale, message, values) {
+  try {
+    const mf = getOrCreateMessageFormat(locale, message);
+    return mf.formatToParts(values);
+  } catch {
+    return [{ type: "literal", value: message }];
+  }
+}
+function compileTranslations(locale, raw) {
+  const compiled = {};
+  for (const [key, message] of Object.entries(raw)) {
+    compiled[key] = compileMessage(locale, message);
+  }
+  return compiled;
+}
+
+export {
+  compileMessage,
+  formatMessageToParts,
+  compileTranslations
+};

package/dist/{chunk-ZKXMIGSF.js → chunk-MSJHXRJB.js}

@@ -1,6 +1,6 @@
 import {
   compileTranslations
-} from "./chunk-KNDYKTHE.js";
+} from "./chunk-33JVAFGQ.js";
 
 // src/extraction/hash.ts
 import { createHash } from "crypto";

package/dist/chunk-VGPVG5JP.js

@@ -0,0 +1,73 @@
+// src/shared/meta.ts
+function normalizeMeta(meta) {
+  return typeof meta === "string" ? { fallback: meta } : meta;
+}
+
+// src/shared/rich.ts
+var REACT_ELEMENT_TYPE = /* @__PURE__ */ Symbol.for("react.element");
+var REACT_TRANSITIONAL_ELEMENT_TYPE = /* @__PURE__ */ Symbol.for("react.transitional.element");
+function isReactElement(value) {
+  if (typeof value !== "object" || value === null || !("$$typeof" in value)) {
+    return false;
+  }
+  const type = value.$$typeof;
+  return type === REACT_ELEMENT_TYPE || type === REACT_TRANSITIONAL_ELEMENT_TYPE;
+}
+function addKeyIfNeeded(element, key) {
+  if (isReactElement(element) && element.key === null) {
+    return { ...element, key };
+  }
+  return element;
+}
+function isMarkupPart(part) {
+  return part.type === "markup";
+}
+function partsToNodes(parts, components) {
+  const result = [];
+  const stack = [];
+  let keyIndex = 0;
+  for (const part of parts) {
+    const target = stack.length > 0 ? stack[stack.length - 1].children : result;
+    if (isMarkupPart(part)) {
+      if (part.kind === "open") {
+        stack.push({ name: part.name, children: [] });
+      } else if (part.kind === "close") {
+        const frame = stack.pop();
+        if (!frame) {
+          continue;
+        }
+        const component = components[frame.name];
+        const parent = stack.length > 0 ? stack[stack.length - 1].children : result;
+        if (component) {
+          parent.push(addKeyIfNeeded(component(frame.children), `rich-${keyIndex++}`));
+        } else {
+          parent.push(...frame.children);
+        }
+      } else if (part.kind === "standalone") {
+        const component = components[part.name];
+        if (component) {
+          target.push(addKeyIfNeeded(component([]), `rich-${keyIndex++}`));
+        }
+      }
+    } else if (part.type === "text") {
+      target.push(part.value);
+    } else if (part.type === "bidiIsolation") {
+    } else {
+      if ("value" in part && part.value !== void 0 && part.value !== null) {
+        const stringValue = String(part.value);
+        target.push(stringValue);
+      }
+    }
+  }
+  while (stack.length > 0) {
+    const frame = stack.pop();
+    const parent = stack.length > 0 ? stack[stack.length - 1].children : result;
+    parent.push(...frame.children);
+  }
+  return result;
+}
+
+export {
+  normalizeMeta,
+  partsToNodes
+};

package/dist/{chunk-3VF2YMJG.js → chunk-Z3LDPCYD.js}

@@ -85,11 +85,16 @@ async function extractKeysFromFile(options) {
 
 // src/extraction/key-store.ts
 var KeyStore = class {
-  constructor(logger) {
+  constructor(logger, consistency = "warn") {
     this.logger = logger;
+    this.consistency = consistency;
   }
   /** All key occurrences (may have duplicates) */
   occurrences = [];
+  /** Tracks reported inconsistencies to avoid duplicate warnings */
+  reportedInconsistencies = /* @__PURE__ */ new Set();
+  /** Whether an error-level inconsistency was found (for build failure) */
+  hasInconsistencyError = false;
   fileToKeys = /* @__PURE__ */ new Map();
   filesWithI18n = /* @__PURE__ */ new Set();
   /**
@@ -119,11 +124,103 @@ var KeyStore = class {
       }
     }
     this.filesWithI18n.add(filename);
+    if (this.consistency !== "off") {
+      this.checkConsistency(keys);
+    }
     if (keys.length > 0) {
       this.occurrences.push(...keys);
     }
     this.fileToKeys.set(filename, newKeyStrings);
   }
+  /**
+   * Check new keys for inconsistencies with existing occurrences.
+   */
+  checkConsistency(newKeys) {
+    const existingByKey = /* @__PURE__ */ new Map();
+    for (const occ of this.occurrences) {
+      if (!existingByKey.has(occ.key)) {
+        existingByKey.set(occ.key, occ);
+      }
+    }
+    for (const newKey of newKeys) {
+      const existing = existingByKey.get(newKey.key);
+      if (!existing) continue;
+      const inconsistencies = this.findInconsistencies(newKey, existing);
+      for (const inc of inconsistencies) {
+        this.reportInconsistency(inc);
+      }
+    }
+  }
+  /**
+   * Compare two occurrences and find any metadata inconsistencies.
+   */
+  findInconsistencies(a, b) {
+    const result = [];
+    const locA = `${a.file}:${a.line}`;
+    const locB = `${b.file}:${b.line}`;
+    if (a.meta.fallback !== b.meta.fallback) {
+      result.push({
+        key: a.key,
+        field: "fallback",
+        locations: [locA, locB],
+        values: [a.meta.fallback, b.meta.fallback]
+      });
+    }
+    if (a.meta.description !== b.meta.description) {
+      result.push({
+        key: a.key,
+        field: "description",
+        locations: [locA, locB],
+        values: [a.meta.description ?? "(none)", b.meta.description ?? "(none)"]
+      });
+    }
+    const varsA = this.serializeVariables(a.meta);
+    const varsB = this.serializeVariables(b.meta);
+    if (varsA !== varsB) {
+      result.push({
+        key: a.key,
+        field: "variables",
+        locations: [locA, locB],
+        values: [varsA || "(none)", varsB || "(none)"]
+      });
+    }
+    return result;
+  }
+  /**
+   * Serialize variables for comparison.
+   */
+  serializeVariables(meta) {
+    if (!meta.variables) return "";
+    const sorted = {};
+    for (const key of Object.keys(meta.variables).sort()) {
+      sorted[key] = meta.variables[key];
+    }
+    return JSON.stringify(sorted);
+  }
+  /**
+   * Report an inconsistency via logger.
+   */
+  reportInconsistency(inc) {
+    const incKey = `${inc.key}:${inc.field}`;
+    if (this.reportedInconsistencies.has(incKey)) return;
+    this.reportedInconsistencies.add(incKey);
+    const message = `inconsistent ${inc.field} for key "${inc.key}"
+  ${inc.locations[0]}: ${JSON.stringify(inc.values[0])}
+  ${inc.locations[1]}: ${JSON.stringify(inc.values[1])}`;
+    if (this.consistency === "error") {
+      this.logger.error(message);
+      this.hasInconsistencyError = true;
+    } else {
+      this.logger.warn(message);
+    }
+  }
+  /**
+   * Check if any error-level inconsistencies were found.
+   * Call this at the end of build to determine if it should fail.
+   */
+  get hasErrors() {
+    return this.hasInconsistencyError;
+  }
   /**
    * Get deduplicated keys with all file locations merged.
    * Last occurrence's meta wins for each key.
@@ -164,6 +261,9 @@ var KeyStore = class {
     for (const file of other.filesWithI18n) {
       this.filesWithI18n.add(file);
     }
+    if (this.consistency !== "off") {
+      this.checkConsistency(other.occurrences);
+    }
     this.occurrences.push(...other.occurrences);
   }
   /**
@@ -187,8 +287,9 @@ async function compileAstro(code, filename) {
     return null;
   }
 }
-async function scan(projectRoot, logger) {
-  const store = new KeyStore(logger);
+async function scan(options) {
+  const { projectRoot, logger, consistency } = options;
+  const store = new KeyStore(logger, consistency);
   const files = await glob(GLOB_PATTERN, {
     cwd: projectRoot,
     absolute: true,
@@ -197,7 +298,7 @@ async function scan(projectRoot, logger) {
   const results = await Promise.all(
     files.map(async (file) => {
       let code = await fs.promises.readFile(file, "utf-8");
-      if (!code.includes("@astroscope/i18n/t")) {
+      if (!code.includes("@astroscope/i18n/translate")) {
         return { file, keys: null };
       }
       if (file.endsWith(".astro")) {
@@ -231,8 +332,8 @@ var RESOLVED_VIRTUAL_MODULE_ID = `\0${VIRTUAL_MODULE_ID}`;
 var isResolvedVirtualModuleId = (id) => id === RESOLVED_VIRTUAL_MODULE_ID || id.startsWith(`\0${VIRTUAL_MODULE_ID}?`);
 var MANIFEST_FILE_NAME = "i18n-manifest.json";
 function i18nVitePlugin(options) {
-  const { logger } = options;
-  const store = new KeyStore(logger);
+  const { logger, consistency } = options;
+  const store = new KeyStore(logger, consistency);
   const syncGlobalState = () => {
     const state = getGlobalState();
     state.extractedKeys = store.extractedKeys;
@@ -254,7 +355,7 @@ function i18nVitePlugin(options) {
       if (server.config.isProduction || isBuild) {
         return;
       }
-      const result = await scan(projectRoot, logger);
+      const result = await scan({ projectRoot, logger, consistency });
       store.merge(result);
       syncGlobalState();
       logger.info(`dev mode: scanned ${result.fileToKeys.size} files, found ${result.uniqueKeyCount} keys`);
@@ -293,7 +394,7 @@ export function getManifest() { return _getManifest(); }
       if (filename.includes("node_modules")) {
         return null;
       }
-      if (!code.includes("@astroscope/i18n/t")) {
+      if (!code.includes("@astroscope/i18n/translate")) {
         return null;
       }
       const result = await extractKeysFromFile({
@@ -379,6 +480,9 @@ export function getManifest() { return _getManifest(); }
         }
       }
       logger.info(`manifest: ${Object.keys(state.chunkManifest).length} chunks, ${store.uniqueKeyCount} keys`);
+      if (consistency === "error" && store.hasErrors) {
+        throw new Error("i18n: build failed due to translation key inconsistencies");
+      }
     },
     writeBundle(outputOptions) {
       if (!isSSR && outputOptions.dir) {

package/dist/client/translate.d.ts

@@ -0,0 +1,41 @@
+import { R as RichComponents } from '../rich-CQUhdwBc.js';
+import { a as TranslateFunction, T as TranslationMeta } from '../types-DNRFj1XA.js';
+import '../types-BeDFfFIL.js';
+
+declare function getLocale(): string;
+/**
+ * Client-side translate function
+ *
+ * Reads from window.__i18n__.translations (injected per-chunk).
+ * In production, translations are always loaded before component code runs
+ * via the chunk loader injected by the Vite plugin.
+ *
+ * Call patterns:
+ * - Development: t('key', 'fallback') or t('key', 'fallback', values)
+ * - Production: t('key') or t('key', undefined, values)
+ *
+ * Falls back to meta.fallback (dev) or key (prod) when translation is missing.
+ */
+declare const t: TranslateFunction;
+/**
+ * Client-side rich text translation function
+ *
+ * Parses MF2 markup syntax and applies component callbacks to wrap content.
+ * Works with any JSX runtime (React, Preact, etc.).
+ *
+ * @param key - Translation key
+ * @param meta - Fallback string or meta object with fallback (used as message template)
+ * @param components - Map of tag names to component callbacks
+ * @param values - Runtime interpolation values (ICU MessageFormat)
+ *
+ * @example
+ * ```tsx
+ * rich('tos', 'Read our {#link}Terms{/link}', {
+ *   link: (children) => <a href="/tos">{children}</a>
+ * })
+ * // Returns: ['Read our ', <a href="/tos">Terms</a>]
+ * ```
+ */
+declare function rich<T = unknown>(key: string, meta?: TranslationMeta | string | undefined, components?: RichComponents<T> | undefined, values?: Record<string, unknown> | undefined): (string | T)[];
+
+export { getLocale, rich, t };

package/dist/client/{t.js → translate.js}

@@ -1,11 +1,13 @@
 import {
-  normalizeMeta
-} from "../chunk-EMM6LRO2.js";
+  normalizeMeta,
+  partsToNodes
+} from "../chunk-VGPVG5JP.js";
 import {
-  compileMessage
-} from "../chunk-KNDYKTHE.js";
+  compileMessage,
+  formatMessageToParts
+} from "../chunk-33JVAFGQ.js";
 
-// src/client/t.ts
+// src/client/translate.ts
 var cache = /* @__PURE__ */ new Map();
 function getLocale() {
   return window.__i18n__.locale;
@@ -31,7 +33,14 @@ var t = ((key, meta, values) => {
   }
   return compiled(values);
 });
+function rich(key, meta, components, values) {
+  const normalizedMeta = meta ? normalizeMeta(meta) : { fallback: "" };
+  const raw = window.__i18n__.translations[key] ?? normalizedMeta.fallback ?? key;
+  const parts = formatMessageToParts(window.__i18n__.locale, raw, values);
+  return partsToNodes(parts, components ?? {});
+}
 export {
   getLocale,
+  rich,
   t
 };

package/dist/extraction/index.d.ts

@@ -2,6 +2,7 @@ import { a as ExtractionManifest } from '../types-moTgocy7.js';
 export { C as ChunkManifest, E as ExtractedKey } from '../types-moTgocy7.js';
 import { AstroIntegrationLogger } from 'astro';
 import { Plugin } from 'vite';
+import { C as ConsistencyCheckLevel } from '../types-B_8vAmvv.js';
 import '../types-DNRFj1XA.js';
 
 /**
@@ -18,6 +19,7 @@ declare function getManifest(): ExtractionManifest;
 
 type I18nVitePluginOptions = {
     logger: AstroIntegrationLogger;
+    consistency: ConsistencyCheckLevel;
 };
 /**
  * Vite plugin for i18n extraction, chunk mapping, and loader injection

package/dist/extraction/index.js

@@ -1,7 +1,7 @@
 import {
   getManifest,
   i18nVitePlugin
-} from "../chunk-3VF2YMJG.js";
+} from "../chunk-Z3LDPCYD.js";
 import "../chunk-4A5BKHFN.js";
 export {
   getManifest,

package/dist/{i18n-CbSjmzlu.d.ts → i18n-DaLnNvss.d.ts}

@@ -11,6 +11,7 @@ type FallbackBehavior = 'key' | 'fallback' | 'throw' | ((key: string, meta?: Tra
 type I18nContext = {
     locale: string;
     translations: CompiledTranslations;
+    rawTranslations: RawTranslations;
     fallback: FallbackBehavior;
 };
 

package/dist/index.d.ts

@@ -1,12 +1,10 @@
 import { AstroIntegration, MiddlewareHandler, APIContext } from 'astro';
-export { F as FallbackBehavior, I as I18nConfig, i as i18n } from './i18n-CbSjmzlu.js';
+import { I as I18nOptions } from './types-B_8vAmvv.js';
+export { F as FallbackBehavior, I as I18nConfig, i as i18n } from './i18n-DaLnNvss.js';
 import { ExcludePattern } from '@astroscope/excludes';
 export { R as RawTranslations, T as TranslationMeta } from './types-DNRFj1XA.js';
 export { E as ExtractedKey, a as ExtractionManifest } from './types-moTgocy7.js';
 
-interface I18nOptions {
-}
-
 /**
  * Astro integration for i18n with automatic per-chunk translation loading.
  *
@@ -14,7 +12,7 @@ interface I18nOptions {
  * - Client directives (`client:load-x`, `client:idle-x`, `client:visible-x`, `client:media-x`, `client:only-x`)
  * - Vite plugin for translation key extraction
  */
-declare function i18nIntegration(_options?: I18nOptions): AstroIntegration;
+declare function i18nIntegration(options?: I18nOptions): AstroIntegration;
 
 type I18nMiddlewareOptions = {
     locale: (ctx: APIContext) => string;

package/dist/index.js

@@ -1,16 +1,17 @@
 import {
   i18nVitePlugin
-} from "./chunk-3VF2YMJG.js";
+} from "./chunk-Z3LDPCYD.js";
 import {
   i18n,
   runWithContext
-} from "./chunk-ZKXMIGSF.js";
-import "./chunk-KNDYKTHE.js";
+} from "./chunk-MSJHXRJB.js";
+import "./chunk-33JVAFGQ.js";
 import "./chunk-4A5BKHFN.js";
 
 // src/integration/integration.ts
 var CLIENT_DIRECTIVES = ["load-x", "idle-x", "visible-x", "media-x", "only-x"];
-function i18nIntegration(_options = {}) {
+function i18nIntegration(options = {}) {
+  const { consistency = "warn" } = options;
   return {
     name: "@astroscope/i18n",
     hooks: {
@@ -24,7 +25,7 @@ function i18nIntegration(_options = {}) {
         }
         updateConfig({
           vite: {
-            plugins: [i18nVitePlugin({ logger })]
+            plugins: [i18nVitePlugin({ logger, consistency })]
           }
         });
       },
@@ -112,6 +113,7 @@ function createI18nMiddleware(options) {
     const context = {
       locale,
       translations: i18n.getCompiledTranslations(locale),
+      rawTranslations: i18n.getTranslations(locale),
       fallback: i18n.getConfig().fallback
     };
     return runWithContext(context, () => next());

package/dist/internal.d.ts

@@ -1,5 +1,5 @@
-import { a as I18nContext } from './i18n-CbSjmzlu.js';
-export { i as i18n } from './i18n-CbSjmzlu.js';
+import { a as I18nContext } from './i18n-DaLnNvss.js';
+export { i as i18n } from './i18n-DaLnNvss.js';
 export { I as I18nClientState } from './types-DNRFj1XA.js';
 import './types-moTgocy7.js';
 

package/dist/internal.js

@@ -1,8 +1,8 @@
 import {
   getContext,
   i18n
-} from "./chunk-ZKXMIGSF.js";
-import "./chunk-KNDYKTHE.js";
+} from "./chunk-MSJHXRJB.js";
+import "./chunk-33JVAFGQ.js";
 export {
   getContext,
   i18n

package/dist/rich-CQUhdwBc.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Component callbacks for rich text rendering.
+ * Each key maps to a function that wraps children in a component.
+ *
+ * @example
+ * ```tsx
+ * const components: RichComponents = {
+ *   link: (children) => <a href="/tos">{children}</a>,
+ *   bold: (children) => <strong>{children}</strong>,
+ * };
+ * ```
+ */
+type RichComponents<T = unknown> = Record<string, (children: (string | T)[]) => T>;
+
+export type { RichComponents as R };

package/dist/server/translate.d.ts

@@ -0,0 +1,38 @@
+import { R as RichComponents } from '../rich-CQUhdwBc.js';
+import { a as TranslateFunction, T as TranslationMeta } from '../types-DNRFj1XA.js';
+
+/**
+ * Get the current locale from request context.
+ * Returns defaultLocale if called outside a request (e.g. during build).
+ */
+declare function getLocale(): string;
+/**
+ * Server-side translate function
+ *
+ * Call patterns:
+ * - Development: t('key', 'fallback') or t('key', 'fallback', values)
+ * - Production: t('key') or t('key', undefined, values)
+ */
+declare const t: TranslateFunction;
+/**
+ * Server-side rich text translation function
+ *
+ * Parses MF2 markup syntax and applies component callbacks to wrap content.
+ * Works with any JSX runtime (Astro, React during SSR, etc.).
+ *
+ * @param key - Translation key
+ * @param meta - Fallback string or meta object with fallback (used as message template)
+ * @param components - Map of tag names to component callbacks
+ * @param values - Runtime interpolation values (ICU MessageFormat)
+ *
+ * @example
+ * ```tsx
+ * rich('tos', 'Read our {#link}Terms{/link}', {
+ *   link: (children) => <a href="/tos">{children}</a>
+ * })
+ * // Returns: ['Read our ', <a href="/tos">Terms</a>]
+ * ```
+ */
+declare function rich<T = unknown>(key: string, meta?: TranslationMeta | string | undefined, components?: RichComponents<T> | undefined, values?: Record<string, unknown> | undefined): (string | T)[];
+
+export { getLocale, rich, t };

package/dist/server/{t.js → translate.js}

@@ -1,15 +1,17 @@
 import {
   getContext,
   i18n
-} from "../chunk-ZKXMIGSF.js";
+} from "../chunk-MSJHXRJB.js";
 import {
-  normalizeMeta
-} from "../chunk-EMM6LRO2.js";
+  normalizeMeta,
+  partsToNodes
+} from "../chunk-VGPVG5JP.js";
 import {
-  compileMessage
-} from "../chunk-KNDYKTHE.js";
+  compileMessage,
+  formatMessageToParts
+} from "../chunk-33JVAFGQ.js";
 
-// src/server/t.ts
+// src/server/translate.ts
 var fallbackCache = /* @__PURE__ */ new Map();
 function applyFallback(key, meta, fallback) {
   if (typeof fallback === "function") {
@@ -53,7 +55,16 @@ var t = ((key, meta, values) => {
   }
   return compiled(values);
 });
+function rich(key, meta, components, values) {
+  const normalizedMeta = meta ? normalizeMeta(meta) : { fallback: "" };
+  const ctx = getContext();
+  const locale = ctx?.locale ?? i18n.getConfig().defaultLocale;
+  const raw = ctx?.rawTranslations[key] ?? normalizedMeta.fallback ?? key;
+  const parts = formatMessageToParts(locale, raw, values);
+  return partsToNodes(parts, components ?? {});
+}
 export {
   getLocale,
+  rich,
   t
 };

package/dist/types-B_8vAmvv.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Consistency check level for translation keys.
+ * Controls behavior when the same key has different fallbacks/variables across files.
+ *
+ * - 'warn' (default): Log a warning but continue
+ * - 'error': Fail the build
+ * - 'off': Disable consistency checking
+ */
+type ConsistencyCheckLevel = 'off' | 'warn' | 'error';
+interface I18nOptions {
+    /**
+     * How to handle inconsistent translation keys (same key with different fallbacks/variables).
+     * @default 'warn'
+     */
+    consistency?: ConsistencyCheckLevel | undefined;
+}
+
+export type { ConsistencyCheckLevel as C, I18nOptions as I };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@astroscope/i18n",
-  "version": "0.2.4",
-  "description": "i18n for Astro + React islands — automatic tree-shaking, parallel loading, any translation source",
+  "version": "0.3.1",
+  "description": "i18n for Astro + React islands — MessageFormat 2, automatic tree-shaking, parallel loading, any translation source",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -10,10 +10,10 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
-    "./t": {
-      "types": "./dist/client/t.d.ts",
-      "browser": "./dist/client/t.js",
-      "default": "./dist/server/t.js"
+    "./translate": {
+      "types": "./dist/client/translate.d.ts",
+      "browser": "./dist/client/translate.js",
+      "default": "./dist/server/translate.js"
     },
     "./client-directives/load.js": {
       "types": "./dist/client/directives/load.d.ts",
@@ -35,8 +35,8 @@
       "types": "./dist/client/directives/only.d.ts",
       "import": "./dist/client/directives/only.js"
     },
-    "./components": {
-      "import": "./src/components/index.ts"
+    "./astro": {
+      "import": "./src/astro/index.ts"
     },
     "./internal": {
       "types": "./dist/internal.d.ts",
@@ -49,7 +49,7 @@
   },
   "files": [
     "dist",
-    "src/components"
+    "src/astro"
   ],
   "sideEffects": [
     "./dist/client/directives/*.js",
@@ -69,6 +69,8 @@
     "i18n",
     "internationalization",
     "translations",
+    "messageformat",
+    "mf2",
     "react",
     "islands",
     "ssr"
@@ -80,7 +82,7 @@
   },
   "homepage": "https://github.com/smnbbrv/astroscope/tree/main/packages/i18n#readme",
   "scripts": {
-    "build": "tsup src/index.ts src/internal.ts src/extraction/index.ts src/server/t.ts src/client/t.ts src/client/directives/load.ts src/client/directives/idle.ts src/client/directives/visible.ts src/client/directives/media.ts src/client/directives/only.ts src/client/directives/utils.ts --format esm --dts --external astro --external astro/client/load.js --external astro/client/idle.js --external astro/client/visible.js --external astro/client/media.js --external astro/client/only.js --external virtual:@astroscope/i18n/manifest --external @babel/core",
+    "build": "tsup src/index.ts src/internal.ts src/extraction/index.ts src/server/translate.ts src/client/translate.ts src/client/directives/load.ts src/client/directives/idle.ts src/client/directives/visible.ts src/client/directives/media.ts src/client/directives/only.ts src/client/directives/utils.ts --format esm --dts --external astro --external astro/client/load.js --external astro/client/idle.js --external astro/client/visible.js --external astro/client/media.js --external astro/client/only.js --external virtual:@astroscope/i18n/manifest --external @babel/core",
     "typecheck": "tsc --noEmit",
     "lint": "eslint 'src/**/*.ts'",
     "lint:fix": "eslint 'src/**/*.ts' --fix"
@@ -89,7 +91,7 @@
     "@astrojs/compiler": "^2.12.2",
     "@babel/core": "^7.28.6",
     "@babel/preset-typescript": "^7.28.5",
-    "@messageformat/core": "^3.4.0",
+    "messageformat": "^4.0.0",
     "glob": "^11.0.0",
     "magic-string": "^0.30.21"
   },

package/dist/chunk-EMM6LRO2.js

@@ -1,8 +0,0 @@
-// src/shared/meta.ts
-function normalizeMeta(meta) {
-  return typeof meta === "string" ? { fallback: meta } : meta;
-}
-
-export {
-  normalizeMeta
-};

package/dist/chunk-KNDYKTHE.js

@@ -1,31 +0,0 @@
-// src/shared/compiler.ts
-import MessageFormat from "@messageformat/core";
-var cache = /* @__PURE__ */ new Map();
-function getMessageFormat(locale) {
-  let mf = cache.get(locale);
-  if (!mf) {
-    mf = new MessageFormat(locale);
-    cache.set(locale, mf);
-  }
-  return mf;
-}
-function compileMessage(locale, message) {
-  const mf = getMessageFormat(locale);
-  try {
-    return mf.compile(message);
-  } catch {
-    return () => message;
-  }
-}
-function compileTranslations(locale, raw) {
-  const compiled = {};
-  for (const [key, message] of Object.entries(raw)) {
-    compiled[key] = compileMessage(locale, message);
-  }
-  return compiled;
-}
-
-export {
-  compileMessage,
-  compileTranslations
-};

package/dist/client/t.d.ts

@@ -1,20 +0,0 @@
-import { a as TranslateFunction } from '../types-DNRFj1XA.js';
-import '../types-BeDFfFIL.js';
-
-declare function getLocale(): string;
-/**
- * Client-side translate function
- *
- * Reads from window.__i18n__.translations (injected per-chunk).
- * In production, translations are always loaded before component code runs
- * via the chunk loader injected by the Vite plugin.
- *
- * Call patterns:
- * - Development: t('key', 'fallback') or t('key', 'fallback', values)
- * - Production: t('key') or t('key', undefined, values)
- *
- * Falls back to meta.fallback (dev) or key (prod) when translation is missing.
- */
-declare const t: TranslateFunction;
-
-export { getLocale, t };

package/dist/server/t.d.ts

@@ -1,17 +0,0 @@
-import { a as TranslateFunction } from '../types-DNRFj1XA.js';
-
-/**
- * Get the current locale from request context.
- * Returns defaultLocale if called outside a request (e.g. during build).
- */
-declare function getLocale(): string;
-/**
- * Server-side translate function
- *
- * Call patterns:
- * - Development: t('key', 'fallback') or t('key', 'fallback', values)
- * - Production: t('key') or t('key', undefined, values)
- */
-declare const t: TranslateFunction;
-
-export { getLocale, t };