champollion 0.3.3 → 0.4.0

package/lib/translate.js

@@ -41,6 +41,8 @@ import { ExternalMethod } from './methods/external.js';
 import { DEFAULT_OPENROUTER_MODEL } from './config.js';
 import { manifestEntries, cliNameFor } from './method-manifest.js';
 import { assertRoutable } from './commercial-eligibility.js';
+import { CONTENT_SEPARATOR, parseContentPrompt } from './methods/content-separator.js';
+import { SEGMENT_MARKER_PREFIX, SEGMENT_MARKER_SUFFIX } from './segment.js';
 
 /**
  * Registry of available translation methods.
@@ -69,6 +71,27 @@ const METHOD_REGISTRY = {
   'external': ExternalMethod,
 };
 
+/**
+ * ExternalMethod instances by plugin path. Each instance owns a Python bridge
+ * process, so building one per call (getMethod runs for every batch, every
+ * preflight, every content file) started a new process each time and never
+ * stopped any. One instance per plugin is reused for the whole run and
+ * stopped by shutdownMethods().
+ */
+const externalMethods = new Map();
+
+/**
+ * Stop every bridge process started through getMethod(). Call when a run is
+ * finished; a later getMethod() starts a fresh bridge on demand.
+ *
+ * @returns {Promise<void>}
+ */
+async function shutdownMethods() {
+  const instances = [...externalMethods.values()];
+  externalMethods.clear();
+  await Promise.all(instances.map(m => m.shutdown()));
+}
+
 /**
  * Find a shared-registry entry that exists but is NOT served in the CLI runtime.
  *
@@ -153,14 +176,27 @@ function getMethod(methodName, pluginContext) {
       methodVersion: pluginContext.pluginVersion,
       qualityTier: pluginContext.qualityTier,
       provenance: pluginContext.pluginProvenance,
+      acceptsInstructions: pluginContext.acceptsInstructions,
     });
   }
 
-  // ExternalMethod needs methodPath to find the Python plugin directory
+  // LLMCoachedMethod needs the pair's transport so preflight checks the
+  // credential the run will actually use (OPENAI_API_KEY, not OpenRouter's).
+  if (methodName === 'llm-coached') {
+    return new MethodClass({ provider: pluginContext?.provider });
+  }
+
+  // ExternalMethod needs methodPath to find the Python plugin directory.
+  // Shared per plugin so the run reuses one bridge process (see above).
   if (methodName === 'external') {
-    return new MethodClass({
-      methodPath: pluginContext?.methodPath || null,
-    });
+    const methodPath = pluginContext?.methodPath || null;
+    if (!methodPath) return new MethodClass({ methodPath });
+    let instance = externalMethods.get(methodPath);
+    if (!instance) {
+      instance = new MethodClass({ methodPath });
+      externalMethods.set(methodPath, instance);
+    }
+    return instance;
   }
 
   return new MethodClass();
@@ -197,7 +233,44 @@ async function translateRawContent(prompt, options) {
   // (api → endpoint, external → methodPath) are constructed the same
   // way here as on the key-value path in translateBatch.
   const method = getMethod(pairConfig.method, pairConfig);
+  if (method.translatesRawText) {
+    return translateBlocksForRawTextEngine(method, prompt, pairConfig, options);
+  }
   return method.translateContent(prompt, pairConfig, options);
 }
 
-export { translateBatch, translateRawContent, buildPrompt, isUnsafeKey, inferKeyTypes, getMethod, METHOD_REGISTRY };
+/**
+ * A raw-text engine gets only Markdown, one block at a time.
+ *
+ * Those engines read the body after "\n---\n"; the default BLOCK-batch
+ * prompt has no such separator, so they were sent — and billed for — the
+ * whole LLM instruction prompt with every block in it, and the ⟦SEG_N⟧
+ * markers survived only by luck (found 2026-10-03). Each block now goes as
+ * its own page-shaped prompt and the reply is reassembled under its marker;
+ * a block the engine fails is simply absent, which the content gate reports.
+ */
+async function translateBlocksForRawTextEngine(method, prompt, pairConfig, options) {
+  const request = parseContentPrompt(prompt);
+  if (!request) return null; // nothing but instructions — never send those
+  if (request.mode === 'page') {
+    return method.translateContent(`${CONTENT_SEPARATOR}${request.keys.body}`, pairConfig, options);
+  }
+  const translated = new Map();
+  const queue = [...request.ids];
+  const worker = async () => {
+    while (queue.length > 0) {
+      const id = queue.shift();
+      const text = request.keys[`segment.${id}`];
+      if (!text || !text.trim()) { translated.set(id, text ?? ''); continue; }
+      const out = await method.translateContent(`${CONTENT_SEPARATOR}${text}`, pairConfig, options);
+      if (typeof out === 'string') translated.set(id, out);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(4, request.ids.length) }, worker));
+  const parts = request.ids
+    .filter((id) => translated.has(id))
+    .map((id) => `${SEGMENT_MARKER_PREFIX}${id}${SEGMENT_MARKER_SUFFIX}\n${translated.get(id)}`);
+  return parts.length > 0 ? parts.join('\n\n') : null;
+}
+
+export { translateBatch, translateRawContent, translateBlocksForRawTextEngine, buildPrompt, isUnsafeKey, inferKeyTypes, getMethod, shutdownMethods, METHOD_REGISTRY };

package/lib/types.js

@@ -23,8 +23,11 @@
  * @property {number} version - Config schema version (currently 3)
  * @property {string} inputLocale - Source locale code (e.g., 'en')
  * @property {string} baseUrl - Site base URL for SEO commands
- * @property {string} localesDir - Absolute path to locale files directory
- * @property {string|null} contentDir - Hugo/Docusaurus content directory, or null if disabled
+ * @property {string} localesDir - Absolute path to locale files directory (derived from localesPattern when that is set)
+ * @property {string|null} [localesPattern] - Absolute locale-file pattern with {lang} and optional {ns} (lib/locale-layout.js)
+ * @property {'flat'|'dir'|null} [localesLayout] - Forces the layout auto-detection's answer
+ * @property {string|null} [defaultNamespace] - Namespace file `wrap` adds keys to in a multi-file locale
+ * @property {string|null} contentDir - Folder of Markdown/MDX to translate (a Hugo content/ dir or any folder), or null if disabled
  * @property {string[]|null} translatableFields - Override for content translatable fields, or null for defaults
  * @property {Array<string>|object} languages - Target languages (array of codes or object with config)
  * @property {Object<string, LanguageConfig>} [resolvedLanguages] - Fully resolved language map (code → config). Set by resolveConfig.
@@ -33,6 +36,7 @@
  * @property {object|null} pairs - Advanced per-pair overrides, or null
  * @property {string} model - Default translation model (e.g., 'openai/gpt-4o-mini')
  * @property {string} defaultMethod - Global default method: 'llm', 'google-translate', 'api'
+ * @property {string|null} [provider] - LLM-lane transport: 'openrouter' (default), 'openai', 'anthropic', 'gemini', 'local'
  * @property {number} batchSize - Default batch size for translation calls
  * @property {string} fallbackPrefix - Prefix for untranslated fallback values (default: '[EN] ')
  * @property {string} apiKeyEnvVar - Environment variable name for the API key
@@ -54,6 +58,7 @@
  * @property {string} source - Source locale code (e.g., 'en')
  * @property {string} target - Target locale code (e.g., 'fr')
  * @property {string} method - Translation method name: 'llm', 'llm-coached', 'google-translate', 'api'
+ * @property {string|null} provider - Resolved transport for llm-coached / a rewritten llm pair; null for engine methods
  * @property {string} model - Model identifier (e.g., 'openai/gpt-4o-mini')
  * @property {string} qualityTier - Quality tier: 'standard', 'high', 'research', 'verified'
  * @property {number} batchSize - Max keys per API call
@@ -70,6 +75,8 @@
  * @property {string|null} formalitySystem - Formality system name (e.g., 'T-V', 'speech-levels'). Used by DeepL for structured formality mapping.
  * @property {string|null} genderGuidance - Language-specific gender guidance for LLM prompts, or null
  * @property {Set<string>} _defaults - Fields that were filled from system defaults (used by plugin precedence)
+ * @property {PairConfig} [fallback] - The second method for what this pair's own method cannot translate safely (set by resolvePairs when configured; see pairs.js resolveFallbackForPair). Itself a full PairConfig with `isFallback: true` and no `fallback` of its own.
+ * @property {boolean} [isFallback] - True on a resolved fallback config
  *
  * --- Plugin-injected fields (present after resolvePluginForPair) ---
  * @property {string} [endpoint] - Plugin API endpoint URL
@@ -100,9 +107,18 @@
  * @property {string} [dir] - Text direction: 'ltr' or 'rtl'
  * @property {string|null} [formalitySystem] - Formality system name (e.g., 'T-V', 'speech-levels', 'keigo')
  * @property {string} [model] - Per-language model override
+ * @property {string} [provider] - Per-language LLM-lane transport override
  * @property {number} [batchSize] - Per-language batch size override
  * @property {number} [maxRetries] - Per-language max retries override
  * @property {string} [script] - Script system override (e.g., 'syllabics' for Cree)
+ * @property {string} [method] - Per-language translation method
+ * @property {string} [endpoint] - API endpoint for the `api` method
+ * @property {number} [temperature] - Per-language temperature
+ * @property {string} [coachingFile] - Per-language coaching prompt file
+ * @property {string} [coachingPrompt] - Per-language coaching prompt text
+ * @property {string} [promptContext] - Per-language application context
+ * @property {'block'|'page'} [contentSegmentation] - Markdown body granularity
+ * @property {object|null} [fallback] - Raw `fallback` (a second method), resolved by pairs.js
  */
 
 // -----------------------------------------------------------------
@@ -218,10 +234,13 @@
  * @property {string} [format] - Locale file format override
  * @property {string} [out] - Output file path (seo sitemap)
  * @property {string} [src] - Source directory for lint/wrap
- * @property {string} ['content-dir'] - Hugo content directory
+ * @property {string} ['content-dir'] - Folder of Markdown/MDX to translate (overrides contentDir)
  * @property {string} ['base-url'] - Site base URL override
  * @property {string} ['min-length'] - Minimum string length to flag
  * @property {string} ['force-keys'] - Comma-separated keys to force re-translate
+ * @property {boolean} ['fresh-on-model-change'] - Serve only exact-model TM hits (default reuses other models' cached translations)
+ * @property {string[]} [files] - sync: only these content files (globs)
+ * @property {string[]} [retranslate] - sync: translate these content files fresh (globs)
  * @property {boolean} ['warn-only'] - Exit 0 even with issues
  */