vite-plugin-ai-auto-i18n 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,213 @@
-# Temporary Holding Version
+# 🌍 vite-plugin-autoi18n — MVP sketch 🚀
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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
+
+- 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.
+- Persists opaque message IDs in `.autoi18n/registry.json`.
+- Marks disappeared messages as orphaned and deletes them after a retention period (default 30 days, see `orphanRetentionMinutes`).
+- 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 the `sources` map of `.autoi18n/locales/<locale>.json`.
+- Includes a deliberately varied document-dashboard example.
+
+## 📦 Installation
+
+### 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 { 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>
+```
+
+### 🧪 Try the bundled example
+
+A React document dashboard under `example/`:
+
+```sh
+npm install
+npm run example:dev     # dev server
+npm run example:build   # production build into example/dist
+```
+
+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.
+
+`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.
+
+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 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.
+
+🙈 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: "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:
+
+```ts
+import { locales, resolveSupported, setLocale, getLocale, subscribe, t } from "virtual:autoi18n";
+
+setLocale(resolveSupported(navigator.languages)); // call before first render
+```
+
+`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.
+
+## ⚙️ 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:
+
+1. Runtime delivery loads a catalogue per locale; a message's source text is used until its catalogue has loaded.
+2. Mixed JSX sentences with simple expressions (`You have {count} documents`, where `count` is an identifier or member path) are translated as one message with named `{name}` placeholders; translations that change the placeholders are rejected. Sentences with complex expressions (calls, JSX, computed access) are left entirely in the source language. ICU plural generation is not implemented yet.
+3. Duplicate identical occurrences are paired by stable source ordering. This handles ordinary line shifts, but cannot guarantee identity if indistinguishable duplicates are reordered or moved independently. Such cases are reported through `onAmbiguous`; they are not resolved automatically.
+4. Dev-server HMR re-indexes the whole project after saved or added/removed source files (debounced by 150 ms) rather than only the changed module. This is simple and correct, but may be slow in very large projects.
+5. Only JSX text, and the attributes `alt`, `title`, `placeholder`, `label`, `summary`, `aria-label`, `aria-description`, `aria-placeholder`, `aria-roledescription` and `aria-valuetext` on intrinsic (lowercase) elements, are extracted. Text inside capitalised components (for example `<Button>Save</Button>`) and other attributes such as `href` are not extracted. JS string literals, template literals, Markdown, server-rendered content and rich-text components need explicit policies.
+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
+
+- IDs are opaque and persistent; never expose semantic fingerprints as runtime keys.
+- AI suggestions never silently overwrite an existing translation.
+- Source English is always a valid fallback.
+- Ambiguous identity matches should be surfaced, not guessed.
+- Translation happens outside the render path.

package/dist/chunk-LLL7ZSKW.js

@@ -0,0 +1,169 @@
+// src/debug.ts
+var debugLog = (message) => console.log(`[autoi18n debug] ${(/* @__PURE__ */ new Date()).toISOString()} ${message}`);
+
+// src/io.ts
+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 {
+    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/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: {} });
+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 assigned = /* @__PURE__ */ new Map();
+  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) {
+        assigned.set(message, 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)}`;
+        assigned.set(message, 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";
+  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;
+function pruneOrphans(registry, retentionMinutes, now = Date.now()) {
+  const cutoff = now - retentionMinutes * MINUTE_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, toJson(registry));
+}
+
+export {
+  debugLog,
+  hashContent,
+  emptyLocaleFile,
+  localeFilePath,
+  readLocaleFile,
+  writeLocaleFile,
+  pruneCatalog,
+  loadRegistry,
+  reconcile,
+  DEFAULT_ORPHAN_RETENTION_MINUTES,
+  pruneOrphans,
+  saveRegistry
+};

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

@@ -0,0 +1,74 @@
+import {
+  DEFAULT_ORPHAN_RETENTION_MINUTES,
+  debugLog,
+  loadRegistry,
+  pruneCatalog,
+  pruneOrphans,
+  readLocaleFile,
+  saveRegistry,
+  writeLocaleFile
+} from "../chunk-LLL7ZSKW.js";
+
+// src/cli/prune.ts
+import { existsSync } from "fs";
+import { readdir } from "fs/promises";
+import path from "path";
+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 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;
+    await writeLocaleFile(file, { messages: messages.catalog, sources: sources.catalog });
+    results.push({ file, removed });
+  }
+  return results;
+}
+function parseArgs(argv) {
+  const args = { directory: ".autoi18n", retentionMinutes: DEFAULT_ORPHAN_RETENTION_MINUTES, debug: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--debug") {
+      args.debug = true;
+    } else if (arg === "--directory" || arg === "--retention-minutes") {
+      const value = argv[++i];
+      if (value === void 0) throw new Error(`${arg} needs a value`);
+      if (arg === "--directory") args.directory = value;
+      else args.retentionMinutes = Number(value);
+    } else {
+      throw new Error(`Unknown option ${arg}`);
+    }
+  }
+  if (!(args.retentionMinutes >= 0)) throw new Error("--retention-minutes must be a number of minutes, 0 or more");
+  return args;
+}
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const registryFile = path.resolve(process.cwd(), args.directory, "registry.json");
+  if (!existsSync(registryFile)) {
+    console.log(`autoi18n: no registry found at ${registryFile}; nothing to prune.`);
+    return;
+  }
+  const registry = await loadRegistry(registryFile, (message) => console.warn(message));
+  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 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) {
+      for (const id of ids) debugLog(`removed ${id} from ${file}`);
+    }
+  }
+  console.log(`autoi18n: removed ${removed.length} registry entries orphaned for more than ${args.retentionMinutes} minutes.`);
+  if (catalogs.length) console.log(`autoi18n: removed stale keys from ${catalogs.length} locale files.`);
+}
+main().catch((error) => {
+  console.error(`autoi18n: ${error.message}`);
+  process.exitCode = 1;
+});

package/dist/index.js

@@ -0,0 +1,743 @@
+import {
+  DEFAULT_ORPHAN_RETENTION_MINUTES,
+  debugLog,
+  emptyLocaleFile,
+  hashContent,
+  loadRegistry,
+  localeFilePath,
+  pruneCatalog,
+  pruneOrphans,
+  readLocaleFile,
+  reconcile,
+  saveRegistry,
+  writeLocaleFile
+} from "./chunk-LLL7ZSKW.js";
+import {
+  createLocaleLoader,
+  resolveLocale
+} from "./chunk-ZDZ3YVET.js";
+
+// src/index.ts
+import fg from "fast-glob";
+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";
+import * as t from "@babel/types";
+
+// src/identity/fingerprint.ts
+import { createHash } from "crypto";
+function normalizeSource(value) {
+  return value.replace(/\s+/g, " ").trim();
+}
+function createFingerprint(message) {
+  const material = [normalizeSource(message.source), message.kind, message.tag.toLowerCase(), message.attribute ?? "", message.context].join("");
+  return createHash("sha256").update(material).digest("hex").slice(0, 24);
+}
+
+// src/compiler/extract.ts
+var traverse = traverseModule.default ?? traverseModule;
+var COMPONENT_TAG = /^[A-Z]/;
+var IGNORED_TAGS = /* @__PURE__ */ new Set(["script", "style", "code", "pre"]);
+var TRANSLATABLE_ATTRS = /* @__PURE__ */ new Set(["alt", "title", "placeholder", "label", "summary", "aria-label", "aria-description", "aria-placeholder", "aria-roledescription", "aria-valuetext"]);
+var IGNORE_ATTR = "translate";
+var IGNORE_VALUE = "no";
+function hasIgnoreMarker(opening) {
+  return opening.attributes.some((a) => t.isJSXAttribute(a) && t.isJSXIdentifier(a.name, { name: IGNORE_ATTR }) && t.isStringLiteral(a.value, { value: IGNORE_VALUE }));
+}
+function isExtractableTag(name) {
+  return t.isJSXIdentifier(name) && !COMPONENT_TAG.test(name.name) && !IGNORED_TAGS.has(name.name);
+}
+function placeholderExpressionName(expression) {
+  if (t.isIdentifier(expression)) return expression.name;
+  if (t.isMemberExpression(expression) && !expression.computed && t.isIdentifier(expression.property)) {
+    const object = placeholderExpressionName(expression.object);
+    return object ? `${object}.${expression.property.name}` : void 0;
+  }
+  return void 0;
+}
+function extractMessages(code, filename) {
+  const ast = parse(code, { sourceType: "unambiguous", sourceFilename: filename, plugins: ["jsx", "typescript", "decorators-legacy"] });
+  const found = [];
+  function componentName(nodePath) {
+    const fn = nodePath.findParent((p) => p.isFunctionDeclaration() || p.isFunctionExpression() || p.isArrowFunctionExpression());
+    if (!fn) return "<module>";
+    const parent = fn.parentPath;
+    if (parent?.isVariableDeclarator() && t.isIdentifier(parent.node.id)) return parent.node.id.name;
+    if (fn.isFunctionDeclaration() && fn.node.id) return fn.node.id.name;
+    return "<anonymous>";
+  }
+  function elementContext(elementNode, tag, attr) {
+    const openingElement = t.isJSXElement(elementNode) ? elementNode.openingElement : elementNode;
+    const attrs = openingElement.attributes.filter((a) => t.isJSXAttribute(a) && t.isJSXIdentifier(a.name) && ["aria-label", "title", "name", "type", "role"].includes(a.name.name)).map((a) => `${a.name.name}=${t.isStringLiteral(a.value) ? a.value.value : "{expr}"}`).sort().join(";");
+    const handlers = openingElement.attributes.filter((a) => t.isJSXAttribute(a) && t.isJSXIdentifier(a.name) && /^on[A-Z]/.test(a.name.name)).map((a) => {
+      const expression = t.isJSXExpressionContainer(a.value) ? a.value.expression : null;
+      const semanticHandler = expression && t.isIdentifier(expression) ? expression.name : expression?.type ?? "handler";
+      return `${a.name.name}=${semanticHandler}`;
+    }).sort().join(",");
+    return [tag, attr ?? "", attrs, handlers].filter(Boolean).join(" | ");
+  }
+  function isMarkedUntranslated(nodePath) {
+    for (let p = nodePath; p; p = p.parentPath) {
+      const opening = p.isJSXOpeningElement() ? p.node : p.isJSXElement() ? p.node.openingElement : void 0;
+      if (opening && hasIgnoreMarker(opening)) return true;
+    }
+    return false;
+  }
+  traverse(ast, {
+    JSXElement(p) {
+      if (isMarkedUntranslated(p)) return;
+      const children = p.node.children;
+      const expressions = children.filter((child) => t.isJSXExpressionContainer(child));
+      if (!expressions.length) return;
+      if (children.some((child) => !t.isJSXText(child) && !t.isJSXExpressionContainer(child))) return;
+      if (!expressions.every((child) => placeholderExpressionName(child.expression) !== void 0)) return;
+      if (!children.some((child) => t.isJSXText(child) && /[A-Za-z]/.test(child.value))) return;
+      const rawTag = p.node.openingElement.name;
+      if (!isExtractableTag(rawTag)) return;
+      const names = [];
+      for (const child of expressions) {
+        const base = placeholderExpressionName(child.expression);
+        let name = base;
+        for (let suffix = 2; names.includes(name); suffix++) name = `${base}_${suffix}`;
+        names.push(name);
+      }
+      let raw = "";
+      let index = 0;
+      for (const child of children) raw += t.isJSXText(child) ? child.value : `{${names[index++]}}`;
+      const source = normalizeSource(raw);
+      if (!source) return;
+      const tag = rawTag.name;
+      const item = {
+        source,
+        prefix: raw.match(/^\s*/)?.[0] ?? "",
+        suffix: raw.match(/\s*$/)?.[0] ?? "",
+        kind: "mixed",
+        placeholders: names,
+        file: filename,
+        start: p.node.start ?? 0,
+        end: p.node.end ?? 0,
+        tag,
+        component: componentName(p),
+        context: elementContext(p.node, tag),
+        fingerprint: ""
+      };
+      item.fingerprint = createFingerprint(item);
+      found.push(item);
+    },
+    JSXText(p) {
+      if (isMarkedUntranslated(p)) return;
+      const raw = p.node.value;
+      const source = normalizeSource(raw);
+      if (!source) return;
+      const element = p.findParent((x) => x.isJSXElement());
+      if (!element?.isJSXElement()) return;
+      if (element.node.children.some((child) => t.isJSXExpressionContainer(child))) return;
+      const rawTag = element.node.openingElement.name;
+      if (!isExtractableTag(rawTag)) return;
+      const tag = rawTag.name;
+      const component = componentName(element);
+      const context = elementContext(element.node, tag);
+      const prefix = raw.match(/^\s*/)?.[0] ?? "";
+      const suffix = raw.match(/\s*$/)?.[0] ?? "";
+      const item = { source, prefix, suffix, kind: "text", file: filename, start: p.node.start ?? 0, end: p.node.end ?? 0, tag, component, context, fingerprint: "" };
+      item.fingerprint = createFingerprint(item);
+      found.push(item);
+    },
+    JSXAttribute(p) {
+      const attr = p.node;
+      if (!t.isJSXIdentifier(attr.name) || !TRANSLATABLE_ATTRS.has(attr.name.name)) return;
+      if (isMarkedUntranslated(p)) return;
+      if (!t.isStringLiteral(attr.value)) return;
+      const source = normalizeSource(attr.value.value);
+      if (!source || !/[A-Za-z]/.test(source)) return;
+      const element = p.parentPath;
+      if (!element.isJSXOpeningElement() || !isExtractableTag(element.node.name)) return;
+      const tag = element.node.name.name;
+      const parentElement = p.findParent((x) => x.isJSXElement());
+      if (!parentElement?.isJSXElement()) return;
+      const component = componentName(parentElement);
+      const context = elementContext(parentElement.node, tag, attr.name.name);
+      const item = { source, kind: "attribute", file: filename, start: attr.value.start ?? 0, end: attr.value.end ?? 0, tag, component, attribute: attr.name.name, context, fingerprint: "" };
+      item.fingerprint = createFingerprint(item);
+      found.push(item);
+    }
+  });
+  return found.sort((a, b) => a.start - b.start);
+}
+
+// src/compiler/transform.ts
+import { parse as parse2 } from "@babel/parser";
+import traverseModule2 from "@babel/traverse";
+import generateModule from "@babel/generator";
+import * as t2 from "@babel/types";
+var traverse2 = traverseModule2.default ?? traverseModule2;
+var generate = generateModule.default ?? generateModule;
+var RUNTIME_MODULE = "virtual:autoi18n";
+var RUNTIME_LOOKUP = "__autoI18nT";
+var RUNTIME_FORMAT = "__autoI18nFormat";
+function transformSource(code, filename, messages, locale, catalog, runtime = false, sourceLocale = "en") {
+  const ast = parse2(code, { sourceType: "unambiguous", sourceFilename: filename, plugins: ["jsx", "typescript", "decorators-legacy"] });
+  const byStart = new Map(messages.map((m) => [m.start, m]));
+  let usesRuntime = false;
+  let usesFormat = false;
+  const lookup = (message) => {
+    if (runtime) {
+      usesRuntime = true;
+      return t2.callExpression(t2.identifier(RUNTIME_LOOKUP), [t2.stringLiteral(message.id), t2.stringLiteral(message.source)]);
+    }
+    return t2.stringLiteral(locale === sourceLocale ? message.source : catalog[message.id] ?? message.source);
+  };
+  traverse2(ast, {
+    JSXElement(p) {
+      const message = byStart.get(p.node.start ?? -1);
+      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 ?? "";
+      const suffix = message.suffix ?? "";
+      if (runtime) {
+        usesFormat = true;
+        const values = t2.objectExpression(names.map((name, i) => t2.objectProperty(t2.stringLiteral(name), t2.cloneNode(expressions[i]))));
+        const text2 = [prefix && t2.stringLiteral(prefix), lookup(message), suffix && t2.stringLiteral(suffix)].filter(Boolean);
+        const joined = text2.reduce((left, right) => t2.binaryExpression("+", left, right));
+        p.node.children = [t2.jsxExpressionContainer(t2.callExpression(t2.identifier(RUNTIME_FORMAT), [joined, values]))];
+        return;
+      }
+      const translated = locale === sourceLocale ? message.source : catalog[message.id] ?? message.source;
+      const text = isUsableTranslation(translated, names) ? translated : message.source;
+      const children = [];
+      let last = 0;
+      const pushText = (value) => {
+        if (value) children.push(t2.jsxExpressionContainer(t2.stringLiteral(value)));
+      };
+      pushText(prefix);
+      for (const match of text.matchAll(PLACEHOLDER)) {
+        pushText(text.slice(last, match.index));
+        children.push(t2.jsxExpressionContainer(t2.cloneNode(expressions[names.indexOf(match[1])])));
+        last = match.index + match[0].length;
+      }
+      pushText(text.slice(last) + suffix);
+      p.node.children = children;
+    },
+    JSXText(p) {
+      const message = byStart.get(p.node.start ?? -1);
+      if (!message) return;
+      const parts = [];
+      if (runtime) {
+        if (message.prefix) parts.push(t2.stringLiteral(message.prefix));
+        parts.push(lookup(message));
+        if (message.suffix) parts.push(t2.stringLiteral(message.suffix));
+      } else {
+        const translated = lookup(message).value;
+        parts.push(t2.stringLiteral(`${message.prefix ?? ""}${translated}${message.suffix ?? ""}`));
+      }
+      const expression = parts.reduce((left, right) => t2.binaryExpression("+", left, right));
+      p.replaceWith(t2.jsxExpressionContainer(expression));
+    },
+    JSXAttribute(p) {
+      const valueNode = p.node.value;
+      if (!t2.isStringLiteral(valueNode)) return;
+      const message = byStart.get(valueNode.start ?? -1);
+      if (!message) return;
+      p.node.value = runtime ? t2.jsxExpressionContainer(lookup(message)) : lookup(message);
+    }
+  });
+  const runtimeSpecifiers = [
+    ...usesRuntime ? [t2.importSpecifier(t2.identifier(RUNTIME_LOOKUP), t2.identifier("t"))] : [],
+    ...usesFormat ? [t2.importSpecifier(t2.identifier(RUNTIME_FORMAT), t2.identifier("format"))] : []
+  ];
+  if (runtimeSpecifiers.length) {
+    ast.program.body.unshift(t2.importDeclaration(runtimeSpecifiers, t2.stringLiteral(RUNTIME_MODULE)));
+  }
+  const result = generate(ast, { sourceMaps: true, sourceFileName: filename }, code);
+  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)}).then(m => (m.default ?? m).messages)`).join(",\n");
+  return [
+    `const loaders = {
+${loaders}
+};`,
+    `const sourceLocale = ${JSON.stringify(sourceLocale)};`,
+    `const resolveLocale = ${resolveLocale.toString()};`,
+    `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 = {};`,
+    `let version = 0;`,
+    `let latestRequest = 0;`,
+    `export const locales = Object.keys(loaders);`,
+    `export function getLocale() { return currentLocale; }`,
+    `export function getVersion() { return version; }`,
+    `export function resolveSupported(preferred) { return resolveLocale(preferred, locales, sourceLocale); }`,
+    `export async function setLocale(locale) {`,
+    `  const request = ++latestRequest;`,
+    `  let selected = loaders[locale] ? locale : sourceLocale;`,
+    `  let catalog;`,
+    `  try {`,
+    `    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 loadLocale(selected);`,
+    `  }`,
+    `  // A slower earlier request must not overwrite the locale the user picked last.`,
+    `  if (request !== latestRequest) return;`,
+    `  messages = catalog;`,
+    `  currentLocale = selected;`,
+    `  notify();`,
+    `}`,
+    `function notify() {`,
+    `  version++;`,
+    `  listeners.forEach(fn => fn(currentLocale));`,
+    `}`,
+    `export function subscribe(fn) { listeners.add(fn); return () => { listeners.delete(fn); }; }`,
+    `export function t(id, source) { return messages[id] ?? source; }`,
+    `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)) loadLocale.prime(locale, catalog);`,
+    `    if (data.catalogs[currentLocale]) messages = data.catalogs[currentLocale];`,
+    `    notify();`,
+    `  });`,
+    `}`
+  ].join("\n") + "\n";
+}
+
+// src/ai/provider.ts
+var ProviderError = class extends Error {
+  constructor(message, retryable) {
+    super(message);
+    this.retryable = retryable;
+  }
+  retryable;
+};
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var OpenAICompatibleProvider = class {
+  constructor(options) {
+    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 = {};
+    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;
+    const retryDelayMs = this.options.retryDelayMs ?? 500;
+    for (let attempt = 0; ; attempt++) {
+      try {
+        return await this.request(input);
+      } catch (error) {
+        const retryable = !(error instanceof ProviderError) || error.retryable;
+        if (!retryable || attempt >= maxRetries) throw error;
+        await sleep(retryDelayMs * 2 ** attempt);
+      }
+    }
+  }
+  async request(input) {
+    const response = await fetch(`${this.options.baseURL ?? "https://api.openai.com/v1"}/chat/completions`, {
+      method: "POST",
+      signal: AbortSignal.timeout(this.options.timeoutMs ?? 6e4),
+      headers: { Authorization: `Bearer ${this.options.apiKey}`, "Content-Type": "application/json" },
+      body: JSON.stringify({
+        model: this.options.model,
+        temperature: 0,
+        response_format: { type: "json_object" },
+        messages: [
+          { role: "system", content: `You are a professional software localization engine. Translate UI messages from ${input.sourceLocale} to ${input.targetLocale}. Preserve placeholders exactly. Respect context and UI conventions. Return ONLY a JSON object mapping message IDs to translated strings. Do not translate product names or code.` },
+          { role: "user", content: JSON.stringify(input.messages.map((m) => ({ id: m.id, text: m.source, context: m.context, kind: m.kind }))) }
+        ]
+      })
+    });
+    if (!response.ok) {
+      const retryable = response.status === 408 || response.status === 409 || response.status === 429 || response.status >= 500;
+      throw new ProviderError(`Translation API failed (${response.status}): ${await response.text()}`, retryable);
+    }
+    const json = await response.json();
+    const content = json.choices?.[0]?.message?.content;
+    if (typeof content !== "string" || !content) throw new ProviderError("Translation provider returned no content", true);
+    let parsed;
+    try {
+      parsed = JSON.parse(content);
+    } catch {
+      throw new ProviderError("Translation provider returned invalid JSON", true);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new ProviderError("Translation provider returned a non-object", true);
+    const requested = new Set(input.messages.map((m) => m.id));
+    const result = {};
+    for (const [id, text] of Object.entries(parsed)) {
+      if (requested.has(id) && typeof text === "string" && text.trim()) result[id] = text;
+    }
+    return result;
+  }
+};
+
+// src/index.ts
+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 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";
+  const delivery = options.delivery ?? "build";
+  const debug = options.debug ?? false;
+  const orphanRetentionMinutes = options.orphanRetentionMinutes ?? DEFAULT_ORPHAN_RETENTION_MINUTES;
+  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();
+  const warnedFiles = /* @__PURE__ */ new Set();
+  let server;
+  let queue = Promise.resolve();
+  let watchTimer;
+  const selectedLocale = () => options.locale ?? process.env.AUTOI18N_LOCALE ?? sourceLocale;
+  function localesToTranslate() {
+    const others = options.locales.filter((x) => x !== sourceLocale);
+    const explicit = options.locale ?? process.env.AUTOI18N_LOCALE;
+    if (delivery === "build" && explicit && config.command !== "serve") return others.filter((x) => x === explicit);
+    return others;
+  }
+  async function sync(report) {
+    const files = await fg(options.include ?? DEFAULT_INCLUDE, { cwd: config.root, ignore: options.exclude ?? DEFAULT_EXCLUDE, absolute: true });
+    const nextExtractions = /* @__PURE__ */ new Map();
+    const indexed = [];
+    for (const file of files) {
+      const code = await readFile(file, "utf8");
+      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 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);
+    }
+    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 (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: ${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.`);
+      }
+    }
+    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));
+    queue = next.catch(() => void 0);
+    return next;
+  }
+  function pushCatalogs() {
+    server?.ws.send({ type: "custom", event: UPDATE_EVENT, data: { catalogs: Object.fromEntries(catalogs) } });
+  }
+  async function retranslate() {
+    try {
+      await runSync(reporterFor(config.logger));
+      pushCatalogs();
+    } catch (error) {
+      config.logger.error(`autoi18n: re-translation failed: ${error.message}`);
+    }
+  }
+  function scheduleRetranslate() {
+    clearTimeout(watchTimer);
+    watchTimer = setTimeout(() => void retranslate(), WATCH_DEBOUNCE_MS);
+  }
+  function isSourceCandidate(file) {
+    if (!/\.[jt]sx?$/.test(file)) return false;
+    const relative = path.relative(config.root, file).split(path.sep).join("/");
+    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",
+    enforce: "pre",
+    configResolved(resolved) {
+      config = resolved;
+      registryFile = path.resolve(config.root, directory, "registry.json");
+      const selected = selectedLocale();
+      if (selected !== sourceLocale && !options.locales.includes(selected)) {
+        throw new Error(`autoi18n: locale "${selected}" is not one of the configured locales (${options.locales.join(", ")}).`);
+      }
+    },
+    resolveId(id) {
+      if (id === RUNTIME_MODULE) return `\0${RUNTIME_MODULE}`;
+    },
+    load(id) {
+      if (id === `\0${RUNTIME_MODULE}`) return createRuntimeModule(catalogFiles, sourceLocale);
+    },
+    configureServer(devServer) {
+      server = devServer;
+      devServer.watcher.on("add", (file) => {
+        if (isSourceCandidate(file)) scheduleRetranslate();
+      });
+      devServer.watcher.on("unlink", (file) => {
+        if (fileMessages.has(file)) scheduleRetranslate();
+      });
+    },
+    closeBundle() {
+      clearTimeout(watchTimer);
+    },
+    async buildStart() {
+      await sync({ info: (m) => this.info(m), warn: (m) => this.warn(m), error: (m) => this.error(m) });
+    },
+    async transform(code, id) {
+      const file = id.split("?")[0];
+      if (!fileMessages.has(file)) return null;
+      if (hashContent(code) !== fileHashes.get(file)) {
+        await runSync(reporterFor(config.logger));
+      }
+      const messages = fileMessages.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.`);
+        }
+        return null;
+      }
+      const locale = config.command === "serve" ? sourceLocale : selectedLocale();
+      const result = transformSource(code, file, messages, locale, catalogs.get(locale) ?? {}, delivery === "runtime", sourceLocale);
+      return { code: result.code, map: result.map };
+    },
+    async handleHotUpdate({ file }) {
+      if (file.startsWith(path.resolve(config.root, directory, "locales") + path.sep)) return [];
+      if (!fileMessages.has(file)) return;
+      await retranslate();
+    }
+  };
+}
+export {
+  OpenAICompatibleProvider,
+  PartialTranslationError,
+  autoI18n as default
+};

package/dist/runtime/index.js

@@ -0,0 +1,8 @@
+import {
+  createLocaleLoader,
+  resolveLocale
+} from "../chunk-ZDZ3YVET.js";
+export {
+  createLocaleLoader,
+  resolveLocale
+};

package/package.json

@@ -1,6 +1,56 @@
 {
-  "name": "vite-plugin-ai-auto-i18n",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "vite-plugin-ai-auto-i18n",
+    "version": "0.2.0",
+    "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": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        },
+        "./runtime": {
+            "types": "./dist/runtime/index.d.ts",
+            "import": "./dist/runtime/index.js"
+        }
+    },
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "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",
+        "preview": "vite build example && vite preview example --port 4173 --strictPort",
+        "test": "vitest run",
+        "typecheck": "tsc --noEmit"
+    },
+    "peerDependencies": {
+        "vite": ">=5"
+    },
+    "dependencies": {
+        "@babel/generator": "^7.26.0",
+        "@babel/parser": "^7.26.0",
+        "@babel/traverse": "^7.26.0",
+        "@babel/types": "^7.26.0",
+        "fast-glob": "^3.3.2"
+    },
+    "devDependencies": {
+        "@types/babel__generator": "^7.6.8",
+        "@types/babel__traverse": "^7.20.6",
+        "@types/node": "^22.10.0",
+        "@vitejs/plugin-react": "^4.3.4",
+        "react": "^19.3.1",
+        "react-dom": "^19.3.1",
+        "tsup": "^8.3.5",
+        "typescript": "^5.7.2",
+        "vite": "^6.0.0",
+        "vitest": "^2.1.8"
+    }
+}