champollion 0.3.4 → 0.4.0

package/README.md

@@ -16,6 +16,8 @@ npx champollion sync
 
 Champollion auto-detects your locale files, their format, and the target languages. It translates missing keys, skips what's already done, and writes the results. That's it.
 
+**License:** source-available under the [PolyForm Noncommercial License 1.0.0](LICENSE) — free to use, change and share for noncommercial purposes (personal projects, research, teaching, and use by charities, schools and public bodies). Using it for a commercial purpose is not covered by this license. The evaluation harness is open source (AGPL-3.0-or-later). [Who may use this](https://champollion.dev/docs/getting-started/who-may-use-this) · [Details](#license).
+
 > **Part of Champollion** — infrastructure for trustworthy machine-translation
 > evaluation across every language, source-available and free for noncommercial
 > use (the evaluation harness and shared registries are open source). This CLI is the
@@ -160,6 +162,7 @@ Champollion supports 10 translation methods. Each language pair can use a differ
 | `openai` | `OPENAI_API_KEY` | Direct OpenAI API (gpt-4o, gpt-4o-mini) |
 | `anthropic` | `ANTHROPIC_API_KEY` | Direct Anthropic API (Claude Sonnet, Haiku, Opus) |
 | `gemini` | `GEMINI_API_KEY` | Direct Google Gemini API (Flash, Pro) — free tier available |
+| `local` | *(none)* | Your own model behind an OpenAI-compatible endpoint (Ollama, vLLM, LM Studio, a model trained with `nmt-forge`). Set `LOCAL_API_BASE` if it is not at Ollama's default. Text never leaves your infrastructure |
 
 **Traditional MT** — best for speed, cost, and high-volume key-value pairs:
 
@@ -203,7 +206,7 @@ Plugins are pre-packaged translation recipes for specific language pairs. They'r
 champollion plugin install ./french-formal-v1/    # install from directory
 champollion plugin list                           # see installed plugins
 champollion plugin remove french-formal-v1        # uninstall
-champollion status                                # shows quality tiers + benchmarks
+champollion status                                # shows each pair's method, model + plugin benchmarks
 ```
 
 See [the reference docs](https://champollion.dev/docs/reference/plugin-spec) for the manifest format.
@@ -217,12 +220,8 @@ See [the reference docs](https://champollion.dev/docs/reference/plugin-spec) for
 | `serve` | Serve this project's translation stack over HTTP (api-method contract) |
 | `watch` | Auto-sync on file changes |
 | `audit` | Flag incomplete locales (CI gate) |
-| `card` | Pretty-print a language card (`card <code>`, `--json` for raw) |
-| `register-corpus` | Register an evaluation corpus: pick a license + exposure tier (local-only/private/public/sealed) |
-| `seal-corpus` | Sealed-tier crypto verbs: `keygen` / `seal` / `open` (organizer-node bridge) |
-| `submit` | Propose an index entry (review-gated) — prints a pre-filled GitHub issue |
 | `lint` | Find hardcoded strings in source code |
-| `status` | Show pair configuration, methods, registers, and quality tiers |
+| `status` | Show pair configuration, methods, registers, and plugin benchmarks |
 | `provenance` | Audit translation resource licensing |
 | `wrap` | Auto-wrap hardcoded strings in `t()` calls (with undo) |
 | `seo` | Generate hreflang, sitemap.xml, or JSON-LD schema |
@@ -233,10 +232,21 @@ See [the reference docs](https://champollion.dev/docs/reference/plugin-spec) for
 | `xliff` | Export/import XLIFF 1.2 for professional translator review |
 | `models` | List available models for a provider (`--method gemini`) |
 | `verify` | Re-read written locale files and confirm translations are present and correct (CI gate) |
-| `leaderboard` | Show the MT leaderboard (`--pair`, `--sort`, `--install N`) |
-| `recommend` | Method guidance for a pair — availability + cited evidence (`--use`, `--json`) |
 | `doctor` | System health check: cards, config, methods, and converters |
 
+The commands that work with the shared index and leaderboard, rather than your
+project, are grouped under `champollion network` (each also works without the
+prefix):
+
+| Command | Purpose |
+|---------|---------|
+| `network card` | Pretty-print a language card (`network card <code>`, `--json` for raw) |
+| `network recommend` | Method guidance for a pair — availability + cited evidence (`network recommend eng fra`, `--use`, `--json`) |
+| `network leaderboard` | Show the MT leaderboard (`--pair`, `--sort`, `--install N`) |
+| `network register-corpus` | Register an evaluation corpus: pick a license + exposure tier (local-only/private/public/sealed) |
+| `network seal-corpus` | Sealed-tier crypto verbs: `keygen` / `seal` / `open` (organizer-node bridge) |
+| `network submit` | Propose an index entry (review-gated) — prints a pre-filled GitHub issue |
+
 Run `champollion <command> --help` for detailed help on any command.
 
 Full reference: [the reference docs](https://champollion.dev/docs/reference/cli)
@@ -247,7 +257,7 @@ Full reference: [the reference docs](https://champollion.dev/docs/reference/cli)
 
 ```bash
 mkdir -p .githooks
-printf '#!/bin/sh\nnpx champollion lint\n' > .githooks/pre-commit
+printf '#!/bin/sh\nnpx --yes champollion@0.4 lint\n' > .githooks/pre-commit   # pinned: a new release never changes what the hook runs
 chmod +x .githooks/pre-commit
 git config core.hooksPath .githooks   # once per clone
 ```
@@ -284,8 +294,9 @@ Create `champollion.config.json` or run `champollion init`:
 | Option | Default | Description |
 |--------|---------|-------------|
 | `inputLocale` | `"en"` | Source language code |
-| `localesDir` | `"./locales"` | Path to locale files |
-| `contentDir` | `null` | Hugo content directory (enables Markdown translation) |
+| `localesDir` | `"./locales"` | Path to locale files: one file per language (`fr.json`) or one folder per language (`fr/common.json`, i18next) |
+| `localesPattern` | `null` | Any other layout, e.g. `"src/i18n/{ns}/{lang}.json"` (replaces `localesDir`) |
+| `contentDir` | `null` | Folder of Markdown/MDX to translate (a Hugo `content/` or any folder); each translation is written beside its source as `<name>.<locale>.md` |
 | `format` | `"auto"` | File format: `json`, `toml`, `yaml`, or `auto` |
 | `model` | `"google/gemini-3.5-flash"` | Default model (OpenRouter slug). Direct providers resolve their own default at runtime. Run `champollion models --method gemini` to discover available models. |
 | `defaultMethod` | `"llm"` | Default translation method (overridden by `--method` flag) |
@@ -302,7 +313,7 @@ Create `champollion.config.json` or run `champollion init`:
     "crk": {
       "name": "Plains Cree",
       "register": "SRO syllabics with grammatical precision.",
-      "model": "google/gemini-2.5-pro",
+      "model": "google/gemini-3.1-pro-preview",
       "batchSize": 5,
       "maxRetries": 5,
       "script": "Cans"
@@ -322,30 +333,34 @@ See the [CLI Reference](https://champollion.dev/docs/reference/cli) for framewor
 When you run `sync`, champollion shows exactly what's happening:
 
 ```
-champollion v0.1.0
+champollion v0.4.0
 
 [INFO] Detected format: json (auto)
 [INFO] Detected framework: Hugo
-[INFO] Source: en.json (2,847 keys)
+[INFO] Source: en.json (2847 keys)
 [INFO] Pairs: es-MX:llm, fr:deepl, it:llm
-[INFO] Estimated translation cost:
+Estimated translation cost:
 
-  Pair       Method   Keys  Est. Cost
-  ────────   ──────   ────  ─────────
-  en:es-MX   llm      2847    ~$0.8400
-  en:fr      deepl    2847    ~$0.5694
-  en:it      llm      2847    ~$0.8400
+  Pair      Method    Keys  TM hits   Est. Cost
+  ────────  ──────  ──────  ───────  ──────────
+  en:es-MX  llm       2847        0    ~$0.3843
+  en:fr     deepl     2847        0    ~$1.7794
+  en:it     llm       2847        0    ~$0.3843
 
-  Total: ~$2.2494
+  Total: ~$2.5480
+  Rates: google/gemini-3.5-flash $0.30 input / $2.50 output per 1M tokens — OpenRouter's price list, read 2026-10-04 14:02 UTC; deepl $25.00 per 1M characters — the provider's published price, as checked 2026-06-08. An estimate: ~200 input + ~30 output tokens or ~25 characters per key assumed — the bill depends on the real lengths (--json has the detail).
 
-[INFO] es-MX.json — 2,847 missing
+[INFO] Translating 3 locale(s) with concurrency 50
+[INFO] es-MX.json — 2847 missing
+     ████████████████████████████████ 2,847/2,847 keys
+[INFO] fr.json — 2847 missing
      ████████████████████████████████ 2,847/2,847 keys
-[INFO] fr.json — 2,847 missing
+[INFO] it.json — 2847 missing
      ████████████████████████████████ 2,847/2,847 keys
-[OK] Synced 5,694 keys total.
+[OK] Synced 8541 keys total — 8541 key(s) sent to the model, 0 served from the cache (free).
 ```
 
-The progress bar updates in-place as each batch completes (~80 keys per update). Framework detection shows `Hugo` when `contentDir` is set. Format detection distinguishes `(auto)` from `(config)` to clarify how the format was resolved.
+The estimate's last line names the rate each figure was priced at, where it came from and when (`--json` carries the detail). "Translating …" is said only when something will be sent: a dry run, or a run with nothing to send, says it is checking the locales instead. The progress bar updates in-place as each batch completes (~80 keys per update). When `contentDir` is set, sync names the folder and where its translations go; it says `Detected framework: Hugo` only when it finds a real Hugo site (`hugo.toml`, a `config.toml` with Hugo settings, `archetypes/`, …). Format detection distinguishes `(auto)` from `(config)` to clarify how the format was resolved.
 
 **Output modes**: `--quiet` suppresses informational output (errors and warnings only). `--json` emits machine-readable NDJSON for CI/CD pipelines.
 
@@ -384,4 +399,4 @@ npm run test:methods             # translation method suite
 
 ## License
 
-PolyForm Noncommercial 1.0.0. The Champollion CLI is source-available — free to install, use, and modify for noncommercial purposes (research, education, community work) under the [PolyForm Noncommercial License 1.0.0](LICENSE); commercial use requires the licensor's permission. The published `champollion` npm package is PolyForm-Noncommercial-1.0.0; `cli/LICENSE` is the authoritative license for the distributed package. The companion MT Eval Harness and specs are open source, licensed AGPL-3.0-or-later — with a §7 eval-standard-plugin exception — at the public [harness repository](https://github.com/gamedaysuits/Champollion).
+PolyForm Noncommercial 1.0.0. The Champollion CLI is source-available — free to install, use, and modify for noncommercial purposes (research, education, community work) under the [PolyForm Noncommercial License 1.0.0](LICENSE); using it for a commercial purpose is not covered by this license. In plain words, with examples — a school, a public hospital or clinic, a charity, a personal or research project is covered; a for-profit business's product, such as a shop's storefront, is not: [Who may use this](https://champollion.dev/docs/getting-started/who-may-use-this) (a summary, not legal advice; the license text governs). The published `champollion` npm package is PolyForm-Noncommercial-1.0.0; `cli/LICENSE` is the authoritative license for the distributed package. The companion MT Eval Harness and specs are open source, licensed AGPL-3.0-or-later — with a §7 eval-standard-plugin exception — at the public [harness repository](https://github.com/gamedaysuits/Champollion).

package/bin/cli.js

@@ -34,10 +34,17 @@ const CLI_OPTIONS = {
     version:          { type: 'boolean', short: 'v' },
     yes:              { type: 'boolean', short: 'y' },
     'warn-only':      { type: 'boolean' },
+    strict:           { type: 'boolean' },  // verify --strict: warnings fail the check (exit 1)
     'no-verify':      { type: 'boolean' },  // skip post-sync verification
     undo:             { type: 'boolean' },
     'force-content':  { type: 'boolean' },  // ignore the content lock (TM still serves unchanged bodies/blocks)
+    files:          { type: 'string', multiple: true },  // sync: only these content files (glob, repeatable)
+    retranslate:    { type: 'string', multiple: true },  // sync: translate these content files fresh (glob, repeatable)
+    redo:           { type: 'string', multiple: true },  // sync: queue again — all | keys:<k> | content | files:<glob> (lib/redo.js)
+    fresh:          { type: 'boolean' },  // sync: do not use the cache for what is queued (billed again)
+    prune:          { type: 'string', multiple: true },  // sync: remove what the locale cannot use — plural-extras (i18next keys for forms the language does not have)
     'no-tm':          { type: 'boolean' },  // skip Translation Memory for this sync run
+    'fresh-on-model-change': { type: 'boolean' },  // don't reuse other models' TM entries
     css:              { type: 'boolean' },  // fonts install --css: generate CSS snippet
     json:             { type: 'boolean' },  // machine-readable NDJSON output
     quiet:            { type: 'boolean', short: 'q' },  // suppress info/ok messages, show only warnings/errors
@@ -49,12 +56,14 @@ const CLI_OPTIONS = {
     'content-dir': { type: 'string' },
     source:        { type: 'string' },
     langs:         { type: 'string' },
+    script:        { type: 'string' },     // init: writing system per target, e.g. crk=Cans (a language with two real orthographies)
     model:         { type: 'string' },
     method:        { type: 'string' },
     format:        { type: 'string' },
     'base-url':    { type: 'string' },
     out:           { type: 'string' },
     src:           { type: 'string' },
+    ignore:        { type: 'string' },     // lint: comma-separated directory/file names to skip
     'min-length':  { type: 'string' },
     'force-keys':  { type: 'string' },
     'list-keys':   { type: 'boolean' },    // sync --dry: name every queued key per reason
@@ -63,7 +72,8 @@ const CLI_OPTIONS = {
     'json-concurrency':    { type: 'string' },     // max parallel API calls for JSON key-value translation (default: 50)
     'content-concurrency': { type: 'string' },     // max parallel API calls for markdown content (default: 12)
     'batch-size':  { type: 'string' },     // keys per translation API call (positive integer; overrides config batchSize)
-    'max-cost':    { type: 'string' },     // sync: USD cap — abort (exit 2) before any API call if the estimate exceeds it or is unknown
+    'max-cost':    { type: 'string' },
+    'show-prompt': { type: 'string' },     // sync --dry: print the exact request the method would get (optionally for one key)     // sync: USD cap — abort (exit 2) before any API call if the estimate exceeds it or is unknown
     temperature:   { type: 'string' },     // sampling temperature for LLM methods
     'coaching-file': { type: 'string' },   // path to coaching prompt text file
     locale:        { type: 'string' },     // target locale for xliff export, tm clear/seed
@@ -80,7 +90,7 @@ const CLI_OPTIONS = {
     license:       { type: 'string' },     // register-corpus: license key / SPDX id / list number
     tier:          { type: 'string' },     // register-corpus: exposure tier (local-only|private|public)
     exposure:      { type: 'string' },     // register-corpus: alias for --tier
-    name:          { type: 'string' },     // register-corpus: corpus name
+    name:          { type: 'string' },     // register-corpus: corpus name; init: display name of a language with no card (qaa="…")
     publisher:     { type: 'string' },     // register-corpus: publisher / author
     description:   { type: 'string' },     // register-corpus: one-line description
     'source-lang': { type: 'string' },     // register-corpus: source language code (alt to --pair)
@@ -90,10 +100,12 @@ const CLI_OPTIONS = {
     'license-url': { type: 'string' },     // register-corpus: upstream license URL
     builder:       { type: 'string' },     // register-corpus: builder adapter id
     sha256:        { type: 'string' },     // register-corpus: built-corpus hash (optional)
+    data:          { type: 'string' },     // register-corpus: the local file the card describes (hashed, never uploaded)
     contamination: { type: 'string' },     // register-corpus: NONE|LOW|MEDIUM|HIGH
     domain:        { type: 'string' },     // register-corpus: corpus domain
     size:          { type: 'string' },     // register-corpus: number of sentence pairs
     id:            { type: 'string' },     // register-corpus: override card id
+    role:          { type: 'string' },     // register-corpus: test|dev|train — in the id only when stated
     version:       { type: 'string' },     // register-corpus: corpus version (major)
     'do-not-train': { type: 'boolean' },   // register-corpus: benchmark-integrity flag (default true)
     'cards-dir':   { type: 'string' },     // register-corpus: corpora-cards dir override (advanced/testing)
@@ -133,7 +145,8 @@ const CLI_OPTIONS = {
     'max-cost-per-request':  { type: 'string' },   // serve: USD cap per request (unknown estimates refuse)
     'max-session-cost':      { type: 'string' },   // serve: USD spend ceiling for the server process
     'emit-manifest':         { type: 'boolean' },  // serve: write the consumer method.json and exit
-    endpoint:                { type: 'string' },   // serve --emit-manifest: public endpoint URL for the manifest
+    endpoint:                { type: 'string' },   // serve --emit-manifest: public endpoint URL; init --method api: the champollion API endpoint
+    'accepts-instructions':  { type: 'string' },   // init --method api: does the endpoint follow per-key instructions (true|false)
 };
 
 const { values, positionals } = parseArgs({
@@ -169,6 +182,17 @@ const args = { _: positionals, ...values };
 // --dry-run is an alias for --dry — merge so command modules only check args.dry
 if (args['dry-run']) args.dry = true;
 
+// --redo / --fresh are the one way to say "translate this again"; they are
+// rewritten into the older flags here so sync keeps one set of semantics.
+if (args.redo !== undefined || args.fresh) {
+  const { applyRedo } = await import('../lib/redo.js');
+  const redoError = applyRedo(args);
+  if (redoError) {
+    console.error(`[ERR] ${String(redoError).replace(/\u0004/g, '\u2404')}`);
+    process.exit(1);
+  }
+}
+
 /**
  * Exit only once stdout has actually been written.
  *
@@ -187,7 +211,24 @@ function exitWhenFlushed(code) {
   process.stdout.write('', () => process.exit(code));
 }
 
-const command = args._[0] || 'help';
+// `champollion network <command>` — the commands that work with the shared
+// index and leaderboard rather than this project. Each also works without
+// the prefix (the names people already use).
+// (scripts/check_doc_commands.py reads COMMAND_GROUPS to check the docs.)
+const COMMAND_GROUPS = {
+  network: ['card', 'recommend', 'leaderboard', 'register-corpus', 'seal-corpus', 'submit'],
+};
+const NETWORK_COMMANDS = COMMAND_GROUPS.network;
+let command = args._[0] || 'help';
+if (command === 'network' && args._[1]) {
+  if (!NETWORK_COMMANDS.includes(args._[1])) {
+    console.error(`[ERR] Unknown network command: "${args._[1]}"`);
+    console.error(`      Network commands: ${NETWORK_COMMANDS.join(', ')}`);
+    process.exit(1);
+  }
+  args._ = args._.slice(1);
+  command = args._[0];
+}
 const cwd = process.cwd();
 
 // -----------------------------------------------------------------
@@ -264,11 +305,18 @@ if (args.help && command !== 'help') {
       .then(mod => mod.run(args, cwd))
       .then(code => exitWhenFlushed(code || 0))
       .catch(err => {
-        console.error(`[ERR] ${command} failed:`, err.message);
+        // A gettext context key in the message shows its U+0004 as "␄",
+        // the form --redo keys: accepts back (lib/output.js showKey).
+        console.error(`[ERR] ${command} failed:`, String(err.message).replace(/\u0004/g, '\u2404'));
         exitWhenFlushed(1);
       });
   } else if (command === 'help') {
     import('../lib/commands/help.js').then(mod => mod.run());
+  } else if (command === 'network') {
+    import('../lib/command-help.js').then(({ showCommandHelp }) => {
+      showCommandHelp('network');
+      process.exit(0);
+    });
   } else {
     // Unknown command — error loudly so CI typos don't silently pass
     console.error(`[ERR] Unknown command: "${command}"`);

package/index.js

@@ -15,8 +15,11 @@
  *     getRegisterPresets, getFormality, getGenderGuidance, getAllLanguageCodes,
  *     resolveCode
  *   - Sync: runSync, runContentSync
+ *   - One pair's pipeline: translateWithFallback, translateAndValidate,
+ *     previewRequests, createFallbackBudget
+ *   - Locale layout: discoverLocaleLayout, resolveLocaleFiles
  *   - Quality: validateTranslations
- *   - Utilities: loadApiKey, getEnvOrFileVar
+ *   - Utilities: loadApiKey, getEnvOrFileVar, costLabel
  */
 
 // ── Translation method classes ─────────────────────────────────────
@@ -49,6 +52,19 @@ export {
 } from './lib/config.js';
 export { resolvePairs } from './lib/pairs.js';
 
+// ── Writing systems (a pair's `script`) ────────────────────────────
+// The same decision sync makes: a locale with two real orthographies (crk,
+// sr) refuses until one is chosen; a chosen display script is produced by
+// converting the working-script translation. The MCP translate tool uses
+// these so it never picks an orthography sync would refuse to pick.
+export {
+  resolveTargetScript,
+  formatScriptChoiceError,
+  convertScript,
+  applyScriptFallback,
+  getConverterInfo,
+} from './lib/scripts.js';
+
 // ── Language cards & registers ─────────────────────────────────────
 export {
   getLanguageCard,
@@ -60,6 +76,10 @@ export {
   getAllLanguageCodes,
   getMethodSupport,
   resolveCode,
+  // A code or a language NAME ("French") → the code to work in; with a
+  // project's locales, the project's own spelling ("fr"). Never guesses.
+  findLanguagesByName,
+  resolveLanguageInput,
   // Dynamic card tier (packaged installs): warm the per-user cache up
   // front instead of paying a per-miss synchronous fetch.
   prefetchLanguageCards,
@@ -83,12 +103,39 @@ export {
 // ── Sync pipeline ──────────────────────────────────────────────────
 export { runSync, runContentSync } from './lib/sync.js';
 
+// ── One pair's translation pipeline ────────────────────────────────
+// What `champollion sync` and `serve` run for a batch of keys: cache →
+// method → quality gate → cache, then the pair's fallback for what that
+// left (a resolved pair from resolvePairs; `options.tm` from loadTM;
+// `options.cwd` = the project directory, where methods read their key,
+// endpoint, coaching and glossary). The MCP translate tool runs a project's
+// fallback through it. createFallbackBudget caps a fallback under a cost.
+export { translateWithFallback, translateAndValidate, previewRequests } from './lib/translate-pair.js';
+export { createFallbackBudget } from './lib/fallback.js';
+
+// ── Locale layout ───────────────────────────────────────────────────
+// Which files make up each locale (flat, folder per locale, localesPattern)
+// — the same answer sync, verify and xliff use, for build scripts and
+// agents that need to find a project's locale files.
+export { discoverLocaleLayout, resolveLocaleFiles } from './lib/locale-layout.js';
+
 // ── Quality gate ───────────────────────────────────────────────────
-export { validateTranslations } from './lib/validate.js';
+// The shared-output rule (one text for several different sources) — the MCP
+// translate tool holds its answers to it, as sync does.
+export { validateTranslations, SharedOutputIndex, sharedOutputItems, sharedOutputReason } from './lib/validate.js';
+// The index a sync of one locale starts with (the memorized sentences its
+// cache remembers + what the project's files and pages already hold): the
+// MCP translate tool, given a project_dir, refuses what sync would refuse.
+export { projectSharedOutputIndex } from './lib/shared-output-seed.js';
 
 // ── API key resolution ─────────────────────────────────────────────
 export { loadApiKey, getEnvOrFileVar } from './lib/api-key.js';
 
+// ── Cost wording ───────────────────────────────────────────────────
+// One label for an estimate ("$0 API cost (runs on this machine)",
+// "est. ~$0.0123"): the MCP translate tool names a price in the CLI's words.
+export { costLabel, LOCAL_COST_LABEL } from './lib/cost-label.js';
+
 // ── Coaching utilities (for custom method implementations) ─────────
 export {
   loadCoachingData,
@@ -107,7 +154,21 @@ export {
   partitionByTM,
   tmMethodKey,
   tmSize,
+  // A project's cache from before coaching was keyed reads as sync reads it.
+  adoptLegacyCoachingKeys,
+  // Which setup wrote the entry a lookup serves (an earlier model's, under
+  // model carry-over), and that key in words — so a cached answer can say
+  // who wrote it when that is not the engine named (MCP translate).
+  servingMethodKey,
+  describeMethodKey,
 } from './lib/tm.js';
+// The text a key is cached under — a gettext msgctxt folded in
+// ("msgctxt\u0004msgid" → "msgctxt\u0004<text>") — and which contexts a
+// project's source gives each text: the MCP translate tool keys a context as
+// sync does, and never writes a context-free entry for a text the project
+// has only with a context.
+export { tmSourceText, CONTEXT_SEPARATOR } from './lib/tm-evict.js';
+export { sourceTextContexts } from './lib/source-contexts.js';
 
 // ── XLIFF interchange ──────────────────────────────────────────────
 export {

package/lib/api-key.js

@@ -83,22 +83,35 @@ function loadApiKey(config, cwd) {
  * @returns {string|null} The variable value, or null if not found
  */
 function getEnvOrFileVar(keyName, cwd = process.cwd()) {
+  return findEnvOrFileVar(keyName, cwd)?.value ?? null;
+}
+
+/**
+ * getEnvOrFileVar, saying WHERE the value was found — for messages that
+ * must name the setting a run used (e.g. the endpoint a local method could
+ * not reach, and whether it came from the shell or a .env file).
+ *
+ * @param {string} keyName - Name of the environment variable
+ * @param {string} [cwd=process.cwd()] - Project root directory
+ * @returns {{ value: string, origin: 'environment'|'.env.local'|'.env', file: string|null }|null}
+ */
+function findEnvOrFileVar(keyName, cwd = process.cwd()) {
   // Priority 1: Check environment directly. Normalize identically to file
   // values (trim + strip surrounding quotes) so a quoted/padded exported secret
   // never reaches an Authorization header verbatim.
   if (process.env[keyName]) {
-    return normalizeKeyValue(process.env[keyName]);
+    return { value: normalizeKeyValue(process.env[keyName]), origin: 'environment', file: null };
   }
 
   // Priority 2: .env.local (Vercel/Next.js convention)
   const envLocalPath = path.join(cwd, '.env.local');
   const fromLocal = readKeyFromFile(envLocalPath, keyName);
-  if (fromLocal) return fromLocal;
+  if (fromLocal) return { value: fromLocal, origin: '.env.local', file: envLocalPath };
 
   // Priority 3: .env
   const envPath = path.join(cwd, '.env');
   const fromEnv = readKeyFromFile(envPath, keyName);
-  if (fromEnv) return fromEnv;
+  if (fromEnv) return { value: fromEnv, origin: '.env', file: envPath };
 
   return null;
 }
@@ -124,4 +137,4 @@ function readKeyFromFile(filePath, targetKey) {
   return null;
 }
 
-export { loadApiKey, parseEnvLine, getEnvOrFileVar };
+export { loadApiKey, parseEnvLine, getEnvOrFileVar, findEnvOrFileVar };

package/lib/autofix.js

@@ -12,6 +12,14 @@
  *   5. One-undo — `wrap --undo` restores from backup
  *   6. Diff output — prints git-style diff of every change
  *
+ * NOT FOR FLUTTER OR GETTEXT. wrap writes dotted keys for t('…') calls.
+ * An ARB key must be a Dart identifier, read as
+ * AppLocalizations.of(context)!.homeTitle; a gettext key IS the source
+ * text, marked with _("…") and collected by the project's own extractor.
+ * Writing "general.welcome" into either produces a catalog the app cannot
+ * use, so wrap refuses those formats before any component is rewritten
+ * (wrapUnsupportedReason, checked by the wrap command up front).
+ *
  * KEY GENERATION:
  *   "Welcome to my portfolio" → t("general.welcome_to_my_portfolio")
  *   "Get in Touch" → t("general.get_in_touch")
@@ -24,6 +32,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { execSync } from 'node:child_process';
 import { isNonTranslatableString } from './string-classify.js';
+import { readLocaleFile, writeLocaleFile, detectYAMLStyle } from './format.js';
 
 // -----------------------------------------------------------------
 // Key generation
@@ -343,57 +352,94 @@ function isAmbiguous(text, lineContext) {
 }
 
 /**
- * Add generated keys to locale files.
+ * Why `wrap` cannot store extracted keys in this locale file, or null when
+ * it can. Checked by the wrap command BEFORE any component is rewritten
+ * (a rewritten t('…') call with nowhere to store its key shows the raw key
+ * name in the app), and again by addKeysToLocales.
  *
- * @param {object[]} fixes - Array of { key, text } from processFile
- * @param {string} localesDir - Path to locale files directory
- * @param {string} sourceLocale - Source locale code (e.g., 'en')
- * @param {string[]} targetLocales - Target locale codes
+ * @param {{ format: string, rel?: string, path?: string }} file
+ * @returns {string|null}
  */
-function addKeysToLocales(fixes, localesDir, sourceLocale, targetLocales) {
-  if (fixes.length === 0) return;
-
-  // Build key-value map from fixes
-  const newKeys = {};
-  for (const fix of fixes) {
-    // Expand dot-notation key into nested object
-    const parts = fix.key.split('.');
-    let current = newKeys;
-    for (let i = 0; i < parts.length - 1; i++) {
-      if (!current[parts[i]]) current[parts[i]] = {};
-      current = current[parts[i]];
-    }
-    current[parts[parts.length - 1]] = fix.text;
+function wrapUnsupportedReason(file) {
+  const name = file.rel || (file.path ? path.basename(file.path) : 'the locale file');
+  if (file.format === 'arb') {
+    return `wrap does not apply to Flutter ARB files (${name}): it writes dotted keys for t('…') calls, `
+      + 'but an ARB key must be a Dart identifier, read as AppLocalizations.of(context)!.myKey. '
+      + `Add messages to ${name} yourself — champollion sync translates them.`;
   }
+  if (file.format === 'po') {
+    return `wrap does not apply to gettext catalogs (${name}): in gettext the key IS the source text. `
+      + 'Mark strings with _("…") / gettext("…") (Django: {% translate %}), collect them with your '
+      + 'extractor (makemessages, pybabel extract, xgettext), and champollion sync translates the catalog.';
+  }
+  return null;
+}
 
-  // Update source locale file
-  const sourcePath = path.join(localesDir, `${sourceLocale}.json`);
-  if (fs.existsSync(sourcePath)) {
-    const existing = JSON.parse(fs.readFileSync(sourcePath, 'utf-8'));
-    const merged = deepMerge(existing, newKeys);
-    fs.writeFileSync(sourcePath, JSON.stringify(merged, null, 2) + '\n', 'utf-8');
+/**
+ * Add generated keys to locale files.
+ *
+ * The files come from the project's locale layout (lib/locale-layout.js),
+ * resolved by the caller BEFORE any source file is rewritten: one file for
+ * a flat project, the chosen namespace's file for a folder-per-locale one.
+ * The format is the file's own — a Hugo project's en.toml gains TOML keys
+ * (this used to look only for `<locale>.json`, so TOML/YAML projects lost
+ * every extracted key without a word).
+ *
+ * Source gets the extracted text; each EXISTING target file gets the same
+ * keys with an "[EN] " placeholder, which the next sync translates. Keys
+ * already present are never overwritten.
+ *
+ * @param {object[]} fixes - Array of { key, text } from processFile
+ * @param {{ path: string, format: string }} sourceFile - Source locale file
+ * @param {Array<{ path: string, format: string }>} targetFiles - Target locale files
+ * @returns {{ source: boolean, targets: number }} What was written
+ */
+function addKeysToLocales(fixes, sourceFile, targetFiles = []) {
+  const written = { source: false, targets: 0 };
+  if (fixes.length === 0) return written;
+  // Defense in depth: the wrap command refuses these formats up front.
+  for (const file of [sourceFile, ...targetFiles]) {
+    const reason = wrapUnsupportedReason(file);
+    if (reason) throw new Error(reason);
   }
 
-  // Add placeholder entries to target locale files
-  for (const locale of targetLocales) {
-    const targetPath = path.join(localesDir, `${locale}.json`);
-    if (fs.existsSync(targetPath)) {
-      const existing = JSON.parse(fs.readFileSync(targetPath, 'utf-8'));
-      // Use [EN] prefix for target locales as untranslated markers
-      const placeholders = {};
+  const addTo = (file, prefix) => {
+    if (!fs.existsSync(file.path)) return false;
+    if (file.format === 'json') {
+      // Build the nested object of new keys from dot-notation keys.
+      const newKeys = {};
       for (const fix of fixes) {
         const parts = fix.key.split('.');
-        let current = placeholders;
+        let current = newKeys;
         for (let i = 0; i < parts.length - 1; i++) {
           if (!current[parts[i]]) current[parts[i]] = {};
           current = current[parts[i]];
         }
-        current[parts[parts.length - 1]] = `[EN] ${fix.text}`;
+        current[parts[parts.length - 1]] = `${prefix}${fix.text}`;
       }
-      const merged = deepMerge(existing, placeholders);
-      fs.writeFileSync(targetPath, JSON.stringify(merged, null, 2) + '\n', 'utf-8');
+      const existing = JSON.parse(fs.readFileSync(file.path, 'utf-8'));
+      const merged = deepMerge(existing, newKeys);
+      fs.writeFileSync(file.path, JSON.stringify(merged, null, 2) + '\n', 'utf-8');
+      return true;
+    }
+    // TOML / YAML: flat maps through the same reader/writer sync uses.
+    const flat = readLocaleFile(file.path, file.format);
+    for (const fix of fixes) {
+      if (!(fix.key in flat)) flat[fix.key] = `${prefix}${fix.text}`;
     }
+    const yamlStyle = file.format === 'yaml'
+      ? detectYAMLStyle(fs.readFileSync(file.path, 'utf-8'))
+      : null;
+    writeLocaleFile(file.path, flat, file.format, flat, yamlStyle);
+    return true;
+  };
+
+  written.source = addTo(sourceFile, '');
+  // Use [EN] prefix for target locales as untranslated markers
+  for (const target of targetFiles) {
+    if (addTo(target, '[EN] ')) written.targets++;
   }
+  return written;
 }
 
 /**
@@ -428,5 +474,6 @@ export {
   shouldFixText,
   isAmbiguous,
   addKeysToLocales,
+  wrapUnsupportedReason,
   deepMerge,
 };