vite-plugin-ai-auto-i18n 0.2.2 → 0.3.0

package/README.md

@@ -5,6 +5,7 @@ Implicit build-time localization for JSX: author English directly, let the compi
 ## 🧩 Current MVP scope
 
 - Extracts JSX text nodes and static string JSX attributes.
+- Extracts string literals outside JSX only when they are marked with a leading `/* i18n */` comment.
 - 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`).
@@ -104,6 +105,8 @@ Messages removed from the source are kept as orphans in `registry.json` so their
 
 🙈 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 translate copy outside JSX, put a `/* i18n */` block comment directly before the string literal, for example `const items = [{ label: /* i18n */ "Shared with your team" }];`. Marked strings are translated in both build and runtime delivery. Unmarked string literals are never extracted.
+
 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
@@ -175,7 +178,7 @@ 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
+  kind: "text" | "attribute" | "mixed" | "string"; // text node, static attribute, JSX with expressions, or a /* i18n */-marked string literal
   placeholders?: string[]; // {name} placeholders that must survive translation
 }
 ```
@@ -192,6 +195,23 @@ Return only the IDs you translated. Omitted IDs stay in the source language and
 
 The `prune` CLI options (`--directory`, `--retention-minutes`, `--debug`) are described in the orphan paragraph of [Try the bundled example](#-try-the-bundled-example).
 
+## 🧪 Test coverage
+
+Run the suite with coverage (V8 provider, `src/**`):
+
+```bash
+npx vitest run --coverage --coverage.include='src/**' --coverage.reporter=text
+```
+
+| Metric | Coverage |
+|---|---|
+| Statements | 99.4% |
+| Branches | 89.4% |
+| Functions | 97.6% |
+| Lines | 99.4% |
+
+Critical modules such as the plugin hooks (`src/index.ts`), translation pipeline (`src/translate.ts`), build engine (`src/engine.ts`), runtime helpers (`src/runtime/`), and prune CLI (`src/cli/prune.ts`) are all at or above 98% statements.
+
 ## ⚠️ Important prototype limitations
 
 This is a compiler MVP, not production-ready localization yet:
@@ -200,7 +220,7 @@ This is a compiler MVP, not production-ready localization yet:
 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.
+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 automatically. String literals outside JSX are extracted only when marked with `/* i18n */`. Text inside capitalised components (for example `<Button>Save</Button>`) and other attributes such as `href` are not extracted. Unmarked 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.
 

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { Plugin } from 'vite';
 
-type MessageKind = "text" | "attribute" | "mixed";
+type MessageKind = "text" | "attribute" | "mixed" | "string";
 interface ExtractedMessage {
     source: string;
     prefix?: string;

package/dist/index.js

@@ -168,6 +168,7 @@ 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 STRING_MARKER = "i18n";
 var IGNORE_ATTR = "translate";
 var IGNORE_VALUE = "no";
 function hasIgnoreMarker(opening) {
@@ -289,6 +290,15 @@ function extractMessages(code, filename) {
       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);
+    },
+    StringLiteral(p) {
+      if (p.parentPath.isJSXAttribute()) return;
+      if (!p.node.leadingComments?.some((c) => c.type === "CommentBlock" && c.value.trim() === STRING_MARKER)) return;
+      const source = normalizeSource(p.node.value);
+      if (!source || !/[A-Za-z]/.test(source)) return;
+      const item = { source, kind: "string", file: filename, start: p.node.start ?? 0, end: p.node.end ?? 0, tag: "", component: componentName(p), context: "", fingerprint: "" };
+      item.fingerprint = createFingerprint(item);
+      found.push(item);
     }
   });
   return found.sort((a, b) => a.start - b.start);
@@ -369,6 +379,11 @@ function transformSource(code, filename, messages, locale, catalog, runtime = fa
       const message = byStart.get(valueNode.start ?? -1);
       if (!message) return;
       p.node.value = runtime ? t2.jsxExpressionContainer(lookup(message)) : lookup(message);
+    },
+    StringLiteral(p) {
+      const message = byStart.get(p.node.start ?? -1);
+      if (message?.kind !== "string") return;
+      p.replaceWith(lookup(message));
     }
   });
   const runtimeSpecifiers = [

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "vite-plugin-ai-auto-i18n",
-    "version": "0.2.2",
+    "version": "0.3.0",
     "type": "module",
     "description": "Implicit, build-time AI localization for JSX applications",
     "engines": {
@@ -46,6 +46,7 @@
         "@types/babel__traverse": "^7.20.6",
         "@types/node": "^22.10.0",
         "@vitejs/plugin-react": "^4.3.4",
+        "@vitest/coverage-v8": "^2.1.9",
         "react": "^19.3.1",
         "react-dom": "^19.3.1",
         "tsup": "^8.3.5",