@pulsetechnologies/i18n 0.1.0 → 0.2.1

package/README.md

@@ -7,7 +7,7 @@ The shared language layer for every Pulse product (PulseWork epic **ENG-1**, thi
 - **Matching**: `matchLocale` maps real-world tags to the languages we offer: `zh-TW` → `zh-Hant`, `pt-PT` → `pt-BR`, `es-MX` → `es`, `tl` → `fil`.
 - **Formatting**: `createFormatters(locale, { timeZone })` covers numbers, percent, `money(minor, currency)` for Pulse's minor-unit amounts, dates, times, relative times and lists. Haitian Creole borrows French formats because CLDR has no data for it.
 - **i18next**: `createI18n({ resources, locale })` sets up English fallback, no catalog bleed between `zh-Hans` and `zh-Hant`, React-safe interpolation, and an optional `en-XA` pseudo-locale for catching text that was never extracted.
-- **Catalog check**: `missingKeys(en, target, locale)` is plural-aware per language. Arabic needs six plural forms, Japanese one, and Spanish needs `_many`. Without it, Spanish users see English for counts in the millions. ENG-4 runs it in CI.
+- **Catalog check**: `missingKeys(en, target, locale)` is plural-aware per language. Arabic needs six plural forms, Japanese one, and Spanish needs `_many`. Without it, Spanish users see English for counts in the millions. The `pulse-i18n check` command below runs it in CI.
 - **React**: `<LanguagePicker persist={saveToProfile} />` is an accessible native `<select>` that shows each language in its own script. It keeps `<html lang dir>` in step, writes the cookie and calls `persist` (the ENG-3 profile save). `<LanguageSelect>` and `useLanguage()` are the lower-level pieces.
 
 ```tsx
@@ -30,6 +30,46 @@ npm test          # vitest (the picker tests use jsdom)
 npm run demo      # http://localhost:5480, a sample invoice in 5 languages + pseudo
 ```
 
+## Translating a product: the `pulse-i18n` CLI (ENG-4)
+
+Each product keeps its English catalogs at `<dir>/en/<namespace>.json` and commits the other languages next to them. Add a `pulse-i18n.config.json` at the product's root:
+
+```json
+{
+  "dir": "src/locales",
+  "locales": ["es", "fr", "zh-Hans"],
+  "glossary": ["PulseVoice", "PiP", "Pulse"],
+  "review": ["legal.", "billing:", "e911."],
+  "context": "PulseVoice is a business phone system for companies and their staff."
+}
+```
+
+- `locales` is the set of languages the product ships. Leave it out to ship all 18.
+- `glossary` lists terms that are never translated, and checks that they come back unchanged.
+- `review` lists key prefixes (`"ns:key"` or `"key"`) whose translations a person must sign off: legal, invoice and 911 text.
+
+Commands:
+
+| Command | What it does |
+|---|---|
+| `npx pulse-i18n check` | **The CI gate.** Exits 1 when, for any language, a string is missing, a translation was made from English that has since changed, a key no longer exists in English, or a `{{placeholder}}`, `$t()` or `<0>` tag, or a glossary term, was dropped or invented. Plural forms are checked per language: Arabic needs 6, Japanese 1, and Spanish, French and Portuguese need `_many`. Pending reviews show as warnings. |
+| `npx pulse-i18n translate [--locale es,fr] [--batch 60]` | Fills exactly what `check` flags, using Claude Opus 5.5 (structured JSON output, `fallbacks: "default"`, a cached prompt prefix). It validates every answer, retries once naming the problem, and reports anything still wrong without writing it. Needs `ANTHROPIC_API_KEY` (or `ant auth login`) and `npm i -D @anthropic-ai/sdk`. |
+| `npx pulse-i18n approve <locale> [prefix]` | Marks reviewed translations as approved. |
+
+`translate` keeps `<dir>/.pulse-i18n-lock.json` (commit it). It records the English each translation was made from, so:
+
+- when English changes, that string is re-translated;
+- a translation someone **edited by hand** is never overwritten;
+- translations that existed before the tool are adopted as they are.
+
+A hand edit that breaks a placeholder is redone, because it would fail at runtime.
+
+Product CI:
+
+```yaml
+- run: npx pulse-i18n check
+```
+
 ## Release
 
 The package is published publicly to npm as `@pulsetechnologies/i18n`. To release:

package/dist/tools/catalogs.d.ts

@@ -0,0 +1,19 @@
+export type Flat = Map<string, string>;
+/** Namespaces English has: the files that every other language is checked against. */
+export declare function namespacesOf(dir: string): string[];
+export declare function readCatalog(dir: string, locale: string, ns: string): Flat;
+/** Flat "a.b.c" keys back to nested JSON, in the order given. */
+export declare function unflatten(entries: Iterable<[string, string]>): Record<string, unknown>;
+export declare function writeCatalog(dir: string, locale: string, ns: string, entries: Iterable<[string, string]>): void;
+/** Short, stable fingerprint of an English string: what a translation was made from. */
+export declare const fingerprint: (s: string) => string;
+export interface LockEntry {
+    src: string;
+    review?: true;
+}
+export interface Lock {
+    version: 1;
+    locales: Record<string, Record<string, LockEntry>>;
+}
+export declare function readLock(dir: string): Lock;
+export declare function writeLock(dir: string, lock: Lock): void;

package/dist/tools/catalogs.js

@@ -0,0 +1,71 @@
+// Reading and writing a product's catalogs on disk, for the pulse-i18n CLI (ENG-4).
+//
+// Layout: <dir>/<locale>/<namespace>.json, nested JSON of strings, English (en) the source.
+//   src/locales/en/common.json      { "nav": { "home": "Home" }, "items_one": "{{count}} item" }
+//   src/locales/es/common.json
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { flattenCatalog } from "../catalog.js";
+import { SOURCE_LOCALE } from "../locales.js";
+/** Namespaces English has: the files that every other language is checked against. */
+export function namespacesOf(dir) {
+    const en = join(dir, SOURCE_LOCALE);
+    if (!existsSync(en))
+        throw new Error(`no English catalogs at ${en}`);
+    return readdirSync(en).filter((f) => f.endsWith(".json")).map((f) => f.slice(0, -5)).sort();
+}
+export function readCatalog(dir, locale, ns) {
+    const file = join(dir, locale, `${ns}.json`);
+    if (!existsSync(file))
+        return new Map();
+    let json;
+    try {
+        json = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch (e) {
+        throw new Error(`${file} is not valid JSON: ${e.message}`);
+    }
+    return flattenCatalog(json);
+}
+/** Flat "a.b.c" keys back to nested JSON, in the order given. */
+export function unflatten(entries) {
+    const out = {};
+    for (const [key, value] of entries) {
+        const parts = key.split(".");
+        let node = out;
+        for (const p of parts.slice(0, -1)) {
+            const next = node[p];
+            if (typeof next === "string")
+                throw new Error(`key "${key}" collides with the string at "${p}"`);
+            node = (node[p] ??= {});
+        }
+        node[parts.at(-1)] = value;
+    }
+    return out;
+}
+export function writeCatalog(dir, locale, ns, entries) {
+    mkdirSync(join(dir, locale), { recursive: true });
+    writeFileSync(join(dir, locale, `${ns}.json`), JSON.stringify(unflatten(entries), null, 2) + "\n");
+}
+/** Short, stable fingerprint of an English string: what a translation was made from. */
+export const fingerprint = (s) => createHash("sha256").update(s).digest("hex").slice(0, 16);
+const LOCK_FILE = ".pulse-i18n-lock.json";
+export function readLock(dir) {
+    const file = join(dir, LOCK_FILE);
+    if (!existsSync(file))
+        return { version: 1, locales: {} };
+    const lock = JSON.parse(readFileSync(file, "utf8"));
+    if (lock.version !== 1)
+        throw new Error(`${file}: unsupported lock version ${String(lock.version)}`);
+    return lock;
+}
+export function writeLock(dir, lock) {
+    // Sorted, so the file diffs cleanly in review.
+    const locales = Object.fromEntries(Object.keys(lock.locales).sort().map((l) => [
+        l,
+        Object.fromEntries(Object.keys(lock.locales[l]).sort().map((k) => [k, lock.locales[l][k]])),
+    ]));
+    writeFileSync(join(dir, LOCK_FILE), JSON.stringify({ version: 1, locales }, null, 2) + "\n");
+}
+//# sourceMappingURL=catalogs.js.map

package/dist/tools/catalogs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalogs.js","sourceRoot":"","sources":["../../src/tools/catalogs.ts"],"names":[],"mappings":"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"}

package/dist/tools/claude.d.ts

@@ -0,0 +1,6 @@
+import type { Translator } from "./pipeline.js";
+export declare const MODEL = "claude-opus-5-5";
+export declare function systemPrompt(glossary: string[], context?: string): string;
+export declare function claudeTranslator(opts?: {
+    apiKey?: string;
+}): Promise<Translator>;

package/dist/tools/claude.js

@@ -0,0 +1,70 @@
+export const MODEL = "claude-opus-5-5";
+const INSTRUCTIONS = `You translate the user-interface text of business software from English into another language.
+
+Each item has an "id", the "english" text, and sometimes a "note". Return one translation per item, with the same id.
+
+Rules:
+- Translate the meaning for someone using the product, the way a well-localized professional product reads in that language. Keep it as short as the English; these are buttons, labels, menus, messages and emails.
+- Use the register business software uses in that language (for example, formal "Sie" in German, "vous" in French).
+- Copy these exactly as they appear, untranslated: anything in {{double braces}}, $t(...) references, and tags like <0>, </0>, <b>, <br/>. Move them within the sentence if the grammar needs it.
+- Leave the glossary terms exactly as written, in Latin script, even in languages with another script.
+- A note about a plural form tells you which plural category the text is for; write that form naturally for the language.
+- If a note says your previous answer was rejected, fix exactly what it names.
+- Never add explanations, quotes or extra text to a translation.`;
+const SCHEMA = {
+    type: "object",
+    properties: {
+        translations: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: { id: { type: "string" }, text: { type: "string" } },
+                required: ["id", "text"],
+                additionalProperties: false,
+            },
+        },
+    },
+    required: ["translations"],
+    additionalProperties: false,
+};
+export function systemPrompt(glossary, context) {
+    return [
+        INSTRUCTIONS,
+        context ? `About the product: ${context}` : "",
+        glossary.length ? `Glossary (never translate): ${glossary.join(", ")}` : "",
+    ].filter(Boolean).join("\n\n");
+}
+export async function claudeTranslator(opts = {}) {
+    let Anthropic;
+    try {
+        Anthropic = (await import("@anthropic-ai/sdk")).default;
+    }
+    catch {
+        throw new Error("pulse-i18n translate needs @anthropic-ai/sdk: npm i -D @anthropic-ai/sdk");
+    }
+    const client = new Anthropic(opts.apiKey ? { apiKey: opts.apiKey } : {});
+    return async (req) => {
+        const stream = client.beta.messages.stream({
+            model: MODEL,
+            max_tokens: 64000,
+            betas: ["server-side-fallback-2026-07-01"],
+            fallbacks: "default",
+            cache_control: { type: "ephemeral" },
+            output_config: { effort: "medium", format: { type: "json_schema", schema: SCHEMA } },
+            system: systemPrompt(req.glossary, req.context),
+            messages: [{
+                    role: "user",
+                    content: `Translate into ${req.language} (${req.locale}).\n\n${JSON.stringify(req.items, null, 1)}`,
+                }],
+        });
+        const msg = await stream.finalMessage();
+        if (msg.stop_reason === "refusal")
+            throw new Error(`the model declined to translate this batch into ${req.locale}`);
+        if (msg.stop_reason === "max_tokens")
+            throw new Error(`the answer for ${req.locale} was cut off; use a smaller --batch`);
+        const text = msg.content.flatMap((b) => (b.type === "text" ? [b.text] : [])).join("");
+        const parsed = JSON.parse(text);
+        return new Map(parsed.translations.map((t) => [t.id, t.text]));
+    };
+}
+//# sourceMappingURL=claude.js.map

package/dist/tools/claude.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude.js","sourceRoot":"","sources":["../../src/tools/claude.ts"],"names":[],"mappings":"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"}

package/dist/tools/cli.d.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { type NamespaceReport, type PipelineConfig } from "./pipeline.js";
+export declare function loadConfig(path: string): PipelineConfig;
+export declare function formatReport(reports: NamespaceReport[]): string[];
+export declare function main(argv: string[]): Promise<number>;

package/dist/tools/cli.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+// pulse-i18n: check and translate a product's catalogs (ENG-4).
+//
+//   pulse-i18n check                 CI gate; exits 1 when anything is missing, outdated or broken
+//   pulse-i18n translate [--locale es,fr] [--batch 60]
+//                                    fill what check flags, with Claude (needs ANTHROPIC_API_KEY)
+//   pulse-i18n approve <locale> [prefix]
+//                                    mark translations a person has reviewed
+//
+// Settings come from pulse-i18n.config.json in the working directory (or --config <file>):
+//   { "dir": "src/locales", "locales": ["es", "fr"], "glossary": ["PulseVoice"],
+//     "review": ["legal:", "billing."], "context": "PulseVoice is a business phone system." }
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { isLocaleCode } from "../locales.js";
+import { claudeTranslator } from "./claude.js";
+import { approve, check, translate } from "./pipeline.js";
+function flag(args, name) {
+    const i = args.indexOf(`--${name}`);
+    return i >= 0 ? args[i + 1] : undefined;
+}
+export function loadConfig(path) {
+    const raw = JSON.parse(readFileSync(path, "utf8"));
+    if (!raw.dir)
+        throw new Error(`${path}: "dir" is required`);
+    for (const l of raw.locales ?? [])
+        if (!isLocaleCode(l))
+            throw new Error(`${path}: "${l}" is not a language Pulse offers`);
+    return { ...raw, dir: resolve(dirname(path), raw.dir) };
+}
+export function formatReport(reports) {
+    const lines = [];
+    for (const r of reports) {
+        const where = `${r.locale}/${r.ns}`;
+        const list = (label, keys) => {
+            if (keys.length)
+                lines.push(`${where}: ${keys.length} ${label}: ${keys.slice(0, 8).join(", ")}${keys.length > 8 ? ", …" : ""}`);
+        };
+        list("missing", r.missing);
+        list("outdated (English changed)", r.outdated);
+        list("no longer in English", r.stale);
+        for (const b of r.broken)
+            lines.push(`${where}: ${b.key}: ${b.problems.join("; ")}`);
+        if (r.pendingReview.length)
+            lines.push(`${where}: ${r.pendingReview.length} awaiting review (warning)`);
+    }
+    return lines;
+}
+export async function main(argv) {
+    const [cmd, ...args] = argv;
+    const cfg = loadConfig(resolve(flag(args, "config") ?? "pulse-i18n.config.json"));
+    if (cmd === "check") {
+        const { ok, reports } = check(cfg);
+        for (const line of formatReport(reports))
+            console.log(line);
+        console.log(ok ? "pulse-i18n: all translations complete" : "pulse-i18n: translations need work (run pulse-i18n translate)");
+        return ok ? 0 : 1;
+    }
+    if (cmd === "translate") {
+        const only = flag(args, "locale")?.split(",").map((s) => s.trim());
+        for (const l of only ?? [])
+            if (!isLocaleCode(l))
+                throw new Error(`"${l}" is not a language Pulse offers`);
+        const batch = Number(flag(args, "batch") ?? 60);
+        const r = await translate(cfg, await claudeTranslator(), { batchSize: batch, only: only, log: (l) => console.log(l) });
+        console.log(`translated ${r.translated}, adopted ${r.adopted} existing, removed ${r.removed} stale, ${r.flaggedForReview} flagged for review`);
+        for (const f of r.failed)
+            console.error(`FAILED ${f.locale}/${f.ns} ${f.key}: ${f.problems.join("; ")}`);
+        return r.failed.length ? 1 : 0;
+    }
+    if (cmd === "approve") {
+        const [locale, prefix] = args.filter((a) => !a.startsWith("--") && a !== flag(args, "config"));
+        if (!isLocaleCode(locale))
+            throw new Error("usage: pulse-i18n approve <locale> [prefix]");
+        console.log(`approved ${approve(cfg, locale, prefix ?? "")} in ${locale}`);
+        return 0;
+    }
+    console.error("usage: pulse-i18n check | translate [--locale es,fr] [--batch 60] | approve <locale> [prefix]  [--config file]");
+    return 2;
+}
+// Run when executed directly (the bin), not when imported by tests.
+if (process.argv[1] && /cli\.(js|ts)$/.test(process.argv[1])) {
+    main(process.argv.slice(2)).then((code) => process.exit(code), (e) => {
+        const hint = /authentication method/i.test(e.message) ? " (set ANTHROPIC_API_KEY, or sign in with `ant auth login`)" : "";
+        console.error(`pulse-i18n: ${e.message}${hint}`);
+        process.exit(2);
+    });
+}
+//# sourceMappingURL=cli.js.map

package/dist/tools/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/tools/cli.ts"],"names":[],"mappings":"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"}

package/dist/tools/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./catalogs.js";
+export * from "./placeholders.js";
+export * from "./pipeline.js";
+export { claudeTranslator, systemPrompt, MODEL } from "./claude.js";

package/dist/tools/index.js

@@ -0,0 +1,5 @@
+export * from "./catalogs.js";
+export * from "./placeholders.js";
+export * from "./pipeline.js";
+export { claudeTranslator, systemPrompt, MODEL } from "./claude.js";
+//# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC"}

package/dist/tools/pipeline.d.ts

@@ -0,0 +1,77 @@
+import { type LocaleCode } from "../locales.js";
+import { type Flat } from "./catalogs.js";
+export interface PipelineConfig {
+    /** Directory holding <locale>/<namespace>.json. */
+    dir: string;
+    /** Languages this product ships; defaults to every language Pulse offers. */
+    locales?: LocaleCode[];
+    /** Terms never translated: product names and the like ("PulseVoice", "PiP"). */
+    glossary?: string[];
+    /** Keys needing a person's review once translated: prefixes of "ns:key" or of the key. */
+    review?: string[];
+    /** A sentence or two about the product, so word choices fit it. */
+    context?: string;
+}
+/** One target key and the English it's translated from. */
+interface Slot {
+    key: string;
+    english: string;
+    plural: boolean;
+}
+/** Every key a language needs for one namespace, in English's order, with its English source. */
+export declare function slotsFor(en: Flat, locale: string): Slot[];
+export declare const needsReview: (cfg: PipelineConfig, ns: string, key: string) => boolean;
+/** Glossary terms the English uses that the translation lost. */
+export declare function glossaryProblems(english: string, translation: string, glossary?: string[]): string[];
+export interface NamespaceReport {
+    locale: LocaleCode;
+    ns: string;
+    missing: string[];
+    outdated: string[];
+    stale: string[];
+    broken: {
+        key: string;
+        problems: string[];
+    }[];
+    pendingReview: string[];
+}
+export declare const targetLocales: (cfg: PipelineConfig) => LocaleCode[];
+/** The CI gate. `ok` is false when anything but pending reviews is found. */
+export declare function check(cfg: PipelineConfig): {
+    ok: boolean;
+    reports: NamespaceReport[];
+};
+export interface TranslateItem {
+    id: string;
+    english: string;
+    note?: string;
+}
+export interface TranslateRequest {
+    locale: LocaleCode;
+    language: string;
+    items: TranslateItem[];
+    glossary: string[];
+    context?: string;
+}
+/** Turns English items into the target language, keyed by item id. */
+export type Translator = (req: TranslateRequest) => Promise<Map<string, string>>;
+export interface TranslateResult {
+    translated: number;
+    adopted: number;
+    removed: number;
+    failed: {
+        locale: LocaleCode;
+        ns: string;
+        key: string;
+        problems: string[];
+    }[];
+    flaggedForReview: number;
+}
+export declare function translate(cfg: PipelineConfig, translator: Translator, opts?: {
+    batchSize?: number;
+    only?: LocaleCode[];
+    log?: (line: string) => void;
+}): Promise<TranslateResult>;
+/** Mark translations as reviewed by a person: every pending one in a locale, or those matching a prefix. */
+export declare function approve(cfg: PipelineConfig, locale: LocaleCode, prefix?: string): number;
+export {};

package/dist/tools/pipeline.js

@@ -0,0 +1,190 @@
+// The translation pipeline behind `pulse-i18n check` and `pulse-i18n translate` (ENG-4).
+//
+// check     : the CI gate. Per language and namespace: strings still missing, translations made
+//             from an English string that has since changed, keys English no longer has, broken
+//             placeholders, and (as a warning) translations still awaiting a person's review.
+// translate : fills exactly what check would flag (missing or outdated), through a Translator
+//             (Claude in production, a fake in tests), validates every answer, and records what
+//             each translation was made from in the lock file. Hand edits are never overwritten.
+import { pluralCategoriesOf } from "../catalog.js";
+import { LOCALE_CODES, localeInfo, SOURCE_LOCALE } from "../locales.js";
+import { fingerprint, namespacesOf, readCatalog, readLock, writeCatalog, writeLock } from "./catalogs.js";
+import { placeholderProblems } from "./placeholders.js";
+const PLURAL = /_(zero|one|two|few|many|other)$/;
+/** Every key a language needs for one namespace, in English's order, with its English source. */
+export function slotsFor(en, locale) {
+    const cats = pluralCategoriesOf(locale);
+    const out = [];
+    const seen = new Set();
+    for (const key of en.keys()) {
+        const m = PLURAL.exec(key);
+        if (!m) {
+            out.push({ key, english: en.get(key), plural: false });
+            continue;
+        }
+        const base = key.slice(0, m.index);
+        if (seen.has(base))
+            continue;
+        seen.add(base);
+        for (const cat of cats) {
+            // A form English has (one, other, an optional zero) is its own source; the rest read from other.
+            const english = en.get(`${base}_${cat}`) ?? en.get(`${base}_other`) ?? en.get(key);
+            out.push({ key: `${base}_${cat}`, english, plural: true });
+        }
+    }
+    return out;
+}
+const isOptionalZero = (key, en) => key.endsWith("_zero") && [...en.keys()].some((k) => k.startsWith(key.slice(0, -5) + "_"));
+export const needsReview = (cfg, ns, key) => (cfg.review ?? []).some((p) => `${ns}:${key}`.startsWith(p) || key.startsWith(p));
+/** Glossary terms the English uses that the translation lost. */
+export function glossaryProblems(english, translation, glossary = []) {
+    return glossary.filter((t) => english.includes(t) && !translation.includes(t)).map((t) => `"${t}" must stay as is`);
+}
+export const targetLocales = (cfg) => (cfg.locales ?? LOCALE_CODES).filter((l) => l !== SOURCE_LOCALE);
+function inspect(cfg, lock, locale, ns, en) {
+    const tgt = readCatalog(cfg.dir, locale, ns);
+    const entries = lock.locales[locale] ?? {};
+    const slots = slotsFor(en, locale);
+    const report = { locale, ns, missing: [], outdated: [], stale: [], broken: [], pendingReview: [] };
+    for (const s of slots) {
+        const text = tgt.get(s.key);
+        const entry = entries[`${ns}:${s.key}`];
+        if (!text?.trim()) {
+            report.missing.push(s.key);
+            continue;
+        }
+        if (entry && entry.src !== fingerprint(s.english))
+            report.outdated.push(s.key);
+        const problems = [...placeholderProblems(s.english, text, { plural: s.plural }), ...glossaryProblems(s.english, text, cfg.glossary)];
+        if (problems.length)
+            report.broken.push({ key: s.key, problems });
+        if (entry?.review)
+            report.pendingReview.push(s.key);
+    }
+    const wanted = new Set(slots.map((s) => s.key));
+    for (const key of tgt.keys())
+        if (!wanted.has(key) && !isOptionalZero(key, en))
+            report.stale.push(key);
+    return { report, slots, tgt };
+}
+/** The CI gate. `ok` is false when anything but pending reviews is found. */
+export function check(cfg) {
+    const lock = readLock(cfg.dir);
+    const reports = [];
+    for (const ns of namespacesOf(cfg.dir)) {
+        const en = readCatalog(cfg.dir, SOURCE_LOCALE, ns);
+        for (const locale of targetLocales(cfg))
+            reports.push(inspect(cfg, lock, locale, ns, en).report);
+    }
+    const ok = reports.every((r) => !r.missing.length && !r.outdated.length && !r.stale.length && !r.broken.length);
+    return { ok, reports };
+}
+const chunk = (xs, n) => Array.from({ length: Math.ceil(xs.length / n) }, (_, i) => xs.slice(i * n, i * n + n));
+export async function translate(cfg, translator, opts = {}) {
+    const lock = readLock(cfg.dir);
+    const log = opts.log ?? (() => { });
+    const result = { translated: 0, adopted: 0, removed: 0, failed: [], flaggedForReview: 0 };
+    const locales = targetLocales(cfg).filter((l) => !opts.only || opts.only.includes(l));
+    for (const ns of namespacesOf(cfg.dir)) {
+        const en = readCatalog(cfg.dir, SOURCE_LOCALE, ns);
+        for (const locale of locales) {
+            const { report, slots, tgt } = inspect(cfg, lock, locale, ns, en);
+            const entries = (lock.locales[locale] ??= {});
+            // Broken placeholders fail at runtime whoever wrote them, so those are redone too.
+            const todo = new Set([...report.missing, ...report.outdated, ...report.broken.map((b) => b.key)]);
+            const bySlot = new Map(slots.map((s) => [s.key, s]));
+            const fresh = new Map();
+            const run = async (keys, hint) => {
+                for (const batch of chunk(keys, opts.batchSize ?? 60)) {
+                    const items = batch.map((key) => {
+                        const s = bySlot.get(key);
+                        const notes = [];
+                        if (s.plural)
+                            notes.push(`plural form "${key.replace(/^.*_/, "")}": used when the count falls in that ${localeInfo(locale).english} plural category`);
+                        if (hint?.get(key))
+                            notes.push(`your previous answer was rejected: ${hint.get(key).join("; ")}`);
+                        return { id: key, english: s.english, ...(notes.length ? { note: notes.join(". ") } : {}) };
+                    });
+                    const out = await translator({ locale, language: localeInfo(locale).english, items, glossary: cfg.glossary ?? [], context: cfg.context });
+                    for (const key of batch) {
+                        const text = out.get(key);
+                        if (text !== undefined)
+                            fresh.set(key, text);
+                    }
+                }
+            };
+            const problemsOf = (key) => {
+                const s = bySlot.get(key);
+                const text = fresh.get(key);
+                if (!text?.trim())
+                    return ["no translation returned"];
+                return [...placeholderProblems(s.english, text, { plural: s.plural }), ...glossaryProblems(s.english, text, cfg.glossary)];
+            };
+            if (todo.size) {
+                log(`${locale}/${ns}: translating ${todo.size}`);
+                await run([...todo]);
+                // One retry for anything that came back wrong, telling the model what was wrong.
+                const bad = new Map([...todo].map((k) => [k, problemsOf(k)]).filter(([, p]) => p.length));
+                if (bad.size) {
+                    for (const k of bad.keys())
+                        fresh.delete(k);
+                    await run([...bad.keys()], bad);
+                }
+            }
+            const next = [];
+            for (const s of slots) {
+                const lockKey = `${ns}:${s.key}`;
+                if (todo.has(s.key)) {
+                    const problems = problemsOf(s.key);
+                    if (problems.length) {
+                        result.failed.push({ locale, ns, key: s.key, problems });
+                        // Keep an outdated translation rather than nothing; its lock entry still says outdated.
+                        const old = tgt.get(s.key);
+                        if (old?.trim())
+                            next.push([s.key, old]);
+                        continue;
+                    }
+                    next.push([s.key, fresh.get(s.key)]);
+                    const review = needsReview(cfg, ns, s.key);
+                    entries[lockKey] = { src: fingerprint(s.english), ...(review ? { review: true } : {}) };
+                    result.translated++;
+                    if (review)
+                        result.flaggedForReview++;
+                }
+                else {
+                    next.push([s.key, tgt.get(s.key)]);
+                    // A translation nobody recorded (written by hand, or before this tool) is adopted as is.
+                    if (!entries[lockKey]) {
+                        entries[lockKey] = { src: fingerprint(s.english) };
+                        result.adopted++;
+                    }
+                }
+            }
+            // Optional "_zero" forms a translator added by hand are kept.
+            for (const key of tgt.keys())
+                if (!bySlot.has(key) && isOptionalZero(key, en))
+                    next.push([key, tgt.get(key)]);
+            result.removed += report.stale.length;
+            for (const key of report.stale)
+                delete entries[`${ns}:${key}`];
+            if (todo.size || report.stale.length)
+                writeCatalog(cfg.dir, locale, ns, next);
+            writeLock(cfg.dir, lock);
+        }
+    }
+    return result;
+}
+/** Mark translations as reviewed by a person: every pending one in a locale, or those matching a prefix. */
+export function approve(cfg, locale, prefix = "") {
+    const lock = readLock(cfg.dir);
+    let n = 0;
+    for (const [k, e] of Object.entries(lock.locales[locale] ?? {})) {
+        if (e.review && (k.startsWith(prefix) || k.split(":")[1].startsWith(prefix))) {
+            delete e.review;
+            n++;
+        }
+    }
+    writeLock(cfg.dir, lock);
+    return n;
+}
+//# sourceMappingURL=pipeline.js.map

package/dist/tools/pipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.js","sourceRoot":"","sources":["../../src/tools/pipeline.ts"],"names":[],"mappings":"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"}

package/dist/tools/placeholders.d.ts

@@ -0,0 +1,10 @@
+/** Each token as a comparable string, with how many times it appears. */
+export declare function placeholdersOf(text: string): Map<string, number>;
+/**
+ * What's wrong with a translation's placeholders, compared with its English source, or [] when
+ * nothing is. A plural form may leave out {{count}} ("one item" rather than "1 item"); everything
+ * else must appear exactly as often as in English.
+ */
+export declare function placeholderProblems(source: string, translation: string, opts?: {
+    plural?: boolean;
+}): string[];

package/dist/tools/placeholders.js

@@ -0,0 +1,36 @@
+// The parts of a string a translation must carry over untouched: i18next interpolations
+// ({{name}}, {{count, number}}), nesting ($t(other.key)) and the numbered or named tags <Trans>
+// renders (<0>…</0>, <b>…</b>, <br/>). A translation that drops or invents one breaks at runtime.
+const TOKEN = /\{\{\s*([^}\s,]+)[^}]*\}\}|\$t\(([^)]*)\)|<\/?([a-zA-Z0-9]+)\s*\/?>/g;
+/** Each token as a comparable string, with how many times it appears. */
+export function placeholdersOf(text) {
+    const out = new Map();
+    for (const m of text.matchAll(TOKEN)) {
+        const id = m[1] !== undefined ? `{{${m[1]}}}` : m[2] !== undefined ? `$t(${m[2].trim()})` : `<${m[0].startsWith("</") ? "/" : ""}${m[3]}>`;
+        out.set(id, (out.get(id) ?? 0) + 1);
+    }
+    return out;
+}
+/**
+ * What's wrong with a translation's placeholders, compared with its English source, or [] when
+ * nothing is. A plural form may leave out {{count}} ("one item" rather than "1 item"); everything
+ * else must appear exactly as often as in English.
+ */
+export function placeholderProblems(source, translation, opts = {}) {
+    const want = placeholdersOf(source);
+    const got = placeholdersOf(translation);
+    const problems = [];
+    for (const [id, n] of want) {
+        const have = got.get(id) ?? 0;
+        if (have === n)
+            continue;
+        if (opts.plural && id === "{{count}}" && have <= n)
+            continue;
+        problems.push(have === 0 ? `missing ${id}` : `${id} appears ${have}× (English has ${n})`);
+    }
+    for (const id of got.keys())
+        if (!want.has(id))
+            problems.push(`unexpected ${id}`);
+    return problems;
+}
+//# sourceMappingURL=placeholders.js.map

package/dist/tools/placeholders.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"placeholders.js","sourceRoot":"","sources":["../../src/tools/placeholders.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,gGAAgG;AAChG,kGAAkG;AAElG,MAAM,KAAK,GAAG,sEAAsE,CAAC;AAErF,yEAAyE;AACzE,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,MAAM,GAAG,GAAG,IAAI,GAAG,EAAkB,CAAC;IACtC,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACrC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;QAC3I,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACtC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAc,EAAE,WAAmB,EAAE,OAA6B,EAAE;IACtG,MAAM,IAAI,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;IACpC,MAAM,GAAG,GAAG,cAAc,CAAC,WAAW,CAAC,CAAC;IACxC,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,KAAK,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;QAC9B,IAAI,IAAI,KAAK,CAAC;YAAE,SAAS;QACzB,IAAI,IAAI,CAAC,MAAM,IAAI,EAAE,KAAK,WAAW,IAAI,IAAI,IAAI,CAAC;YAAE,SAAS;QAC7D,QAAQ,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,YAAY,IAAI,kBAAkB,CAAC,GAAG,CAAC,CAAC;IAC5F,CAAC;IACD,KAAK,MAAM,EAAE,IAAI,GAAG,CAAC,IAAI,EAAE;QAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YAAE,QAAQ,CAAC,IAAI,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC;IAClF,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pulsetechnologies/i18n",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Shared language list, detection, formatting and language picker for every Pulse product.",
   "type": "module",
   "license": "UNLICENSED",
@@ -26,6 +26,10 @@
     "./react": {
       "types": "./dist/react/index.d.ts",
       "import": "./dist/react/index.js"
+    },
+    "./tools": {
+      "types": "./dist/tools/index.d.ts",
+      "import": "./dist/tools/index.js"
     }
   },
   "files": [
@@ -44,7 +48,8 @@
   "peerDependencies": {
     "i18next": ">=25",
     "react": ">=18",
-    "react-i18next": ">=15"
+    "react-i18next": ">=15",
+    "@anthropic-ai/sdk": ">=0.131"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -52,10 +57,15 @@
     },
     "react-i18next": {
       "optional": true
+    },
+    "@anthropic-ai/sdk": {
+      "optional": true
     }
   },
   "devDependencies": {
+    "@anthropic-ai/sdk": "^0.131.0",
     "@testing-library/react": "^16.3.3",
+    "@types/node": "^24.19.0",
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
     "@vitejs/plugin-react": "^6.1.1",
@@ -67,5 +77,8 @@
     "typescript": "^5.9.3",
     "vite": "^8.3.1",
     "vitest": "^5.0.3"
+  },
+  "bin": {
+    "pulse-i18n": "dist/tools/cli.js"
   }
 }