localewarden 0.1.1 → 0.3.0

package/dist/project.js

@@ -1,66 +1,159 @@
 import path from 'node:path';
-import { CHECKS, Checker, ERROR_CHECKS } from './checks.js';
-import { findSourceFiles, flatten, readText } from './files.js';
+import { CHECKS, Checker, isError } from './checks.js';
+import { groupsOf, selectGroups } from './config.js';
+import { listFiles } from './engine/sources.js';
+import { findSourceFiles, flatten, isArbMetadata, parseDoc, readText, writeText } from './files.js';
+import { PluginHost } from './plugins.js';
 import { reviewId, State } from './state.js';
 import { hash } from './util.js';
+/**
+ * Short sibling strings (same parent key) that differ in the source but got the same
+ * translation: answer options, tabs or menu items the user can no longer tell apart.
+ */
+export function collapsedSiblings(source, target) {
+    const groups = new Map();
+    for (const key of target.keys()) {
+        // Only nested keys: in a flat file every string would be a "sibling" of every other.
+        if (!key.includes('.'))
+            continue;
+        const parent = key.slice(0, key.lastIndexOf('.'));
+        // Plural forms of one string are meant to look alike.
+        if (/_(zero|one|two|few|many|other)$/.test(key))
+            continue;
+        groups.set(parent, [...(groups.get(parent) ?? []), key]);
+    }
+    const out = [];
+    for (const keys of groups.values()) {
+        const seen = new Map();
+        for (const key of keys) {
+            const src = source.get(key)?.trim();
+            const text = target.get(key)?.trim().toLocaleLowerCase();
+            if (!src || !text || src.length > 40)
+                continue;
+            const earlier = seen.get(text);
+            if (earlier !== undefined && source.get(earlier)?.trim().toLocaleLowerCase() !== src.toLocaleLowerCase()) {
+                out.push({ key, note: `same translation as "${earlier}", although the source differs ("${source.get(earlier)}" / "${src}")` });
+            }
+            else if (earlier === undefined) {
+                seen.set(text, key);
+            }
+        }
+    }
+    return out;
+}
 function readJson(file) {
     const text = readText(file);
-    return text === null ? null : JSON.parse(text);
+    return text === null ? null : parseDoc(file, text);
 }
 /**
- * Runs the quality checks over every translated string. Approved hand edits are skipped
- * except for placeholder and script errors, which break the app either way.
+ * Runs the quality checks over every translated string of every group. Approved strings are
+ * skipped except for errors (placeholder, unsafe, script, plugin errors), which break the
+ * software either way.
  */
-export function checkProject(config, languages = config.targetLanguages) {
-    const checker = new Checker(config);
+export function checkProject(config, optionsOrLanguages = {}) {
+    const options = Array.isArray(optionsOrLanguages) ? { languages: optionsOrLanguages } : optionsOrLanguages;
+    const host = new PluginHost(options.plugins ?? []);
     const state = new State(path.join(config.root, config.stateDir));
     const findings = [];
-    for (const file of findSourceFiles(config.root, config.files, config.sourceLanguage)) {
-        const sourceDoc = readJson(path.join(config.root, file.pathFor(config.sourceLanguage)));
-        if (sourceDoc === null)
-            continue;
-        const source = flatten(sourceDoc);
-        for (const lang of languages) {
-            const rel = file.pathFor(lang);
-            let doc;
-            try {
-                doc = readJson(path.join(config.root, rel));
-            }
-            catch (error) {
-                findings.push({ lang, check: 'markup', severity: 'error', file: rel, key: '(file)', text: '', note: `invalid JSON: ${error.message}` });
-                continue;
-            }
-            if (doc === null)
+    for (const group of selectGroups(config, options.groups, options.languages)) {
+        const checker = new Checker(group, host);
+        const languages = group.targetLanguages.filter(lang => !options.languages?.length || options.languages.includes(lang));
+        for (const file of listFiles(group, checker.scope, host)) {
+            const sourceDoc = readJson(path.join(group.root, file.pathFor(group.sourceLanguage)));
+            if (sourceDoc === null)
                 continue;
-            for (const [key, text] of flatten(doc)) {
-                // Plural forms only the target language has are checked against the source "_other".
-                const sourceText = source.get(key) ?? (/_(zero|one|two|few|many)$/.test(key) ? source.get(key.replace(/_(zero|one|two|few|many)$/, '_other')) : undefined);
-                if (sourceText === undefined || sourceText.trim() === '')
+            const source = flatten(sourceDoc);
+            for (const lang of languages) {
+                const rel = file.pathFor(lang);
+                let doc;
+                try {
+                    doc = readJson(path.join(group.root, rel));
+                }
+                catch (error) {
+                    findings.push({ lang, check: 'markup', severity: 'error', file: rel, key: '(file)', text: '', note: `invalid JSON: ${error.message}`, group: group.name });
+                    continue;
+                }
+                if (doc === null)
                     continue;
-                const review = state.review[reviewId(lang, file.id, key)];
-                const approved = review?.status === 'approved' && review.valueHash === hash(text);
-                for (const issue of checker.checkString(lang, key, sourceText, text)) {
-                    if (approved && !ERROR_CHECKS.has(issue.check))
+                const translated = flatten(doc);
+                for (const { key, note } of collapsedSiblings(source, translated)) {
+                    const review = state.review[reviewId(lang, file.id, key)];
+                    if (review?.status === 'approved')
                         continue;
-                    findings.push({
-                        lang,
-                        check: issue.check,
-                        severity: ERROR_CHECKS.has(issue.check) ? 'error' : 'warning',
-                        file: rel,
-                        key,
-                        text,
-                        note: issue.note,
-                    });
+                    findings.push({ lang, check: 'partial', severity: 'warning', file: rel, key, text: translated.get(key) ?? '', note, group: group.name });
+                }
+                for (const [key, text] of translated) {
+                    // Plural forms only the target language has are checked against the source "_other".
+                    const sourceText = source.get(key) ?? (/_(zero|one|two|few|many)$/.test(key) ? source.get(key.replace(/_(zero|one|two|few|many)$/, '_other')) : undefined);
+                    if (sourceText === undefined || sourceText.trim() === '' || isArbMetadata(rel, key) || checker.scope.isLiteral(key, sourceText))
+                        continue;
+                    const review = state.review[reviewId(lang, file.id, key)];
+                    const approved = review?.status === 'approved' && review.valueHash === hash(text);
+                    for (const issue of checker.checkString(lang, key, sourceText, text, file.id)) {
+                        if (approved && !isError(issue))
+                            continue;
+                        findings.push({
+                            lang,
+                            check: issue.check,
+                            severity: isError(issue) ? 'error' : 'warning',
+                            file: rel,
+                            key,
+                            text,
+                            note: issue.note,
+                            group: group.name,
+                        });
+                    }
                 }
             }
         }
     }
     return findings;
 }
+/**
+ * Repairs placeholder findings that have exactly one possible fix: the source has one
+ * placeholder and the translation one brace token with another name ("{heures}" for
+ * "{hours}"). The file text is edited in place, so its formatting stays as it is.
+ * Returns the repaired findings.
+ */
+export function fixPlaceholders(config, findings) {
+    const fixed = [];
+    const sources = new Map();
+    for (const group of groupsOf(config)) {
+        const checker = new Checker(group);
+        for (const file of findSourceFiles(group.root, group.files, group.sourceLanguage)) {
+            const doc = readJson(path.join(group.root, file.pathFor(group.sourceLanguage)));
+            if (doc)
+                for (const lang of group.targetLanguages)
+                    sources.set(file.pathFor(lang), { values: flatten(doc), checker });
+        }
+    }
+    for (const finding of findings.filter(f => f.check === 'placeholder')) {
+        const entry = sources.get(finding.file);
+        const source = entry?.values.get(finding.key);
+        if (!entry || source === undefined)
+            continue;
+        const expected = source.match(entry.checker.placeholderRe) ?? [];
+        const tokens = finding.text.match(/\{\{?[^{}]+\}?\}/g) ?? [];
+        const [want, got] = [expected[0], tokens[0]];
+        if (new Set(expected).size !== 1 || tokens.length !== 1 || !want || !got || got === want)
+            continue;
+        const repaired = finding.text.replace(got, want);
+        const file = path.join(config.root, finding.file);
+        const text = readText(file);
+        const before = JSON.stringify(finding.text).slice(1, -1);
+        if (text === null || text.split(before).length !== 2)
+            continue; // not found exactly once
+        writeText(file, text.replace(before, JSON.stringify(repaired).slice(1, -1)));
+        fixed.push({ ...finding, text: repaired });
+    }
+    return fixed;
+}
 /** Table of finding counts per language and check. */
 export function summaryTable(findings, languages) {
-    const header = ['lang', ...CHECKS];
-    const rows = languages.map(lang => [lang, ...CHECKS.map(check => String(findings.filter(f => f.lang === lang && f.check === check).length))]);
+    // Built-in checks always; plugin checks when they found something.
+    const checks = [...CHECKS, ...new Set(findings.map(f => f.check).filter(c => !CHECKS.includes(c)))];
+    const header = ['lang', ...checks];
+    const rows = languages.map(lang => [lang, ...checks.map(check => String(findings.filter(f => f.lang === lang && f.check === check).length))]);
     const widths = header.map((h, i) => Math.max(h.length, ...rows.map(row => row[i].length)));
     const line = (cells) => cells.map((cell, i) => cell.padEnd(widths[i])).join('  ').trimEnd();
     return [line(header), ...rows.map(line)].join('\n');

package/dist/prompt.d.ts

@@ -4,9 +4,15 @@ export interface PromptItem {
     source: string;
     /** Existing translation of an older version of the source (revision mode). */
     previous?: string;
+    /** Maximum characters of the translation (store listings, SEO titles, buttons). */
+    maxLength?: number;
+    /** Set when --fix-flagged revises a translation that lost content. */
+    completing?: boolean;
+    /** File id ("locales/{lang}/common.json"), for plugins. */
+    file?: string;
 }
 /** System prompt for translating a JSON array of strings. */
-export declare function batchPrompt(config: Config, lang: string, items: PromptItem[]): string;
+export declare function batchPrompt(config: Config, lang: string, items: PromptItem[], notes?: string): string;
 /** System prompt for translating one string as plain text. */
 export declare function singlePrompt(config: Config, lang: string, item: PromptItem, extra?: string): string;
 /** Turns a translation request into a minimal correction of an existing translation. */

package/dist/prompt.js

@@ -36,7 +36,7 @@ function rules(config, lang, texts) {
 }
 const REVISION_RULE = 'start from the existing translation: keep its wording, terms and sentence structure wherever it still says what the source now says, and change only the parts where the source differs. Remove anything the existing translation says that the source no longer says, and add what is new. Do not reword text that is still correct.';
 /** System prompt for translating a JSON array of strings. */
-export function batchPrompt(config, lang, items) {
+export function batchPrompt(config, lang, items, notes = '') {
     const keys = ` CONTEXT: each element is a UI string. Its key (by 1-based position) hints at the screen and role; use it to pick the right meaning, never translate or output it: ${items
         .map((item, i) => `${i + 1}=${item.key}`)
         .join(', ')}.`;
@@ -46,17 +46,24 @@ export function batchPrompt(config, lang, items) {
     const revision = revised.length > 0
         ? ` REVISION: the source of some elements was edited after they had been translated. Their existing translation (of the older source) by 1-based position: ${JSON.stringify(Object.fromEntries(revised))}. For these elements, ${REVISION_RULE}`
         : '';
+    const limited = items.map((item, i) => (item.maxLength ? `element ${i + 1} at most ${item.maxLength}` : null)).filter(Boolean);
+    const lengths = limited.length > 0
+        ? ` LENGTH LIMIT: these elements are cut off past a character limit (counting spaces): ${limited.join(', ')} characters. Stay under it even if that means a shorter, freer phrasing; never pad.`
+        : '';
     const plural = items.some(item => /_(zero|one|two|few|many|other)$/.test(item.key))
         ? ` PLURALS: keys ending in _zero, _one, _two, _few, _many or _other are plural forms (Unicode CLDR categories) of ${languageName(lang)}. Write the form of that category, even when the source text given is the English plural (_zero is used when the count is 0, _two when it is 2; keep the {{count}} placeholder).`
         : '';
-    return `${intro(config, lang)} Translate each string in the JSON array. Return ONLY a valid JSON array of strings with the same number of elements in the same order. No explanations, no code fences.${rules(config, lang, items.map(i => i.source))}${keys}${plural}${revision}`;
+    return `${intro(config, lang)} Translate each string in the JSON array. Return ONLY a valid JSON array of strings with the same number of elements in the same order. No explanations, no code fences.${rules(config, lang, items.map(i => i.source))}${keys}${lengths}${plural}${revision}${notes}`;
 }
 /** System prompt for translating one string as plain text. */
 export function singlePrompt(config, lang, item, extra = '') {
     const revision = item.previous
         ? ` REVISION: the source was edited after it had been translated. Existing translation (of the older source): ${JSON.stringify(item.previous)}. ${REVISION_RULE[0].toUpperCase()}${REVISION_RULE.slice(1)}`
         : '';
-    return `${intro(config, lang)} The user message is one UI string (key: ${item.key}). Output only the translation, with no explanations, quotes or commentary.${rules(config, lang, [item.source])}${revision}${extra}`;
+    const length = item.maxLength
+        ? ` LENGTH LIMIT: at most ${item.maxLength} characters including spaces; the text is cut off past that. Prefer a shorter, freer phrasing over a literal one.`
+        : '';
+    return `${intro(config, lang)}${length} The user message is one UI string (key: ${item.key}). Output only the translation, with no explanations, quotes or commentary.${rules(config, lang, [item.source])}${revision}${extra}`;
 }
 /** Turns a translation request into a minimal correction of an existing translation. */
 export function repairInstruction(existing, problems) {

package/dist/review.d.ts

@@ -1,4 +1,4 @@
-import type { Config } from './config.js';
+import { type Config } from './config.js';
 export interface ReviewItem {
     id: string;
     lang: string;

package/dist/review.js

@@ -1,13 +1,16 @@
 import path from 'node:path';
-import { flatten, readText } from './files.js';
-import { parseReviewId, State } from './state.js';
-import { hash } from './util.js';
+import { groupsOf } from './config.js';
+import { findSourceFiles, flatten, parseDoc, readText } from './files.js';
+import { parseReviewId, reviewId, State } from './state.js';
+import { withLock } from './lock.js';
+import { hash, today } from './util.js';
 function currentValue(config, lang, fileId, key) {
-    const text = readText(path.join(config.root, fileId.split('{lang}').join(lang)));
+    const rel = fileId.split('{lang}').join(lang);
+    const text = readText(path.join(config.root, rel));
     if (text === null)
         return undefined;
     try {
-        return flatten(JSON.parse(text)).get(key);
+        return flatten(parseDoc(rel, text)).get(key);
     }
     catch {
         return undefined;
@@ -40,25 +43,48 @@ function matches(selector, lang, key) {
  * Returns the number of entries changed.
  */
 export function updateReview(config, action, selectors) {
-    const state = new State(path.join(config.root, config.stateDir));
-    let changed = 0;
-    for (const [id, entry] of Object.entries(state.review)) {
-        const { lang, file, key } = parseReviewId(id);
-        if (!selectors.some(selector => matches(selector, lang, key)))
-            continue;
-        if (action === 'approve') {
-            const value = currentValue(config, lang, file, key);
-            if (value === undefined)
+    // Under the run lock: a run in progress would otherwise overwrite these changes.
+    return withLock(path.join(config.root, config.stateDir), () => {
+        const state = new State(path.join(config.root, config.stateDir));
+        let changed = 0;
+        for (const [id, entry] of Object.entries(state.review)) {
+            const { lang, file, key } = parseReviewId(id);
+            if (!selectors.some(selector => matches(selector, lang, key)))
                 continue;
-            state.review[id] = { ...entry, status: 'approved', valueHash: hash(value) };
+            if (action === 'approve') {
+                const value = currentValue(config, lang, file, key);
+                if (value === undefined)
+                    continue;
+                state.review[id] = { ...entry, status: 'approved', valueHash: hash(value) };
+            }
+            else {
+                delete state.review[id];
+                state.invalidate(lang, file, key);
+            }
+            changed++;
         }
-        else {
-            delete state.review[id];
-            state.invalidate(lang, file, key);
+        // Approving a string that is not on the list marks it as checked by a person: it is then
+        // protected like a hand edit and the quality check no longer reports warnings for it.
+        if (action === 'approve') {
+            const exact = selectors.filter(sel => sel !== 'all' && !sel.endsWith(':*') && sel.includes(':'));
+            for (const selector of exact) {
+                const colon = selector.indexOf(':');
+                const [lang, key] = [selector.slice(0, colon), selector.slice(colon + 1)];
+                const files = groupsOf(config).flatMap(group => findSourceFiles(group.root, group.files, group.sourceLanguage));
+                for (const file of files) {
+                    const id = reviewId(lang, file.id, key);
+                    if (state.review[id])
+                        continue;
+                    const value = currentValue(config, lang, file.id, key);
+                    if (value === undefined)
+                        continue;
+                    state.review[id] = { status: 'approved', reason: 'approved-by-hand', file: file.pathFor(lang), since: today(), valueHash: hash(value) };
+                    changed++;
+                }
+            }
         }
-        changed++;
-    }
-    if (changed > 0)
-        state.save();
-    return changed;
+        if (changed > 0)
+            state.save();
+        return changed;
+    });
 }

package/dist/scope.d.ts

@@ -0,0 +1,15 @@
+import type { Config } from './config.js';
+import { type LocaleFile } from './files.js';
+/** Which files and strings localewarden translates, and their length limits. */
+export declare class Scope {
+    private readonly config;
+    private readonly excluded;
+    private readonly ignored;
+    private readonly limits;
+    constructor(config: Config);
+    /** Excluded by id ("locales/{lang}/nav.json") or by the source path ("locales/en/nav.json"). */
+    isExcluded(file: LocaleFile): boolean;
+    /** Not text: an ignored key or a URL, email, file path or number. Copied, never translated. */
+    isLiteral(key: string, value: string): boolean;
+    maxLength(key: string): number | undefined;
+}

package/dist/scope.js

@@ -0,0 +1,26 @@
+import { isLiteralValue, keyPattern, pathPattern } from './files.js';
+/** Which files and strings localewarden translates, and their length limits. */
+export class Scope {
+    config;
+    excluded;
+    ignored;
+    limits;
+    constructor(config) {
+        this.config = config;
+        this.excluded = config.exclude.map(pathPattern);
+        this.ignored = config.ignoreKeys.map(keyPattern);
+        this.limits = Object.entries(config.maxLength).map(([pattern, max]) => [keyPattern(pattern), max]);
+    }
+    /** Excluded by id ("locales/{lang}/nav.json") or by the source path ("locales/en/nav.json"). */
+    isExcluded(file) {
+        const paths = [file.id, file.pathFor(this.config.sourceLanguage)];
+        return this.excluded.some(re => paths.some(p => re.test(p)));
+    }
+    /** Not text: an ignored key or a URL, email, file path or number. Copied, never translated. */
+    isLiteral(key, value) {
+        return this.ignored.some(re => re.test(key)) || isLiteralValue(value);
+    }
+    maxLength(key) {
+        return this.limits.find(([re]) => re.test(key))?.[1];
+    }
+}

package/dist/state.d.ts

@@ -9,7 +9,7 @@
  * repair-failures.json  targeted repairs (--fix-flagged) that were rejected, so the same
  *              value is not sent to the model again.
  */
-export type ReviewReason = 'manual-edit' | 'source-changed' | 'edited-after-approval';
+export type ReviewReason = 'manual-edit' | 'source-changed' | 'edited-after-approval' | 'approved-by-hand';
 export interface ReviewEntry {
     status: 'pending' | 'approved';
     reason: ReviewReason;
@@ -39,13 +39,20 @@ export declare class State {
     review: Record<string, ReviewEntry>;
     repairFailures: Record<string, RepairFailure>;
     constructor(dir: string);
-    /** Hashes recorded for a string, or undefined if localewarden has not seen it yet. */
+    /**
+     * Hashes recorded for a string, or undefined if localewarden has not seen it yet. `date` is
+     * the UTC day (YYYY-MM-DD) localewarden wrote it; empty for adopted existing translations.
+     */
     get(lang: string, fileId: string, key: string): {
         source: string;
         value: string;
+        date: string;
     } | undefined;
-    /** Records that `value` is the current translation of `source`. */
-    set(lang: string, fileId: string, key: string, source: string, value: string): void;
+    /**
+     * Records that `value` is the current translation of `source`, written today; pass
+     * `written: false` for a translation that was adopted or protected, not written by us.
+     */
+    set(lang: string, fileId: string, key: string, source: string, value: string, written?: boolean): void;
     /** Marks a recorded string as needing re-translation (source hash cleared). */
     invalidate(lang: string, fileId: string, key: string): void;
     delete(lang: string, fileId: string, key: string): void;

package/dist/state.js

@@ -1,28 +1,37 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { writeText } from './files.js';
 import { hash, sortObject, today } from './util.js';
 /** "<file id>#<key>" */
 export const stringId = (fileId, key) => `${fileId}#${key}`;
 /** "<lang>|<file id>#<key>" */
 export const reviewId = (lang, fileId, key) => `${lang}|${stringId(fileId, key)}`;
 export function parseReviewId(id) {
+    // File ids are paths and contain no "#"; keys may ("faq.#1"), so split at the first one.
     const bar = id.indexOf('|');
-    const hashMark = id.lastIndexOf('#');
+    const hashMark = id.indexOf('#', bar + 1);
     return { lang: id.slice(0, bar), file: id.slice(bar + 1, hashMark), key: id.slice(hashMark + 1) };
 }
 function readJson(file, fallback) {
+    let text;
     try {
-        return JSON.parse(fs.readFileSync(file, 'utf8'));
+        text = fs.readFileSync(file, 'utf8');
     }
     catch (error) {
         if (error.code === 'ENOENT')
             return fallback;
-        throw new Error(`Could not read ${file}: ${error.message}`);
+        throw error;
+    }
+    try {
+        return JSON.parse(text.replace(/^\uFEFF/, ''));
+    }
+    catch (error) {
+        throw new Error(`${file} is not valid JSON (${error.message}). It is localewarden's own bookkeeping: ` +
+            'restore it from git, or delete it (translations are kept and adopted again; hand edits made since are then not detected).');
     }
 }
 function writeJson(file, value) {
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(file, JSON.stringify(value, null, 2) + '\n', 'utf8');
+    writeText(file, JSON.stringify(value, null, 2) + '\n');
 }
 export class State {
     dir;
@@ -36,17 +45,27 @@ export class State {
         this.review = readJson(path.join(dir, 'review.json'), {});
         this.repairFailures = readJson(path.join(dir, 'repair-failures.json'), {});
     }
-    /** Hashes recorded for a string, or undefined if localewarden has not seen it yet. */
+    /**
+     * Hashes recorded for a string, or undefined if localewarden has not seen it yet. `date` is
+     * the UTC day (YYYY-MM-DD) localewarden wrote it; empty for adopted existing translations.
+     */
     get(lang, fileId, key) {
         const raw = this.entries[lang]?.[stringId(fileId, key)];
         if (!raw)
             return undefined;
-        const [source, value] = raw.split(':');
-        return { source, value };
+        const [source, value, date = ''] = raw.split(':');
+        return { source, value, date: date ? `${date.slice(0, 4)}-${date.slice(4, 6)}-${date.slice(6, 8)}` : '' };
     }
-    /** Records that `value` is the current translation of `source`. */
-    set(lang, fileId, key, source, value) {
-        (this.entries[lang] ??= {})[stringId(fileId, key)] = `${hash(source)}:${hash(value)}`;
+    /**
+     * Records that `value` is the current translation of `source`, written today; pass
+     * `written: false` for a translation that was adopted or protected, not written by us.
+     */
+    set(lang, fileId, key, source, value, written = true) {
+        const id = stringId(fileId, key);
+        const previous = this.get(lang, fileId, key);
+        const keepDate = !written && previous && previous.value === hash(value) ? previous.date.replace(/-/g, '') : '';
+        const date = written ? today().replace(/-/g, '') : keepDate;
+        (this.entries[lang] ??= {})[id] = `${hash(source)}:${hash(value)}${date ? `:${date}` : ''}`;
     }
     /** Marks a recorded string as needing re-translation (source hash cleared). */
     invalidate(lang, fileId, key) {

package/dist/translate.d.ts

@@ -1,50 +1,10 @@
-import type { Config } from './config.js';
-import { type Model } from './llm.js';
-export interface Logger {
-    info(message: string): void;
-    warn(message: string): void;
-    error(message: string): void;
-    debug?(message: string): void;
-}
-export declare const consoleLogger: Logger;
-export interface RunOptions {
-    /** Subset of the configured target languages. */
-    languages?: string[];
-    /** Show what would be translated; no API calls, no writes. */
-    dryRun?: boolean;
-    /** Re-translate every string, not only new and changed ones. Hand edits stay protected. */
-    retranslateAll?: boolean;
-    /** Also replace hand-edited translations. */
-    overwriteManual?: boolean;
-    /** Ask the model to fix strings the quality check flags, changing as little as possible. */
-    fixFlagged?: boolean;
-    /** Overrides maxTokensPerRun from the config. */
-    maxTokens?: number;
-    logger?: Logger;
-    /** Model to use instead of the configured OpenAI-compatible endpoint (tests, other SDKs). */
-    model?: Model;
-}
-export interface LanguageSummary {
-    translated: number;
-    revised: number;
-    repaired: number;
-    failed: number;
-    protected: number;
-    removed: number;
-    planned: number;
-    plannedChars: number;
-}
-export interface RunSummary {
-    languages: Record<string, LanguageSummary>;
-    filesWritten: string[];
-    tokens: number;
-    requests: number;
-    stoppedByBudget: boolean;
-    pendingReview: number;
-    dryRun: boolean;
-}
-/** Words not shared by both texts, counted on the longer side (word-level LCS). */
-export declare function changedWords(before: string, after: string): number;
-/** A targeted repair may change a few words of a short string or a quarter of a long one. */
-export declare function tooManyChanges(before: string, after: string): string | null;
+import { type Config } from './config.js';
+import { type RunOptions, type RunSummary } from './engine/context.js';
+export { consoleLogger, type Logger, type LanguageSummary, type RunOptions, type RunSummary } from './engine/context.js';
+export { changedWords, tooManyChanges } from './engine/repair.js';
+/**
+ * Translates new and changed strings, group by group (in config order), language by language.
+ * Within a language, all files of a group share requests, so many small files do not cost a
+ * request each. See engine/planner.ts for what is translated, revised, adopted or protected.
+ */
 export declare function run(config: Config, options?: RunOptions): Promise<RunSummary>;