champollion 0.3.3

package/lib/methods/provider-pricing.js

@@ -0,0 +1,310 @@
+/**
+ * Provider API Pricing — Static rates for non-LLM translation APIs.
+ *
+ * WHY STATIC: Unlike OpenRouter (which exposes /api/v1/models with live
+ * per-token pricing), Google, DeepL, and Microsoft do not have pricing
+ * APIs. These rates must be hardcoded and manually verified.
+ *
+ * WHY THIS MODULE: Four method files each had their own hardcoded rate.
+ * DeepL was wrong ($20 instead of $25). Single source of truth prevents
+ * that class of bug.
+ *
+ * LAST VERIFIED: 2026-06-08
+ * Sources:
+ *   Google Cloud Translation v2: https://cloud.google.com/translate/pricing
+ *   DeepL API Pro:               https://www.deepl.com/pro-api
+ *   Microsoft Translator S1:     https://azure.microsoft.com/pricing/details/cognitive-services/translator/
+ */
+
+import {
+  EST_CHARS_PER_KEY,
+  EST_INPUT_TOKENS_PER_KEY,
+  EST_OUTPUT_TOKENS_PER_KEY,
+} from '../config.js';
+import { fetchModelPricing } from './openrouter-pricing.js';
+
+/**
+ * Per-provider pricing data.
+ *
+ * Each entry has:
+ *   costPerMillionChars — USD cost per 1M characters translated
+ *   source — pricing page identifier (for LAST VERIFIED audit trail)
+ *   note — human-readable pricing context
+ */
+export const PROVIDER_RATES = {
+  'google-translate': {
+    costPerMillionChars: 20,
+    source: 'google-cloud-pricing',
+    note: 'Google Cloud Translation API v2 ($20/1M chars).',
+  },
+  'deepl': {
+    costPerMillionChars: 25,
+    source: 'deepl-api-pro-pricing',
+    note: 'DeepL API Pro (~$25/1M chars). Free tier: 500K chars/month cap.',
+  },
+  'microsoft-translator': {
+    costPerMillionChars: 10,
+    source: 'microsoft-translator-pricing',
+    note: 'Azure Translator S1 ($10/1M chars). 2M chars/month free tier.',
+  },
+  'libretranslate': {
+    costPerMillionChars: 0,
+    source: 'libretranslate-self-hosted',
+    note: 'Self-hosted, free. Infrastructure costs not included.',
+  },
+};
+
+/**
+ * Per-token pricing for the DIRECT LLM providers (anthropic / openai / gemini),
+ * in USD per 1M tokens, keyed by EXACT model ID.
+ *
+ * WHY EXACT IDS, NOT SUBSTRINGS: each provider file used to guess by substring
+ * (`model.includes('opus')` → $15/$75). That silently mispriced two ways —
+ * an unrecognized model got the default tier's rate as though it were known,
+ * and a recognized-but-repriced model kept a rate that no longer existed.
+ * Anthropic's `opus` branch was still charging Claude 3 Opus rates ($15/$75)
+ * for an Opus generation that costs $5/$25 — a 3x overestimate presented to
+ * the user as fact. An exact-ID table cannot drift that way: a model is either
+ * priced from a verified row, or reported as UNKNOWN.
+ *
+ * LIVE DRAW (2026-08-01): none of these three providers expose a pricing API,
+ * but OpenRouter publishes /api/v1/models with live per-token pricing for all
+ * of them, and every model in the table below maps onto an OpenRouter id by a
+ * mechanical rule (see toOpenRouterId). So the rates are now drawn live and
+ * the table below is the OFFLINE FALLBACK, not the primary source.
+ *
+ * That change was not cosmetic. On the day it was made, three pinned rows
+ * disagreed with the live figures — and one disagreed in the direction that
+ * costs money:
+ *
+ *     gemini-2.5-flash   pinned $0.15/$0.60   live $0.30/$2.50
+ *
+ * A 4x UNDER-estimate on output. Under `--max-cost` an under-estimate is the
+ * dangerous kind: it lets a run pass a cap it should have failed. (The other
+ * two, claude-sonnet-5 and gpt-4o, were over-estimates.) A dated static table
+ * is only as good as the last time somebody remembered to date it, and the two
+ * blocks that were wrong are exactly the two marked "unverified".
+ *
+ * HONESTY ABOUT THE SOURCE: OpenRouter's number is what OPENROUTER charges to
+ * serve that model. A direct-provider call bills you at the provider's own list
+ * price, so the live figure is a PROXY for list, not an authority on it. It is
+ * a good proxy — all eight Anthropic rows below, verified against Anthropic's
+ * own pricing page on 2026-07-31, match OpenRouter exactly — but the returned
+ * `source` always says which number was used, and a live/pinned divergence is
+ * reported rather than silently resolved.
+ *
+ * Unknown models return null from estimateLlmCost() — "unknown", never a guess
+ * and never $0. Consumers already treat a null estimate as over-cap under
+ * --max-cost (see cost-report.js), so an unpriced model aborts a capped run
+ * rather than silently running up a bill.
+ */
+export const LLM_RATES = {
+  // ── Anthropic ──────────────────────────────────────────────────────
+  // LAST VERIFIED: 2026-07-31 — https://platform.claude.com/docs/en/pricing
+  // Opus 4.6/4.7/4.8 and Opus 5 are all $5/$25; the $15/$75 this table
+  // replaces was Claude 3 Opus, retired 2026-01-05.
+  'claude-opus-5':     { provider: 'anthropic', input: 5.00,  output: 25.00, verified: '2026-07-31' },
+  'claude-opus-4-8':   { provider: 'anthropic', input: 5.00,  output: 25.00, verified: '2026-07-31' },
+  'claude-opus-4-7':   { provider: 'anthropic', input: 5.00,  output: 25.00, verified: '2026-07-31' },
+  'claude-opus-4-6':   { provider: 'anthropic', input: 5.00,  output: 25.00, verified: '2026-07-31' },
+  'claude-sonnet-5':   { provider: 'anthropic', input: 2.00,  output: 10.00, verified: '2026-08-01' },
+  'claude-sonnet-4-6': { provider: 'anthropic', input: 3.00,  output: 15.00, verified: '2026-07-31' },
+  'claude-haiku-4-5':  { provider: 'anthropic', input: 1.00,  output: 5.00,  verified: '2026-07-31' },
+  'claude-fable-5':    { provider: 'anthropic', input: 10.00, output: 50.00, verified: '2026-07-31' },
+
+  // ── OpenAI ─────────────────────────────────────────────────────────
+  // LAST VERIFIED: 2026-08-01 against the live OpenRouter draw. The values
+  // carried over from openai.js were WRONG: gpt-4o was pinned at $5/$15,
+  // twice the real input rate. Corrected here.
+  'gpt-4o':      { provider: 'openai', input: 2.50, output: 10.00, verified: '2026-08-01' },
+  'gpt-4o-mini': { provider: 'openai', input: 0.15, output: 0.60,  verified: '2026-08-01' },
+
+  // ── Google Gemini ──────────────────────────────────────────────────
+  // LAST VERIFIED: 2026-08-01 against the live OpenRouter draw. The values
+  // carried over from gemini.js were WRONG, and wrong in the dangerous
+  // direction: gemini-2.5-flash output was pinned at $0.60/1M against a real
+  // $2.50/1M — a 4x UNDER-estimate, which lets a --max-cost run pass a cap it
+  // should have failed. Corrected here.
+  'gemini-2.5-flash': { provider: 'gemini', input: 0.30, output: 2.50,  verified: '2026-08-01' },
+  'gemini-2.5-pro':   { provider: 'gemini', input: 1.25, output: 10.00, verified: '2026-08-01' },
+};
+
+/**
+ * Map a native provider model id onto its OpenRouter id.
+ *
+ * The rule is mechanical and was verified against all 337 live OpenRouter
+ * models on 2026-08-01: every id in LLM_RATES resolved.
+ *
+ *   - Anthropic prefixes `anthropic/` and writes the point release with a DOT
+ *     where the native API uses a hyphen: claude-sonnet-4-6 → claude-sonnet-4.6.
+ *     Single-segment names pass through: claude-opus-5 → claude-opus-5.
+ *   - OpenAI prefixes `openai/`, 1:1.
+ *   - Google prefixes `google/`, 1:1.
+ *
+ * @param {string} model native model id
+ * @returns {string|null} OpenRouter id, or null if the family is unrecognised
+ */
+export function toOpenRouterId(model) {
+  if (typeof model !== 'string' || !model) return null;
+  if (model.startsWith('claude-')) {
+    const parts = model.split('-');
+    const [major, minor] = parts.slice(-2);
+    // …-4-6 is a point release; …-5 is not.
+    if (parts.length >= 4 && /^\d+$/.test(major) && /^\d+$/.test(minor)) {
+      return `anthropic/${parts.slice(0, -2).join('-')}-${major}.${minor}`;
+    }
+    return `anthropic/${model}`;
+  }
+  if (model.startsWith('gpt-') || model.startsWith('o1') || model.startsWith('o3')) {
+    return `openai/${model}`;
+  }
+  if (model.startsWith('gemini-')) return `google/${model}`;
+  return null;
+}
+
+// Divergence above this fraction between the live draw and the pinned row is
+// reported. It means the pinned table has drifted and needs re-verifying —
+// silence there is how a 4x under-estimate survived.
+const DIVERGENCE_TOLERANCE = 0.10;
+
+// One warning per model per process; a 3,000-key sync should not print 3,000
+// identical lines.
+const _warnedModels = new Set();
+
+/**
+ * Is the live pricing draw disabled?
+ *
+ * `CHAMPOLLION_PRICING_OFFLINE=1` forces the pinned table. This is not a test
+ * hook — the sovereign-node and airgap-sandbox lanes run with no outbound
+ * network at all, and a cost estimate must still resolve there rather than
+ * hanging on a fetch that cannot complete. It also makes the test suite
+ * deterministic and network-free, which is why the suite sets it.
+ *
+ * @returns {boolean}
+ */
+export function pricingOffline() {
+  return process.env.CHAMPOLLION_PRICING_OFFLINE === '1';
+}
+
+/**
+ * Estimate the token cost of translating a batch of keys with a direct LLM.
+ *
+ * Draws live pricing from OpenRouter and falls back to the pinned table when
+ * the network is unavailable. Returns null — "unknown", never $0 and never a
+ * guess — when neither source prices the model.
+ *
+ * @param {string} provider - 'anthropic' | 'openai' | 'gemini' (for the note)
+ * @param {string} model - EXACT model ID
+ * @param {number} keyCount - Number of translation keys in the batch
+ * @returns {Promise<{ estimatedCost: number|null, currency: string, source: string, note: string }>}
+ */
+export async function estimateLlmCost(provider, model, keyCount) {
+  const pinned = LLM_RATES[model];
+  const pinnedUsable = pinned && pinned.provider === provider;
+
+  // ── live draw ────────────────────────────────────────────────────
+  let rate = null;
+  let source = null;
+  let divergence = '';
+
+  // The OpenRouter namespace must match the provider being billed. Without
+  // this, estimateLlmCost('anthropic', 'gpt-4o', …) would happily price the
+  // model through openai/gpt-4o — losing the cross-provider guard that the
+  // exact-ID table exists to enforce.
+  const OR_NAMESPACE = { anthropic: 'anthropic/', openai: 'openai/', gemini: 'google/' };
+  const orId = toOpenRouterId(model);
+  const namespaceOk = orId && OR_NAMESPACE[provider] && orId.startsWith(OR_NAMESPACE[provider]);
+  if (orId && namespaceOk && !pricingOffline()) {
+    let live = null;
+    try {
+      const pricing = await fetchModelPricing();
+      live = pricing.get(orId) || null;
+    } catch {
+      // fetchModelPricing already degrades to an empty Map offline; this
+      // catch only guards an unexpected throw. Fall through to pinned.
+      live = null;
+    }
+    if (live && (live.input > 0 || live.output > 0)) {
+      // openrouter-pricing.js stores cost PER TOKEN; this module works in
+      // dollars per million tokens.
+      rate = { input: live.input * 1_000_000, output: live.output * 1_000_000 };
+      source = `openrouter-live (proxy for ${provider} list price)`;
+
+      if (pinnedUsable) {
+        const drift = (a, b) => (b === 0 ? (a === 0 ? 0 : 1) : Math.abs(a - b) / b);
+        const dIn = drift(rate.input, pinned.input);
+        const dOut = drift(rate.output, pinned.output);
+        if (dIn > DIVERGENCE_TOLERANCE || dOut > DIVERGENCE_TOLERANCE) {
+          divergence =
+            ` PINNED TABLE HAS DRIFTED: provider-pricing.js says `
+            + `$${pinned.input}/$${pinned.output} per 1M, live says `
+            + `$${rate.input.toFixed(2)}/$${rate.output.toFixed(2)}. `
+            + `Using live. Re-verify the pinned row against the provider's `
+            + `pricing page and re-date it.`;
+          if (!_warnedModels.has(model)) {
+            _warnedModels.add(model);
+            console.warn(`⚠ pricing drift for ${model}:${divergence}`);
+          }
+        }
+      }
+    }
+  }
+
+  // ── offline fallback ─────────────────────────────────────────────
+  if (!rate && pinnedUsable) {
+    rate = { input: pinned.input, output: pinned.output };
+    source = `pinned-table (${pinned.verified ? `verified ${pinned.verified}` : 'UNVERIFIED'}; live draw unavailable)`;
+  }
+
+  if (!rate) {
+    return {
+      estimatedCost: null,
+      currency: 'USD',
+      source: `${provider}-pricing-unknown`,
+      note: `No rate for ${provider} model "${model}" — not on OpenRouter and `
+        + `no pinned row. Cost is UNKNOWN (not $0). Add a row to LLM_RATES in `
+        + `provider-pricing.js to price it.`,
+    };
+  }
+
+  const inputTokens = keyCount * EST_INPUT_TOKENS_PER_KEY;
+  const outputTokens = keyCount * EST_OUTPUT_TOKENS_PER_KEY;
+  const estimatedCost =
+    (inputTokens * rate.input + outputTokens * rate.output) / 1_000_000;
+
+  return {
+    estimatedCost: Math.round(estimatedCost * 10000) / 10000,
+    currency: 'USD',
+    source,
+    note: `Based on ${provider} ${model} pricing `
+      + `($${rate.input.toFixed(2)}/1M input, $${rate.output.toFixed(2)}/1M output, `
+      + `${source}).${divergence}`,
+  };
+}
+
+/**
+ * Estimate the API cost for translating a batch of keys.
+ *
+ * @param {string} provider - Provider name matching a PROVIDER_RATES key
+ * @param {number} keyCount - Number of translation keys in the batch
+ * @returns {{ estimatedCost: number, currency: string, source: string, note: string }}
+ * @throws {Error} If provider is not in PROVIDER_RATES — forces new
+ *   providers to add pricing data before estimateCost() can be called.
+ */
+export function estimateProviderCost(provider, keyCount) {
+  const rate = PROVIDER_RATES[provider];
+  if (!rate) {
+    throw new Error(
+      `No pricing data for provider "${provider}". ` +
+      `Add it to provider-pricing.js before using estimateCost().`
+    );
+  }
+  const estimatedChars = keyCount * EST_CHARS_PER_KEY;
+  const costPerChar = rate.costPerMillionChars / 1_000_000;
+  return {
+    estimatedCost: Math.round(estimatedChars * costPerChar * 10000) / 10000,
+    currency: 'USD',
+    source: rate.source,
+    note: rate.note,
+  };
+}

package/lib/methods/tilde.js

@@ -0,0 +1,150 @@
+/**
+ * Tilde MT Translation Method — European-developed neural MT via the Tilde MT
+ * REST API. Mirrors the harness TildeMethod
+ * (arena/mt_eval_harness/methods/tilde.py): same endpoint, env var, body, and
+ * response shape, so config is interchangeable between CLI and harness.
+ *
+ *   Endpoint: POST https://translate.tilde.ai/api/translate/text
+ *   Auth:     header  X-Api-Key: <key>
+ *   Env:      TILDE_API_KEY (free trial key at translate.tilde.ai/access-keys)
+ *   Body:     { srcLang, trgLang, domain:"general", text:[...], termCollections:[] }
+ *   Response: json.translations[i].translation
+ *   Locale:   ISO 639-1.
+ */
+
+import { TranslationMethod } from './base.js';
+import { getEnvOrFileVar } from '../api-key.js';
+import { DEFAULT_METHOD_CONCURRENCY } from '../config.js';
+import { extractContentBody } from './content-separator.js';
+import { output } from '../output.js';
+import { fetchWithRetry } from './fetch-with-retry.js';
+import { pMap } from '../concurrent.js';
+
+const TILDE_API_URL = 'https://translate.tilde.ai/api/translate/text';
+const TILDE_TIMEOUT_MS = 15000;
+const TILDE_MAX_BATCH = 25;
+
+class TildeMethod extends TranslationMethod {
+  constructor(options = {}) {
+    super('tilde', options);
+  }
+
+  _resolveApiKey(options = {}) {
+    return options.tildeApiKey
+      || getEnvOrFileVar('TILDE_API_KEY')
+      || getEnvOrFileVar('TILDE_API_KEY', options.cwd);
+  }
+
+  async _translateBatch(apiKey, orderedKeys, sourceTexts, srcLang, trgLang, batchNum) {
+    const res = await fetchWithRetry(TILDE_API_URL, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'X-Api-Key': apiKey },
+      body: JSON.stringify({
+        srcLang, trgLang, domain: 'general', text: sourceTexts, termCollections: [],
+      }),
+    }, { label: `Tilde batch ${batchNum}`, timeoutMs: TILDE_TIMEOUT_MS });
+
+    if (!res) return null;
+    if (!res.ok) {
+      const body = await res.text();
+      output.error(`Tilde batch ${batchNum}: ${res.status} — ${body.slice(0, 200)}`);
+      return null;
+    }
+    const json = await res.json();
+    const translations = json?.translations;
+    if (!Array.isArray(translations) || translations.length !== orderedKeys.length) {
+      output.error(`Tilde batch ${batchNum}: response length mismatch`);
+      return null;
+    }
+    const result = {};
+    for (let i = 0; i < orderedKeys.length; i++) {
+      result[orderedKeys[i]] = translations[i]?.translation;
+    }
+    return result;
+  }
+
+  async translate(keys, sourceFlat, pairConfig, options) {
+    const apiKey = this._resolveApiKey(options);
+    if (!apiKey) {
+      output.warn('Tilde: no API key (TILDE_API_KEY) — skipping.');
+      return null;
+    }
+    const srcLang = pairConfig.source || 'en';
+    const trgLang = pairConfig.target;
+    const maxBatch = pairConfig.batchSize || options.batchSize || TILDE_MAX_BATCH;
+    const allTranslated = {};
+
+    const chunks = [];
+    for (let i = 0; i < keys.length; i += maxBatch) chunks.push(keys.slice(i, i + maxBatch));
+
+    await pMap(chunks, async (chunk, idx) => {
+      const orderedKeys = [];
+      const sourceTexts = [];
+      for (const key of chunk) {
+        const val = sourceFlat[key];
+        if (typeof val === 'string' && val) { orderedKeys.push(key); sourceTexts.push(val); }
+      }
+      if (!sourceTexts.length) return;
+      const r = await this._translateBatch(apiKey, orderedKeys, sourceTexts, srcLang, trgLang, idx + 1);
+      if (r) Object.assign(allTranslated, r);
+    }, { concurrency: DEFAULT_METHOD_CONCURRENCY });
+
+    return Object.keys(allTranslated).length > 0 ? allTranslated : null;
+  }
+
+  async translateContent(prompt, pairConfig, options) {
+    const apiKey = this._resolveApiKey(options);
+    if (!apiKey) return null;
+    const body = extractContentBody(prompt);
+    if (!body.trim()) return null;
+    const r = await this._translateBatch(
+      apiKey, ['__content__'], [body], pairConfig.source || 'en', pairConfig.target, 'content',
+    );
+    return r ? r['__content__'] : null;
+  }
+
+  checkReadiness(context) {
+    const apiKey = this._resolveApiKey(context || {});
+    if (!apiKey) {
+      return {
+        ready: false,
+        reason: 'No Tilde API key (TILDE_API_KEY). Free trial key at https://translate.tilde.ai/access-keys.',
+      };
+    }
+    return { ready: true };
+  }
+
+  estimateCost(_keyCount) {
+    // Tilde pricing is plan-based; per-character cost is not published, so we
+    // do not fabricate one (fail-honest — null, not a guessed $).
+    return {
+      estimatedCost: null,
+      currency: 'USD',
+      source: 'tilde-proprietary',
+      note: 'Tilde pricing is plan-based (free trial 250K chars); per-char cost not published.',
+    };
+  }
+
+  getQualityTier() {
+    return 'standard';
+  }
+
+  getProvenance() {
+    return {
+      resources: [{ name: 'Tilde MT API', license: 'Proprietary (Tilde ToS)', type: 'api' }],
+      commercialReady: true,
+      flags: [],
+    };
+  }
+
+  getSetupHelp() {
+    return [
+      '  Tilde MT (European neural MT):',
+      '   1. Sign up: https://tilde.ai/translate/machine-translation-api/ (free trial 250K chars).',
+      '   2. Create an access key: https://translate.tilde.ai/access-keys',
+      '   3. export TILDE_API_KEY=...  (or add to .env.local)',
+    ];
+  }
+}
+
+export { TildeMethod };

package/lib/methods/translated.js

@@ -0,0 +1,229 @@
+/**
+ * Translated (Lara) — professional MT via Translated's Lara Translate API.
+ *
+ *   Endpoint: official @translated/lara SDK (REST /v2/translate under the
+ *             hood; requests are HMAC-signed by the SDK — we never hand-roll
+ *             the signature)
+ *   Auth:     LARA_ACCESS_KEY_ID + LARA_ACCESS_KEY_SECRET (dashboard →
+ *             Settings → API Keys at laratranslate.com)
+ *   Codes:    BCP-47; base ISO 639-1 codes are accepted and auto-resolve to
+ *             the default regional locale (en → en-US), so we pass our locale
+ *             codes through unchanged.
+ *   Batch:    the SDK accepts string arrays; we chunk to keep request sizes
+ *             polite and failures isolated.
+ *
+ * ModernMT note: Translated is sunsetting ModernMT into Lara (API-compatible
+ * migration path until end of 2026); this adapter targets Lara only.
+ */
+
+import { TranslationMethod } from './base.js';
+import { getEnvOrFileVar } from '../api-key.js';
+import { DEFAULT_METHOD_CONCURRENCY } from '../config.js';
+import { extractContentBody } from './content-separator.js';
+import { output } from '../output.js';
+import { pMap } from '../concurrent.js';
+
+const TRANSLATED_MAX_BATCH = 50;
+
+class TranslatedMethod extends TranslationMethod {
+  constructor(options = {}) {
+    super('translated', options);
+    this._client = options.laraClient || null; // injectable for tests
+  }
+
+  // ── Credential / client resolution ─────────────────────────────
+
+  /**
+   * Resolve the Lara access-key pair from options, env vars, or .env files.
+   * @param {object} options - Caller-provided options
+   * @returns {{id: string, secret: string}|null}
+   */
+  _resolveCredentials(options = {}) {
+    const id = options.laraAccessKeyId
+      || getEnvOrFileVar('LARA_ACCESS_KEY_ID')
+      || getEnvOrFileVar('LARA_ACCESS_KEY_ID', options.cwd);
+    const secret = options.laraAccessKeySecret
+      || getEnvOrFileVar('LARA_ACCESS_KEY_SECRET')
+      || getEnvOrFileVar('LARA_ACCESS_KEY_SECRET', options.cwd);
+    return id && secret ? { id, secret } : null;
+  }
+
+  /**
+   * Lazily construct the official Lara SDK client. The SDK owns request
+   * signing (HMAC over the request envelope), retries, and endpoint choice.
+   * @param {object} options
+   * @returns {Promise<object|null>} Translator instance or null
+   */
+  async _getClient(options = {}) {
+    if (this._client) return this._client;
+    const creds = this._resolveCredentials(options);
+    if (!creds) return null;
+    let lara;
+    try {
+      lara = await import('@translated/lara');
+    } catch {
+      output.error(
+        'Translated (Lara): the @translated/lara SDK is not installed — '
+        + 'run `npm install` in the champollion package.',
+      );
+      return null;
+    }
+    const { Credentials, Translator } = lara;
+    this._client = new Translator(new Credentials(creds.id, creds.secret));
+    return this._client;
+  }
+
+  // ── Translation ────────────────────────────────────────────────
+
+  /**
+   * Translate one chunk of texts. Returns the translations array (in input
+   * order) or null on failure — callers treat null as a skipped batch.
+   */
+  async _translateBatch(client, sourceTexts, sourceLocale, targetLocale, batchNum) {
+    try {
+      const result = await client.translate(sourceTexts, sourceLocale, targetLocale);
+      const translations = Array.isArray(result?.translation)
+        ? result.translation
+        : [result?.translation];
+      if (translations.length !== sourceTexts.length) {
+        output.error(
+          `Translated batch ${batchNum}: response length mismatch `
+          + `(sent ${sourceTexts.length}, got ${translations.length})`,
+        );
+        return null;
+      }
+      return translations;
+    } catch (err) {
+      output.error(`Translated batch ${batchNum}: ${err?.message || err}`);
+      return null;
+    }
+  }
+
+  /**
+   * Translate a batch of key-value pairs via the Lara API.
+   *
+   * @param {string[]} keys - Flat dot-notation keys to translate
+   * @param {object} sourceFlat - Full flattened source locale
+   * @param {import('../types.js').PairConfig} pairConfig - Pair config
+   * @param {object} options - { laraAccessKeyId, laraAccessKeySecret, batchSize }
+   * @returns {object|null} Map of key → translated value, or null
+   */
+  async translate(keys, sourceFlat, pairConfig, options) {
+    const client = await this._getClient(options);
+    if (!client) {
+      output.warn(
+        'Translated (Lara): no credentials (LARA_ACCESS_KEY_ID / '
+        + 'LARA_ACCESS_KEY_SECRET) — skipping.',
+      );
+      return null;
+    }
+
+    const sourceLocale = pairConfig.source || 'en';
+    const targetLocale = pairConfig.target;
+    const maxSegments = pairConfig.batchSize || options.batchSize || TRANSLATED_MAX_BATCH;
+    const allTranslated = {};
+
+    const batchChunks = [];
+    for (let i = 0; i < keys.length; i += maxSegments) {
+      batchChunks.push(keys.slice(i, i + maxSegments));
+    }
+
+    await pMap(batchChunks, async (chunk, idx) => {
+      const orderedKeys = [];
+      const sourceTexts = [];
+      for (const key of chunk) {
+        const val = sourceFlat[key];
+        if (val && typeof val === 'string') {
+          orderedKeys.push(key);
+          sourceTexts.push(val);
+        }
+      }
+      if (sourceTexts.length === 0) return;
+
+      const translations = await this._translateBatch(
+        client, sourceTexts, sourceLocale, targetLocale, idx + 1,
+      );
+      if (!translations) return;
+      for (let i = 0; i < orderedKeys.length; i++) {
+        if (typeof translations[i] === 'string') {
+          allTranslated[orderedKeys[i]] = translations[i];
+        }
+      }
+    }, { concurrency: DEFAULT_METHOD_CONCURRENCY });
+
+    return Object.keys(allTranslated).length > 0 ? allTranslated : null;
+  }
+
+  /**
+   * Translate freeform Markdown content via Lara.
+   * @param {string} prompt - Content prompt (body extracted before sending)
+   * @param {import('../types.js').PairConfig} pairConfig
+   * @param {object} options
+   * @returns {Promise<string|null>}
+   */
+  async translateContent(prompt, pairConfig, options) {
+    const client = await this._getClient(options);
+    if (!client) return null;
+    const body = extractContentBody(prompt);
+    if (!body.trim()) return null;
+    const translations = await this._translateBatch(
+      client, [body], pairConfig.source || 'en', pairConfig.target, 'content',
+    );
+    return translations ? translations[0] : null;
+  }
+
+  // ── Metadata ───────────────────────────────────────────────────
+
+  checkReadiness(context) {
+    const creds = this._resolveCredentials(context || {});
+    if (!creds) {
+      return {
+        ready: false,
+        reason: 'No Lara credentials (LARA_ACCESS_KEY_ID + LARA_ACCESS_KEY_SECRET). '
+          + 'Create an API key at laratranslate.com → Settings → API Keys.',
+      };
+    }
+    return { ready: true };
+  }
+
+  estimateCost(_keyCount) {
+    // Proprietary per-character pricing behind Translated's plans; never
+    // invent a number (Project rule: never invent pricing).
+    return {
+      estimatedCost: null,
+      currency: 'USD',
+      source: 'translated-lara-proprietary',
+      note: 'Lara pricing is plan-based; per-character cost not published.',
+    };
+  }
+
+  getQualityTier() {
+    return 'standard';
+  }
+
+  getProvenance() {
+    return {
+      resources: [
+        {
+          name: 'Translated Lara Translate API',
+          license: 'Proprietary (Translated ToS)',
+          type: 'api',
+        },
+      ],
+      commercialReady: true,
+      flags: [],
+    };
+  }
+
+  getSetupHelp() {
+    return [
+      '  Translated (Lara) — professional MT API, 200+ languages:',
+      '   1. Sign up: https://laratranslate.com',
+      '   2. Settings → API Keys → create an access key',
+      '   3. export LARA_ACCESS_KEY_ID=...  LARA_ACCESS_KEY_SECRET=...',
+      '      (or add both to .env.local)',
+    ];
+  }
+}
+
+export { TranslatedMethod, TRANSLATED_MAX_BATCH };