champollion 0.3.3 → 0.4.0

package/lib/commands/doctor.js

@@ -337,6 +337,58 @@ function checkFST(report, langCode) {
  * @param {DiagnosticReport} report
  * @param {string} cwd - Project root, for .env.local/.env key lookup
  */
+/**
+ * OpenRouter's documented endpoint for a key's own limits and usage:
+ * authenticated, free (it translates nothing), and HTTP 401 for a key that
+ * is missing, invalid or disabled (openrouter.ai/docs/api-reference/limits).
+ */
+const OPENROUTER_KEY_URL = 'https://openrouter.ai/api/v1/key';
+
+/**
+ * Ask OpenRouter whether it accepts the key — the one check here that sends
+ * it anywhere, and it costs nothing. doctor used to call the model list
+ * (/api/v1/models), which answers without a key: "Connected — N models
+ * available" for any value, a placeholder included, while claiming to
+ * validate it (Round 11). 401/403 = rejected (a failed check); any other
+ * answer, or none, = not checked (a warning). The key is never printed.
+ *
+ * @param {DiagnosticReport} report
+ * @param {string} key
+ * @param {string} source - where it was read from, for the advice
+ */
+async function checkOpenRouterKey(report, key, source) {
+  let resp;
+  try {
+    resp = await fetch(OPENROUTER_KEY_URL, {
+      headers: { Authorization: `Bearer ${key}` },
+      signal: AbortSignal.timeout(5000),
+    });
+  } catch (err) {
+    report.warn('OpenRouter key check', `not checked — could not reach OpenRouter (${err.name === 'TimeoutError' ? 'no answer in 5 s' : err.message})`);
+    return;
+  }
+  if (resp.status === 401 || resp.status === 403) {
+    report.fail('OpenRouter key check', `rejected by OpenRouter (HTTP ${resp.status}): the key is invalid, disabled or revoked. `
+      + `Check the value of OPENROUTER_API_KEY (set via ${source}); the llm and llm-coached methods cannot run with it.`);
+    return;
+  }
+  if (!resp.ok) {
+    report.warn('OpenRouter key check', `not checked — OpenRouter answered HTTP ${resp.status}`);
+    return;
+  }
+  let data = {};
+  try { data = (await resp.json())?.data || {}; } catch { /* the status said accepted */ }
+  const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+  const usage = num(data.usage);
+  const limit = num(data.limit);
+  const left = num(data.limit_remaining);
+  const credits = [
+    usage !== null ? `${usage} credits used` : null,
+    limit !== null ? `${left !== null ? `${left} of ${limit}` : `limit ${limit}`} left` : (data.limit === null ? 'no credit limit' : null),
+  ].filter(Boolean).join(', ');
+  report.pass('OpenRouter key check', `accepted by OpenRouter (GET /api/v1/key — no charge)${credits ? `; ${credits}` : ''}`);
+}
+
 async function checkMethods(report, cwd) {
   output.raw('');
   output.raw('  ── Methods ──');
@@ -369,24 +421,8 @@ async function checkMethods(report, cwd) {
   const openRouterKey = getEnvOrFileVar('OPENROUTER_API_KEY', cwd);
   if (openRouterKey) {
     const source = process.env.OPENROUTER_API_KEY ? 'environment' : '.env.local/.env';
-    report.pass('OpenRouter API key', `Set via ${source} (LLM methods available)`);
-
-    // Try to validate by checking the /api/v1/models endpoint
-    try {
-      const resp = await fetch('https://openrouter.ai/api/v1/models', {
-        headers: { 'Authorization': `Bearer ${openRouterKey}` },
-        signal: AbortSignal.timeout(5000),
-      });
-      if (resp.ok) {
-        const data = await resp.json();
-        const modelCount = data.data?.length || 0;
-        report.pass('OpenRouter API', `Connected — ${modelCount} models available`);
-      } else {
-        report.warn('OpenRouter API', `HTTP ${resp.status} — key may be invalid`);
-      }
-    } catch (err) {
-      report.warn('OpenRouter API', `Could not reach API: ${err.message}`);
-    }
+    report.pass('OpenRouter API key', `Set via ${source}`);
+    await checkOpenRouterKey(report, openRouterKey, source);
   } else {
     report.warn('OpenRouter API key', 'OPENROUTER_API_KEY not set (checked environment, .env.local, .env) — LLM methods unavailable');
   }

package/lib/commands/help.js

@@ -14,75 +14,80 @@ const DEFAULT_CONFIG_FILENAME = CONFIG_FILENAMES[0];
  */
 function run() {
   console.log(`
-  champollion — Research-grade translation engine for i18n projects
+  champollion — translate your project, and deploy MT you have measured
 
-  COMMANDS
-    init         Interactive setup wizard (or --yes for quick defaults)
-    sync         Translate & sync all locale files
-    serve        Serve this project's translation stack over HTTP (api-method contract)
+  TRANSLATE YOUR PROJECT
+    init         Set up: detects your framework's locale files (or --yes for defaults)
+    sync         Translate what changed (--redo / --fresh to translate again)
+    verify       Check translations are present and correct (CI gate)
+    status       Show pair graph, methods, and config summary
     watch        Auto-sync when the source file changes
+    serve        Serve this project's translation stack over HTTP (api-method contract)
     audit        List all untranslated [EN] fallback values
-    card         Pretty-print a language card (card \<code\> [--json])
-    register-corpus  Register a 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): print a pre-filled GitHub issue
+    integrity    Audit locale files for placeholder/encoding/ICU issues
+    tm           Manage Translation Memory cache (stats, clear, seed, prune)
+    xliff        Export/import XLIFF 1.2 for professional review
     lint         Scan source files for hardcoded strings (pre-commit gate)
     wrap         Auto-wrap hardcoded strings in t() calls (with undo)
     seo          Generate hreflang, sitemap.xml, or JSON-LD schema
-    integrity    Audit locale files for placeholder/encoding issues
     repair-script  Restore romanization where script conversion was unwanted
-    status       Show pair graph, methods, and config summary
-    provenance   Show licensing & resource dependencies for all pairs
     plugin       Manage method plugins (install, remove, list)
-    fonts        Download web fonts for PUA script converters
-    tm           Manage Translation Memory cache (stats, clear, seed, prune)
-    xliff        Export/import XLIFF 1.2 for professional review
     models       List available models for a provider
-    verify       Verify translations are present and correct (CI gate)
-    leaderboard  Show MT leaderboard from Supabase (--pair, --sort, --json)
-    recommend    Method guidance for a pair — availability + cited evidence (--use, --json)
+    fonts        Download web fonts for PUA script converters
+    provenance   Show licensing & resource dependencies for all pairs
     doctor       System health check (cards, config, FSTs, methods)
 
+  THE NETWORK   champollion network <command> — each also works without the prefix
+    card         What the index knows about a language (card \<code\> [--json])
+    recommend    Methods you can run for a pair, with the evidence for each
+    leaderboard  Published results (--pair, --sort, --json)
+    register-corpus  Register a test set without handing it over (local-only/private/public/sealed)
+    seal-corpus  Sealed-tier crypto verbs: keygen / seal / open (organizer-node bridge)
+    submit       Propose an index entry (review-gated): print a pre-filled GitHub issue
+
+  Building MT for a language end to end (measure, train, prove, deploy)?
+    https://champollion.dev/docs/build-mt-for-your-language
+
   OPTIONS
     --config <path>    Path to config file (default: ${DEFAULT_CONFIG_FILENAME})
     --dir <path>       Override locales directory
-    --content-dir <p>  Hugo content directory for Markdown translation
+    --content-dir <p>  Folder of Markdown/MDX to translate (Hugo content/ or any folder)
     --source <code>    Override source locale (default: en)
     --base-url <url>   Override base URL for SEO commands
-    --model <model>    Override translation model
-    --method <method>  Default translation method: llm, llm-coached, google-translate, api, deepl, microsoft-translator, libretranslate, openai, anthropic, gemini
-    --format <fmt>     Locale file format: json, toml, yaml, or auto (default: auto)
+    --model <model>    Translation model for this run only (the config's "model" is not changed)
+    --method <method>  Translation method for this run only: llm, llm-coached, local (your own model), openai, anthropic, gemini, google-translate, deepl, microsoft-translator, libretranslate, api
+    --format <fmt>     Locale file format: json, toml, yaml, po, arb, or auto (default: auto)
     --dry              Preview changes without writing files
-    --force-keys <k>   Comma-separated dot-notation keys to force re-translate
+    --redo <scope>     Translate again: all | keys:<k1,k2> | content | files:<glob> (cache still serves) | gaps (plural forms a model left out, asked anew)
+    --prune plural-extras  Remove i18next plural keys for forms a language does not have (sync)
+    --fresh            Do not use the cache for what is queued (billed again)
     --src <path>       Source directory for lint/wrap (auto-detected)
     --min-length <n>   Minimum string length to flag (default: 2)
     --warn-only        Exit 0 even with issues (lint, integrity)
     --undo             Restore files from .champollion-backup/ (wrap)
     --out <path>       Write output to file (seo sitemap, xliff export)
     --locale <code>    Target locale (xliff export, tm clear, tm seed)
-    --no-tm            Skip Translation Memory cache for this sync run
     --no-verify        Skip post-sync verification pass
 
   SUPPORTED FORMATS
     json     Standard JSON (next-intl, i18next, react-intl)
     toml     Hugo i18n TOML files (i18n/*.toml)
     yaml     Hugo i18n YAML files (i18n/*.yaml)
-    auto     Auto-detect from file extensions in locales directory
+    po       gettext catalogs (Django, GNU gettext; .pot templates)
+    arb      Flutter Application Resource Bundles (app_<locale>.arb)
+    auto     Auto-detect from file extensions
 
   QUICK START
-    1. Set OPENROUTER_API_KEY (or provider key like OPENAI_API_KEY, DEEPL_API_KEY, etc.) in your environment or .env.local
-    2. Put your source locale (en.json / en.toml / en.yaml) in a locales/ directory
+    1. Set OPENROUTER_API_KEY (or a provider key; or --method local for a model on this machine)
+    2. Run: champollion init     # finds your locale files
     3. Run: champollion sync
 
   The tool will:
-    • Auto-detect locale file format (JSON, TOML, or YAML)
-    • Translate missing keys via OpenRouter (${DEFAULT_OPENROUTER_MODEL})
-    • Translate Hugo Markdown content files (if --content-dir is set)
+    • Translate only what changed; the Translation Memory never bills the same sentence twice
+    • Protect placeholders, ICU plurals and markup (a damaged translation is rejected and retried)
     • Fail loud on any translation errors (no silent failures)
     • Verify translations after writing (key parity, placeholders, script compliance)
-    • Batch translations to avoid token overflow
     • Preserve your file structure and formatting
-    • Cache translations in Translation Memory to avoid redundant API calls
 
   Run champollion <command> --help for detailed help on any command.
   `);