vite-plugin-ai-auto-i18n 0.1.0 → 0.2.1

package/README.md

@@ -1,8 +1,8 @@
-# vite-plugin-autoi18n — MVP sketch
+# 🌍 vite-plugin-autoi18n — MVP sketch 🚀
 
 Implicit build-time localization for JSX: author English directly, let the compiler extract user-facing copy, persist message identities, and optionally translate through an AI provider.
 
-## Current MVP scope
+## 🧩 Current MVP scope
 
 - Extracts JSX text nodes and static string JSX attributes.
 - Uses tag/attribute/semantic-attribute/handler context to form fingerprints; component names and file paths are excluded so ordinary moves and renames do not automatically invalidate IDs.
@@ -11,37 +11,70 @@ Implicit build-time localization for JSX: author English directly, let the compi
 - Supports a pluggable translation provider; includes an OpenAI-compatible implementation.
 - Writes locale JSON catalogues and keeps source English as fallback.
 - Two delivery modes: `build` (one compiled bundle per locale) and `runtime` (one bundle, locales loaded on demand through `virtual:autoi18n`).
-- Re-translates a message when its source text changes, tracked in `.autoi18n/locales/<locale>.sources.json`.
+- Re-translates a message when its source text changes, tracked in the `sources` map of `.autoi18n/locales/<locale>.json`.
 - Includes a deliberately varied document-dashboard example.
 
-## Install / try
+## 📦 Installation
 
-This repository is a plugin prototype. Add dependencies from `package.json`, then configure it in Vite:
+### 1️⃣ Install the package
+
+In your React + Vite project:
+
+```sh
+npm install -D vite-plugin-ai-auto-i18n
+```
+
+Works the same with `pnpm add -D vite-plugin-ai-auto-i18n` or `yarn add -D vite-plugin-ai-auto-i18n`. It requires Vite 5 or newer (a peer dependency). For React, also keep `@vitejs/plugin-react` in your Vite config.
+
+### 2️⃣ Add your API key
+
+Put the key in `.env.local` and keep that file out of git:
+
+```sh
+OPENAI_API_KEY=your-key-here
+```
+
+### 3️⃣ Configure Vite
+
+Add the plugin to `vite.config.ts`. `loadEnv` reads `.env.local` for the config file:
 
 ```ts
-import autoI18n, { OpenAICompatibleProvider } from "vite-plugin-autoi18n";
-
-export default defineConfig({
-  plugins: [
-    autoI18n({
-      locales: ["en", "de", "fr"],
-      sourceLocale: "en",
-      provider: new OpenAICompatibleProvider({
-        apiKey: process.env.OPENAI_API_KEY!,
-        model: "gpt-4.1-mini"
-      })
-    })
-  ]
+import { defineConfig, loadEnv } from "vite";
+import react from "@vitejs/plugin-react";
+import autoI18n, { OpenAICompatibleProvider } from "vite-plugin-ai-auto-i18n";
+
+export default defineConfig(({ mode }) => {
+  const env = loadEnv(mode, process.cwd(), "");
+
+  return {
+    plugins: [
+      autoI18n({
+        locales: ["en", "de", "fr"],
+        sourceLocale: "en",
+        provider: new OpenAICompatibleProvider({
+          apiKey: env.OPENAI_API_KEY!,
+          model: "gpt-4.1-mini"
+        })
+      }),
+      react() // in runtime delivery, keep autoI18n before the React plugin
+    ]
+  };
 });
 ```
 
+### 4️⃣ Commit the generated files
+
+The build writes `.autoi18n/` (registry and catalogues). Commit it so existing translations are reused instead of requested again. ✅
+
 Then write ordinary JSX:
 
 ```tsx
 <button title="Save the current document">Save</button>
 ```
 
-To try the bundled example (a React document dashboard under `example/`):
+### 🧪 Try the bundled example
+
+A React document dashboard under `example/`:
 
 ```sh
 npm install
@@ -49,25 +82,31 @@ npm run example:dev     # dev server
 npm run example:build   # production build into example/dist
 ```
 
-Run Vite. The plugin writes `.autoi18n/registry.json`, `.autoi18n/locales/<locale>.json` and `.autoi18n/locales/<locale>.sources.json`. The sidecar records the source text each translation was made from; if the source changes, that message is re-translated on the next build.
+Run Vite. The plugin writes `.autoi18n/registry.json` and `.autoi18n/locales/<locale>.json`. Each locale file has two parts: `messages` (the translations) and `sources` (the source text each translation was made from). If the source changes, that message is re-translated on the next build.
+
+Upgrading from an earlier version: the old flat locale files and `*.sources.json` sidecars are not read. Every message is re-translated once on the first build, and the sidecars are deleted.
+
+If a translation batch fails, the other batches are still stored. The failed messages fall back to the source text until the next build. If every batch for a locale fails, that locale keeps its previous file and the build reports the error after writing the other locales.
+
+🔑 Translations require a provider. With `failOnMissingProvider: true` the build fails when a locale is missing translations and no provider is configured, instead of silently shipping English.
 
-Translations require a provider. With `failOnMissingProvider: true` the build fails when a locale is missing translations and no provider is configured, instead of silently shipping English.
+`OpenAICompatibleProvider` sends messages in batches (`batchSize`, default 40), runs up to `concurrency` batches at once (default 4), aborts a request after `timeoutMs` (default 60000), and retries network errors, timeouts, 408/409/429 and 5xx responses or malformed output up to `maxRetries` times (default 2) with exponential backoff from `retryDelayMs` (default 500). Other 4xx errors fail immediately. If the provider omits some messages, the rest are kept and the missing ones stay in the source language until the next build retries them; the build logs how many were left untranslated.
 
-`OpenAICompatibleProvider` sends messages in batches (`batchSize`, default 40), aborts a request after `timeoutMs` (default 60000), and retries network errors, timeouts, 408/409/429 and 5xx responses or malformed output up to `maxRetries` times (default 2) with exponential backoff from `retryDelayMs` (default 500). Other 4xx errors fail immediately. If the provider omits some messages, the rest are kept and the missing ones stay in the source language until the next build retries them; the build logs how many were left untranslated.
+The plugin translates up to `localeConcurrency` locales at once (default 2). Total parallel requests are roughly `localeConcurrency × concurrency`, so lower one or both if your provider rate-limits your account.
 
 Ambiguous identity matches (duplicate identical strings whose count changed) are logged as warnings. Set `onAmbiguous: "error"` to fail the build instead.
 
 Messages removed from the source are kept as orphans in `registry.json` so their IDs can be reused if the text returns. Orphans not seen for `orphanRetentionMinutes` minutes (default `43200`, i.e. 30 days) are deleted on the next build, and the build logs how many were removed. Use `0` to delete them immediately or `Infinity` to keep them forever. Once deleted, a returning message gets a new ID and is translated again.
 
-To prune without running a build, use the CLI. In this repository, `npm run prune` builds and then runs it on the example app's `example/.autoi18n/` with `--retention-minutes 0`, so every orphan is removed. Pass options after `--` to override, for example `npm run prune -- --directory .autoi18n --retention-minutes 1440 --debug`. Options: `--directory` (default `.autoi18n`, relative to the current directory), `--retention-minutes` (default `43200`, i.e. 30 days, the plugin default) and `--debug` (prints each removed entry with its source text and last-seen time). The CLI also removes any key from `locales/*.json` and `locales/*.sources.json` that is no longer an active registry entry, so the catalogues match the registry. If no registry exists at that path, the CLI says so and changes nothing. Installed packages can run `node node_modules/vite-plugin-autoi18n/dist/cli/prune.js` with the same options.
+🧹 To prune without running a build, use the CLI. In this repository, `npm run prune` builds and then runs it on the example app's `example/.autoi18n/` with `--retention-minutes 0`, so every orphan is removed. Pass options after `--` to override, for example `npm run prune -- --directory .autoi18n --retention-minutes 1440 --debug`. Options: `--directory` (default `.autoi18n`, relative to the current directory), `--retention-minutes` (default `43200`, i.e. 30 days, the plugin default) and `--debug` (prints each removed entry with its source text and last-seen time). The CLI also removes any key from the `messages` and `sources` maps of `locales/*.json` that is no longer an active registry entry, so the catalogues match the registry. If no registry exists at that path, the CLI says so and changes nothing. Installed packages can run `node node_modules/vite-plugin-ai-auto-i18n/dist/cli/prune.js` with the same options.
 
-Set `debug: true` (default `false`) to print every translation exchange to the console: each message sent to the provider (`sent`) and each translation received back (`received`), prefixed with `[autoi18n debug]` and an ISO timestamp.
+🐞 Set `debug: true` (default `false`) to print every translation exchange to the console: each message sent to the provider (`sent`) and each translation received back (`received`), prefixed with `[autoi18n debug]` and an ISO timestamp.
 
-To keep copy out of automatic translation, add `translate="no"` to the element (for example `<h2 translate="no">Sample code</h2>`). This is the standard HTML marker, and it also covers the element's descendants and attributes such as `title`.
+🙈 To keep copy out of automatic translation, add `translate="no"` to the element (for example `<h2 translate="no">Sample code</h2>`). This is the standard HTML marker, and it also covers the element's descendants and attributes such as `title`.
 
 Corrupt `registry.json` or catalogue files are renamed to `<file>.corrupt-<timestamp>` and a warning is logged; the plugin continues with an empty state. Writes are atomic, so an interrupted build does not leave a truncated file.
 
-### Delivery modes
+### 🚚 Delivery modes
 
 - `delivery: "build"` (default): compiles one locale per build. Use `AUTOI18N_LOCALE=de vite build` (on Windows use `cross-env AUTOI18N_LOCALE=de vite build`) or `locale: "de"` in plugin options, typically in a CI build matrix. When a locale is set explicitly, only that locale is translated during the build. Without one, all configured locales are translated. An unknown locale fails the build.
 - `delivery: "runtime"`: one bundle for all locales. Text is wrapped in `t(id, source)` calls and catalogues are fetched on demand. Import the API from the virtual module:
@@ -78,13 +117,82 @@ import { locales, resolveSupported, setLocale, getLocale, subscribe, t } from "v
 setLocale(resolveSupported(navigator.languages)); // call before first render
 ```
 
-`createLocaleLoader` and `resolveLocale` are available from the `vite-plugin-autoi18n/runtime` subpath, not the main entry.
+`createLocaleLoader` and `resolveLocale` are available from the `vite-plugin-ai-auto-i18n/runtime` subpath, not the main entry.
 
 `subscribe(listener)` returns an unsubscribe function. `getVersion()` changes whenever the locale or the catalogues change, so `useSyncExternalStore(subscribe, getVersion, getVersion)` re-renders components that read `t()` during render. Components wrapped in `memo` must subscribe themselves, or they keep the old text until their props change. List `autoI18n()` before `@vitejs/plugin-react` in `plugins`. The React plugin rewrites JSX in dev before other pre-transforms run, so the plugin must see the original JSX. Add a type declaration for `virtual:autoi18n` (see [example/src/autoi18n-virtual.d.ts](/home/bogdan/git/vite-plugin-ai-i18n/example/src/autoi18n-virtual.d.ts)). The example app uses this mode with a locale switcher.
 
 In dev, saving a source file re-indexes the project, translates only new or changed messages and pushes the updated catalogues to the browser over an `autoi18n:update` event. Files added or removed are indexed as well. The page is not reloaded, so new JSX text appears once its translation is ready.
 
-## Important prototype limitations
+## ⚙️ Configuration reference
+
+### Plugin options (`autoI18n({...})`)
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `locales` | `string[]` | _required_ | Locales the app ships, for example `["en", "de", "fr"]`. The source locale is never translated, so including it is harmless. |
+| `sourceLocale` | `string` | `"en"` | Language the JSX is written in. Used as the fallback when a translation is missing. |
+| `delivery` | `"build" \| "runtime"` | `"build"` | `build` compiles one locale per build. `runtime` ships every catalogue and switches locale in the browser with `setLocale()` from `virtual:autoi18n`. |
+| `locale` | `string` | `sourceLocale` | Locale to compile in `build` delivery. Also read from the `AUTOI18N_LOCALE` environment variable, which is handy for CI matrix builds. In `build` delivery during a non-dev build, only this locale is translated. |
+| `include` | `string[]` | `["src/**/*.{tsx,jsx,ts,js}"]` | Glob patterns of source files to scan, relative to the Vite root. |
+| `exclude` | `string[]` | `["**/*.test.*", "**/node_modules/**"]` | Glob patterns of files to skip, relative to the Vite root. |
+| `directory` | `string` | `".autoi18n"` | Folder for `registry.json` and `locales/`, relative to the Vite root. |
+| `provider` | `TranslationProvider` | `undefined` | Translates missing and changed messages. Without one, untranslated messages fall back to the source text. |
+| `failOnMissingProvider` | `boolean` | `false` | When `true`, the build fails if a locale has untranslated messages and no `provider` is set. |
+| `onAmbiguous` | `"warn" \| "error"` | `"warn"` | What to do when duplicated identical texts change their occurrence count, so their IDs may have moved. `"error"` fails the build. |
+| `orphanRetentionMinutes` | `number` | `43200` (30 days) | Minutes an orphaned message is kept before it is deleted. `0` deletes on the next build; `Infinity` keeps forever. |
+| `localeConcurrency` | `number` | `2` | Locales translated at the same time. Values below 1 are raised to 1, and fractions are rounded down. |
+| `debug` | `boolean` | `false` | Logs each message sent to the provider, each translation received, and each removed orphan, with timestamps. |
+
+### `OpenAICompatibleProvider` options
+
+Create the provider with `new OpenAICompatibleProvider(options)`.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `apiKey` | `string` | _required_ | Bearer token for the endpoint. Read it from an environment variable and do not commit it. |
+| `model` | `string` | _required_ | Model name sent in each request, for example `"gpt-4.1-mini"`. |
+| `baseURL` | `string` | `"https://api.openai.com/v1"` | Base URL of any OpenAI-compatible API. Requests go to `${baseURL}/chat/completions`. |
+| `batchSize` | `number` | `40` | Messages per request. Smaller batches keep responses within output limits. |
+| `concurrency` | `number` | `4` | Batches sent in parallel for one locale. |
+| `timeoutMs` | `number` | `60000` | Milliseconds before a single request is aborted. |
+| `maxRetries` | `number` | `2` | Extra attempts for network errors, timeouts, 408/409/429/5xx responses and malformed output. |
+| `retryDelayMs` | `number` | `500` | Delay before the first retry. It doubles on each attempt. |
+
+### Custom provider (`TranslationProvider`)
+
+Any object with this shape can be passed as `provider`:
+
+```ts
+interface TranslationProvider {
+  translate(input: {
+    sourceLocale: string;
+    targetLocale: string;
+    messages: TranslationRequest[];
+  }): Promise<Record<string, string>>; // message ID -> translated text
+}
+
+interface TranslationRequest {
+  id: string;             // opaque ID to echo back in the result
+  source: string;         // English text
+  context: string;        // for example "Toolbar > Save button"
+  kind: "text" | "attribute" | "mixed"; // text node, static attribute, or both in one message
+  placeholders?: string[]; // {name} placeholders that must survive translation
+}
+```
+
+Return only the IDs you translated. Omitted IDs stay in the source language and are requested again on the next build. If your provider can only translate some batches, throw `PartialTranslationError` (exported from the package) with the translations you have and the number of failed messages, so the successful ones are still stored. Any other error fails the whole locale, which keeps its previous file.
+
+### Environment variables
+
+| Variable | Effect |
+|---|---|
+| `AUTOI18N_LOCALE` | Same as the `locale` option. The option wins when both are set. |
+
+### Prune CLI
+
+The `prune` CLI options (`--directory`, `--retention-minutes`, `--debug`) are described in the orphan paragraph of [Try the bundled example](#-try-the-bundled-example).
+
+## ⚠️ Important prototype limitations
 
 This is a compiler MVP, not production-ready localization yet:
 
@@ -96,7 +204,7 @@ This is a compiler MVP, not production-ready localization yet:
 6. The example uses a React plugin in its Vite config; install `@vitejs/plugin-react` in the consuming example.
 7. The initial fingerprint is a heuristic. It excludes file and line position, but component names and nearby semantic signals can still change during refactors.
 
-## Design rules
+## 🧭 Design rules
 
 - IDs are opaque and persistent; never expose semantic fingerprints as runtime keys.
 - AI suggestions never silently overwrite an existing translation.

package/dist/{chunk-ASK7BKZ3.js → chunk-LLL7ZSKW.js}

@@ -2,9 +2,11 @@
 var debugLog = (message) => console.log(`[autoi18n debug] ${(/* @__PURE__ */ new Date()).toISOString()} ${message}`);
 
 // src/io.ts
-import { randomUUID } from "crypto";
+import { createHash, randomUUID } from "crypto";
 import { mkdir, readFile, rename, writeFile } from "fs/promises";
 import path from "path";
+var toJson = (value) => JSON.stringify(value, null, 2) + "\n";
+var hashContent = (text) => createHash("sha256").update(text).digest("hex");
 async function readJsonFile(file, fallback, warn) {
   let text;
   try {
@@ -30,6 +32,28 @@ async function writeFileAtomic(file, content) {
   await rename(temp, file);
 }
 
+// src/catalog.ts
+import path2 from "path";
+var emptyLocaleFile = () => ({ messages: {}, sources: {} });
+function localeFilePath(outDir, locale) {
+  return path2.join(outDir, `${locale}.json`);
+}
+async function readLocaleFile(file, warn) {
+  const parsed = await readJsonFile(file, null, warn);
+  if (!parsed || typeof parsed.messages !== "object" || typeof parsed.sources !== "object") return emptyLocaleFile();
+  return { messages: parsed.messages, sources: parsed.sources };
+}
+var writeLocaleFile = (file, content) => writeFileAtomic(file, toJson(content));
+function pruneCatalog(catalog, keep) {
+  const kept = {};
+  const removed = [];
+  for (const [id, text] of Object.entries(catalog)) {
+    if (keep.has(id)) kept[id] = text;
+    else removed.push(id);
+  }
+  return { catalog: kept, removed };
+}
+
 // src/identity/registry.ts
 import { randomUUID as randomUUID2 } from "crypto";
 var emptyRegistry = () => ({ version: 1, entries: {} });
@@ -63,6 +87,7 @@ function reconcile(registry, messages) {
     list.push(message);
     incoming.set(message.fingerprint, list);
   }
+  const assigned = /* @__PURE__ */ new Map();
   const seen = /* @__PURE__ */ new Set();
   const ambiguous = [];
   for (const [fingerprint, current] of incoming) {
@@ -76,7 +101,7 @@ function reconcile(registry, messages) {
       const message = current[i];
       const candidate = previous[i];
       if (candidate) {
-        message.id = candidate.id;
+        assigned.set(message, candidate.id);
         candidate.status = "active";
         candidate.lastSeen = now;
         candidate.source = message.source;
@@ -84,7 +109,7 @@ function reconcile(registry, messages) {
         seen.add(candidate.id);
       } else {
         const id = `msg_${randomUUID2().replaceAll("-", "").slice(0, 16)}`;
-        message.id = id;
+        assigned.set(message, id);
         registry.entries[id] = {
           id,
           source: message.source,
@@ -104,7 +129,12 @@ function reconcile(registry, messages) {
     }
   }
   for (const entry of Object.values(registry.entries)) if (!seen.has(entry.id)) entry.status = "orphaned";
-  return { registry, ambiguous };
+  const resolved = messages.map((message) => {
+    const id = assigned.get(message);
+    if (id === void 0) throw new Error(`autoi18n: no message ID was assigned to ${message.file}:${message.start}`);
+    return { ...message, id };
+  });
+  return { registry, ambiguous, messages: resolved };
 }
 var MINUTE_MS = 60 * 1e3;
 var DEFAULT_ORPHAN_RETENTION_MINUTES = 30 * 24 * 60;
@@ -120,13 +150,17 @@ function pruneOrphans(registry, retentionMinutes, now = Date.now()) {
   return removed;
 }
 async function saveRegistry(file, registry) {
-  await writeFileAtomic(file, JSON.stringify(registry, null, 2) + "\n");
+  await writeFileAtomic(file, toJson(registry));
 }
 
 export {
   debugLog,
-  readJsonFile,
-  writeFileAtomic,
+  hashContent,
+  emptyLocaleFile,
+  localeFilePath,
+  readLocaleFile,
+  writeLocaleFile,
+  pruneCatalog,
   loadRegistry,
   reconcile,
   DEFAULT_ORPHAN_RETENTION_MINUTES,

package/dist/chunk-ZDZ3YVET.js

@@ -0,0 +1,38 @@
+// src/runtime/loader.ts
+function createLocaleLoader(loaders, fallback = "en") {
+  const cache = /* @__PURE__ */ new Map();
+  function loadLocale(locale) {
+    const selected = loaders[locale] ? locale : fallback;
+    const cached = cache.get(selected);
+    if (cached) return cached;
+    const loader = loaders[selected];
+    if (!loader) return Promise.reject(new Error(`No catalogue loader for locale "${selected}"`));
+    const pending = loader().then((module) => "default" in module ? module.default : module);
+    cache.set(selected, pending);
+    pending.catch(() => {
+      if (cache.get(selected) === pending) cache.delete(selected);
+    });
+    return pending;
+  }
+  loadLocale.prime = (locale, catalog) => {
+    cache.set(locale, Promise.resolve(catalog));
+  };
+  return loadLocale;
+}
+
+// src/runtime/resolve.ts
+function resolveLocale(preferred, supported, fallback = "en") {
+  for (const candidate of preferred) {
+    const exact = supported.find((x) => x.toLowerCase() === candidate.toLowerCase());
+    if (exact) return exact;
+    const base = candidate.split("-")[0].toLowerCase();
+    const language = supported.find((x) => x.split("-")[0].toLowerCase() === base);
+    if (language) return language;
+  }
+  return fallback;
+}
+
+export {
+  createLocaleLoader,
+  resolveLocale
+};

package/dist/cli/prune.js

@@ -2,27 +2,29 @@ import {
   DEFAULT_ORPHAN_RETENTION_MINUTES,
   debugLog,
   loadRegistry,
+  pruneCatalog,
   pruneOrphans,
-  readJsonFile,
+  readLocaleFile,
   saveRegistry,
-  writeFileAtomic
-} from "../chunk-ASK7BKZ3.js";
+  writeLocaleFile
+} from "../chunk-LLL7ZSKW.js";
 
 // src/cli/prune.ts
 import { existsSync } from "fs";
 import { readdir } from "fs/promises";
 import path from "path";
-async function pruneCatalogs(localesDir, activeIds) {
+async function pruneLocaleFiles(localesDir, activeIds) {
   if (!existsSync(localesDir)) return [];
   const results = [];
   for (const name of await readdir(localesDir)) {
     if (!name.endsWith(".json")) continue;
     const file = path.join(localesDir, name);
-    const catalog = await readJsonFile(file, {}, (message) => console.warn(message));
-    const removed = Object.keys(catalog).filter((id) => !activeIds.has(id));
+    const current = await readLocaleFile(file, (message) => console.warn(message));
+    const messages = pruneCatalog(current.messages, activeIds);
+    const sources = pruneCatalog(current.sources, activeIds);
+    const removed = [.../* @__PURE__ */ new Set([...messages.removed, ...sources.removed])];
     if (!removed.length) continue;
-    for (const id of removed) delete catalog[id];
-    await writeFileAtomic(file, JSON.stringify(catalog, null, 2) + "\n");
+    await writeLocaleFile(file, { messages: messages.catalog, sources: sources.catalog });
     results.push({ file, removed });
   }
   return results;
@@ -56,7 +58,7 @@ async function main() {
   const removed = pruneOrphans(registry, args.retentionMinutes);
   if (removed.length) await saveRegistry(registryFile, registry);
   const activeIds = new Set(Object.values(registry.entries).filter((entry) => entry.status === "active").map((entry) => entry.id));
-  const catalogs = await pruneCatalogs(path.join(path.dirname(registryFile), "locales"), activeIds);
+  const catalogs = await pruneLocaleFiles(path.join(path.dirname(registryFile), "locales"), activeIds);
   if (args.debug) {
     for (const entry of removed) debugLog(`removed ${entry.id} ${JSON.stringify(entry.source)} (last seen ${entry.lastSeen})`);
     for (const { file, removed: ids } of catalogs) {

package/dist/index.d.ts

@@ -16,22 +16,18 @@ interface ExtractedMessage {
     attribute?: string;
     context: string;
     fingerprint: string;
-    id?: string;
 }
-interface RegistryEntry {
+/** A message with the stable ID that the registry assigned to it. */
+type ResolvedMessage = ExtractedMessage & {
+    id: string;
+};
+type RegistryEntry = Pick<ExtractedMessage, "source" | "kind" | "tag" | "component" | "attribute" | "context" | "fingerprint"> & {
     id: string;
-    source: string;
-    kind: MessageKind;
-    tag: string;
-    component: string;
-    attribute?: string;
-    context: string;
-    fingerprint: string;
     location: string;
     status: "active" | "orphaned";
     firstSeen: string;
     lastSeen: string;
-}
+};
 interface Registry {
     version: 1;
     entries: Record<string, RegistryEntry>;
@@ -52,6 +48,16 @@ interface TranslationProvider {
     }): Promise<Catalog>;
 }
 
+/**
+ * Some batches of a translation request failed while others succeeded. `partial` holds the translations
+ * that did come back, so the caller can keep them and report the rest.
+ */
+declare class PartialTranslationError extends Error {
+    readonly partial: Catalog;
+    readonly failed: number;
+    constructor(message: string, partial: Catalog, failed: number);
+}
+
 interface OpenAICompatibleOptions {
     apiKey: string;
     model: string;
@@ -64,10 +70,16 @@ interface OpenAICompatibleOptions {
     maxRetries?: number;
     /** Base delay before a retry; doubles on each attempt. Default 500. */
     retryDelayMs?: number;
+    /** Batches sent in parallel. Default 4. */
+    concurrency?: number;
 }
 declare class OpenAICompatibleProvider implements TranslationProvider {
     private options;
     constructor(options: OpenAICompatibleOptions);
+    /**
+     * Translates in parallel batches. If every batch fails, the first error is thrown. If only some fail,
+     * a PartialTranslationError carries the translations that succeeded.
+     */
     translate(input: {
         sourceLocale: string;
         targetLocale: string;
@@ -98,9 +110,14 @@ interface AutoI18nOptions {
      * Default 43200 (30 days). `0` deletes orphans on the next build; `Infinity` keeps them forever.
      */
     orphanRetentionMinutes?: number;
+    /**
+     * Locales translated at the same time. Default 2. Batches within a locale are limited separately by
+     * `OpenAICompatibleOptions.concurrency`. Lower this if your provider rate-limits per account.
+     */
+    localeConcurrency?: number;
     /** Log each message sent to the translation provider and each translation received, with timestamps. Default false. */
     debug?: boolean;
 }
 declare function autoI18n(options: AutoI18nOptions): Plugin;
 
-export { type AutoI18nOptions, type Catalog, type ExtractedMessage, type MessageKind, type OpenAICompatibleOptions, OpenAICompatibleProvider, type Registry, type RegistryEntry, type TranslationProvider, type TranslationRequest, autoI18n as default };
+export { type AutoI18nOptions, type Catalog, type ExtractedMessage, type MessageKind, type OpenAICompatibleOptions, OpenAICompatibleProvider, PartialTranslationError, type Registry, type RegistryEntry, type ResolvedMessage, type TranslationProvider, type TranslationRequest, autoI18n as default };

package/dist/index.js

@@ -1,23 +1,153 @@
 import {
   DEFAULT_ORPHAN_RETENTION_MINUTES,
   debugLog,
+  emptyLocaleFile,
+  hashContent,
   loadRegistry,
+  localeFilePath,
+  pruneCatalog,
   pruneOrphans,
-  readJsonFile,
+  readLocaleFile,
   reconcile,
   saveRegistry,
-  writeFileAtomic
-} from "./chunk-ASK7BKZ3.js";
+  writeLocaleFile
+} from "./chunk-LLL7ZSKW.js";
 import {
+  createLocaleLoader,
   resolveLocale
-} from "./chunk-RVYJXXTU.js";
+} from "./chunk-ZDZ3YVET.js";
 
 // src/index.ts
 import fg from "fast-glob";
-import { createHash as createHash2 } from "crypto";
-import { readFile } from "fs/promises";
+import { readFile, rm } from "fs/promises";
 import path from "path";
 
+// src/concurrency.ts
+async function mapWithConcurrency(items, limit, task) {
+  const results = new Array(items.length);
+  let next = 0;
+  const worker = async () => {
+    while (next < items.length) {
+      const index = next++;
+      try {
+        results[index] = { status: "fulfilled", value: await task(items[index]) };
+      } catch (reason) {
+        results[index] = { status: "rejected", reason };
+      }
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(Math.max(1, limit), items.length) }, worker));
+  return results;
+}
+
+// src/compiler/placeholders.ts
+var PLACEHOLDER_PATTERN = "\\{([^{}]+)\\}";
+var PLACEHOLDER = new RegExp(PLACEHOLDER_PATTERN, "g");
+function placeholderNames(text) {
+  return [...text.matchAll(PLACEHOLDER)].map((match) => match[1]);
+}
+function sameNames(a, b) {
+  const left = new Set(a);
+  const right = new Set(b);
+  return left.size === right.size && [...left].every((name) => right.has(name));
+}
+function isUsableTranslation(text, placeholders) {
+  return text.trim() !== "" && sameNames(placeholderNames(text), placeholders);
+}
+
+// src/errors.ts
+var PartialTranslationError = class extends Error {
+  constructor(message, partial, failed) {
+    super(message);
+    this.partial = partial;
+    this.failed = failed;
+    this.name = "PartialTranslationError";
+  }
+  partial;
+  failed;
+};
+
+// src/translate.ts
+async function translateLocale(input) {
+  const { provider, sourceLocale, locale, requests, previous, debug } = input;
+  const active = new Set(requests.map((x) => x.id));
+  const previousMessages = pruneCatalog(previous.messages, active).catalog;
+  const previousSources = pruneCatalog(previous.sources, active).catalog;
+  const missing = requests.filter((x) => previousMessages[x.id] === void 0 || previousSources[x.id] !== x.source);
+  let translated = {};
+  let failed = 0;
+  let failure;
+  if (missing.length && provider) {
+    if (debug) {
+      for (const m of missing) debugLog(`sent ${sourceLocale} -> ${locale} ${m.id}: ${JSON.stringify(m.source)} (context: ${m.context})`);
+    }
+    try {
+      translated = await provider.translate({ sourceLocale, targetLocale: locale, messages: missing });
+    } catch (error) {
+      if (!(error instanceof PartialTranslationError)) throw error;
+      translated = error.partial;
+      failed = error.failed;
+      failure = error.message;
+    }
+    if (debug) {
+      for (const m of missing) {
+        const text = translated[m.id];
+        debugLog(`received ${sourceLocale} -> ${locale} ${m.id}: ${typeof text === "string" ? JSON.stringify(text) : "(no translation)"}`);
+      }
+    }
+  }
+  const messages = { ...previousMessages };
+  const sources = { ...previousSources };
+  let rejected = 0;
+  for (const request of missing) {
+    delete messages[request.id];
+    delete sources[request.id];
+    const text = translated[request.id];
+    if (typeof text !== "string" || !text.trim()) continue;
+    if (request.kind === "mixed" && !isUsableTranslation(text, request.placeholders ?? [])) {
+      rejected++;
+      continue;
+    }
+    messages[request.id] = text;
+    sources[request.id] = request.source;
+  }
+  const untranslated = requests.filter((x) => messages[x.id] === void 0).length;
+  return { file: { messages, sources }, untranslated, rejected, requested: missing.length, failed, failure };
+}
+
+// src/engine.ts
+async function buildCatalogs(input) {
+  const { registry, ambiguous, messages } = reconcile(input.registry, input.files.flatMap((f) => f.messages));
+  const pruned = pruneOrphans(registry, input.orphanRetentionMinutes);
+  const sourceCatalog = {};
+  for (const m of messages) sourceCatalog[m.id] = m.source;
+  const requests = messages.map((m) => ({ id: m.id, source: m.source, context: `${m.component} > ${m.context}`, kind: m.kind, placeholders: m.placeholders }));
+  const outcomes = await mapWithConcurrency(input.locales, input.localeConcurrency, (locale) => translateLocale({
+    provider: input.provider,
+    sourceLocale: input.sourceLocale,
+    locale,
+    requests,
+    previous: input.previous.get(locale) ?? emptyLocaleFile(),
+    debug: input.debug
+  }));
+  const locales = /* @__PURE__ */ new Map();
+  const failures = /* @__PURE__ */ new Map();
+  outcomes.forEach((outcome, index) => {
+    const locale = input.locales[index];
+    if (outcome.status === "fulfilled") locales.set(locale, outcome.value);
+    else failures.set(locale, outcome.reason);
+  });
+  return {
+    registry,
+    ambiguous,
+    pruned,
+    messages,
+    sourceFile: { messages: sourceCatalog, sources: {} },
+    locales,
+    failures
+  };
+}
+
 // src/compiler/extract.ts
 import { parse } from "@babel/parser";
 import traverseModule from "@babel/traverse";
@@ -169,22 +299,6 @@ import { parse as parse2 } from "@babel/parser";
 import traverseModule2 from "@babel/traverse";
 import generateModule from "@babel/generator";
 import * as t2 from "@babel/types";
-
-// src/compiler/placeholders.ts
-var PLACEHOLDER = /\{([^{}]+)\}/g;
-function placeholderNames(text) {
-  return [...text.matchAll(PLACEHOLDER)].map((match) => match[1]);
-}
-function sameNames(a, b) {
-  const left = new Set(a);
-  const right = new Set(b);
-  return left.size === right.size && [...left].every((name) => right.has(name));
-}
-function isUsableTranslation(text, placeholders) {
-  return text.trim() !== "" && sameNames(placeholderNames(text), placeholders);
-}
-
-// src/compiler/transform.ts
 var traverse2 = traverseModule2.default ?? traverseModule2;
 var generate = generateModule.default ?? generateModule;
 var RUNTIME_MODULE = "virtual:autoi18n";
@@ -205,7 +319,7 @@ function transformSource(code, filename, messages, locale, catalog, runtime = fa
   traverse2(ast, {
     JSXElement(p) {
       const message = byStart.get(p.node.start ?? -1);
-      if (message?.kind !== "mixed" || !message.id) return;
+      if (message?.kind !== "mixed") return;
       const names = message.placeholders ?? [];
       const expressions = p.node.children.filter((c) => t2.isJSXExpressionContainer(c)).map((c) => c.expression);
       const prefix = message.prefix ?? "";
@@ -236,7 +350,7 @@ function transformSource(code, filename, messages, locale, catalog, runtime = fa
     },
     JSXText(p) {
       const message = byStart.get(p.node.start ?? -1);
-      if (!message?.id) return;
+      if (!message) return;
       const parts = [];
       if (runtime) {
         if (message.prefix) parts.push(t2.stringLiteral(message.prefix));
@@ -253,7 +367,7 @@ function transformSource(code, filename, messages, locale, catalog, runtime = fa
       const valueNode = p.node.value;
       if (!t2.isStringLiteral(valueNode)) return;
       const message = byStart.get(valueNode.start ?? -1);
-      if (!message?.id) return;
+      if (!message) return;
       p.node.value = runtime ? t2.jsxExpressionContainer(lookup(message)) : lookup(message);
     }
   });
@@ -268,16 +382,34 @@ function transformSource(code, filename, messages, locale, catalog, runtime = fa
   return { code: result.code, map: result.map };
 }
 
+// src/runtime/format.ts
+function formatPlaceholders(text, values, placeholder) {
+  const parts = [];
+  let last = 0;
+  for (const match of text.matchAll(placeholder)) {
+    if (!Object.hasOwn(values, match[1])) continue;
+    const index = match.index ?? 0;
+    if (index > last) parts.push(text.slice(last, index));
+    parts.push(values[match[1]]);
+    last = index + match[0].length;
+  }
+  if (last < text.length) parts.push(text.slice(last));
+  return parts;
+}
+
 // src/runtime/virtual.ts
 function createRuntimeModule(catalogFiles, sourceLocale) {
-  const loaders = Object.entries(catalogFiles).map(([locale, file]) => `  ${JSON.stringify(locale)}: () => import(${JSON.stringify(file)})`).join(",\n");
+  const loaders = Object.entries(catalogFiles).map(([locale, file]) => `  ${JSON.stringify(locale)}: () => import(${JSON.stringify(file)}).then(m => (m.default ?? m).messages)`).join(",\n");
   return [
     `const loaders = {
 ${loaders}
 };`,
     `const sourceLocale = ${JSON.stringify(sourceLocale)};`,
     `const resolveLocale = ${resolveLocale.toString()};`,
-    `const cache = new Map();`,
+    `const createLocaleLoader = ${createLocaleLoader.toString()};`,
+    `const formatPlaceholders = ${formatPlaceholders.toString()};`,
+    `const PLACEHOLDER = new RegExp(${JSON.stringify(PLACEHOLDER_PATTERN)}, "g");`,
+    `const loadLocale = createLocaleLoader(loaders, sourceLocale);`,
     `const listeners = new Set();`,
     `let currentLocale = sourceLocale;`,
     `let messages = {};`,
@@ -287,25 +419,17 @@ ${loaders}
     `export function getLocale() { return currentLocale; }`,
     `export function getVersion() { return version; }`,
     `export function resolveSupported(preferred) { return resolveLocale(preferred, locales, sourceLocale); }`,
-    `function loadCatalog(locale) {`,
-    `  if (!cache.has(locale)) {`,
-    `    const pending = loaders[locale]().then(m => m.default ?? m);`,
-    `    cache.set(locale, pending);`,
-    `    pending.catch(() => { if (cache.get(locale) === pending) cache.delete(locale); });`,
-    `  }`,
-    `  return cache.get(locale);`,
-    `}`,
     `export async function setLocale(locale) {`,
     `  const request = ++latestRequest;`,
     `  let selected = loaders[locale] ? locale : sourceLocale;`,
     `  let catalog;`,
     `  try {`,
-    `    catalog = await loadCatalog(selected);`,
+    `    catalog = await loadLocale(selected);`,
     `  } catch (error) {`,
     `    if (selected === sourceLocale) throw error;`,
     `    console.warn('autoi18n: could not load "' + selected + '", falling back to "' + sourceLocale + '".', error);`,
     `    selected = sourceLocale;`,
-    `    catalog = await loadCatalog(selected);`,
+    `    catalog = await loadLocale(selected);`,
     `  }`,
     `  // A slower earlier request must not overwrite the locale the user picked last.`,
     `  if (request !== latestRequest) return;`,
@@ -319,23 +443,11 @@ ${loaders}
     `}`,
     `export function subscribe(fn) { listeners.add(fn); return () => { listeners.delete(fn); }; }`,
     `export function t(id, source) { return messages[id] ?? source; }`,
-    `// Splits a translated sentence at its {name} placeholders so values keep their React nodes; unknown names stay literal.`,
-    `export function format(text, values) {`,
-    `  const parts = [];`,
-    `  let last = 0;`,
-    `  for (const match of text.matchAll(/\\{([^{}]+)\\}/g)) {`,
-    `    if (!Object.hasOwn(values, match[1])) continue;`,
-    `    if (match.index > last) parts.push(text.slice(last, match.index));`,
-    `    parts.push(values[match[1]]);`,
-    `    last = match.index + match[0].length;`,
-    `  }`,
-    `  if (last < text.length) parts.push(text.slice(last));`,
-    `  return parts;`,
-    `}`,
+    `export function format(text, values) { return formatPlaceholders(text, values, PLACEHOLDER); }`,
     `// Dev server pushes fresh catalogues after a source change; no page reload is needed.`,
     `if (import.meta.hot) {`,
     `  import.meta.hot.on("autoi18n:update", data => {`,
-    `    for (const [locale, catalog] of Object.entries(data.catalogs)) cache.set(locale, Promise.resolve(catalog));`,
+    `    for (const [locale, catalog] of Object.entries(data.catalogs)) loadLocale.prime(locale, catalog);`,
     `    if (data.catalogs[currentLocale]) messages = data.catalogs[currentLocale];`,
     `    notify();`,
     `  });`,
@@ -343,42 +455,6 @@ ${loaders}
   ].join("\n") + "\n";
 }
 
-// src/translate.ts
-async function translateLocale(input) {
-  const { provider, sourceLocale, locale, requests, previous, previousSources, debug } = input;
-  const missing = requests.filter((x) => previous[x.id] === void 0 || previousSources[x.id] !== x.source);
-  let translated = {};
-  if (missing.length && provider) {
-    if (debug) {
-      for (const m of missing) debugLog(`sent ${sourceLocale} -> ${locale} ${m.id}: ${JSON.stringify(m.source)} (context: ${m.context})`);
-    }
-    translated = await provider.translate({ sourceLocale, targetLocale: locale, messages: missing });
-    if (debug) {
-      for (const m of missing) {
-        const text = translated[m.id];
-        debugLog(`received ${sourceLocale} -> ${locale} ${m.id}: ${typeof text === "string" ? JSON.stringify(text) : "(no translation)"}`);
-      }
-    }
-  }
-  const catalog = { ...previous };
-  const sources = { ...previousSources };
-  let rejected = 0;
-  for (const request of missing) {
-    delete catalog[request.id];
-    delete sources[request.id];
-    const text = translated[request.id];
-    if (typeof text !== "string" || !text.trim()) continue;
-    if (request.kind === "mixed" && !isUsableTranslation(text, request.placeholders ?? [])) {
-      rejected++;
-      continue;
-    }
-    catalog[request.id] = text;
-    sources[request.id] = request.source;
-  }
-  const untranslated = requests.filter((x) => catalog[x.id] === void 0).length;
-  return { catalog, sources, untranslated, rejected, requested: missing.length };
-}
-
 // src/ai/provider.ts
 var ProviderError = class extends Error {
   constructor(message, retryable) {
@@ -393,13 +469,31 @@ var OpenAICompatibleProvider = class {
     this.options = options;
   }
   options;
+  /**
+   * Translates in parallel batches. If every batch fails, the first error is thrown. If only some fail,
+   * a PartialTranslationError carries the translations that succeeded.
+   */
   async translate(input) {
     const batchSize = Math.max(1, this.options.batchSize ?? 40);
+    const batches = [];
+    for (let start = 0; start < input.messages.length; start += batchSize) batches.push(input.messages.slice(start, start + batchSize));
+    const settled = await mapWithConcurrency(batches, this.options.concurrency ?? 4, (batch) => this.translateBatch({ ...input, messages: batch }));
     const result = {};
-    for (let start = 0; start < input.messages.length; start += batchSize) {
-      Object.assign(result, await this.translateBatch({ ...input, messages: input.messages.slice(start, start + batchSize) }));
-    }
-    return result;
+    const errors = [];
+    let failed = 0;
+    let succeeded = 0;
+    settled.forEach((outcome, index) => {
+      if (outcome.status === "fulfilled") {
+        succeeded++;
+        Object.assign(result, outcome.value);
+      } else {
+        errors.push(outcome.reason);
+        failed += batches[index].length;
+      }
+    });
+    if (!errors.length) return result;
+    if (!succeeded) throw errors[0];
+    throw new PartialTranslationError(`${failed} messages failed to translate: ${errors[0].message}`, result, failed);
   }
   async translateBatch(input) {
     const maxRetries = this.options.maxRetries ?? 2;
@@ -457,9 +551,14 @@ var UPDATE_EVENT = "autoi18n:update";
 var DEFAULT_INCLUDE = ["src/**/*.{tsx,jsx,ts,js}"];
 var DEFAULT_EXCLUDE = ["**/*.test.*", "**/node_modules/**"];
 var WATCH_DEBOUNCE_MS = 150;
-var hashOf = (code) => createHash2("sha1").update(code).digest("hex");
-var toJson = (value) => JSON.stringify(value, null, 2) + "\n";
-var pathWithGlob = path;
+var reporterFor = (logger) => ({
+  info: (m) => logger.info(m),
+  warn: (m) => logger.warn(m),
+  error: (m) => logger.error(m)
+});
+async function removeLegacySidecars(outDir, locales) {
+  await Promise.all(locales.map((locale) => rm(path.join(outDir, `${locale}.sources.json`), { force: true })));
+}
 function autoI18n(options) {
   const sourceLocale = options.sourceLocale ?? "en";
   const directory = options.directory ?? ".autoi18n";
@@ -469,6 +568,7 @@ function autoI18n(options) {
   let config;
   let registryFile = "";
   let catalogFiles = {};
+  let extractions = /* @__PURE__ */ new Map();
   let fileMessages = /* @__PURE__ */ new Map();
   let fileHashes = /* @__PURE__ */ new Map();
   let catalogs = /* @__PURE__ */ new Map();
@@ -476,7 +576,6 @@ function autoI18n(options) {
   let server;
   let queue = Promise.resolve();
   let watchTimer;
-  const devReporter = () => ({ info: (m) => config.logger.info(m), warn: (m) => config.logger.warn(m), error: (m) => config.logger.error(m) });
   const selectedLocale = () => options.locale ?? process.env.AUTOI18N_LOCALE ?? sourceLocale;
   function localesToTranslate() {
     const others = options.locales.filter((x) => x !== sourceLocale);
@@ -486,62 +585,74 @@ function autoI18n(options) {
   }
   async function sync(report) {
     const files = await fg(options.include ?? DEFAULT_INCLUDE, { cwd: config.root, ignore: options.exclude ?? DEFAULT_EXCLUDE, absolute: true });
-    const all = [];
-    const nextMessages = /* @__PURE__ */ new Map();
-    const nextHashes = /* @__PURE__ */ new Map();
+    const nextExtractions = /* @__PURE__ */ new Map();
+    const indexed = [];
     for (const file of files) {
       const code = await readFile(file, "utf8");
-      const messages = extractMessages(code, file);
-      nextMessages.set(file, messages);
-      nextHashes.set(file, hashOf(code));
-      all.push(...messages);
+      const hash = hashContent(code);
+      const cached = extractions.get(file);
+      const entry = cached?.hash === hash ? cached : { hash, messages: extractMessages(code, file) };
+      nextExtractions.set(file, entry);
+      indexed.push({ file, messages: entry.messages });
     }
-    const { registry, ambiguous } = reconcile(await loadRegistry(registryFile, report.warn), all);
-    const pruned = pruneOrphans(registry, orphanRetentionMinutes);
-    if (debug) for (const entry of pruned) debugLog(`removed ${entry.id} ${JSON.stringify(entry.source)} (last seen ${entry.lastSeen})`);
-    if (pruned.length) report.info(`autoi18n: removed ${pruned.length} registry entries no longer in the source.`);
-    await saveRegistry(registryFile, registry);
-    if (ambiguous.length) {
-      const message = `autoi18n: ${ambiguous.length} duplicated texts changed occurrence count, so their IDs may have moved (e.g. "${ambiguous[0]}").`;
+    const outDir = path.resolve(config.root, directory, "locales");
+    const locales = localesToTranslate();
+    const previous = /* @__PURE__ */ new Map();
+    for (const locale of locales) previous.set(locale, await readLocaleFile(localeFilePath(outDir, locale), report.warn));
+    const result = await buildCatalogs({
+      files: indexed,
+      registry: await loadRegistry(registryFile, report.warn),
+      orphanRetentionMinutes,
+      sourceLocale,
+      locales,
+      localeConcurrency: Math.max(1, Math.floor(options.localeConcurrency ?? 2)),
+      previous,
+      provider: options.provider,
+      debug
+    });
+    if (debug) for (const entry of result.pruned) debugLog(`removed ${entry.id} ${JSON.stringify(entry.source)} (last seen ${entry.lastSeen})`);
+    if (result.pruned.length) report.info(`autoi18n: removed ${result.pruned.length} registry entries no longer in the source.`);
+    await saveRegistry(registryFile, result.registry);
+    if (result.ambiguous.length) {
+      const message = `autoi18n: ${result.ambiguous.length} duplicated texts changed occurrence count, so their IDs may have moved (e.g. "${result.ambiguous[0]}").`;
       if (options.onAmbiguous === "error") report.error(message);
       else report.warn(message);
     }
-    const outDir = path.resolve(config.root, directory, "locales");
-    const sourceCatalog = {};
-    for (const m of all) if (m.id) sourceCatalog[m.id] = m.source;
-    await writeFileAtomic(path.join(outDir, `${sourceLocale}.json`), toJson(sourceCatalog));
-    const requests = all.filter((m) => m.id).map((m) => ({ id: m.id, source: m.source, context: `${m.component} > ${m.context}`, kind: m.kind, placeholders: m.placeholders }));
-    const nextFiles = Object.fromEntries(options.locales.map((locale) => [locale, path.join(outDir, `${locale}.json`)]));
-    const nextCatalogs = /* @__PURE__ */ new Map([[sourceLocale, sourceCatalog]]);
-    for (const locale of localesToTranslate()) {
-      const catalogPath = nextFiles[locale];
-      const sourcesPath = path.join(outDir, `${locale}.sources.json`);
-      const result = await translateLocale({
-        provider: options.provider,
-        sourceLocale,
-        locale,
-        requests,
-        previous: await readJsonFile(catalogPath, {}, report.warn),
-        previousSources: await readJsonFile(sourcesPath, {}, report.warn),
-        debug
-      });
-      if (result.requested && !options.provider && options.failOnMissingProvider) {
-        report.error(`Missing ${result.requested} ${locale} translations and no provider is configured.`);
+    await writeLocaleFile(localeFilePath(outDir, sourceLocale), result.sourceFile);
+    await removeLegacySidecars(outDir, [sourceLocale, ...options.locales]);
+    const nextCatalogs = /* @__PURE__ */ new Map([[sourceLocale, result.sourceFile.messages]]);
+    for (const [locale, translation] of result.locales) {
+      await writeLocaleFile(localeFilePath(outDir, locale), translation.file);
+      nextCatalogs.set(locale, translation.file.messages);
+    }
+    for (const locale of result.failures.keys()) nextCatalogs.set(locale, previous.get(locale)?.messages ?? {});
+    let offset = 0;
+    fileMessages = /* @__PURE__ */ new Map();
+    for (const { file, messages } of indexed) {
+      fileMessages.set(file, result.messages.slice(offset, offset + messages.length));
+      offset += messages.length;
+    }
+    fileHashes = new Map([...nextExtractions].map(([file, entry]) => [file, entry.hash]));
+    extractions = nextExtractions;
+    catalogs = nextCatalogs;
+    catalogFiles = Object.fromEntries(options.locales.map((locale) => [locale, localeFilePath(outDir, locale)]));
+    for (const [locale, translation] of result.locales) {
+      if (translation.requested && !options.provider && options.failOnMissingProvider) {
+        report.error(`Missing ${translation.requested} ${locale} translations and no provider is configured.`);
       }
-      if (result.rejected) report.info(`autoi18n: rejected ${result.rejected} ${locale} translations with changed placeholders.`);
-      if (result.untranslated) {
+      if (translation.rejected) report.info(`autoi18n: rejected ${translation.rejected} ${locale} translations with changed placeholders.`);
+      if (translation.untranslated) {
         const log = options.provider ? report.warn : report.info;
-        log(`autoi18n: ${result.untranslated} ${locale} messages have no translation and fall back to the source text.`);
+        log(`autoi18n: ${translation.untranslated} ${locale} messages have no translation and fall back to the source text.`);
+      }
+      if (translation.failed) {
+        report.warn(`autoi18n: ${translation.failed} ${locale} translation batches failed (${translation.failure}); they will be requested again on the next build.`);
       }
-      await writeFileAtomic(catalogPath, toJson(result.catalog));
-      await writeFileAtomic(sourcesPath, toJson(result.sources));
-      nextCatalogs.set(locale, result.catalog);
     }
-    fileMessages = nextMessages;
-    fileHashes = nextHashes;
-    catalogs = nextCatalogs;
-    catalogFiles = nextFiles;
-    if (all.length) report.info(`autoi18n: indexed ${all.length} messages across ${files.length} files.`);
+    if (result.messages.length) report.info(`autoi18n: indexed ${result.messages.length} messages across ${files.length} files.`);
+    const failures = [...result.failures];
+    for (const [locale, error] of failures.slice(1)) report.warn(`autoi18n: ${locale} translation failed: ${error.message}`);
+    if (failures.length) throw failures[0][1];
   }
   function runSync(report) {
     const next = queue.then(() => sync(report));
@@ -553,7 +664,7 @@ function autoI18n(options) {
   }
   async function retranslate() {
     try {
-      await runSync(devReporter());
+      await runSync(reporterFor(config.logger));
       pushCatalogs();
     } catch (error) {
       config.logger.error(`autoi18n: re-translation failed: ${error.message}`);
@@ -565,10 +676,8 @@ function autoI18n(options) {
   }
   function isSourceCandidate(file) {
     if (!/\.[jt]sx?$/.test(file)) return false;
-    if (!pathWithGlob.matchesGlob) return true;
     const relative = path.relative(config.root, file).split(path.sep).join("/");
-    const matches = pathWithGlob.matchesGlob;
-    return (options.include ?? DEFAULT_INCLUDE).some((p) => matches(relative, p)) && !(options.exclude ?? DEFAULT_EXCLUDE).some((p) => matches(relative, p));
+    return (options.include ?? DEFAULT_INCLUDE).some((p) => path.matchesGlob(relative, p)) && !(options.exclude ?? DEFAULT_EXCLUDE).some((p) => path.matchesGlob(relative, p));
   }
   return {
     name: "vite-plugin-autoi18n",
@@ -605,11 +714,11 @@ function autoI18n(options) {
     async transform(code, id) {
       const file = id.split("?")[0];
       if (!fileMessages.has(file)) return null;
-      if (hashOf(code) !== fileHashes.get(file)) {
-        await runSync(devReporter());
+      if (hashContent(code) !== fileHashes.get(file)) {
+        await runSync(reporterFor(config.logger));
       }
       const messages = fileMessages.get(file);
-      if (!messages || hashOf(code) !== fileHashes.get(file)) {
+      if (!messages || hashContent(code) !== fileHashes.get(file)) {
         if (!warnedFiles.has(file)) {
           warnedFiles.add(file);
           this.warn(`autoi18n: ${file} changed while it was being indexed; its messages are left untranslated.`);
@@ -629,5 +738,6 @@ function autoI18n(options) {
 }
 export {
   OpenAICompatibleProvider,
+  PartialTranslationError,
   autoI18n as default
 };

package/dist/runtime/index.d.ts

@@ -8,7 +8,14 @@ declare function resolveLocale(preferred: string[], supported: string[], fallbac
 type LocaleLoader = () => Promise<{
     default: Record<string, string>;
 } | Record<string, string>>;
-
-declare function createLocaleLoader(loaders: Record<string, LocaleLoader>, fallback?: string): (locale: string) => Promise<Record<string, string>>;
+/**
+ * Returns a cached catalogue loader. Unknown locales load the fallback, and a failed load is not cached.
+ * `prime` stores a catalogue that was already fetched, such as one pushed by the dev server.
+ * Serialised into the runtime module via toString(), so it must not reference anything outside its body.
+ */
+declare function createLocaleLoader(loaders: Record<string, LocaleLoader>, fallback?: string): {
+    (locale: string): Promise<Record<string, string>>;
+    prime(locale: string, catalog: Record<string, string>): void;
+};
 
 export { type LocaleLoader, createLocaleLoader, resolveLocale };

package/dist/runtime/index.js

@@ -1,24 +1,7 @@
 import {
+  createLocaleLoader,
   resolveLocale
-} from "../chunk-RVYJXXTU.js";
-
-// src/runtime/index.ts
-function createLocaleLoader(loaders, fallback = "en") {
-  const cache = /* @__PURE__ */ new Map();
-  return function loadLocale(locale) {
-    const selected = loaders[locale] ? locale : fallback;
-    const cached = cache.get(selected);
-    if (cached) return cached;
-    const loader = loaders[selected];
-    if (!loader) return Promise.reject(new Error(`No catalogue loader for locale "${selected}"`));
-    const pending = loader().then((module) => "default" in module ? module.default : module);
-    cache.set(selected, pending);
-    pending.catch(() => {
-      if (cache.get(selected) === pending) cache.delete(selected);
-    });
-    return pending;
-  };
-}
+} from "../chunk-ZDZ3YVET.js";
 export {
   createLocaleLoader,
   resolveLocale

package/package.json

@@ -1,8 +1,11 @@
 {
     "name": "vite-plugin-ai-auto-i18n",
-    "version": "0.1.0",
+    "version": "0.2.1",
     "type": "module",
     "description": "Implicit, build-time AI localization for JSX applications",
+    "engines": {
+        "node": ">=20.17.0 <21 || >=22.5.0"
+    },
     "main": "./dist/index.js",
     "types": "./dist/index.d.ts",
     "exports": {
@@ -19,7 +22,8 @@
         "dist"
     ],
     "scripts": {
-        "build": "tsup src/index.ts src/runtime/index.ts src/cli/prune.ts --format esm --dts",
+        "build": "tsup --clean src/index.ts src/runtime/index.ts src/cli/prune.ts --format esm --dts",
+        "publish": "npm run build && npm publish",
         "prune": "npm run build && node dist/cli/prune.js --directory example/.autoi18n --retention-minutes 0",
         "example:dev": "vite example",
         "example:build": "vite build example",

package/dist/chunk-DQHH7Y2U.js

@@ -1,135 +0,0 @@
-// src/debug.ts
-var debugLog = (message) => console.log(`[autoi18n debug] ${(/* @__PURE__ */ new Date()).toISOString()} ${message}`);
-
-// src/io.ts
-import { randomUUID } from "crypto";
-import { mkdir, readFile, rename, writeFile } from "fs/promises";
-import path from "path";
-async function readJsonFile(file, fallback, warn) {
-  let text;
-  try {
-    text = await readFile(file, "utf8");
-  } catch (error) {
-    if (error.code === "ENOENT") return fallback;
-    warn?.(`autoi18n: could not read ${file}: ${error.message}`);
-    return fallback;
-  }
-  try {
-    return JSON.parse(text);
-  } catch (error) {
-    const backup = `${file}.corrupt-${Date.now()}`;
-    await rename(file, backup).catch(() => void 0);
-    warn?.(`autoi18n: ${file} is not valid JSON (${error.message}); moved to ${backup} and starting fresh.`);
-    return fallback;
-  }
-}
-async function writeFileAtomic(file, content) {
-  await mkdir(path.dirname(file), { recursive: true });
-  const temp = `${file}.${process.pid}.${randomUUID()}.tmp`;
-  await writeFile(temp, content, "utf8");
-  await rename(temp, file);
-}
-
-// src/identity/registry.ts
-import { randomUUID as randomUUID2 } from "crypto";
-var emptyRegistry = () => ({ version: 1, entries: {} });
-async function loadRegistry(file, warn) {
-  const parsed = await readJsonFile(file, null, warn);
-  if (!parsed || parsed.version !== 1 || !parsed.entries) {
-    if (parsed) warn?.(`autoi18n: ${file} has an unsupported format; message IDs will be regenerated.`);
-    return emptyRegistry();
-  }
-  return parsed;
-}
-function orderKey(file, start) {
-  return `${file}:${String(start).padStart(12, "0")}`;
-}
-function locationKey(location) {
-  const split = location.lastIndexOf(":");
-  return orderKey(location.slice(0, split), Number(location.slice(split + 1)));
-}
-function reconcile(registry, messages) {
-  const now = (/* @__PURE__ */ new Date()).toISOString();
-  const oldEntries = Object.values(registry.entries);
-  const groups = /* @__PURE__ */ new Map();
-  for (const entry of oldEntries) {
-    const list = groups.get(entry.fingerprint) ?? [];
-    list.push(entry);
-    groups.set(entry.fingerprint, list);
-  }
-  const incoming = /* @__PURE__ */ new Map();
-  for (const message of messages) {
-    const list = incoming.get(message.fingerprint) ?? [];
-    list.push(message);
-    incoming.set(message.fingerprint, list);
-  }
-  const seen = /* @__PURE__ */ new Set();
-  const ambiguous = [];
-  for (const [fingerprint, current] of incoming) {
-    const previous = (groups.get(fingerprint) ?? []).filter((x) => x.status === "active");
-    current.sort((a, b) => orderKey(a.file, a.start).localeCompare(orderKey(b.file, b.start)));
-    previous.sort((a, b) => locationKey(a.location).localeCompare(locationKey(b.location)));
-    if (current.length !== previous.length && (current.length > 1 || previous.length > 1)) {
-      ambiguous.push(current[0].source);
-    }
-    for (let i = 0; i < current.length; i++) {
-      const message = current[i];
-      const candidate = previous[i];
-      if (candidate) {
-        message.id = candidate.id;
-        candidate.status = "active";
-        candidate.lastSeen = now;
-        candidate.source = message.source;
-        candidate.location = `${message.file}:${message.start}`;
-        seen.add(candidate.id);
-      } else {
-        const id = `msg_${randomUUID2().replaceAll("-", "").slice(0, 16)}`;
-        message.id = id;
-        registry.entries[id] = {
-          id,
-          source: message.source,
-          kind: message.kind,
-          tag: message.tag,
-          component: message.component,
-          attribute: message.attribute,
-          context: message.context,
-          fingerprint: message.fingerprint,
-          location: `${message.file}:${message.start}`,
-          status: "active",
-          firstSeen: now,
-          lastSeen: now
-        };
-        seen.add(id);
-      }
-    }
-  }
-  for (const entry of Object.values(registry.entries)) if (!seen.has(entry.id)) entry.status = "orphaned";
-  return { registry, ambiguous };
-}
-var DAY_MS = 24 * 60 * 60 * 1e3;
-var DEFAULT_ORPHAN_RETENTION_DAYS = 30;
-function pruneOrphans(registry, retentionDays, now = Date.now()) {
-  const cutoff = now - retentionDays * DAY_MS;
-  const removed = [];
-  for (const [id, entry] of Object.entries(registry.entries)) {
-    if (entry.status === "orphaned" && Date.parse(entry.lastSeen) <= cutoff) {
-      delete registry.entries[id];
-      removed.push(entry);
-    }
-  }
-  return removed;
-}
-async function saveRegistry(file, registry) {
-  await writeFileAtomic(file, JSON.stringify(registry, null, 2) + "\n");
-}
-
-export {
-  debugLog,
-  readJsonFile,
-  writeFileAtomic,
-  loadRegistry,
-  reconcile,
-  DEFAULT_ORPHAN_RETENTION_DAYS,
-  pruneOrphans,
-  saveRegistry
-};

package/dist/chunk-RVYJXXTU.js

@@ -1,15 +0,0 @@
-// src/runtime/resolve.ts
-function resolveLocale(preferred, supported, fallback = "en") {
-  for (const candidate of preferred) {
-    const exact = supported.find((x) => x.toLowerCase() === candidate.toLowerCase());
-    if (exact) return exact;
-    const base = candidate.split("-")[0].toLowerCase();
-    const language = supported.find((x) => x.split("-")[0].toLowerCase() === base);
-    if (language) return language;
-  }
-  return fallback;
-}
-
-export {
-  resolveLocale
-};