localewarden 0.2.0 → 0.3.0

package/README.md

@@ -41,7 +41,11 @@ localewarden grew out of the translation pipeline of a production app that ships
 - **Glossary and protected names.** You choose fixed renderings ("Privacy Policy" -> "Politique de confidentialité") and names that must never be translated. The check accepts grammatical case endings.
 - **Quality check for CI.** `localewarden check` runs all checks without any API calls and exits non-zero on errors.
 - **Targeted repair.** `--fix-flagged` asks the model to fix only what the check flagged. The fix is accepted only if the problem is gone and little else changed.
-- **Budget control.** A token budget per run, a dry run with a cost estimate, and graceful stop and resume.
+- **Budget control.** A token budget per run and per day (for scheduled jobs), a dry run with a cost estimate, and graceful stop and resume.
+- **Groups.** Parts of a project with their own files, languages and model settings, translated in a fixed order (say app UI first, long-form content last, with a cheaper setting).
+- **Plugins.** Your own checks, prompt notes, post-processing and file order, without forking.
+- **Web interface.** `npx localewarden ui`: progress per language, strings with inline editing, check findings, the review list, and runs with a live log. Local only.
+- **Reliable in daily use.** Lock against parallel runs, atomic writes, progress saved on Ctrl+C, Windows line endings and byte order marks kept.
 - **No runtime dependencies.** Node.js 20+.
 
 ## Example
@@ -118,7 +122,12 @@ German uses "du" and French "vous", as configured. Spanish and French use senten
    git add locales .localewarden
    ```
 
-   `.localewarden/` holds the hashes that tell localewarden what changed and what was edited by hand. Commit it so your team and your CI share the same state.
+   `.localewarden/` holds the hashes that tell localewarden what changed and what was edited by hand. Commit it so your team and your CI share the same state, except two local files:
+
+   ```gitignore
+   .localewarden/usage.json
+   .localewarden/run.lock
+   ```
 
 ## How it decides what to translate
 
@@ -222,6 +231,22 @@ npx localewarden --fix-flagged
 
 For each flagged string, the model gets the source, the current translation and the exact findings, with the instruction to change only what is needed. The fix is written only if the same check passes afterwards, nothing else breaks, and few words changed. Rejected fixes are recorded in `.localewarden/repair-failures.json` and not retried until the translation changes.
 
+## Web interface
+
+```bash
+npx localewarden ui            # prints a local URL with an access token
+```
+
+- **Overview:** progress per group and language, hand edits waiting for review, tokens used today.
+- **Strings:** search by key, source or translation; show only missing ones; edit a translation inline. An edit counts as checked by a person: it is approved and protected from runs.
+- **Check:** run the quality check and filter findings by language and check.
+- **Review:** approve hand edits or hand them back.
+- **Run:** dry run, translate or fix flagged strings, with a live log.
+
+The interface listens on `127.0.0.1` only, needs the random token from the printed URL, and
+rejects requests with another host name, so websites open in your browser cannot use it.
+It writes only to the project's own locale files.
+
 ## Hand edits and review
 
 ```bash
@@ -264,6 +289,71 @@ npx localewarden review --release de:home.title   # hand it back: next run revis
 | `concurrency` | `4` | Languages translated in parallel |
 | `batchSize` | `20` | Strings per request (smaller for scripts that need many tokens) |
 | `stateDir` | `".localewarden"` | Where state and the review list live |
+| `dailyTokenBudget` | | Token limit per UTC day across runs (for scheduled jobs); usage is kept in `<stateDir>/usage.json` (add it to `.gitignore`) |
+| `copies` | `{}` | Locales that are a copy of another one instead of a translation: `{"en-GB": "en-US", "fr-CA": "fr-FR"}` |
+| `chunkChars` | `8000` | Longer strings are translated paragraph by paragraph |
+| `plugins` | `[]` | Plugin modules, see [Plugins](#plugins) |
+| `groups` | | Parts of the project with their own settings, see [Groups](#groups) |
+
+### Groups
+
+Different parts of a project often need different settings: the app UI translated first and
+with care, long articles last and with a cheaper setting, store listings with other locale
+codes. Each group inherits the top-level settings and may override them:
+
+```json
+{
+  "targetLanguages": ["de", "fr", "pl"],
+  "dailyTokenBudget": 2000000,
+  "groups": [
+    { "name": "app", "files": "src/locales/{lang}/*.json" },
+    { "name": "store", "files": "fastlane/metadata/{lang}/*.txt", "sourceLanguage": "en-US",
+      "targetLanguages": ["de-DE", "fr-FR", "pl"], "copies": { "fr-CA": "fr-FR" } },
+    { "name": "articles", "files": "content/*/*.{lang}.json", "reasoningEffort": "low",
+      "ignoreKeys": ["id", "slug", "image"] }
+  ]
+}
+```
+
+Groups run in this order and share the budget, so the important ones are done first when the
+budget runs out. `--group app,store` runs only some; an unknown group name is an error.
+
+What a group inherits: maps (`formality`, `glossary` per language, `termNotes`, `instructions`,
+`maxLength`) are merged with the top level, lists (`doNotTranslate`, `ignoreKeys`, `exclude`)
+are extended, and everything else is replaced. A group with its own `targetLanguages` or
+`sourceLanguage` does not inherit `copies`, since those name locales. `stateDir`, `plugins`, `dailyTokenBudget`,
+`maxTokensPerRun` and `concurrency` apply to the whole run and can only be set at the top level.
+
+### Plugins
+
+A plugin adds project rules without forking localewarden. It is an ES module; its default
+export is a plugin object, or a function that receives the options from the config:
+
+```js
+// rules/my-plugin.mjs
+export default (options) => ({
+  name: 'my-rules',
+  // Extra findings for one translated string. "error" blocks writing it and fails `check`;
+  // "fixable" lets --fix-flagged repair it.
+  checks: ({ lang, key, file, source, text }) =>
+    lang === 'es' && /\bcoger\b/i.test(text)
+      ? [{ check: 'regional-term', note: 'use "tomar"', fixable: true }]
+      : [],
+  // Extra prompt text for a batch (sent with every request of the batch).
+  promptNotes: ({ lang, items }) => (lang === 'es' ? 'Use neutral Latin American Spanish.' : ''),
+  // Rewrites a model answer before it is checked and written.
+  postProcess: ({ lang, text }) => (lang === 'fr' ? text.replace(/ ([?!:;])/g, '\u00a0$1') : text),
+  // Reorders or filters the files of a group.
+  order: (files, { group }) => files,
+});
+```
+
+```json
+{ "plugins": ["./rules/my-plugin.mjs", { "module": "./rules/blog.mjs", "options": { "draftsFolder": "drafts" } }] }
+```
+
+All hooks are optional. The interface is marked experimental in 0.x and may change in a minor
+version. A complete example is in [`examples/plugin`](examples/plugin).
 
 ### App Store and Play Store listings (fastlane)
 
@@ -311,10 +401,12 @@ Small local models make noticeably more mistakes. The checks catch the mechanica
 ## Commands
 
 ```text
-localewarden [translate]  --dry-run --lang de,fr --fix-flagged --retranslate-all
+localewarden [translate]  --dry-run --lang de,fr --group app --fix-flagged --retranslate-all
+                          --retranslate-files <patterns> --refresh-before <YYYY-MM-DD>
                           --overwrite-manual --max-tokens <n> --verbose
-localewarden check        --lang de,fr --verbose --limit <n> --strict --json --fix
+localewarden check        --lang de,fr --group app --verbose --limit <n> --strict --json --fix
 localewarden review       --all --approve <sel>... --release <sel>...
+localewarden ui           --port <n>
 localewarden init
 Global: --config <path>  --help  --version
 ```
@@ -350,6 +442,18 @@ Translations are treated as untrusted: any markup the source does not have is bl
 - Rules for form of address, gender and typography exist for the languages listed above. Other languages are translated with the general rules.
 - A run that is interrupted keeps everything written so far. Unwritten strings are picked up on the next run.
 
+## Reliability
+
+- **One run at a time:** a lock file in the state folder stops a second run (say CI and a local run), or an approval or edit during a run, from writing the same state; a lock left by a crashed process (or committed from another machine) is taken over safely.
+- **Errors stop cleanly:** when one language fails, no further language starts, and the run ends only after the running ones finished.
+- **Symbolic links** to locale files are written through; the file keeps its permissions.
+- **No half-written files:** locale files and state are written to a temporary file and renamed.
+- **Ctrl+C or a CI timeout** saves what was translated so far.
+- **File formats are kept:** indentation, key order of existing files, Windows line endings, byte order marks. A file whose content did not change is not rewritten.
+- **Unicode:** text is compared NFC-normalized, so an editor that saves "é" decomposed does not look like a hand edit.
+- **Clear errors** for invalid JSON, a corrupt state file, an unknown group, an old Node.js version, or a dotted key that collides with a nested one.
+- **Symbolic links** to locale folders are followed (once, so a link loop does no harm).
+
 ## Contributing
 
 Bug reports with a concrete example (source, language, output, expected) help most. See [CONTRIBUTING.md](CONTRIBUTING.md).

package/dist/budget.d.ts

@@ -0,0 +1,25 @@
+export declare class BudgetExceededError extends Error {
+}
+/**
+ * Token budget shared by every request of a run: a limit for the run and, optionally, a
+ * limit per UTC day that holds across runs (for scheduled jobs). Daily usage is kept in a
+ * small JSON file; a run that crosses midnight starts counting the new day.
+ */
+export declare class Budget {
+    readonly maxRunTokens: number;
+    readonly dailyTokens?: number | undefined;
+    private readonly usageFile?;
+    /** Tokens and requests of this run. */
+    tokens: number;
+    requests: number;
+    private usage;
+    constructor(maxRunTokens: number, dailyTokens?: number | undefined, usageFile?: string | undefined);
+    private load;
+    /** Tokens used today, including earlier runs. */
+    get usedToday(): number;
+    /** Why no further request may start, or null. */
+    get exceeded(): string | null;
+    /** Throws when the budget is used up. Called before each request. */
+    check(): void;
+    record(tokens: number): void;
+}

package/dist/budget.js

@@ -0,0 +1,74 @@
+import fs from 'node:fs';
+import { writeText } from './files.js';
+export class BudgetExceededError extends Error {
+}
+const utcDay = () => new Date().toISOString().slice(0, 10);
+/**
+ * Token budget shared by every request of a run: a limit for the run and, optionally, a
+ * limit per UTC day that holds across runs (for scheduled jobs). Daily usage is kept in a
+ * small JSON file; a run that crosses midnight starts counting the new day.
+ */
+export class Budget {
+    maxRunTokens;
+    dailyTokens;
+    usageFile;
+    /** Tokens and requests of this run. */
+    tokens = 0;
+    requests = 0;
+    usage;
+    constructor(maxRunTokens, dailyTokens, usageFile) {
+        this.maxRunTokens = maxRunTokens;
+        this.dailyTokens = dailyTokens;
+        this.usageFile = usageFile;
+        this.usage = this.load();
+    }
+    load() {
+        if (this.usageFile) {
+            try {
+                const data = JSON.parse(fs.readFileSync(this.usageFile, 'utf8'));
+                if (data.date === utcDay())
+                    return data;
+            }
+            catch {
+                // missing or unreadable: start the day at zero
+            }
+        }
+        return { date: utcDay(), tokens: 0, requests: 0 };
+    }
+    /** Tokens used today, including earlier runs. */
+    get usedToday() {
+        if (this.usage.date !== utcDay())
+            this.usage = { date: utcDay(), tokens: 0, requests: 0 };
+        return this.usage.tokens;
+    }
+    /** Why no further request may start, or null. */
+    get exceeded() {
+        if (this.tokens >= this.maxRunTokens)
+            return `token budget of ${this.maxRunTokens.toLocaleString('en')} for this run reached`;
+        if (this.dailyTokens !== undefined && this.usedToday >= this.dailyTokens) {
+            return `daily token budget of ${this.dailyTokens.toLocaleString('en')} reached (${this.usedToday.toLocaleString('en')} used today)`;
+        }
+        return null;
+    }
+    /** Throws when the budget is used up. Called before each request. */
+    check() {
+        const reason = this.exceeded;
+        if (reason)
+            throw new BudgetExceededError(reason);
+    }
+    record(tokens) {
+        this.tokens += tokens;
+        this.requests++;
+        this.usedToday; // rolls the day over if midnight passed
+        this.usage.tokens += tokens;
+        this.usage.requests++;
+        if (this.usageFile) {
+            try {
+                writeText(this.usageFile, JSON.stringify(this.usage, null, 2) + '\n');
+            }
+            catch {
+                // not fatal: the run limit still applies
+            }
+        }
+    }
+}

package/dist/checks.d.ts

@@ -1,4 +1,5 @@
 import type { Config } from './config.js';
+import { PluginHost } from './plugins.js';
 import { Scope } from './scope.js';
 /**
  * Deterministic quality checks. No API calls, so they can run in CI on every commit.
@@ -27,16 +28,26 @@ export declare const ERROR_CHECKS: Set<CheckName>;
 /** Checks a targeted repair (--fix-flagged) may try to fix. */
 export declare const FIXABLE_CHECKS: Set<CheckName>;
 export interface Issue {
-    check: CheckName;
+    /** A built-in check name, or a plugin's own check name. */
+    check: CheckName | (string & {});
     note?: string;
+    /** Set for plugin issues; built-in checks use ERROR_CHECKS. */
+    severity?: 'error' | 'warning';
+    /** Set for plugin issues; built-in checks use FIXABLE_CHECKS. */
+    fixable?: boolean;
 }
+/** Errors break the software (and fail `localewarden check`); everything else is a warning. */
+export declare const isError: (issue: Issue) => boolean;
+/** Whether `--fix-flagged` may ask the model to fix the issue. */
+export declare const isFixable: (issue: Issue) => boolean;
 export declare class Checker {
     readonly config: Config;
     readonly placeholderRe: RegExp;
     readonly scope: Scope;
     /** Words of termNotes and doNotTranslate: terms a translation may keep in the source language. */
     readonly keptWords: Set<string>;
-    constructor(config: Config);
+    readonly plugins: PluginHost;
+    constructor(config: Config, plugins?: PluginHost);
     /** The text without doNotTranslate names, which stay the same in every language. */
     withoutNames(text: string): string;
     /** "62 characters, limit 60", or null. */
@@ -45,7 +56,7 @@ export declare class Checker {
     placeholdersMatch(key: string, source: string, text: string): boolean;
     placeholderNote(source: string, text: string): string;
     /** All issues of one translated string. */
-    checkString(lang: string, key: string, source: string, text: string): Issue[];
+    checkString(lang: string, key: string, source: string, text: string, file?: string): Issue[];
     /**
      * Output check right after the API call.
      *   hard: certain corruption (placeholders, foreign alphabet, changed link targets, broken
@@ -53,7 +64,7 @@ export declare class Checker {
      *   soft: likely loss (tag count, missing year, source words left in). Retried once, then
      *         accepted; `localewarden check` keeps reporting it.
      */
-    defect(lang: string, key: string, source: string, text: string): {
+    defect(lang: string, key: string, source: string, text: string, file?: string): {
         hard: string | null;
         soft: string | null;
     };

package/dist/checks.js

@@ -1,5 +1,6 @@
 import { placeholderRegExp, placeholderSignature, placeholdersMatch } from './placeholders.js';
 import { GENDERED_FORMS, NO_AMPERSAND_LANGUAGES, SENTENCE_CASE_LANGUAGES, formalityRule, registerFor, withoutQuotedSpeech, } from './style.js';
+import { PluginHost } from './plugins.js';
 import { Scope } from './scope.js';
 import { baseLanguage, escapeRegExp, isTraditionalChinese } from './util.js';
 export const CHECKS = [
@@ -29,14 +30,20 @@ export const FIXABLE_CHECKS = new Set([
     'glossary',
     'partial',
 ]);
+/** Errors break the software (and fail `localewarden check`); everything else is a warning. */
+export const isError = (issue) => issue.severity === 'error' || ERROR_CHECKS.has(issue.check);
+/** Whether `--fix-flagged` may ask the model to fix the issue. */
+export const isFixable = (issue) => issue.fixable ?? FIXABLE_CHECKS.has(issue.check);
 export class Checker {
     config;
     placeholderRe;
     scope;
     /** Words of termNotes and doNotTranslate: terms a translation may keep in the source language. */
     keptWords;
-    constructor(config) {
+    plugins;
+    constructor(config, plugins = new PluginHost()) {
         this.config = config;
+        this.plugins = plugins;
         this.placeholderRe = placeholderRegExp(config.placeholders);
         this.scope = new Scope(config);
         this.keptWords = new Set([...Object.keys(config.termNotes), ...config.doNotTranslate].flatMap(term => term.toLowerCase().split(/[^\p{L}]+/u)).filter(Boolean));
@@ -61,7 +68,7 @@ export class Checker {
         return `source has [${placeholderSignature(source, this.placeholderRe)}], got [${placeholderSignature(text, this.placeholderRe)}]`;
     }
     /** All issues of one translated string. */
-    checkString(lang, key, source, text) {
+    checkString(lang, key, source, text, file = '') {
         const issues = [];
         const add = (check, note) => issues.push({ check, note });
         const base = baseLanguage(lang);
@@ -136,6 +143,9 @@ export class Checker {
                 add('partial', 'hedge dropped: the source says "tend to", the translation states it as certain');
             }
         }
+        for (const issue of this.plugins.checks({ lang, key, file, source, text })) {
+            issues.push({ severity: 'warning', fixable: false, ...issue });
+        }
         return issues;
     }
     /**
@@ -145,9 +155,13 @@ export class Checker {
      *   soft: likely loss (tag count, missing year, source words left in). Retried once, then
      *         accepted; `localewarden check` keeps reporting it.
      */
-    defect(lang, key, source, text) {
+    defect(lang, key, source, text, file = '') {
         if (!text.trim())
             return { hard: 'empty translation', soft: null };
+        // A plugin error blocks writing, like a broken placeholder.
+        const pluginError = this.plugins.checks({ lang, key, file, source, text }).find(issue => issue.severity === 'error');
+        if (pluginError)
+            return { hard: `${pluginError.check}${pluginError.note ? `: ${pluginError.note}` : ''}`, soft: null };
         const placeholders = this.placeholdersMatch(key, source, text) ? null : `placeholder mismatch: ${this.placeholderNote(source, text)}`;
         const foreign = foreignScript(this.config.sourceLanguage, source) ? null : foreignScript(lang, text);
         const links = hrefSignature(source) !== hrefSignature(text) ? `links changed: [${hrefSignature(source)}] -> [${hrefSignature(text)}]` : null;

package/dist/cli.js

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 import fs from 'node:fs';
 import path from 'node:path';
-import { ConfigError, CONFIG_FILE, loadConfig } from './config.js';
+import { ConfigError, CONFIG_FILE, loadConfig, selectGroups } from './config.js';
+import { loadPlugins } from './plugins.js';
+import { startUi } from './ui/server.js';
 import { CHECKS } from './checks.js';
 import { findSourceFiles } from './files.js';
 import { isReasoningModel } from './llm.js';
@@ -14,6 +16,7 @@ Usage:
   localewarden [translate] [options]   translate new and changed strings
   localewarden check [options]         quality check, no API calls (use in CI)
   localewarden review [options]        list and resolve hand-edited translations
+  localewarden ui [--port 4848]        local web interface (127.0.0.1 only)
   localewarden init                    create ${CONFIG_FILE}
 
 Translate options:
@@ -21,15 +24,19 @@ Translate options:
   --lang de,fr           only these languages
   --fix-flagged          let the model fix strings the quality check flags
   --retranslate-all      translate every string again (hand edits stay protected)
+  --retranslate-files <patterns>  translate every string of these files again, e.g. "locales/{lang}/onboarding.json"
+  --refresh-before <YYYY-MM-DD>   translate again what was written before that day (or adopted)
+  --group app,web        only these groups (config "groups")
   --overwrite-manual     also replace hand-edited translations
   --max-tokens <n>       token budget for this run (default: maxTokensPerRun)
   --verbose              more output
 
 Check options:
   --lang de,fr           only these languages
+  --group app,web        only these groups
   --verbose, -v          list findings, not only counts
   --limit <n>            findings shown per check with --verbose (default 20)
-  --strict               exit 1 on warnings too (default: only placeholder/script errors)
+  --strict               exit 1 on warnings too (default: only errors)
   --json                 print findings as JSON
   --fix                  repair placeholders with exactly one possible fix ({heures} -> {hours})
 
@@ -43,7 +50,7 @@ Global:
   --config <path>        config file (default ./${CONFIG_FILE})
   --help, --version
 `;
-const VALUE_FLAGS = new Set(['--lang', '--max-tokens', '--config', '--limit', '--approve', '--release']);
+const VALUE_FLAGS = new Set(['--port', '--lang', '--group', '--max-tokens', '--config', '--limit', '--approve', '--release', '--retranslate-files', '--refresh-before']);
 function parseArgs(argv) {
     const args = { command: 'translate', flags: new Set(), values: new Map() };
     let commandSet = false;
@@ -76,6 +83,7 @@ function parseArgs(argv) {
     }
     return args;
 }
+const listArg = (args, name) => args.values.get(name)?.flatMap(value => value.split(',')).map(v => v.trim()).filter(Boolean);
 const languagesArg = (args) => args.values.get('--lang')?.flatMap(value => value.split(',')).map(l => l.trim()).filter(Boolean);
 function version() {
     const pkg = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
@@ -131,8 +139,14 @@ async function translateCommand(args) {
     const maxTokens = args.values.get('--max-tokens')?.[0];
     if (maxTokens !== undefined && !(Number(maxTokens) > 0))
         throw new ConfigError('--max-tokens must be a positive number');
+    const refreshBefore = args.values.get('--refresh-before')?.[0];
+    if (refreshBefore !== undefined && !/^\d{4}-\d{2}-\d{2}$/.test(refreshBefore))
+        throw new ConfigError('--refresh-before must be a date like 2026-10-01');
     const summary = await run(config, {
         languages: languagesArg(args),
+        groups: listArg(args, '--group'),
+        retranslateFiles: listArg(args, '--retranslate-files'),
+        refreshBefore,
         dryRun: args.flags.has('--dry-run'),
         retranslateAll: args.flags.has('--retranslate-all'),
         overwriteManual: args.flags.has('--overwrite-manual'),
@@ -150,6 +164,7 @@ async function translateCommand(args) {
         }
         // Rough: prompt overhead per request plus input and output text (~4 characters per token).
         const requests = Math.ceil(strings / config.batchSize) + Math.ceil(strings * 0.05);
+        // Groups may use different models; the estimate uses the first group's.
         const low = Math.round(requests * 900 + (chars / 4) * 2.2);
         const high = Math.round(low * (isReasoningModel(config.model) ? 3 : 1.5));
         console.log(`Dry run: ${strings} string(s), ${chars.toLocaleString('en')} characters to translate.`);
@@ -171,8 +186,10 @@ async function translateCommand(args) {
     if (rows.length === 0)
         console.log('Everything is up to date.');
     console.log(`\n${summary.filesWritten.length} file(s) written, ${summary.requests} request(s), ${summary.tokens.toLocaleString('en')} tokens.`);
+    if (summary.filesCopied.length > 0)
+        console.log(`${summary.filesCopied.length} file(s) copied to their regional locales.`);
     if (summary.stoppedByBudget)
-        console.log('Stopped at the token budget. Run again to continue.');
+        console.log(`Stopped: ${summary.stopReason ?? 'token budget reached'}. Run again to continue.`);
     if (summary.pendingReview > 0)
         console.log(`${summary.pendingReview} hand-edited translation(s) to review: npx localewarden review`);
     const failed = Object.values(summary.languages).some(s => s.failed > 0);
@@ -180,17 +197,21 @@ async function translateCommand(args) {
         console.log('Failed strings were not written and will be retried on the next run.');
     return 0;
 }
-function checkCommand(args) {
+async function checkCommand(args) {
     const config = loadConfig(args.values.get('--config')?.[0]);
-    const languages = languagesArg(args) ?? config.targetLanguages;
-    let findings = checkProject(config, languages);
+    const plugins = await loadPlugins(config);
+    const groupNames = listArg(args, '--group');
+    const groups = selectGroups(config, groupNames, languagesArg(args));
+    const languages = languagesArg(args) ?? [...new Set(groups.flatMap(g => g.targetLanguages))];
+    const options = { languages, groups: groupNames, plugins };
+    let findings = checkProject(config, options);
     if (args.flags.has('--fix')) {
         const fixed = fixPlaceholders(config, findings);
         for (const f of fixed)
             console.log(`fixed [${f.lang}] ${f.file} ${f.key}: ${f.text}`);
         console.log(`${fixed.length} placeholder(s) repaired.\n`);
         if (fixed.length > 0)
-            findings = checkProject(config, languages);
+            findings = checkProject(config, options);
     }
     if (args.flags.has('--json')) {
         console.log(JSON.stringify(findings, null, 2));
@@ -252,6 +273,9 @@ function reviewCommand(args) {
     return 0;
 }
 async function main() {
+    const major = Number(process.versions.node.split('.')[0]);
+    if (major < 20)
+        throw new ConfigError(`localewarden needs Node.js 20 or newer; this is ${process.versions.node}.`);
     const args = parseArgs(process.argv.slice(2));
     if (args.flags.has('--help')) {
         console.log(HELP);
@@ -265,12 +289,23 @@ async function main() {
         case 'translate':
             return translateCommand(args);
         case 'check':
-            return checkCommand(args);
+            return await checkCommand(args);
         case 'review':
             return reviewCommand(args);
         case 'init':
             init();
             return 0;
+        case 'ui': {
+            const config = loadConfig(args.values.get('--config')?.[0]);
+            const port = args.values.get('--port')?.[0];
+            if (port !== undefined && !/^\d+$/.test(port))
+                throw new ConfigError('--port must be a number');
+            const ui = await startUi(config, { port: port === undefined ? undefined : Number(port) });
+            console.log(`localewarden interface: ${ui.url}`);
+            console.log('Only reachable from this computer. Press Ctrl+C to stop.');
+            await new Promise(() => { }); // runs until Ctrl+C
+            return 0;
+        }
         default:
             throw new ConfigError(`Unknown command "${args.command}". See --help.`);
     }

package/dist/config.d.ts

@@ -1,3 +1,4 @@
+import type { PluginSpec } from './plugins.js';
 export type Register = 'formal' | 'informal';
 export interface Config {
     /** Language of the source files. Default "en". Several checks assume English. */
@@ -52,14 +53,39 @@ export interface Config {
     batchSize: number;
     /** Where state, review list and repair report live, relative to the config file. */
     stateDir: string;
+    /**
+     * Target locales that are a copy of another one instead of a translation, e.g. store
+     * listings: { "en-GB": "en-US", "fr-CA": "fr-FR" }. The value may be the source language.
+     */
+    copies: Record<string, string>;
+    /** Strings longer than this many characters are translated paragraph by paragraph. */
+    chunkChars: number;
+    /** Plugin modules (relative to the config file), see plugins.ts. */
+    plugins: PluginSpec[];
+    /** Token limit per UTC day across runs; usage is kept in <stateDir>/usage.json. */
+    dailyTokenBudget?: number;
+    /** Group name, when this config is one of `groups`. */
+    name?: string;
+    /**
+     * Parts of the project with their own files and settings, translated in this order
+     * (e.g. app UI first, long-form content last). Each group inherits the top-level settings.
+     */
+    groups?: Config[];
     /** Directory of the config file; all relative paths resolve against it. */
     root: string;
 }
 export declare const CONFIG_FILE = "localewarden.config.json";
-export declare const DEFAULTS: Omit<Config, 'targetLanguages' | 'files' | 'root'>;
+export declare const DEFAULTS: Omit<Config, 'targetLanguages' | 'files' | 'root' | 'groups' | 'name'>;
 export declare class ConfigError extends Error {
 }
 /** Validates a parsed config object and fills in defaults. */
 export declare function resolveConfig(raw: unknown, root: string): Config;
+/** The groups of a config, or the config itself as its only group. */
+export declare const groupsOf: (config: Config) => Config[];
+/**
+ * The groups to work on, in config order, limited by name; unknown group or language names
+ * are an error (a typo must not turn into "nothing to do" or a green check).
+ */
+export declare function selectGroups(config: Config, names?: string[], languages?: string[]): Config[];
 /** Loads the config file (default: localewarden.config.json in the working directory). */
 export declare function loadConfig(configPath?: string): Config;