ext-localize 0.0.0-stage → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,123 @@
1
+ import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from "node:fs";
2
+ import { dirname, join } from "node:path";
3
+ /** Read and strictly parse a messages.json. Chrome drops a locale whose file does not parse. */
4
+ export function readMessagesFile(path) {
5
+ let text;
6
+ try {
7
+ text = readFileSync(path, "utf8");
8
+ }
9
+ catch (e) {
10
+ return { ok: false, error: `cannot read file: ${e.message}` };
11
+ }
12
+ const hadBom = text.charCodeAt(0) === 0xfeff;
13
+ if (hadBom)
14
+ text = text.slice(1);
15
+ try {
16
+ const data = JSON.parse(text);
17
+ if (data === null || typeof data !== "object" || Array.isArray(data)) {
18
+ return { ok: false, error: "top level must be a JSON object" };
19
+ }
20
+ return { ok: true, data: data, hadBom };
21
+ }
22
+ catch (e) {
23
+ return { ok: false, error: `invalid JSON: ${e.message}` };
24
+ }
25
+ }
26
+ /** Write JSON atomically (temp file + rename), 2-space indent, trailing newline. */
27
+ export function writeJsonAtomic(path, data) {
28
+ mkdirSync(dirname(path), { recursive: true });
29
+ const tmp = `${path}.tmp-${process.pid}`;
30
+ writeFileSync(tmp, JSON.stringify(data, null, 2) + "\n", "utf8");
31
+ renameSync(tmp, path);
32
+ }
33
+ /**
34
+ * Remove // and /* *\/ comments outside of strings. Chrome accepts comments in
35
+ * manifest.json, so a strict JSON.parse would fail on some real manifests.
36
+ */
37
+ export function stripJsonComments(text) {
38
+ let out = "";
39
+ let inString = false;
40
+ for (let i = 0; i < text.length; i++) {
41
+ const c = text[i];
42
+ const next = text[i + 1];
43
+ if (inString) {
44
+ out += c;
45
+ if (c === "\\") {
46
+ out += next ?? "";
47
+ i++;
48
+ }
49
+ else if (c === '"')
50
+ inString = false;
51
+ continue;
52
+ }
53
+ if (c === '"') {
54
+ inString = true;
55
+ out += c;
56
+ }
57
+ else if (c === "/" && next === "/") {
58
+ while (i < text.length && text[i] !== "\n")
59
+ i++;
60
+ out += "\n";
61
+ }
62
+ else if (c === "/" && next === "*") {
63
+ i += 2;
64
+ while (i < text.length && !(text[i] === "*" && text[i + 1] === "/"))
65
+ i++;
66
+ i++;
67
+ }
68
+ else
69
+ out += c;
70
+ }
71
+ return out;
72
+ }
73
+ export class ProjectError extends Error {
74
+ }
75
+ export function messagesPath(localesDir, locale) {
76
+ return join(localesDir, locale, "messages.json");
77
+ }
78
+ /** Locale folder names that exist under _locales/ (any name, valid or not). */
79
+ export function listLocaleDirs(localesDir) {
80
+ if (!existsSync(localesDir))
81
+ return [];
82
+ return readdirSync(localesDir)
83
+ .filter((name) => !name.startsWith(".") && statSync(join(localesDir, name)).isDirectory())
84
+ .sort();
85
+ }
86
+ /**
87
+ * Read manifest.json and the default locale's messages.json.
88
+ * Throws ProjectError with a short, fixable message on any problem.
89
+ */
90
+ export function loadProject(root) {
91
+ const manifestPath = join(root, "manifest.json");
92
+ if (!existsSync(manifestPath))
93
+ throw new ProjectError(`No manifest.json in ${root}. Use --dir to point at the extension folder.`);
94
+ let manifest;
95
+ try {
96
+ let raw = readFileSync(manifestPath, "utf8");
97
+ if (raw.charCodeAt(0) === 0xfeff)
98
+ raw = raw.slice(1);
99
+ manifest = JSON.parse(stripJsonComments(raw));
100
+ }
101
+ catch (e) {
102
+ throw new ProjectError(`manifest.json does not parse: ${e.message}`);
103
+ }
104
+ const localesDir = join(root, "_locales");
105
+ const defaultLocale = manifest["default_locale"];
106
+ if (typeof defaultLocale !== "string" || !defaultLocale) {
107
+ throw new ProjectError(existsSync(localesDir)
108
+ ? `manifest.json has no "default_locale", but _locales/ exists. Chrome will refuse to load the extension.`
109
+ : `manifest.json has no "default_locale". Add it (for example "en") and create _locales/en/messages.json.`);
110
+ }
111
+ const sourcePath = messagesPath(localesDir, defaultLocale);
112
+ const read = readMessagesFile(sourcePath);
113
+ if (!read.ok)
114
+ throw new ProjectError(`Source file _locales/${defaultLocale}/messages.json: ${read.error}`);
115
+ const source = {};
116
+ for (const [key, value] of Object.entries(read.data)) {
117
+ if (!value || typeof value !== "object" || typeof value.message !== "string") {
118
+ throw new ProjectError(`Source key "${key}" has no "message" string.`);
119
+ }
120
+ source[key] = value;
121
+ }
122
+ return { root, manifestPath, manifest, defaultLocale, localesDir, sourcePath, source };
123
+ }
package/dist/paths.js ADDED
@@ -0,0 +1,30 @@
1
+ import { isAbsolute, join, relative, resolve, sep } from "node:path";
2
+ /**
3
+ * Where ext-localize keeps its own files (config.json, state.json, glossary.json, out/).
4
+ * Default: <extension folder>/.localizer. With --config <file>, it is the folder of
5
+ * that file, so build tools that wipe the extension folder (WXT, Plasmo) do not
6
+ * delete the state. Kept per extension root, set once by the CLI.
7
+ */
8
+ const overrides = new Map();
9
+ export function setLocalizerDir(root, dir) {
10
+ overrides.set(resolve(root), resolve(dir));
11
+ }
12
+ export function clearLocalizerDir(root) {
13
+ overrides.delete(resolve(root));
14
+ }
15
+ export function localizerDir(root) {
16
+ return overrides.get(resolve(root)) ?? join(root, ".localizer");
17
+ }
18
+ /**
19
+ * Folder that relative paths inside config.json are resolved from: the folder
20
+ * that holds the .localizer folder. For the default layout that is the extension folder.
21
+ */
22
+ export function configBase(root) {
23
+ return resolve(localizerDir(root), "..");
24
+ }
25
+ /** A path relative to the extension folder, with "/" separators (for reports and JSON). */
26
+ export function relPath(root, path) {
27
+ const r = relative(resolve(root), resolve(path));
28
+ return (r === "" ? "." : r).split(sep).join("/");
29
+ }
30
+ export { isAbsolute };
@@ -0,0 +1,171 @@
1
+ /**
2
+ * Chrome message format tokens and how we protect them during translation.
3
+ *
4
+ * Chrome rules (https://developer.chrome.com/docs/extensions/mv3/i18n-messages):
5
+ * $$ -> a literal "$"
6
+ * $name$ -> a named placeholder, defined in the "placeholders" block.
7
+ * Names are case-insensitive and use A-Z a-z 0-9 _ @
8
+ * $1 .. $9 -> positional substitutions passed to chrome.i18n.getMessage()
9
+ *
10
+ * We scan left to right and try "$$" first, so "$$1" is a literal "$" then "1".
11
+ */
12
+ const TOKEN_RE = /\$\$|\$([A-Za-z0-9_@]+)\$|\$([1-9])|\$/g;
13
+ /** Split a message into plain text and format tokens. */
14
+ export function tokenize(message) {
15
+ const out = [];
16
+ let last = 0;
17
+ TOKEN_RE.lastIndex = 0;
18
+ for (let m = TOKEN_RE.exec(message); m; m = TOKEN_RE.exec(message)) {
19
+ if (m.index > last)
20
+ out.push({ kind: "text", raw: message.slice(last, m.index) });
21
+ const raw = m[0];
22
+ if (raw === "$$")
23
+ out.push({ kind: "dollar", raw });
24
+ else if (m[1] !== undefined)
25
+ out.push({ kind: "named", raw, name: m[1].toLowerCase() });
26
+ else if (m[2] !== undefined)
27
+ out.push({ kind: "positional", raw, index: Number(m[2]) });
28
+ else
29
+ out.push({ kind: "lone", raw });
30
+ last = m.index + raw.length;
31
+ }
32
+ if (last < message.length)
33
+ out.push({ kind: "text", raw: message.slice(last) });
34
+ return out;
35
+ }
36
+ export function summarizeFormat(message) {
37
+ const named = new Set();
38
+ const positional = new Set();
39
+ let dollars = 0;
40
+ let lone = 0;
41
+ for (const s of tokenize(message)) {
42
+ if (s.kind === "named")
43
+ named.add(s.name);
44
+ else if (s.kind === "positional")
45
+ positional.add(s.index);
46
+ else if (s.kind === "dollar")
47
+ dollars++;
48
+ else if (s.kind === "lone")
49
+ lone++;
50
+ }
51
+ return {
52
+ named: [...named].sort(),
53
+ positional: [...positional].sort((a, b) => a - b),
54
+ dollars,
55
+ lone,
56
+ };
57
+ }
58
+ /**
59
+ * Compare the format tokens of a source and a translated message.
60
+ * Named and positional sets must match (error). A different "$$" count or a new
61
+ * stray "$" is a warning: a human may write "4,99 EUR" on purpose, but from a
62
+ * translator it usually means a broken token (restoreAndVerify treats all as errors).
63
+ */
64
+ export function compareFormat(source, target) {
65
+ const a = summarizeFormat(source);
66
+ const b = summarizeFormat(target);
67
+ const problems = [];
68
+ const error = (message) => problems.push({ severity: "error", message });
69
+ const warning = (message) => problems.push({ severity: "warning", message });
70
+ const missingNamed = a.named.filter((n) => !b.named.includes(n));
71
+ const extraNamed = b.named.filter((n) => !a.named.includes(n));
72
+ if (missingNamed.length)
73
+ error(`missing placeholder(s) ${missingNamed.map((n) => `$${n}$`).join(", ")}`);
74
+ if (extraNamed.length)
75
+ error(`unknown placeholder(s) ${extraNamed.map((n) => `$${n}$`).join(", ")}`);
76
+ const missingPos = a.positional.filter((n) => !b.positional.includes(n));
77
+ const extraPos = b.positional.filter((n) => !a.positional.includes(n));
78
+ if (missingPos.length)
79
+ error(`missing substitution(s) ${missingPos.map((n) => `$${n}`).join(", ")}`);
80
+ if (extraPos.length)
81
+ error(`extra substitution(s) ${extraPos.map((n) => `$${n}`).join(", ")}`);
82
+ if (a.dollars !== b.dollars)
83
+ warning(`"$$" count differs (source ${a.dollars}, translation ${b.dollars})`);
84
+ if (b.lone > a.lone)
85
+ warning(`stray "$" in translation (use "$$" for a literal dollar sign)`);
86
+ return problems;
87
+ }
88
+ /** True when the placeholder sets match (warnings allowed). */
89
+ export function placeholdersMatch(source, target) {
90
+ return compareFormat(source, target).every((p) => p.severity !== "error");
91
+ }
92
+ function escapeRegExp(s) {
93
+ return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
94
+ }
95
+ /**
96
+ * Replace every Chrome format token (and every glossary "keep" term) with a
97
+ * marker. Translators are told to copy markers unchanged.
98
+ */
99
+ export function protect(message, keepTerms = [], opts = {}) {
100
+ const originals = [];
101
+ const terms = [...new Set(keepTerms.filter((t) => t.trim().length > 0))].sort((a, b) => b.length - a.length);
102
+ const termRe = terms.length
103
+ ? new RegExp(`(?<![\\p{L}\\p{N}_])(?:${terms.map(escapeRegExp).join("|")})(?![\\p{L}\\p{N}_])`, "gu")
104
+ : null;
105
+ let text = "";
106
+ // Store listing text is not a Chrome message: "$4.99" is just text there.
107
+ const segments = opts.formatTokens === false ? [{ kind: "text", raw: message }] : tokenize(message);
108
+ for (const seg of segments) {
109
+ if (seg.kind !== "text") {
110
+ originals.push(seg.raw);
111
+ text += `<x id="${originals.length - 1}"/>`;
112
+ continue;
113
+ }
114
+ if (!termRe) {
115
+ text += seg.raw;
116
+ continue;
117
+ }
118
+ text += seg.raw.replace(termRe, (term) => {
119
+ originals.push(term);
120
+ return `<x id="${originals.length - 1}">${term}</x>`;
121
+ });
122
+ }
123
+ return { text, originals };
124
+ }
125
+ const MARKER_RE = /<x\s+id\s*=\s*["']?(\d+)["']?\s*\/>|<x\s+id\s*=\s*["']?(\d+)["']?\s*>[\s\S]*?<\/x\s*>/g;
126
+ /**
127
+ * Put the original tokens back. Fails when a marker is missing, repeated,
128
+ * unknown, or left half-broken.
129
+ */
130
+ export function restore(translated, originals) {
131
+ const seen = new Map();
132
+ const unknownIds = [];
133
+ const text = translated.replace(MARKER_RE, (_m, a, b) => {
134
+ const id = Number(a ?? b);
135
+ seen.set(id, (seen.get(id) ?? 0) + 1);
136
+ if (id >= originals.length) {
137
+ unknownIds.push(id);
138
+ return "";
139
+ }
140
+ return originals[id];
141
+ });
142
+ if (unknownIds.length)
143
+ return { ok: false, error: `unknown marker id ${unknownIds.join(", ")}` };
144
+ for (let i = 0; i < originals.length; i++) {
145
+ const n = seen.get(i) ?? 0;
146
+ if (n === 0)
147
+ return { ok: false, error: `marker ${i} (${originals[i]}) is missing` };
148
+ if (n > 1)
149
+ return { ok: false, error: `marker ${i} (${originals[i]}) appears ${n} times` };
150
+ }
151
+ if (/<\/?x[\s>/]/.test(text))
152
+ return { ok: false, error: "broken marker left in text" };
153
+ return { ok: true, text };
154
+ }
155
+ /**
156
+ * Restore markers, then re-check the Chrome format tokens against the source.
157
+ * This is the gate every translated string passes before it is written.
158
+ */
159
+ export function restoreAndVerify(source, translated, originals, opts = {}) {
160
+ const r = restore(translated, originals);
161
+ if (!r.ok)
162
+ return r;
163
+ if (r.text.trim() === "" && source.trim() !== "")
164
+ return { ok: false, error: "empty translation" };
165
+ if (opts.checkFormat === false)
166
+ return r;
167
+ const problems = compareFormat(source, r.text);
168
+ if (problems.length)
169
+ return { ok: false, error: problems.map((p) => p.message).join("; ") };
170
+ return r;
171
+ }
@@ -0,0 +1,63 @@
1
+ /**
2
+ * CLDR plural key families in messages.json, for example
3
+ * items_one, items_other (English source)
4
+ * items_one, items_few, items_many, items_other (Russian)
5
+ * items_other (Japanese: no "one")
6
+ *
7
+ * Chrome has no plural support, so extensions often store one key per CLDR
8
+ * category and pick it with Intl.PluralRules. Each language has its own set of
9
+ * categories, so the keys differ per locale on purpose.
10
+ *
11
+ * A family is recognised automatically: the source has <base>_other and at least
12
+ * one more <base>_<category> key. Matching is case-insensitive, like Chrome keys.
13
+ */
14
+ export const PLURAL_CATEGORIES = ["zero", "one", "two", "few", "many", "other"];
15
+ const SUFFIX_RE = /^(.+)_(zero|one|two|few|many|other)$/i;
16
+ /** Split "items_few" into ["items", "few"] (base lower-cased), or null. */
17
+ export function splitPluralKey(key) {
18
+ const m = SUFFIX_RE.exec(key);
19
+ return m ? { base: m[1].toLowerCase(), category: m[2].toLowerCase() } : null;
20
+ }
21
+ /** Lower-cased bases of the plural families in the source keys. */
22
+ export function pluralFamilies(sourceKeys) {
23
+ const byBase = new Map();
24
+ for (const key of sourceKeys) {
25
+ const p = splitPluralKey(key);
26
+ if (!p)
27
+ continue;
28
+ let set = byBase.get(p.base);
29
+ if (!set)
30
+ byBase.set(p.base, (set = new Set()));
31
+ set.add(p.category);
32
+ }
33
+ const out = new Set();
34
+ for (const [base, cats] of byBase)
35
+ if (cats.has("other") && cats.size >= 2)
36
+ out.add(base);
37
+ return out;
38
+ }
39
+ const cache = new Map();
40
+ /** Plural categories of a Chrome locale ("pt_BR", "no", "zh_CN") from Intl.PluralRules. */
41
+ export function pluralCategories(locale) {
42
+ let cats = cache.get(locale);
43
+ if (!cats) {
44
+ const tag = locale.replace(/_/g, "-");
45
+ try {
46
+ cats = new Set(new Intl.PluralRules(tag).resolvedOptions().pluralCategories);
47
+ }
48
+ catch {
49
+ cats = new Set(PLURAL_CATEGORIES);
50
+ }
51
+ cache.set(locale, cats);
52
+ }
53
+ return cats;
54
+ }
55
+ /** If `key` belongs to a source plural family: its category and whether `locale` uses it. */
56
+ export function familyMember(key, families, locale) {
57
+ if (!families.size)
58
+ return null;
59
+ const p = splitPluralKey(key);
60
+ if (!p || !families.has(p.base))
61
+ return null;
62
+ return { ...p, used: pluralCategories(locale).has(p.category) };
63
+ }
@@ -0,0 +1,60 @@
1
+ import { RESPONSE_SCHEMA, buildUserPrompt, systemPromptFor, parseTranslations } from "./prompt.js";
2
+ import { LLM_LIMITS, OutputTruncatedError, ProviderError } from "./types.js";
3
+ /** Current default Claude model (Claude Opus 5.5). Override with --model. */
4
+ export const ANTHROPIC_DEFAULT_MODEL = "claude-opus-5-5";
5
+ /**
6
+ * Claude via the official SDK. Credentials come from the environment
7
+ * (ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN or an `ant auth login` profile);
8
+ * nothing is written to disk.
9
+ *
10
+ * - Structured outputs (output_config.format) give parseable JSON.
11
+ * - The SDK retries 429 / 5xx / connection errors itself (maxRetries).
12
+ * - Server-side refusal fallback is on ("default"); on models without
13
+ * fallback support the request simply runs on the requested model.
14
+ */
15
+ export class AnthropicProvider {
16
+ name = "anthropic";
17
+ label;
18
+ limits = LLM_LIMITS;
19
+ model;
20
+ effort;
21
+ client;
22
+ constructor(opts = {}) {
23
+ this.model = opts.model ?? ANTHROPIC_DEFAULT_MODEL;
24
+ this.effort = opts.effort ?? "medium";
25
+ this.client = opts.client;
26
+ this.label = `anthropic/${this.model}`;
27
+ }
28
+ async getClient() {
29
+ if (!this.client) {
30
+ const { default: AnthropicSdk } = await import("@anthropic-ai/sdk");
31
+ this.client = new AnthropicSdk({ maxRetries: 6 });
32
+ }
33
+ return this.client;
34
+ }
35
+ async translateBatch(req) {
36
+ const client = await this.getClient();
37
+ const response = await client.beta.messages.create({
38
+ model: this.model,
39
+ max_tokens: 16000,
40
+ betas: ["server-side-fallback-2026-07-01"],
41
+ fallbacks: "default",
42
+ output_config: {
43
+ effort: this.effort,
44
+ format: { type: "json_schema", schema: RESPONSE_SCHEMA },
45
+ },
46
+ system: systemPromptFor(req.kind),
47
+ messages: [{ role: "user", content: buildUserPrompt(req) }],
48
+ });
49
+ if (response.stop_reason === "refusal") {
50
+ const category = response.stop_details?.category ?? "unknown";
51
+ throw new ProviderError(`Claude declined this batch (category: ${category})`);
52
+ }
53
+ if (response.stop_reason === "max_tokens")
54
+ throw new OutputTruncatedError();
55
+ const text = response.content
56
+ .map((b) => (b.type === "text" ? b.text : ""))
57
+ .join("");
58
+ return parseTranslations(text, req);
59
+ }
60
+ }