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,269 @@
1
+ import { fetchJson, withRetry } from "../retry.js";
2
+ import { createHash } from "node:crypto";
3
+ import { ProviderError } from "./types.js";
4
+ /** Chrome locale -> DeepL target code, where they differ from plain upper case. */
5
+ const TARGET_MAP = {
6
+ en: "EN-US",
7
+ en_US: "EN-US",
8
+ en_GB: "EN-GB",
9
+ en_AU: "EN-GB",
10
+ es_419: "ES-419",
11
+ pt_BR: "PT-BR",
12
+ pt_PT: "PT-PT",
13
+ zh_CN: "ZH-HANS",
14
+ zh_TW: "ZH-HANT",
15
+ no: "NB",
16
+ fil: "TL",
17
+ };
18
+ export function deeplTargetCode(locale) {
19
+ return TARGET_MAP[locale] ?? locale.split("_")[0].toUpperCase();
20
+ }
21
+ /** DeepL source codes are language-only (EN, PT, ZH). */
22
+ export function deeplSourceCode(locale) {
23
+ return locale === "fil" ? "TL" : locale === "no" ? "NB" : locale.split("_")[0].toUpperCase();
24
+ }
25
+ const MARKER_SPLIT_RE = /(<x id="\d+"\/>|<x id="\d+">[\s\S]*?<\/x>)/;
26
+ function escapeXml(s) {
27
+ return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
28
+ }
29
+ function unescapeXml(s) {
30
+ return s
31
+ .replace(/&lt;/g, "<")
32
+ .replace(/&gt;/g, ">")
33
+ .replace(/&quot;/g, '"')
34
+ .replace(/&apos;/g, "'")
35
+ .replace(/&amp;/g, "&");
36
+ }
37
+ /** Escape the text between markers so DeepL's XML mode sees well-formed input. */
38
+ export function toDeeplXml(text) {
39
+ return text
40
+ .split(MARKER_SPLIT_RE)
41
+ .map((part, i) => i % 2 === 1 ? part.replace(/>([\s\S]*?)<\/x>$/, (_m, inner) => `>${escapeXml(inner)}</x>`) : escapeXml(part))
42
+ .join("");
43
+ }
44
+ export function fromDeeplXml(text) {
45
+ return text
46
+ .split(/(<x\s[^>]*\/>|<x\s[^>]*>[\s\S]*?<\/x>)/)
47
+ .map((part, i) => (i % 2 === 1 ? part : unescapeXml(part)))
48
+ .join("");
49
+ }
50
+ /**
51
+ * Turn glossary terms into DeepL TSV entries. DeepL rejects empty phrases,
52
+ * tabs or line breaks inside a phrase, leading/trailing spaces and duplicate
53
+ * source terms, so those are trimmed or dropped (with a note).
54
+ */
55
+ export function glossaryEntries(terms) {
56
+ const seen = new Set();
57
+ const lines = [];
58
+ const dropped = [];
59
+ for (const [rawSource, rawTarget] of terms) {
60
+ const source = rawSource.trim();
61
+ const target = rawTarget.trim();
62
+ if (!source || !target || /[\t\r\n\u2028\u2029]/.test(source + target)) {
63
+ dropped.push(rawSource);
64
+ continue;
65
+ }
66
+ if (seen.has(source)) {
67
+ dropped.push(rawSource);
68
+ continue;
69
+ }
70
+ seen.add(source);
71
+ lines.push(`${source}\t${target}`);
72
+ }
73
+ // Sorted, so the same terms always give the same glossary name.
74
+ lines.sort();
75
+ return { tsv: lines.join("\n"), count: lines.length, dropped };
76
+ }
77
+ /** Name of the DeepL glossary for one language pair and one set of entries. */
78
+ export function glossaryName(source, target, tsv) {
79
+ const hash = createHash("sha256").update(tsv, "utf8").digest("hex").slice(0, 16);
80
+ return `${GLOSSARY_PREFIX}${source}->${target} ${hash}`;
81
+ }
82
+ export const GLOSSARY_PREFIX = "ext-localize ";
83
+ /** DeepL accepts at most 50 texts per /v2/translate request. */
84
+ export const DEEPL_MAX_TEXTS = 50;
85
+ /** Split text into lines; each line keeps its leading and trailing spaces apart. */
86
+ export function splitLines(text) {
87
+ return text.split(/\r?\n/).map((line) => {
88
+ const m = /^(\s*)([\s\S]*?)(\s*)$/.exec(line);
89
+ return { lead: m[1] ?? "", core: m[2] ?? "", trail: m[3] ?? "" };
90
+ });
91
+ }
92
+ /**
93
+ * DeepL /v2/translate. Markers are sent as XML tags with tag_handling=xml and
94
+ * ignore_tags=["x"], so placeholders and "keep" terms are never touched.
95
+ * Descriptions go into the per-request "context" field (not billed).
96
+ *
97
+ * Formality: "more"/"less" are sent only to languages that support them
98
+ * (others get the default, with a note); "prefer_more"/"prefer_less" are
99
+ * always sent, DeepL falls back by itself.
100
+ *
101
+ * Glossary terms: one DeepL glossary (v3 API) per target locale, named by a
102
+ * hash of its entries. An existing glossary with the same name is reused, so
103
+ * a new one is created only when the terms change. Old ones are not deleted.
104
+ */
105
+ export class DeepLProvider {
106
+ name = "deepl";
107
+ label = "deepl";
108
+ limits = { maxItems: 50, maxChars: 30000 };
109
+ apiKey;
110
+ baseUrl;
111
+ targets;
112
+ glossaryLangs;
113
+ glossaries;
114
+ setup = new Map();
115
+ constructor(opts = {}) {
116
+ const key = opts.apiKey ?? process.env.DEEPL_API_KEY;
117
+ if (!key)
118
+ throw new ProviderError("DEEPL_API_KEY is not set");
119
+ this.apiKey = key;
120
+ this.baseUrl = (opts.baseUrl ??
121
+ process.env.DEEPL_API_URL ??
122
+ (key.endsWith(":fx") ? "https://api-free.deepl.com" : "https://api.deepl.com")).replace(/\/+$/, "");
123
+ }
124
+ headers(json = true) {
125
+ const h = { authorization: `DeepL-Auth-Key ${this.apiKey}` };
126
+ if (json)
127
+ h["content-type"] = "application/json";
128
+ return h;
129
+ }
130
+ get(path) {
131
+ return withRetry(() => fetchJson(`${this.baseUrl}${path}`, { method: "GET", headers: this.headers(false) }));
132
+ }
133
+ /** Target languages of this account, with formality support (free call, cached). */
134
+ targetLanguages() {
135
+ this.targets ??= this.get("/v2/languages?type=target").then((list) => new Map(list.map((l) => [
136
+ l.language.toUpperCase(),
137
+ { formality: l.supports_formality === true },
138
+ ])));
139
+ return this.targets;
140
+ }
141
+ async supportsLocale(locale) {
142
+ return (await this.targetLanguages()).has(deeplTargetCode(locale));
143
+ }
144
+ /** Languages usable in glossaries: upper-case code -> code as DeepL spells it. */
145
+ glossaryLanguages() {
146
+ this.glossaryLangs ??= this.get("/v3/languages?resource=glossary").then((list) => new Map(list.map((l) => [l.lang.toUpperCase(), l.lang])));
147
+ return this.glossaryLangs;
148
+ }
149
+ /** Our glossaries on this account: name -> id (cached for the run). */
150
+ glossaryIndex() {
151
+ this.glossaries ??= this.get("/v3/glossaries").then((data) => {
152
+ const list = data.glossaries ?? [];
153
+ return new Map(list.filter((g) => g.name.startsWith(GLOSSARY_PREFIX)).map((g) => [g.name, g.glossary_id]));
154
+ });
155
+ return this.glossaries;
156
+ }
157
+ async ensureGlossary(source, target, tsv) {
158
+ const name = glossaryName(source, target, tsv);
159
+ const index = await this.glossaryIndex();
160
+ const existing = index.get(name);
161
+ if (existing)
162
+ return { id: existing, created: false, name };
163
+ const body = { name, dictionaries: [{ source_lang: source, target_lang: target, entries: tsv, entries_format: "tsv" }] };
164
+ // Not wrapped in withRetry: a retried POST could create the glossary twice.
165
+ const created = (await fetchJson(`${this.baseUrl}/v3/glossaries`, {
166
+ method: "POST",
167
+ headers: this.headers(),
168
+ body: JSON.stringify(body),
169
+ }));
170
+ if (!created.glossary_id)
171
+ throw new ProviderError("DeepL did not return a glossary_id");
172
+ index.set(name, created.glossary_id);
173
+ return { id: created.glossary_id, created: true, name };
174
+ }
175
+ /** Decide formality and glossary for one locale. Returns notes for the log. */
176
+ async prepareLocale(req) {
177
+ const notes = [];
178
+ const setup = {};
179
+ const target = deeplTargetCode(req.targetLocale);
180
+ if (req.formality && req.formality !== "default") {
181
+ const lang = (await this.targetLanguages()).get(target);
182
+ if (req.formality.startsWith("prefer_") || lang?.formality)
183
+ setup.formality = req.formality;
184
+ else
185
+ notes.push(`formality "${req.formality}" is not supported for ${target}; using the default`);
186
+ }
187
+ if (req.terms.length) {
188
+ const { tsv, count, dropped } = glossaryEntries(req.terms);
189
+ if (dropped.length)
190
+ notes.push(`glossary terms not usable on DeepL (empty, tab, line break or duplicate): ${dropped.join(", ")}`);
191
+ const langs = await this.glossaryLanguages();
192
+ const src = langs.get(deeplSourceCode(req.sourceLocale));
193
+ const tgt = langs.get(target);
194
+ if (count === 0) {
195
+ // nothing left to send
196
+ }
197
+ else if (!src || !tgt) {
198
+ notes.push(`DeepL glossaries do not support ${deeplSourceCode(req.sourceLocale)} -> ${target}; glossary terms not applied`);
199
+ }
200
+ else {
201
+ const g = await this.ensureGlossary(src, tgt, tsv);
202
+ setup.glossaryId = g.id;
203
+ notes.push(`${g.created ? "created" : "using"} DeepL glossary "${g.name}" (${count} term${count === 1 ? "" : "s"})`);
204
+ }
205
+ }
206
+ this.setup.set(req.targetLocale, setup);
207
+ return notes;
208
+ }
209
+ async translateBatch(req) {
210
+ let context;
211
+ if (req.kind === "listing") {
212
+ context = "Store listing of a browser extension: the name, a short summary, and the long description.";
213
+ }
214
+ else {
215
+ // DeepL has one context per request and never sees our keys, so each note
216
+ // quotes the source text it belongs to. This is loose background only.
217
+ const notes = req.items
218
+ .filter((i) => i.description)
219
+ .map((i) => `"${i.text}": ${i.description}`)
220
+ .join("\n");
221
+ context = notes ? `Strings from a Chrome browser extension user interface. Notes per string:\n${notes}` : "";
222
+ }
223
+ const params = {
224
+ source_lang: deeplSourceCode(req.sourceLocale),
225
+ target_lang: deeplTargetCode(req.targetLocale),
226
+ tag_handling: "xml",
227
+ ignore_tags: ["x"],
228
+ preserve_formatting: true,
229
+ };
230
+ if (context)
231
+ params.context = context;
232
+ const setup = this.setup.get(req.targetLocale);
233
+ if (setup) {
234
+ if (setup.formality)
235
+ params.formality = setup.formality;
236
+ if (setup.glossaryId)
237
+ params.glossary_id = setup.glossaryId;
238
+ }
239
+ else if (req.formality?.startsWith("prefer_")) {
240
+ params.formality = req.formality;
241
+ }
242
+ // Listing text: each line is sent as its own text. In XML mode DeepL does not
243
+ // treat a line break as the end of a sentence, so list items could be merged.
244
+ // Blank lines and the spaces around a line are kept here and never sent.
245
+ // UI messages are sent whole, as before.
246
+ const split = req.items.map((item) => (req.kind === "listing" ? splitLines(item.text) : [{ lead: "", core: item.text, trail: "" }]));
247
+ const texts = split.flatMap((lines) => lines.filter((l) => l.core !== "" || lines.length === 1).map((l) => toDeeplXml(l.core)));
248
+ const out = [];
249
+ for (let i = 0; i < texts.length; i += DEEPL_MAX_TEXTS) {
250
+ const chunk = texts.slice(i, i + DEEPL_MAX_TEXTS);
251
+ const body = { ...params, text: chunk };
252
+ const data = (await withRetry(() => fetchJson(`${this.baseUrl}/v2/translate`, { method: "POST", headers: this.headers(), body: JSON.stringify(body) })));
253
+ const list = data.translations ?? [];
254
+ if (list.length !== chunk.length) {
255
+ throw new ProviderError(`DeepL returned ${list.length} texts for ${chunk.length} inputs`);
256
+ }
257
+ out.push(...list.map((t) => fromDeeplXml(t.text)));
258
+ }
259
+ const result = {};
260
+ let n = 0;
261
+ req.items.forEach((item, i) => {
262
+ const lines = split[i] ?? [];
263
+ result[item.key] = lines
264
+ .map((l) => (l.core === "" && lines.length > 1 ? l.lead + l.trail : l.lead + (out[n++] ?? "") + l.trail))
265
+ .join("\n");
266
+ });
267
+ return result;
268
+ }
269
+ }
@@ -0,0 +1,40 @@
1
+ import { AnthropicProvider } from "./anthropic.js";
2
+ import { DeepLProvider } from "./deepl.js";
3
+ import { OllamaProvider } from "./ollama.js";
4
+ import { OpenAIProvider } from "./openai.js";
5
+ import { LLM_LIMITS, ProviderError } from "./types.js";
6
+ export const PROVIDER_NAMES = ["anthropic", "openai", "deepl", "ollama"];
7
+ const EFFORTS = ["low", "medium", "high", "xhigh", "max"];
8
+ export function createProvider(cfg) {
9
+ switch (cfg.name) {
10
+ case "anthropic": {
11
+ if (cfg.effort && !EFFORTS.includes(cfg.effort))
12
+ throw new ProviderError(`--effort must be one of ${EFFORTS.join(", ")}`);
13
+ return new AnthropicProvider({ model: cfg.model, effort: cfg.effort });
14
+ }
15
+ case "openai": {
16
+ const model = cfg.model ?? process.env.OPENAI_MODEL;
17
+ if (!model)
18
+ throw new ProviderError("openai needs a model: pass --model (or set OPENAI_MODEL)");
19
+ return new OpenAIProvider({ model });
20
+ }
21
+ case "ollama": {
22
+ const model = cfg.model ?? process.env.OLLAMA_MODEL;
23
+ if (!model)
24
+ throw new ProviderError('ollama needs a model: pass --model (see "ollama list")');
25
+ return new OllamaProvider({ model });
26
+ }
27
+ case "deepl":
28
+ return new DeepLProvider();
29
+ default:
30
+ throw new ProviderError(`unknown provider "${cfg.name}". Use one of: ${PROVIDER_NAMES.join(", ")}`);
31
+ }
32
+ }
33
+ /** Batch limits without building a provider (no key needed). Used by --dry-run. */
34
+ export function limitsFor(name) {
35
+ if (name === "deepl")
36
+ return { maxItems: 50, maxChars: 30000 };
37
+ if (name === "ollama")
38
+ return { maxItems: 15, maxChars: 3000 };
39
+ return LLM_LIMITS;
40
+ }
@@ -0,0 +1,48 @@
1
+ import { fetchJson, withRetry } from "../retry.js";
2
+ import { RESPONSE_SCHEMA, buildUserPrompt, systemPromptFor, parseTranslations } from "./prompt.js";
3
+ import { OutputTruncatedError, ProviderError } from "./types.js";
4
+ function normalizeHost(host) {
5
+ const withScheme = /^https?:\/\//.test(host) ? host : `http://${host}`;
6
+ return withScheme.replace(/\/+$/, "");
7
+ }
8
+ /**
9
+ * A local model through Ollama's /api/chat with a JSON schema "format".
10
+ * Nothing leaves your machine. Smaller batches, because small local models
11
+ * lose track of long lists. There is no default model: pass --model.
12
+ */
13
+ export class OllamaProvider {
14
+ name = "ollama";
15
+ label;
16
+ limits = { maxItems: 15, maxChars: 3000 };
17
+ model;
18
+ host;
19
+ constructor(opts) {
20
+ this.model = opts.model;
21
+ this.host = normalizeHost(opts.host ?? process.env.OLLAMA_HOST ?? "http://localhost:11434");
22
+ this.label = `ollama/${this.model}`;
23
+ }
24
+ async translateBatch(req) {
25
+ const body = {
26
+ model: this.model,
27
+ stream: false,
28
+ format: RESPONSE_SCHEMA,
29
+ options: { temperature: 0 },
30
+ messages: [
31
+ { role: "system", content: systemPromptFor(req.kind) },
32
+ { role: "user", content: buildUserPrompt(req) },
33
+ ],
34
+ };
35
+ let data;
36
+ try {
37
+ data = (await withRetry(() => fetchJson(`${this.host}/api/chat`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) }), { retries: 2 }));
38
+ }
39
+ catch (e) {
40
+ if (e instanceof TypeError)
41
+ throw new ProviderError(`cannot reach Ollama at ${this.host}. Is "ollama serve" running?`);
42
+ throw e;
43
+ }
44
+ if (data.done_reason === "length")
45
+ throw new OutputTruncatedError();
46
+ return parseTranslations(data.message?.content ?? "", req);
47
+ }
48
+ }
@@ -0,0 +1,50 @@
1
+ import { fetchJson, withRetry } from "../retry.js";
2
+ import { RESPONSE_SCHEMA, buildUserPrompt, systemPromptFor, parseTranslations } from "./prompt.js";
3
+ import { LLM_LIMITS, OutputTruncatedError, ProviderError } from "./types.js";
4
+ /**
5
+ * OpenAI Chat Completions with a strict JSON schema response format.
6
+ * Also works with OpenAI-compatible local servers (LM Studio, vLLM, llama.cpp)
7
+ * through OPENAI_BASE_URL. There is no default model: pass --model.
8
+ */
9
+ export class OpenAIProvider {
10
+ name = "openai";
11
+ label;
12
+ limits = LLM_LIMITS;
13
+ model;
14
+ baseUrl;
15
+ apiKey;
16
+ constructor(opts) {
17
+ this.model = opts.model;
18
+ this.baseUrl = (opts.baseUrl ?? process.env.OPENAI_BASE_URL ?? "https://api.openai.com/v1").replace(/\/+$/, "");
19
+ this.apiKey = opts.apiKey ?? process.env.OPENAI_API_KEY;
20
+ if (!this.apiKey && this.baseUrl.includes("api.openai.com")) {
21
+ throw new ProviderError("OPENAI_API_KEY is not set");
22
+ }
23
+ this.label = `openai/${this.model}`;
24
+ }
25
+ async translateBatch(req) {
26
+ const headers = { "content-type": "application/json" };
27
+ if (this.apiKey)
28
+ headers.authorization = `Bearer ${this.apiKey}`;
29
+ const body = {
30
+ model: this.model,
31
+ messages: [
32
+ { role: "system", content: systemPromptFor(req.kind) },
33
+ { role: "user", content: buildUserPrompt(req) },
34
+ ],
35
+ response_format: {
36
+ type: "json_schema",
37
+ json_schema: { name: "translations", strict: true, schema: RESPONSE_SCHEMA },
38
+ },
39
+ };
40
+ const data = (await withRetry(() => fetchJson(`${this.baseUrl}/chat/completions`, { method: "POST", headers, body: JSON.stringify(body) })));
41
+ const choice = data.choices?.[0];
42
+ if (!choice?.message)
43
+ throw new ProviderError("response has no choices");
44
+ if (choice.message.refusal)
45
+ throw new ProviderError(`model refused: ${choice.message.refusal}`);
46
+ if (choice.finish_reason === "length")
47
+ throw new OutputTruncatedError();
48
+ return parseTranslations(choice.message.content ?? "", req);
49
+ }
50
+ }
@@ -0,0 +1,100 @@
1
+ import { localeDisplayName } from "../locales.js";
2
+ import { ProviderError } from "./types.js";
3
+ /**
4
+ * Shared prompt for LLM providers (Anthropic, OpenAI, Ollama).
5
+ * The system prompt is constant so providers can cache it.
6
+ */
7
+ export const SYSTEM_PROMPT = `You translate user interface strings of a Chrome browser extension.
8
+
9
+ Rules:
10
+ 1. Markers like <x id="0"/> stand for placeholders that the extension fills in at runtime. Copy every marker exactly once, unchanged, at the natural position for the target language.
11
+ 2. Markers like <x id="1">Name</x> wrap words that must not be translated. Copy them exactly, including the inner text.
12
+ 3. Never add, remove, merge or rename markers.
13
+ 4. Keep the meaning and tone. UI text must stay short: aim for a length close to the source.
14
+ 5. The description and marker notes are context for you. Do not translate or include them.
15
+ 6. Keep leading and trailing spaces, line breaks and punctuation style that the target language allows.
16
+ 7. When a glossary is given, always use its translations for those terms.
17
+ 8. Return one entry for every input key, with the key unchanged.`;
18
+ /** Instructions for store listing text (name, summary, long description). */
19
+ export const LISTING_SYSTEM_PROMPT = `You translate the store listing of a browser extension (Chrome Web Store, Firefox Add-ons, Edge Add-ons).
20
+
21
+ Rules:
22
+ 1. Markers like <x id="1">Name</x> wrap words that must not be translated. Copy them exactly, including the inner text. Never add, remove or rename markers.
23
+ 2. Write natural, fluent marketing text for the target language. Keep the meaning; do not add claims or keywords that are not in the source.
24
+ 3. Keep the structure of the long description: the same paragraphs, line breaks, list markers ("- ", "* ", "1. ") and blank lines.
25
+ 4. Respect the maximum length given in the description of each string.
26
+ 5. The description of each string is context for you. Do not translate or include it.
27
+ 6. When a glossary is given, always use its translations for those terms.
28
+ 7. Return one entry for every input key, with the key unchanged.`;
29
+ export function systemPromptFor(kind) {
30
+ return kind === "listing" ? LISTING_SYSTEM_PROMPT : SYSTEM_PROMPT;
31
+ }
32
+ /** JSON schema for the structured response: an array, since keys are dynamic. */
33
+ export const RESPONSE_SCHEMA = {
34
+ type: "object",
35
+ properties: {
36
+ translations: {
37
+ type: "array",
38
+ items: {
39
+ type: "object",
40
+ properties: {
41
+ key: { type: "string" },
42
+ text: { type: "string" },
43
+ },
44
+ required: ["key", "text"],
45
+ additionalProperties: false,
46
+ },
47
+ },
48
+ },
49
+ required: ["translations"],
50
+ additionalProperties: false,
51
+ };
52
+ export function buildUserPrompt(req) {
53
+ const lines = [];
54
+ lines.push(`Source language: ${localeDisplayName(req.sourceLocale)} (${req.sourceLocale})`);
55
+ lines.push(`Target language: ${localeDisplayName(req.targetLocale)} (${req.targetLocale})`);
56
+ if (req.formality === "more" || req.formality === "prefer_more") {
57
+ lines.push("Tone: formal. Use the formal form of address where the language has one (for example German \"Sie\", French \"vous\").");
58
+ }
59
+ else if (req.formality === "less" || req.formality === "prefer_less") {
60
+ lines.push("Tone: informal. Use the informal form of address where the language has one (for example German \"du\", French \"tu\").");
61
+ }
62
+ if (req.terms.length) {
63
+ lines.push("", "Glossary (always use these translations):");
64
+ for (const [term, translation] of req.terms)
65
+ lines.push(`- "${term}" -> "${translation}"`);
66
+ }
67
+ const items = req.items.map((i) => {
68
+ const o = { key: i.key, text: i.text };
69
+ if (i.description)
70
+ o.description = i.description;
71
+ if (i.markerHints?.length)
72
+ o.markers = i.markerHints;
73
+ return o;
74
+ });
75
+ lines.push("", "Strings to translate (JSON):", JSON.stringify(items, null, 1));
76
+ lines.push("", `Return {"translations": [{"key": ..., "text": ...}]} with ${req.items.length} entries.`);
77
+ return lines.join("\n");
78
+ }
79
+ /** Parse the model's JSON answer into key -> text. Unknown keys are ignored. */
80
+ export function parseTranslations(raw, req) {
81
+ let data;
82
+ const trimmed = raw.trim().replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "");
83
+ try {
84
+ data = JSON.parse(trimmed);
85
+ }
86
+ catch {
87
+ throw new ProviderError(`model did not return valid JSON: ${raw.slice(0, 200)}`);
88
+ }
89
+ const list = data?.translations;
90
+ if (!Array.isArray(list))
91
+ throw new ProviderError(`model JSON has no "translations" array`);
92
+ const wanted = new Set(req.items.map((i) => i.key));
93
+ const out = {};
94
+ for (const entry of list) {
95
+ const e = entry;
96
+ if (typeof e?.key === "string" && typeof e.text === "string" && wanted.has(e.key))
97
+ out[e.key] = e.text;
98
+ }
99
+ return out;
100
+ }
@@ -0,0 +1,18 @@
1
+ /** DeepL's formality values. LLM providers get them as a tone instruction. */
2
+ export const FORMALITIES = ["default", "more", "less", "prefer_more", "prefer_less"];
3
+ /** The response was cut off (output token limit). The caller splits the batch. */
4
+ export class OutputTruncatedError extends Error {
5
+ constructor(message = "response was cut off before the end") {
6
+ super(message);
7
+ this.name = "OutputTruncatedError";
8
+ }
9
+ }
10
+ /** Provider refused or returned something unusable. Not retried as-is. */
11
+ export class ProviderError extends Error {
12
+ constructor(message) {
13
+ super(message);
14
+ this.name = "ProviderError";
15
+ }
16
+ }
17
+ /** Default limits for LLM providers: many keys per call, bounded output size. */
18
+ export const LLM_LIMITS = { maxItems: 40, maxChars: 8000 };
package/dist/retry.js ADDED
@@ -0,0 +1,66 @@
1
+ /** HTTP error with enough detail to decide whether to retry. */
2
+ export class HttpError extends Error {
3
+ status;
4
+ retryAfterMs;
5
+ constructor(status, message, retryAfterMs = null) {
6
+ super(message);
7
+ this.name = "HttpError";
8
+ this.status = status;
9
+ this.retryAfterMs = retryAfterMs;
10
+ }
11
+ }
12
+ /** Parse a Retry-After header (seconds or HTTP date) into milliseconds. */
13
+ export function parseRetryAfter(value) {
14
+ if (!value)
15
+ return null;
16
+ const secs = Number(value);
17
+ if (Number.isFinite(secs))
18
+ return Math.max(0, secs * 1000);
19
+ const date = Date.parse(value);
20
+ return Number.isFinite(date) ? Math.max(0, date - Date.now()) : null;
21
+ }
22
+ /** 429 (rate limit), 408, 5xx and network failures are worth retrying. */
23
+ export function isRetryable(err) {
24
+ if (err instanceof HttpError)
25
+ return err.status === 429 || err.status === 408 || err.status >= 500;
26
+ // fetch() throws TypeError on network failures (DNS, connection reset).
27
+ return err instanceof TypeError;
28
+ }
29
+ const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
30
+ /**
31
+ * Run fn, retrying on rate limits and transient errors with exponential
32
+ * backoff and jitter. A Retry-After header wins over the computed delay.
33
+ */
34
+ export async function withRetry(fn, opts = {}) {
35
+ const retries = opts.retries ?? 5;
36
+ const base = opts.baseDelayMs ?? 1000;
37
+ const max = opts.maxDelayMs ?? 60_000;
38
+ const sleep = opts.sleep ?? defaultSleep;
39
+ for (let attempt = 0;; attempt++) {
40
+ try {
41
+ return await fn();
42
+ }
43
+ catch (err) {
44
+ if (attempt >= retries || !isRetryable(err))
45
+ throw err;
46
+ const backoff = Math.min(max, base * 2 ** attempt) * (0.5 + Math.random() / 2);
47
+ const delay = err instanceof HttpError && err.retryAfterMs !== null ? Math.min(max, err.retryAfterMs) : backoff;
48
+ opts.onRetry?.(attempt + 1, delay, err);
49
+ await sleep(delay);
50
+ }
51
+ }
52
+ }
53
+ /** fetch + JSON with HttpError on non-2xx. */
54
+ export async function fetchJson(url, init) {
55
+ const res = await fetch(url, init);
56
+ const text = await res.text();
57
+ if (!res.ok) {
58
+ throw new HttpError(res.status, `${init.method ?? "GET"} ${url} -> HTTP ${res.status}: ${text.slice(0, 300)}`, parseRetryAfter(res.headers.get("retry-after")));
59
+ }
60
+ try {
61
+ return JSON.parse(text);
62
+ }
63
+ catch {
64
+ throw new Error(`${url}: response is not JSON: ${text.slice(0, 200)}`);
65
+ }
66
+ }