localewarden 0.1.1 → 0.3.0

package/README.md

@@ -11,7 +11,7 @@ npx localewarden             # translate new and changed strings
 npx localewarden check       # quality check, no API calls (use it in CI)
 ```
 
-Works with i18next, react-intl / FormatJS, vue-i18n, next-intl, ngx-translate and any other setup that keeps strings in JSON files. Uses any OpenAI-compatible API (OpenAI, OpenRouter, a local Ollama, ...).
+Works with i18next, react-intl / FormatJS, vue-i18n, next-intl, ngx-translate and any other setup that keeps strings in JSON files, with Flutter (`.arb` files) and with fastlane's App Store / Play Store metadata (`.txt` files). Uses any OpenAI-compatible API (OpenAI, OpenRouter, a local Ollama, ...).
 
 ## Why
 
@@ -22,19 +22,30 @@ Translating locale files with a language model is easy once. Keeping 20 language
 - **Models are inconsistent across batches.** French screens mix "tu" and "vous", Spanish copies English Title Case ("Configure Su Cuenta"), and Polish or Russian address every user as a man.
 - **Broken output ships silently.** A translated placeholder (`{heures}` instead of `{hours}`) shows raw braces in your app. A dropped `</strong>` breaks the layout. Stray Cyrillic letters end up in a Danish sentence.
 
-localewarden grew out of the translation pipeline of a production app that ships in 38 languages. Every rule and check in it exists because one of these failures happened in real output.
+localewarden grew out of the translation pipeline of a production app that ships in 38 languages. Every rule and check in it exists because one of these failures happened in real output. The checks are tuned against that app's real texts (UI, website, long-form learning content and store listings, about 165 MB) to report problems without flooding you with false alarms. On those texts they still find things that slipped through earlier pipelines: sections cut off after the English grew, stray letters from other alphabets, a trial notice left in English.
+
+## How it compares
+
+- **Translation platforms** (Crowdin, Lokalise, Phrase, Weblate) are hosted services with editors, translator workflows and review for teams. localewarden is a small CLI that runs in your repository and CI, with no account and no server. If you have professional translators, a platform fits better. If a model translates and people only fix the odd string, this is the lighter setup.
+- **"Translate my JSON with GPT" scripts** usually send every string on every run and overwrite whatever is there. localewarden keeps state, so it only sends what changed, keeps human fixes, and checks the output.
+- **Editor extensions** (such as i18n Ally) help you write and look up keys while coding. localewarden is about filling and maintaining 10 to 40 languages afterwards. The two work well together.
 
 ## What it does
 
 - **Translates only what changed.** It remembers a hash of each source string per language. New strings are translated. Changed strings are *revised*: the model gets the existing translation and changes only what the source change requires. Removed strings are deleted from every language.
 - **Protects hand edits.** If someone edited a translation, localewarden detects it, keeps it, and lists it for review. If the source of a hand-edited string changes later, the string is flagged instead of overwritten.
-- **Checks every result before writing it.** Broken placeholders, injected HTML or scripts, foreign alphabets, changed links, broken HTML and echoed source text are rejected (retried once, then left for the next run). Softer problems are retried and reported.
+- **Checks every result before writing it.** Broken placeholders, injected HTML or scripts, foreign alphabets, changed links, broken HTML and echoed source text are rejected (retried once, then left for the next run). Softer problems (too long, content missing, words left in English) are retried and reported.
 - **Consistent style per language.** It enforces formal or informal address per language (`du`/`Sie`, `tu`/`vous`, `ты`/`вы` and 16 more), uses sentence case where the language does, avoids gendered forms for "you", and applies local typography (French spacing, `92 %` in German, CJK quotation marks).
 - **Plural forms per language.** For i18next-style keys (`item_one`, `item_other`) it adds the forms a language needs but English lacks, such as Polish `_few` and `_many` or Arabic `_zero`, `_two`, `_few` and `_many` (CLDR plural rules).
+- **Data files and store listings.** Fields like `id`, `type` or `image` are copied instead of translated (`ignoreKeys`), and so are URLs, email addresses and file paths. Length limits per key (`maxLength`) are passed to the model and checked: App Store names, SEO titles, buttons.
 - **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
@@ -79,7 +90,7 @@ es  Mantén vivas tus plantas sin tener que pensar en ello
 ja  何も考えなくても、植物を元気に保てます
 ```
 
-German uses "du" and French "vous", as configured. Spanish and French use sentence case, not the English Title Case. French has its space before "!". The hedge "tend to" survived, and so did the placeholders, the link and the brand name. The full example is in [`examples/basic`](examples/basic).
+German uses "du" and French "vous", as configured. Spanish and French use sentence case, not the English Title Case. French has its space before "!". The hedge "tend to" survived, and so did the placeholders, the link and the brand name. The full example is in [`examples/basic`](examples/basic). There are also examples for [Flutter ARB files](examples/flutter) and [App Store / Play Store texts with fastlane](examples/fastlane).
 
 ## Quick start
 
@@ -111,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
 
@@ -135,24 +151,28 @@ The same checks run in two places. Right after each model answer, a failed hard
 | --- | --- | --- |
 | `placeholder` | `{name}`, `{{count}}`, `%s`, `%1$d`, `%{x}`, `${x}`, `<0></0>` renamed, translated, added or dropped. ICU `plural`/`select` arguments are compared, while plural categories may differ per language. | error |
 | `unsafe` | HTML tags, attributes, event handlers or `javascript:`/`data:` URLs that the source does not have. Translations are often rendered as raw HTML, so this would be a script injection. | error |
-| `script` | Letters from an alphabet the language does not use ("刺激" in German), or a word that mixes Latin with Cyrillic/Greek lookalikes ("Вarda") | error |
+| `script` | Letters from an alphabet the language does not use ("刺激" in German), a word that mixes Latin with Cyrillic/Greek lookalikes ("Вarda"), or Simplified characters in Traditional Chinese (`zh-TW`) and the reverse | error |
 | `markup` | Changed link targets, different number of tags, unclosed or misnested tags, dropped list items | warning (broken tags and changed links: never written) |
 | `years` | A year from the source missing or changed (citations, dates) | warning |
 | `formality` | The other form of address than configured, both forms in one string, or masculine-only forms for "you" | warning |
+| `length` | Longer than the `maxLength` configured for the key | warning |
 | `titlecase` | English Title Case copied into a language that uses sentence case | warning |
 | `ampersand` | "&" in languages that write the word | warning |
 | `glossary` | A glossary rendering missing (case endings allowed), or a `doNotTranslate` name translated | warning |
 | `untranslated` | Identical to the source (prose of 3+ words; "OK" and names are fine) | warning |
-| `partial` | Source-language words left inside the translation, an untranslated bold lead-in, or a hedge that became certainty ("tend to" stated as fact) | warning |
+| `partial` | Source-language words left inside the translation, an untranslated bold lead-in, a hedge that became certainty ("tend to" stated as fact), a translation much shorter than its source (content cut off, or the source grew after it was translated), or sibling options that got the same translation although the source differs ("Rarely" and "Occasionally" both "Selten") | warning |
 
 ```bash
 npx localewarden check              # counts per language and check
 npx localewarden check -v           # with examples
 npx localewarden check --strict     # exit 1 on warnings too
 npx localewarden check --json       # for scripts
+npx localewarden check --fix        # repair placeholders with one possible fix, no API calls
 ```
 
-Approved hand edits are skipped, except for errors (placeholder, unsafe, script), which break the app either way.
+`--fix` repairs a translated placeholder when the source has exactly one and the translation renamed it (`{stunden}` back to `{hours}`). The file is edited in place, so its formatting stays as it is. Anything less certain is left for `--fix-flagged` or a person.
+
+Approved strings are skipped, except for errors (placeholder, unsafe, script), which break the app either way. You can approve any string, not only hand edits: `npx localewarden review --approve de:home.title` tells the check that a person looked at it (for example a pun on a brand name that is correct without the name), and runs leave it alone.
 
 ### In CI
 
@@ -211,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
@@ -240,6 +276,9 @@ npx localewarden review --release de:home.title   # hand it back: next run revis
 | `glossary` | `{}` | `{"fr": {"Terms of Service": "Conditions d'utilisation"}}` |
 | `termNotes` | `{}` | Meanings of ambiguous terms, sent only with strings that contain them: `{"snooze": "postpone a reminder"}` |
 | `instructions` | `{}` | Extra instructions per language, `"*"` for all: `{"es": "Use neutral Latin American Spanish."}` |
+| `ignoreKeys` | `[]` | Keys that are not text, copied from the source: `["id", "type", "**.sources.*"]`. `*` matches within a key segment, `**` across segments; a pattern without a dot matches the last segment anywhere. URLs, emails, file paths and numbers are always copied. |
+| `exclude` | `[]` | Source files to skip: `["locales/{lang}/nav.json"]` |
+| `maxLength` | `{}` | Character limits per key pattern: `{"**.meta.title": 60, "name": 30}`. The model is told the limit; longer results are retried once and reported by the `length` check. |
 | `placeholders` | built-in | Regular expressions (strings) that match your placeholders. Replaces the built-in list. |
 | `model` | `"gpt-5.4-mini"` | Any chat model your endpoint offers |
 | `baseUrl` | `"https://api.openai.com/v1"` | Any OpenAI-compatible endpoint |
@@ -250,6 +289,102 @@ 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)
+
+```json
+{
+  "sourceLanguage": "en-US",
+  "targetLanguages": ["de-DE", "fr-FR", "ja"],
+  "files": "fastlane/metadata/{lang}/*.txt",
+  "exclude": ["fastlane/metadata/{lang}/*_url.txt"],
+  "maxLength": { "name": 30, "subtitle": 30, "keywords": 100, "promotional_text": 170, "description": 4000 },
+  "termNotes": { "keywords": "a comma-separated keyword list for store search, not a sentence" }
+}
+```
+
+Each `.txt` file is one string, keyed by its file name, so the limits above apply to `name.txt`, `subtitle.txt` and so on.
+
+### Flutter (ARB)
+
+```json
+{ "files": "lib/l10n/app_{lang}.arb", "targetLanguages": ["de", "fr", "pt_BR"] }
+```
+
+Metadata (`@@locale`, `@key` descriptions and placeholders) is copied, not translated, and `@@locale` is set to the target language. ICU plurals and selects keep their structure, and each language gets the plural categories it needs.
+
+### Data files
+
+For content JSON with ids, types and links, list the non-text keys:
+
+```json
+{ "files": "content/**/*.{lang}.json", "ignoreKeys": ["id", "type", "category", "image", "**.sources.*"] }
+```
 
 ### Other providers
 
@@ -266,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
+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
 ```
@@ -300,11 +437,23 @@ Translations are treated as untrusted: any markup the source does not have is bl
 
 ## Limitations
 
-- JSON only (nested objects, arrays, flat keys). YAML, PO, XLIFF and ARB are not supported yet.
+- JSON (nested objects, arrays, flat keys), Flutter ARB and plain `.txt` files. YAML, PO and XLIFF are not supported yet.
 - The checks catch mechanical problems, not every wrong meaning. Have a native speaker look at important screens, then approve their edits with `review`.
 - 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,6 @@
 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.
  *
@@ -11,31 +13,50 @@ import type { Config } from './config.js';
  *   years         a year from the source is missing or changed (citations, dates)
  *   formality     the other form of address than configured, or both mixed;
  *                 masculine-only forms for "you" when genderNeutral is on
+ *   length        longer than the maxLength configured for the key
  *   titlecase     English Title Case copied into a sentence-case language
  *   ampersand     "&" in a language that writes the word
  *   glossary      a glossary rendering or a doNotTranslate name is missing
  *   untranslated  identical to the source (prose of 3+ words)
  *   partial       source-language words left inside an otherwise translated string,
- *                 or a dropped hedge ("tend to" stated as certain)
+ *                 a dropped hedge ("tend to" stated as certain), or a translation much
+ *                 shorter than its source (content missing or cut off)
  */
-export type CheckName = 'placeholder' | 'unsafe' | 'script' | 'markup' | 'years' | 'formality' | 'titlecase' | 'ampersand' | 'glossary' | 'untranslated' | 'partial';
+export type CheckName = 'placeholder' | 'unsafe' | 'script' | 'markup' | 'years' | 'formality' | 'length' | 'titlecase' | 'ampersand' | 'glossary' | 'untranslated' | 'partial';
 export declare const CHECKS: CheckName[];
 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;
-    constructor(config: Config);
+    readonly scope: Scope;
+    /** Words of termNotes and doNotTranslate: terms a translation may keep in the source language. */
+    readonly keptWords: Set<string>;
+    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. */
+    tooLong(key: string, text: string): string | null;
     get englishSource(): boolean;
     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
@@ -43,13 +64,15 @@ 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;
     };
 }
 /** Non-Latin scripts each language is written in. Latin is always allowed (names, codes). */
 export declare const NATIVE_SCRIPTS: Record<string, string[]>;
+/** Simplified characters in Traditional Chinese text, or the reverse (2+ distinct ones). */
+export declare function wrongChineseScript(lang: string, text: string): string | null;
 /** Why `text` contains letters that cannot belong to `lang`, or null. */
 export declare function foreignScript(lang: string, text: string): string | null;
 /**
@@ -82,3 +105,8 @@ export declare function isUnchangedProse(source: string, text: string, placehold
  * allowed) copied into the translation, or null.
  */
 export declare function sourceRun(source: string, text: string): string | null;
+/**
+ * A translation with a fraction of the source's length lost content: cut off by the model, or
+ * the source grew after it was translated. Markup and placeholders are not counted.
+ */
+export declare function muchShorter(lang: string, source: string, text: string): string | null;