@astroscope/i18n 0.1.0

package/README.md

@@ -0,0 +1,262 @@
+# @astroscope/i18n
+
+i18n for Astro + React islands — automatic tree-shaking, parallel loading, any translation source.
+
+## Why this library?
+
+**SSR-first** — The only i18n solution built specifically for SSR + islands architecture. Works seamlessly with Astro's partial hydration model where most i18n libraries fail.
+
+**Automatic tree-shaking** — Only translations actually used by each component are delivered to the browser. No manual chunk splitting, no configuration. It just works.
+
+**Parallel loading** — Translations load alongside component hydration via custom `client:*-x` directives. No waiting for translations before rendering.
+
+**Unified API** — Same `t()` function works identically in Astro templates and React islands.
+
+**Any translation source** — Fetch translations from any provider: JSON files, database, headless CMS, TMS, or custom API. All of them will be optimized and chunked automatically.
+
+**Production optimized** — Fallback strings are stripped from production bundles via Babel, reducing bundle size while keeping fallbacks available via the manifest.
+
+## Features
+
+- **Per-chunk translation loading** — each island gets only its translations
+- **ICU MessageFormat** support via `@messageformat/core`
+- **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
+
+## Installation
+
+```bash
+npm install @astroscope/i18n @astroscope/boot
+```
+
+## Usage
+
+### 1. Add the integration
+
+```ts
+// astro.config.ts
+import { defineConfig } from 'astro/config';
+import boot from '@astroscope/boot';
+import i18n from '@astroscope/i18n';
+
+export default defineConfig({
+  integrations: [
+    boot(),
+    i18n(),
+  ],
+});
+```
+
+### 2. Configure i18n in your boot file
+
+```ts
+// src/boot.ts
+import { i18n, type RawTranslations } from '@astroscope/i18n';
+
+async function fetchTranslations(locale: string): Promise<RawTranslations> {
+  // fetch from your CMS, API, or local files
+  const response = await fetch(`https://api.example.com/translations/${locale}`);
+  return response.json();
+}
+
+export async function onStartup() {
+  await i18n.configure({
+    locales: ['en', 'de'],
+    defaultLocale: 'en',  // optional, defaults to first locale
+  });
+
+  // load translations for all locales
+  const [en, de] = await Promise.all([
+    fetchTranslations('en'),
+    fetchTranslations('de'),
+  ]);
+
+  i18n.setTranslations('en', en);
+  i18n.setTranslations('de', de);
+}
+```
+
+### 3. Add the middleware
+
+```ts
+// src/middleware.ts
+import { sequence } from 'astro:middleware';
+import { createI18nChunkMiddleware, createI18nMiddleware, i18n } from '@astroscope/i18n';
+
+export const onRequest = sequence(
+  createI18nChunkMiddleware(),  // serves /_i18n/ translation chunks
+  createI18nMiddleware({
+    locale: (ctx) =>
+      ctx.cookies.get('locale')?.value ??
+      i18n.getConfig().defaultLocale,
+  }),
+);
+```
+
+### 4. Add `<I18nScript />` to your layout
+
+Inject translations into the page for hydrated components:
+
+```astro
+---
+import { I18nScript } from '@astroscope/i18n/components';
+---
+<html>
+  <head>
+    <I18nScript />
+  </head>
+  <body>
+    <slot />
+  </body>
+</html>
+```
+
+### 5. Use `t()` in your components
+
+```astro
+---
+// In .astro files
+import { t } from '@astroscope/i18n/t';
+---
+<h1>{t('checkout.title', 'Order Summary')}</h1>
+```
+
+```tsx
+// In React components
+import { t } from '@astroscope/i18n/t';
+
+export function CheckoutSummary() {
+  return (
+    <div>
+      <h1>{t('checkout.title', 'Order Summary')}</h1>
+      <p>{t('checkout.tax', 'Includes {tax} VAT', { tax: '19%' })}</p>
+    </div>
+  );
+}
+```
+
+### 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.
+
+**The solution:** Use `client:*-x` directives to load translations in parallel with the component code:
+
+```astro
+---
+import Cart from '../components/Cart';
+---
+<!-- translations load alongside component code -->
+<Cart client:load-x />
+<Cart client:visible-x />
+<Cart client:idle-x />
+```
+
+## API
+
+### `t(key, fallback, values?)`
+
+Translate a key with optional interpolation values.
+
+```ts
+// simple
+t('checkout.title', 'Order Summary')
+
+// with variables
+t('checkout.tax', 'Includes {tax} VAT', { tax: '19%' })
+
+// with pluralization (ICU MessageFormat)
+t('cart.items', '{count, plural, one {# item} other {# items}}', { count: 5 })
+
+// with metadata object (for extraction tooling)
+t('cart.total', {
+  fallback: 'Total: {amount}',
+  description: 'Cart total price',
+  variables: {
+    amount: { fallback: '$0.00', description: 'Formatted price' }
+  }
+}, { amount: '$49.99' })
+```
+
+### `i18n` singleton
+
+```ts
+import { i18n } from '@astroscope/i18n';
+
+// configure (call once at startup)
+await i18n.configure({
+  locales: ['en', 'de'],
+  defaultLocale: 'en',
+});
+
+// set translations for a locale
+i18n.setTranslations('en', { 'key': 'value' });
+
+// get raw translations (includes manifest fallbacks)
+i18n.getTranslations('en');
+
+// get compiled translations (ICU MessageFormat functions)
+i18n.getCompiledTranslations('en');
+
+// get extraction manifest
+// has all extracted keys with their metadata
+// you can use this to generate translation files or upload to a TMS / CMS
+i18n.getManifest();
+
+// clear cached translations
+i18n.clear();        // all locales
+i18n.clear('en');    // specific locale
+```
+
+### Lazy loading with React.lazy()
+
+Translations load automatically for lazy-loaded components.
+
+```tsx
+import { Suspense, lazy } from 'react';
+
+const StatsModal = lazy(() => import('./StatsModal'));
+
+export function App() {
+  return (
+    <Suspense fallback={<div>Loading...</div>}>
+      <StatsModal />
+    </Suspense>
+  );
+}
+```
+
+## How it works
+
+1. **Build time** — Babel plugin extracts all `t()` calls, maps them to chunks, strips fallbacks from production bundles
+2. **Manifest** — Extracted keys with fallbacks are written to `i18n-manifest.json`
+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`).
+
+### 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.
+
+## Configuration
+
+### i18n.configure()
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `locales` | `string[]` | required | Supported locales |
+| `defaultLocale` | `string` | first locale | Default/fallback locale |
+| `fallback` | `FallbackBehavior` | `'fallback'` | Behavior when translation missing |
+
+### FallbackBehavior
+
+- `'fallback'` — Use the fallback string from manifest (default)
+- `'key'` — Return the translation key
+- `'throw'` — Throw an error
+- `(key, meta) => string` — Custom function
+
+## License
+
+MIT

package/dist/babel-plugin-FUTQRKLT.js

@@ -0,0 +1,121 @@
+// src/extraction/babel-plugin.ts
+function getStringValue(t, node) {
+  if (t.isStringLiteral(node)) {
+    return node.value;
+  }
+  if (t.isTemplateLiteral(node) && node.quasis.length === 1 && node.expressions.length === 0) {
+    return node.quasis[0]?.value.cooked ?? null;
+  }
+  return null;
+}
+function extractMeta(t, node) {
+  const stringValue = getStringValue(t, node);
+  if (stringValue !== null) {
+    return { fallback: stringValue };
+  }
+  if (t.isObjectExpression(node)) {
+    return extractMetaFromObject(t, node);
+  }
+  return { fallback: "" };
+}
+function extractMetaFromObject(t, obj) {
+  const meta = { fallback: "" };
+  for (const prop of obj.properties) {
+    if (!t.isObjectProperty(prop)) continue;
+    if (!t.isIdentifier(prop.key)) continue;
+    const name = prop.key.name;
+    if (name === "fallback") {
+      const value = getStringValue(t, prop.value);
+      if (value !== null) {
+        meta.fallback = value;
+      }
+    } else if (name === "description") {
+      const value = getStringValue(t, prop.value);
+      if (value !== null) {
+        meta.description = value;
+      }
+    } else if (name === "variables" && t.isObjectExpression(prop.value)) {
+      meta.variables = extractVariables(t, prop.value);
+    }
+  }
+  return meta;
+}
+function extractVariables(t, obj) {
+  const result = {};
+  for (const prop of obj.properties) {
+    if (!t.isObjectProperty(prop)) continue;
+    if (!t.isIdentifier(prop.key)) continue;
+    const varName = prop.key.name;
+    if (t.isObjectExpression(prop.value)) {
+      const varDef = {};
+      for (const varProp of prop.value.properties) {
+        if (!t.isObjectProperty(varProp)) continue;
+        if (!t.isIdentifier(varProp.key)) continue;
+        const varPropName = varProp.key.name;
+        const value = getStringValue(t, varProp.value);
+        if (value !== null) {
+          if (varPropName === "fallback") {
+            varDef.fallback = value;
+          } else if (varPropName === "description") {
+            varDef.description = value;
+          }
+        }
+      }
+      result[varName] = varDef;
+    }
+  }
+  return Object.keys(result).length > 0 ? result : void 0;
+}
+function isMetaArgument(t, node) {
+  if (t.isStringLiteral(node) || t.isTemplateLiteral(node)) {
+    return true;
+  }
+  if (t.isObjectExpression(node)) {
+    for (const prop of node.properties) {
+      if (t.isObjectProperty(prop) && t.isIdentifier(prop.key) && prop.key.name === "fallback") {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+function i18nExtractPlugin({ types: t }) {
+  return {
+    name: "@astroscope/i18n/extract",
+    visitor: {
+      CallExpression(path, state) {
+        if (!path.get("callee").isIdentifier({ name: "t" })) return;
+        const args = path.node.arguments;
+        if (args.length < 1) return;
+        const keyArg = args[0];
+        if (!t.isExpression(keyArg)) return;
+        const key = getStringValue(t, keyArg);
+        if (key === null) return;
+        let meta = { fallback: "" };
+        if (args.length >= 2 && t.isExpression(args[1]) && isMetaArgument(t, args[1])) {
+          meta = extractMeta(t, args[1]);
+        }
+        state.opts.onKeyExtracted({
+          key,
+          meta,
+          file: state.filename ?? "",
+          line: path.node.loc?.start.line ?? 0
+        });
+        if (state.opts.stripFallbacks && args.length >= 2) {
+          const secondArg = args[1];
+          if (!t.isExpression(secondArg)) return;
+          if (isMetaArgument(t, secondArg)) {
+            if (args.length === 2) {
+              path.node.arguments = [args[0]];
+            } else if (args.length >= 3) {
+              path.node.arguments = [args[0], args[2]];
+            }
+          }
+        }
+      }
+    }
+  };
+}
+export {
+  i18nExtractPlugin as default
+};

package/dist/babel-plugin-K2K4ZPM5.js

@@ -0,0 +1,118 @@
+// src/extraction/babel-plugin.ts
+function getStringValue(t, node) {
+  if (t.isStringLiteral(node)) {
+    return node.value;
+  }
+  if (t.isTemplateLiteral(node) && node.quasis.length === 1 && node.expressions.length === 0) {
+    return node.quasis[0]?.value.cooked ?? null;
+  }
+  return null;
+}
+function extractMeta(t, node, warn) {
+  const stringValue = getStringValue(t, node);
+  if (stringValue !== null) {
+    return { fallback: stringValue };
+  }
+  if (t.isTemplateLiteral(node) && node.expressions.length > 0) {
+    warn("t() meta contains template literal with expressions - cannot extract statically");
+    return { fallback: "" };
+  }
+  if (t.isObjectExpression(node)) {
+    const meta = { fallback: "" };
+    for (const prop of node.properties) {
+      if (t.isSpreadElement(prop)) {
+        warn("t() meta contains spread element - cannot extract statically");
+        continue;
+      }
+      if (!t.isObjectProperty(prop)) continue;
+      if (!t.isIdentifier(prop.key)) continue;
+      const name = prop.key.name;
+      if (name === "fallback") {
+        const value = getStringValue(t, prop.value);
+        if (value !== null) {
+          meta.fallback = value;
+        } else {
+          warn("t() fallback is not a static string - cannot extract");
+        }
+      } else if (name === "description") {
+        const value = getStringValue(t, prop.value);
+        if (value !== null) {
+          meta.description = value;
+        } else {
+          warn("t() description is not a static string - cannot extract");
+        }
+      } else if (name === "variables" && t.isObjectExpression(prop.value)) {
+        meta.variables = extractVariables(t, prop.value, warn);
+      }
+    }
+    return meta;
+  }
+  warn("t() meta is not a static string or object - cannot extract");
+  return { fallback: "" };
+}
+function extractVariables(t, obj, warn) {
+  const result = {};
+  for (const prop of obj.properties) {
+    if (t.isSpreadElement(prop)) {
+      warn("t() variables contains spread element - cannot extract statically");
+      continue;
+    }
+    if (!t.isObjectProperty(prop)) continue;
+    if (!t.isIdentifier(prop.key)) continue;
+    const varName = prop.key.name;
+    if (t.isObjectExpression(prop.value)) {
+      const varDef = {};
+      for (const varProp of prop.value.properties) {
+        if (t.isSpreadElement(varProp)) {
+          warn(`t() variable "${varName}" contains spread element - cannot extract statically`);
+          continue;
+        }
+        if (!t.isObjectProperty(varProp)) continue;
+        if (!t.isIdentifier(varProp.key)) continue;
+        const varPropName = varProp.key.name;
+        const value = getStringValue(t, varProp.value);
+        if (value !== null) {
+          if (varPropName === "fallback") {
+            varDef.fallback = value;
+          } else if (varPropName === "description") {
+            varDef.description = value;
+          }
+        } else if (varPropName === "fallback" || varPropName === "description") {
+          warn(`t() variable "${varName}.${varPropName}" is not a static string - cannot extract`);
+        }
+      }
+      result[varName] = varDef;
+    }
+  }
+  return Object.keys(result).length > 0 ? result : void 0;
+}
+function i18nExtractPlugin({ types: t }) {
+  return {
+    name: "@astroscope/i18n/extract",
+    visitor: {
+      CallExpression(path, state) {
+        if (!path.get("callee").isIdentifier({ name: "t" })) return;
+        const args = path.node.arguments;
+        const keyArg = args[0];
+        if (!t.isExpression(keyArg)) return;
+        const key = getStringValue(t, keyArg);
+        if (key === null) return;
+        const file = state.filename ?? "";
+        const line = path.node.loc?.start.line ?? 0;
+        const warn = (message) => state.opts.logger.warn(`${message} at ${file}:${line}`);
+        const meta = args.length >= 2 && t.isExpression(args[1]) ? extractMeta(t, args[1], warn) : { fallback: "" };
+        state.opts.onKeyExtracted({ key, meta, file, line });
+        if (state.opts.stripFallbacks && args.length >= 2) {
+          if (args.length === 2) {
+            path.node.arguments = [args[0]];
+          } else {
+            path.node.arguments = [args[0], t.identifier("undefined"), args[2]];
+          }
+        }
+      }
+    }
+  };
+}
+export {
+  i18nExtractPlugin
+};

package/dist/chunk-22ZZFFC2.js

@@ -0,0 +1,159 @@
+import {
+  compileTranslations
+} from "./chunk-KNDYKTHE.js";
+
+// src/server/i18n.ts
+import fs from "fs";
+
+// src/extraction/hash.ts
+import { createHash } from "crypto";
+function hashString(str) {
+  return createHash("sha256").update(str).digest("hex").substring(0, 8);
+}
+function computeChunkHash(translations, keys) {
+  const relevantTranslations = {};
+  for (const key of keys.sort()) {
+    if (translations[key]) {
+      relevantTranslations[key] = translations[key];
+    }
+  }
+  return hashString(JSON.stringify(relevantTranslations));
+}
+function computeAllChunkHashes(translations, manifest) {
+  const hashes = {};
+  for (const [chunkId, keys] of Object.entries(manifest)) {
+    hashes[chunkId] = computeChunkHash(translations, keys);
+  }
+  return hashes;
+}
+
+// src/server/i18n.ts
+function loadExtractionManifest() {
+  const candidates = [
+    "./i18n-manifest.json",
+    // same directory
+    "../i18n-manifest.json"
+    // parent (when code is in chunks/)
+  ];
+  for (const candidate of candidates) {
+    try {
+      const manifestPath = new URL(candidate, import.meta.url);
+      const content = fs.readFileSync(manifestPath, "utf-8");
+      return JSON.parse(content);
+    } catch {
+    }
+  }
+  return void 0;
+}
+var I18nSingleton = class {
+  config = null;
+  rawCache = /* @__PURE__ */ new Map();
+  compiledCache = /* @__PURE__ */ new Map();
+  extractionManifest = void 0;
+  // undefined = not loaded yet
+  hashCache = /* @__PURE__ */ new Map();
+  configure(config) {
+    if (!config.locales?.length) {
+      throw new Error("i18n.configure(): locales array is required and must not be empty");
+    }
+    for (const locale of config.locales) {
+      if (!locale) {
+        throw new Error("i18n.configure(): locale cannot be empty");
+      }
+      if (locale !== locale.trim()) {
+        throw new Error(`i18n.configure(): locale "${locale}" has leading or trailing whitespace`);
+      }
+    }
+    if (new Set(config.locales).size !== config.locales.length) {
+      throw new Error("i18n.configure(): locales array contains duplicates");
+    }
+    if (config.defaultLocale !== void 0) {
+      if (!config.defaultLocale) {
+        throw new Error("i18n.configure(): defaultLocale cannot be empty");
+      }
+      if (config.defaultLocale !== config.defaultLocale.trim()) {
+        throw new Error(`i18n.configure(): defaultLocale "${config.defaultLocale}" has leading or trailing whitespace`);
+      }
+      if (!config.locales.includes(config.defaultLocale)) {
+        throw new Error(`i18n.configure(): defaultLocale "${config.defaultLocale}" is not in locales array`);
+      }
+    }
+    this.config = config;
+  }
+  isConfigured() {
+    return this.config !== null;
+  }
+  getConfig() {
+    if (!this.config) {
+      throw new Error("i18n not configured. Call i18n.configure() first.");
+    }
+    return this.config;
+  }
+  getDefaultLocale() {
+    const config = this.getConfig();
+    return config.defaultLocale ?? config.locales[0];
+  }
+  getFallbackBehavior() {
+    return this.getConfig().fallback ?? "fallback";
+  }
+  setTranslations(locale, raw) {
+    this.rawCache.set(locale, raw);
+    this.compiledCache.set(locale, compileTranslations(locale, raw));
+    this.hashCache.delete(locale);
+    const chunks = this.getChunkManifest();
+    if (chunks) {
+      this.hashCache.set(locale, computeAllChunkHashes(raw, chunks));
+    }
+  }
+  getTranslations(locale) {
+    return this.rawCache.get(locale) ?? {};
+  }
+  getCompiledTranslations(locale) {
+    return this.compiledCache.get(locale) ?? {};
+  }
+  getChunkManifest() {
+    return this.getExtractionManifest()?.chunks ?? {};
+  }
+  /**
+   * Get extracted translation keys with metadata.
+   * Use this to populate your CMS with keys extracted from the codebase.
+   */
+  getExtractedKeys() {
+    return this.getExtractionManifest()?.keys ?? null;
+  }
+  /**
+   * Get the full extraction manifest (keys + chunks).
+   * Returns null in dev mode (manifest doesn't exist).
+   */
+  getExtractionManifest() {
+    if (this.extractionManifest === void 0) {
+      this.extractionManifest = loadExtractionManifest() ?? null;
+    }
+    return this.extractionManifest;
+  }
+  getHashes(locale) {
+    return this.hashCache.get(locale) ?? {};
+  }
+  /**
+   * Clear translations for specified locale(s).
+   * @param locales - Locale(s) to clear, or all if not specified
+   */
+  clear(locales) {
+    const targets = this.resolveLocales(locales);
+    for (const locale of targets) {
+      this.rawCache.delete(locale);
+      this.compiledCache.delete(locale);
+      this.hashCache.delete(locale);
+    }
+  }
+  resolveLocales(locales) {
+    if (!locales) return this.config?.locales ?? [];
+    if (typeof locales === "string") return [locales];
+    return locales;
+  }
+};
+var i18n = new I18nSingleton();
+
+export {
+  i18n
+};