@astroscope/i18n 0.3.0 → 0.3.1

package/README.md

@@ -52,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!

package/dist/{chunk-EXMM4JID.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,
@@ -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`);
@@ -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/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-EXMM4JID.js";
+} from "../chunk-Z3LDPCYD.js";
 import "../chunk-4A5BKHFN.js";
 export {
   getManifest,

package/dist/index.d.ts

@@ -1,12 +1,10 @@
 import { AstroIntegration, MiddlewareHandler, APIContext } from 'astro';
+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,6 +1,6 @@
 import {
   i18nVitePlugin
-} from "./chunk-EXMM4JID.js";
+} from "./chunk-Z3LDPCYD.js";
 import {
   i18n,
   runWithContext
@@ -10,7 +10,8 @@ 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 })]
           }
         });
       },

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,6 +1,6 @@
 {
   "name": "@astroscope/i18n",
-  "version": "0.3.0",
+  "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",