@astroscope/i18n 0.1.0 → 0.2.0

package/README.md

@@ -28,7 +28,7 @@ i18n for Astro + React islands — automatic tree-shaking, parallel loading, any
 ## Installation
 
 ```bash
-npm install @astroscope/i18n @astroscope/boot
+npm install @astroscope/i18n @astroscope/boot @astroscope/excludes
 ```
 
 ## Usage
@@ -51,6 +51,8 @@ export default defineConfig({
 
 ### 2. Configure i18n in your boot file
 
+**VERY IMPORTANT:** `i18n.configure` must be awaited during boot before handling any requests!
+
 ```ts
 // src/boot.ts
 import { i18n, type RawTranslations } from '@astroscope/i18n';
@@ -95,6 +97,24 @@ export const onRequest = sequence(
 );
 ```
 
+By default, `RECOMMENDED_EXCLUDES` (static assets like `/_astro/`) are excluded from locale context setup. To customize:
+
+```ts
+import { sequence } from 'astro:middleware';
+import { createI18nChunkMiddleware, createI18nMiddleware, i18n } from '@astroscope/i18n';
+import { RECOMMENDED_EXCLUDES } from '@astroscope/excludes';
+
+export const onRequest = sequence(
+  createI18nChunkMiddleware(),
+  createI18nMiddleware({
+    locale: (ctx) =>
+      ctx.cookies.get('locale')?.value ??
+      i18n.getConfig().defaultLocale,
+    exclude: [...RECOMMENDED_EXCLUDES, { exact: '/health' }],
+  }),
+);
+```
+
 ### 4. Add `<I18nScript />` to your layout
 
 Inject translations into the page for hydrated components:

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { AstroIntegration, MiddlewareHandler, APIContext } from 'astro';
 export { F as FallbackBehavior, I as I18nConfig, i as i18n } from './i18n-BGfrSNM8.js';
+import { ExcludePattern } from '@astroscope/excludes';
 export { R as RawTranslations, T as TranslationMeta } from './types-Bzp6KxsI.js';
 export { E as ExtractedKey, a as ExtractionManifest } from './types-8uKCwFda.js';
 
@@ -17,6 +18,28 @@ declare function i18nIntegration(_options?: I18nOptions): AstroIntegration;
 
 type I18nMiddlewareOptions = {
     locale: (ctx: APIContext) => string;
+    /**
+     * Patterns to exclude from locale context setup.
+     * Defaults to RECOMMENDED_EXCLUDES if not provided.
+     *
+     * @example
+     * ```ts
+     * import { RECOMMENDED_EXCLUDES } from '@astroscope/excludes';
+     *
+     * // extend defaults
+     * createI18nMiddleware({
+     *   locale: (ctx) => ctx.locals.session?.locale ?? 'en',
+     *   exclude: [...RECOMMENDED_EXCLUDES, { exact: '/health' }],
+     * })
+     *
+     * // disable excludes entirely
+     * createI18nMiddleware({
+     *   locale: (ctx) => ctx.locals.session?.locale ?? 'en',
+     *   exclude: [],
+     * })
+     * ```
+     */
+    exclude?: ExcludePattern[] | ((context: APIContext) => boolean) | undefined;
 };
 /**
  * Create the i18n chunk middleware that serves translation chunks at `/_i18n/` endpoints.

package/dist/index.js

@@ -55,6 +55,7 @@ ${attributes}
 }
 
 // src/server/middleware.ts
+import { RECOMMENDED_EXCLUDES, shouldExclude } from "@astroscope/excludes";
 var I18N_ENDPOINT_PREFIX = "/_i18n/";
 function createI18nChunkMiddleware() {
   return (ctx, next) => {
@@ -111,6 +112,9 @@ function createI18nChunkMiddleware() {
 }
 function createI18nMiddleware(options) {
   return (ctx, next) => {
+    if (shouldExclude(ctx, options.exclude ?? RECOMMENDED_EXCLUDES)) {
+      return next();
+    }
     const locale = options.locale(ctx);
     const context = {
       locale,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astroscope/i18n",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "i18n for Astro + React islands — automatic tree-shaking, parallel loading, any translation source",
   "type": "module",
   "main": "./dist/index.js",
@@ -86,20 +86,21 @@
     "lint:fix": "eslint 'src/**/*.ts' --fix"
   },
   "dependencies": {
-    "@babel/core": "^7.26.0",
-    "@babel/preset-typescript": "^7.26.0",
+    "@babel/core": "^7.28.6",
+    "@babel/preset-typescript": "^7.28.5",
     "@messageformat/core": "^3.4.0",
-    "magic-string": "^0.30.17"
+    "magic-string": "^0.30.21"
   },
   "devDependencies": {
-    "@babel/types": "^7.26.0",
+    "@babel/types": "^7.28.6",
     "@types/babel__core": "^7.20.5",
-    "astro": "^5.1.0",
+    "astro": "^5.16.9",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
-    "vite": "^6.0.0"
+    "vite": "^6.4.1"
   },
   "peerDependencies": {
+    "@astroscope/excludes": "^0.1.2",
     "astro": "^5.0.0"
   }
 }

package/dist/babel-plugin-FUTQRKLT.js

@@ -1,121 +0,0 @@
-// 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/chunk-22ZZFFC2.js

@@ -1,159 +0,0 @@
-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
-};

package/dist/chunk-2PSXD3JJ.js

@@ -1,144 +0,0 @@
-import {
-  compileTranslations
-} from "./chunk-KNDYKTHE.js";
-
-// 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
-var I18nSingleton = class {
-  // normalized user config with defaults applied
-  config = null;
-  // locale -> raw translation strings (before ICU compilation)
-  rawCache = /* @__PURE__ */ new Map();
-  // locale -> compiled ICU MessageFormat functions
-  compiledCache = /* @__PURE__ */ new Map();
-  // locale -> chunk name -> content hash (for cache busting)
-  hashCache = /* @__PURE__ */ new Map();
-  // manifest getter (set by init module, provides live data in dev mode)
-  manifestGetter = null;
-  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 = {
-      locales: config.locales,
-      defaultLocale: config.defaultLocale ?? config.locales[0],
-      fallback: config.fallback ?? "fallback"
-    };
-  }
-  isConfigured() {
-    return this.config !== null;
-  }
-  getConfig() {
-    if (!this.config) {
-      throw new Error("i18n not configured. Call i18n.configure() first.");
-    }
-    return this.config;
-  }
-  setTranslations(locale, raw) {
-    this.rawCache.set(locale, raw);
-    this.compiledCache.set(locale, compileTranslations(locale, raw));
-    this.hashCache.delete(locale);
-    const { chunks } = this.getManifest();
-    if (Object.keys(chunks).length > 0) {
-      this.hashCache.set(locale, computeAllChunkHashes(raw, chunks));
-    }
-  }
-  getTranslations(locale) {
-    return this.rawCache.get(locale) ?? {};
-  }
-  getCompiledTranslations(locale) {
-    return this.compiledCache.get(locale) ?? {};
-  }
-  /**
-   * Get the extraction manifest (keys + chunks).
-   * - keys: translation keys extracted from codebase with metadata
-   * - chunks: mapping of chunk names to their translation keys
-   */
-  getManifest() {
-    if (!this.manifestGetter) {
-      throw new Error("i18n manifest not initialized. Make sure to import '@astroscope/i18n/init' in your boot file.");
-    }
-    return this.manifestGetter();
-  }
-  /**
-   * Set the manifest getter function (called by init module).
-   * In dev mode, this returns live data from the vite plugin.
-   * In production, this returns the static manifest loaded from JSON.
-   * @internal
-   */
-  setManifestGetter(getter) {
-    this.manifestGetter = getter;
-  }
-  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
-};