ai-i18n-tools 1.8.8 → 1.8.10

package/bin/ai-i18n-tools

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * PATH-friendly name (no .mjs suffix) beside the published package.json bin
+ * (`ai-i18n-tools.mjs`). With direnv `PATH_add bin` in `.envrc`, the bare
+ * `ai-i18n-tools` command works in this checkout. pnpm still does not link the
+ * root package's own bin into `node_modules/.bin`.
+ */
+import "./ai-i18n-tools.mjs";

package/dist/api/llm-client.d.ts

@@ -2,32 +2,27 @@ import type { CldrPluralForm, I18nConfig } from "../core/types.js";
 import { type BatchTranslationResult, type ChatResponse, type LlmUsageStats, type Segment, type TranslationResult } from "../core/types.js";
 import { type DocumentBatchResponseFormat, type DocumentPromptContentType, type ProofreadUISlotResult } from "../core/prompt-builder.js";
 import type { Logger } from "../utils/logger.js";
+/** Details attached when every model in a fallback chain fails. */
+export interface LlmAllModelsFailedDetails {
+    systemPrompt: string;
+    userContent: string;
+    lastModel: string;
+    lastError: unknown;
+    /** HTTP response body text when the model returned content but parsing/validation failed. */
+    lastRawAssistantContent?: string;
+    /** Tokens spent across billed-but-discarded attempts before every model failed. */
+    wastedUsage?: LlmUsageStats;
+    /** USD cost spent across billed-but-discarded attempts (undefined when no cost was reported). */
+    wastedCost?: number;
+}
+/** Thrown when every model in the chain fails for a translation request. */
+export declare class LlmAllModelsFailedError extends Error {
+    readonly details: LlmAllModelsFailedDetails;
+    constructor(message: string, details: LlmAllModelsFailedDetails);
+}
 /** Thrown when every model in the chain fails for {@link LlmClient.translateDocumentBatch}. */
-export declare class DocumentBatchAllModelsFailedError extends Error {
-    readonly details: {
-        systemPrompt: string;
-        userContent: string;
-        lastModel: string;
-        lastError: unknown;
-        /** HTTP response body text when the model returned content but parsing failed. */
-        lastRawAssistantContent?: string;
-        /** Tokens spent across billed-but-discarded attempts before every model failed. */
-        wastedUsage?: LlmUsageStats;
-        /** USD cost spent across billed-but-discarded attempts (undefined when no cost was reported). */
-        wastedCost?: number;
-    };
-    constructor(message: string, details: {
-        systemPrompt: string;
-        userContent: string;
-        lastModel: string;
-        lastError: unknown;
-        /** HTTP response body text when the model returned content but parsing failed. */
-        lastRawAssistantContent?: string;
-        /** Tokens spent across billed-but-discarded attempts before every model failed. */
-        wastedUsage?: LlmUsageStats;
-        /** USD cost spent across billed-but-discarded attempts (undefined when no cost was reported). */
-        wastedCost?: number;
-    });
+export declare class DocumentBatchAllModelsFailedError extends LlmAllModelsFailedError {
+    constructor(message: string, details: LlmAllModelsFailedDetails);
 }
 export interface LlmClientOptions {
     config: Pick<I18nConfig, "provider" | "providers" | "sourceLocale" | "localeDisplayNames">;
@@ -40,6 +35,17 @@ export interface LlmClientOptions {
     translationModels?: string[];
     /** Append request/response JSON when set. */
     debugTrafficFilePath?: string | null;
+    /**
+     * When set (CLI `--debug-failed` → `cacheDir`), write a `FAILED-TRANSLATION` file for each
+     * discarded model attempt (script/parse/API), including fallbacks — not only the final
+     * all-models-failed throw.
+     */
+    debugFailedDir?: string | null;
+    /**
+     * Path label used in `--debug-failed` logs for UI/plural/proofread batches. Document batches
+     * prefer `docLogContext.relativePath` when present.
+     */
+    debugFailedRelativePath?: string;
     logger?: Logger;
     httpReferer?: string;
     xTitle?: string;
@@ -67,6 +73,8 @@ export declare class LlmClient {
     private readonly maxTokens;
     private readonly temperature;
     private readonly debugTrafficFilePath;
+    private readonly debugFailedDir;
+    private readonly debugFailedRelativePath;
     private readonly logger?;
     private readonly localeDisplayNames;
     private readonly sourceLanguageLabel;
@@ -95,12 +103,21 @@ export declare class LlmClient {
      * a stray foreign-language quote does not fail the output, and `zh-Hans`/`zh-Hant` are told
      * apart via variant-distinct characters. Uses {@link effectiveScriptSubtag} so bare `hi`
      * (Devanagari by default) is enforced like an explicit `*-Deva` tag. Locales with no
-     * effective script, and composite scripts (e.g. `Jpan`, `Kore`), are not enforced.
+     * effective script are not enforced. Composite families (`Jpan`, `Kore`) are enforced as
+     * allowed-script sets. Fully Latin leftover that is not a preserved brand/code token is
+     * rejected for non-Latin targets.
      */
     private assertExpectedScript;
+    private assertBatchExpectedScript;
     private appendDebugLog;
     /** Match doc-translate log lines: two-space indent, locale, filename. */
     private warnModelSwitch;
+    /**
+     * Persist prompt + raw output + validation error for a discarded model attempt when
+     * `--debug-failed` supplied `debugFailedDir`.
+     */
+    private logFailedModelAttempt;
+    private static promptPartsFromMessages;
     private toOpenRouterMessages;
     private static emptyDiscarded;
     /** Add a billed-but-discarded attempt's tokens/cost onto the running discarded total. */

package/dist/api/llm-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"llm-client.d.ts","sourceRoot":"","sources":["../../src/api/llm-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"llm-client.d.ts","sourceRoot":"","sources":["../../src/api/llm-client.ts"],"names":[],"mappings":"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"}

package/dist/api/llm-client.js

@@ -4,10 +4,11 @@ import { generateText } from "ai";
 import { createOpenAICompatible, } from "@ai-sdk/openai-compatible";
 import { BatchTranslationError, } from "../core/types.js";
 import { englishLanguageNameForLocale, normalizeLocale, resolveTranslationModels, } from "../core/config.js";
-import { effectiveScriptSubtag, scriptValidationIssue } from "../core/locale-utils.js";
+import { batchTranslationScriptIssue, effectiveScriptSubtag, scriptValidationIssue, } from "../core/locale-utils.js";
 import { OPENROUTER_PROVIDER_KEY, resolveActiveProvider, resolveApiKey, resolveProviderSettings, } from "../core/llm-providers.js";
 import { buildDocumentBatchPrompt, buildDocumentSinglePrompt, buildProofreadUIPromptMessages, buildUIPromptMessages, parseBatchJsonArrayResponse, parseBatchJsonObjectResponse, parseBatchTranslationResponse, parseProofreadUIBatchResponse, parsePluralFormsJsonResponse, parseUIJsonArrayResponse, ScriptValidationError, } from "../core/prompt-builder.js";
 import { assertPluralFormsPlaceholders } from "../core/plural-placeholders.js";
+import { warnTranslationFailureLogPath, writeTranslationFailureLog, } from "../utils/translation-failure-log.js";
 /** OpenRouter: prefer throughput; allow backup providers (top-level `provider` routing field). */
 const OPENROUTER_PROVIDER = {
     sort: "throughput",
@@ -41,11 +42,18 @@ const openRouterMetadataExtractor = {
         buildMetadata: () => undefined,
     }),
 };
-/** Thrown when every model in the chain fails for {@link LlmClient.translateDocumentBatch}. */
-export class DocumentBatchAllModelsFailedError extends Error {
+/** Thrown when every model in the chain fails for a translation request. */
+export class LlmAllModelsFailedError extends Error {
     constructor(message, details) {
         super(message);
         this.details = details;
+        this.name = "LlmAllModelsFailedError";
+    }
+}
+/** Thrown when every model in the chain fails for {@link LlmClient.translateDocumentBatch}. */
+export class DocumentBatchAllModelsFailedError extends LlmAllModelsFailedError {
+    constructor(message, details) {
+        super(message, details);
         this.name = "DocumentBatchAllModelsFailedError";
     }
 }
@@ -85,6 +93,8 @@ export class LlmClient {
         this.temperature = settings.temperature;
         this.requestTimeoutMs = settings.requestTimeoutMs;
         this.debugTrafficFilePath = opts.debugTrafficFilePath ?? null;
+        this.debugFailedDir = opts.debugFailedDir ?? null;
+        this.debugFailedRelativePath = opts.debugFailedRelativePath?.trim() || "llm-batch";
         this.logger = opts.logger;
         this.localeDisplayNames = {};
         for (const [k, v] of Object.entries(opts.config.localeDisplayNames ?? {})) {
@@ -153,20 +163,30 @@ export class LlmClient {
      * a stray foreign-language quote does not fail the output, and `zh-Hans`/`zh-Hant` are told
      * apart via variant-distinct characters. Uses {@link effectiveScriptSubtag} so bare `hi`
      * (Devanagari by default) is enforced like an explicit `*-Deva` tag. Locales with no
-     * effective script, and composite scripts (e.g. `Jpan`, `Kore`), are not enforced.
+     * effective script are not enforced. Composite families (`Jpan`, `Kore`) are enforced as
+     * allowed-script sets. Fully Latin leftover that is not a preserved brand/code token is
+     * rejected for non-Latin targets.
      */
-    assertExpectedScript(text, targetLocale) {
+    assertExpectedScript(text, targetLocale, sourceText) {
         const script = effectiveScriptSubtag(targetLocale);
         if (!script) {
             return;
         }
-        const issue = scriptValidationIssue(text, script);
+        const issue = scriptValidationIssue(text, script, sourceText !== undefined ? { sourceText } : undefined);
         if (!issue) {
             return;
         }
         const suffix = issue.sample.length > 0 ? ` (${issue.sample.join(" ")})` : "";
         throw new ScriptValidationError(`Output for ${targetLocale} ${issue.message}${suffix}`, text, issue.sample);
     }
+    assertBatchExpectedScript(outputs, sources, targetLocale) {
+        const issue = batchTranslationScriptIssue(outputs, sources, targetLocale);
+        if (!issue) {
+            return;
+        }
+        const suffix = issue.sample.length > 0 ? ` (${issue.sample.join(" ")})` : "";
+        throw new ScriptValidationError(`Output for ${targetLocale} ${issue.message}${suffix}`, outputs.join("\n"), issue.sample);
+    }
     appendDebugLog(direction, payload) {
         if (!this.debugTrafficFilePath) {
             return;
@@ -187,6 +207,43 @@ export class LlmClient {
         const detail = error instanceof Error ? error.message : String(error);
         console.warn(chalk.yellow(`  ⚠️  ${loc}: ${failedModel} failed (${detail}). Trying ${nextModel}…`));
     }
+    /**
+     * Persist prompt + raw output + validation error for a discarded model attempt when
+     * `--debug-failed` supplied `debugFailedDir`.
+     */
+    logFailedModelAttempt(args) {
+        if (!this.debugFailedDir) {
+            return;
+        }
+        const nextModel = this.modelsToTry[args.modelIndex + 1];
+        const errMsg = args.error instanceof Error ? args.error.message : String(args.error);
+        warnTranslationFailureLogPath(writeTranslationFailureLog({
+            cacheDirAbs: this.debugFailedDir,
+            relativePath: args.relativePath,
+            locale: args.locale,
+            segmentsLabel: args.segmentsLabel ?? "batch",
+            outcome: nextModel ? "retrying_next_model" : "fatal",
+            failedModel: args.model,
+            nextModel,
+            qualityErrors: [errMsg],
+            perSegmentLines: [],
+            systemPrompt: args.systemPrompt,
+            userContent: args.userContent,
+            rawAssistantContent: args.rawAssistantContent ?? "",
+        }));
+    }
+    static promptPartsFromMessages(messages) {
+        return {
+            systemPrompt: messages
+                .filter((m) => m.role === "system")
+                .map((m) => m.content)
+                .join("\n\n"),
+            userContent: messages
+                .filter((m) => m.role === "user")
+                .map((m) => m.content)
+                .join("\n\n"),
+        };
+    }
     toOpenRouterMessages(messages) {
         return messages.map((m) => ({ role: m.role, content: m.content }));
     }
@@ -288,9 +345,12 @@ export class LlmClient {
         const start = Math.max(0, Math.floor(options?.startModelIndex ?? 0));
         let lastError;
         const discarded = LlmClient.emptyDiscarded();
+        const promptParts = LlmClient.promptPartsFromMessages(messages);
+        const failedPath = options?.docLogContext?.relativePath ?? this.debugFailedRelativePath;
+        const failedLocale = options?.docLogContext?.locale ?? "unknown";
         for (let mi = start; mi < this.modelsToTry.length; mi++) {
             const model = this.modelsToTry[mi];
-            const warnFailure = (e) => {
+            const recordFailure = (e, rawAssistantContent) => {
                 const nextModel = this.modelsToTry[mi + 1];
                 if (nextModel && options?.docLogContext) {
                     this.warnModelSwitch(options.docLogContext.locale, options.docLogContext.relativePath, model, nextModel, e);
@@ -298,6 +358,16 @@ export class LlmClient {
                 else if (!options?.docLogContext) {
                     this.logger?.warn(`Model ${model} failed: ${e}`);
                 }
+                this.logFailedModelAttempt({
+                    locale: failedLocale,
+                    relativePath: failedPath,
+                    model,
+                    modelIndex: mi,
+                    error: e,
+                    systemPrompt: promptParts.systemPrompt,
+                    userContent: promptParts.userContent,
+                    rawAssistantContent,
+                });
             };
             let completion;
             try {
@@ -308,7 +378,7 @@ export class LlmClient {
                 if (e instanceof BilledCompletionError) {
                     LlmClient.addDiscarded(discarded, e.usage, e.cost);
                 }
-                warnFailure(e);
+                recordFailure(e);
                 continue;
             }
             try {
@@ -317,7 +387,7 @@ export class LlmClient {
             catch (e) {
                 lastError = e;
                 LlmClient.addDiscarded(discarded, completion.usage, completion.cost);
-                warnFailure(e);
+                recordFailure(e, completion.content);
                 continue;
             }
             const folded = LlmClient.foldDiscarded(completion.usage, completion.cost, discarded);
@@ -345,7 +415,7 @@ export class LlmClient {
         ], {
             startModelIndex: options?.startModelIndex,
             docLogContext: options?.docLogContext,
-            validateResponse: (c) => this.assertExpectedScript(this.stripTranslateTags(c), targetLocale),
+            validateResponse: (c) => this.assertExpectedScript(this.stripTranslateTags(c), targetLocale, content),
         });
         return {
             content: this.stripTranslateTags(res.content),
@@ -410,6 +480,15 @@ export class LlmClient {
                         this.logger?.warn(`Batch request failed with ${model}: ${e}`);
                     }
                 }
+                this.logFailedModelAttempt({
+                    locale,
+                    relativePath: options?.docLogContext?.relativePath ?? this.debugFailedRelativePath,
+                    model,
+                    modelIndex: mi,
+                    error: e,
+                    systemPrompt,
+                    userContent,
+                });
                 continue;
             }
             try {
@@ -423,9 +502,20 @@ export class LlmClient {
                 else {
                     translations = parseBatchTranslationResponse(completion.content, segments.length, completion.content);
                 }
-                for (const value of translations.values()) {
-                    this.assertExpectedScript(value, locale);
+                for (const [index, value] of translations.entries()) {
+                    this.assertExpectedScript(value, locale, segments[index]?.content);
+                }
+                const batchOutputs = [];
+                const batchSources = [];
+                for (let i = 0; i < segments.length; i++) {
+                    const value = translations.get(i);
+                    if (value === undefined) {
+                        continue;
+                    }
+                    batchOutputs.push(value);
+                    batchSources.push(segments[i]?.content ?? "");
                 }
+                this.assertBatchExpectedScript(batchOutputs, batchSources, locale);
                 const folded = LlmClient.foldDiscarded(completion.usage, completion.cost, discarded);
                 return {
                     translations,
@@ -458,6 +548,16 @@ export class LlmClient {
                         this.logger?.warn(`Batch parse failed with ${model}: ${e}`);
                     }
                 }
+                this.logFailedModelAttempt({
+                    locale,
+                    relativePath: options?.docLogContext?.relativePath ?? this.debugFailedRelativePath,
+                    model,
+                    modelIndex: mi,
+                    error: e,
+                    systemPrompt,
+                    userContent,
+                    rawAssistantContent: completion.content,
+                });
             }
         }
         const msg = `All translation models failed for batch (${this.modelsToTry.slice(start).join(", ")}). Last error: ${lastError instanceof Error ? lastError.message : String(lastError)}`;
@@ -503,6 +603,7 @@ export class LlmClient {
         const start = Math.max(0, Math.floor(options?.startModelIndex ?? 0));
         let lastError;
         const discarded = LlmClient.emptyDiscarded();
+        let lastFailureDetails;
         for (let mi = start; mi < this.modelsToTry.length; mi++) {
             const model = this.modelsToTry[mi];
             let result;
@@ -514,14 +615,31 @@ export class LlmClient {
                 if (e instanceof BilledCompletionError) {
                     LlmClient.addDiscarded(discarded, e.usage, e.cost);
                 }
+                lastFailureDetails = {
+                    systemPrompt,
+                    userContent,
+                    lastModel: model,
+                    lastError: e,
+                };
                 this.logger?.warn(`UI batch failed with ${model}: ${e}`);
+                this.logFailedModelAttempt({
+                    locale: targetLocale,
+                    relativePath: this.debugFailedRelativePath,
+                    model,
+                    modelIndex: mi,
+                    error: e,
+                    systemPrompt,
+                    userContent,
+                    segmentsLabel: "ui-batch",
+                });
                 continue;
             }
             try {
                 const translations = parseUIJsonArrayResponse(result.content, texts.length);
-                for (const value of translations) {
-                    this.assertExpectedScript(value, targetLocale);
+                for (let i = 0; i < translations.length; i++) {
+                    this.assertExpectedScript(translations[i], targetLocale, texts[i]);
                 }
+                this.assertBatchExpectedScript(translations, texts, targetLocale);
                 const folded = LlmClient.foldDiscarded(result.usage, result.cost, discarded);
                 return {
                     translations,
@@ -533,10 +651,33 @@ export class LlmClient {
             catch (e) {
                 lastError = e;
                 LlmClient.addDiscarded(discarded, result.usage, result.cost);
+                lastFailureDetails = {
+                    systemPrompt,
+                    userContent,
+                    lastModel: model,
+                    lastError: e,
+                    lastRawAssistantContent: result.content,
+                };
                 this.logger?.warn(`UI batch failed with ${model}: ${e}`);
+                this.logFailedModelAttempt({
+                    locale: targetLocale,
+                    relativePath: this.debugFailedRelativePath,
+                    model,
+                    modelIndex: mi,
+                    error: e,
+                    systemPrompt,
+                    userContent,
+                    rawAssistantContent: result.content,
+                    segmentsLabel: "ui-batch",
+                });
             }
         }
-        throw new Error(`All translation models failed for UI batch (${this.modelsToTry.slice(start).join(", ")}). Last error: ${lastError}`);
+        throw new LlmAllModelsFailedError(`All translation models failed for UI batch (${this.modelsToTry.slice(start).join(", ")}). Last error: ${lastError instanceof Error ? lastError.message : String(lastError)}`, lastFailureDetails ?? {
+            systemPrompt,
+            userContent,
+            lastModel: this.modelsToTry[Math.max(0, this.modelsToTry.length - 1)],
+            lastError,
+        });
     }
     /**
      * `proofread-ui`: review a batch of source-locale UI strings; model returns JSON array of `{ issues: [...] }`.
@@ -573,6 +714,16 @@ export class LlmClient {
                     LlmClient.addDiscarded(discarded, e.usage, e.cost);
                 }
                 this.logger?.warn(`proofread-ui batch failed with ${model}: ${e}`);
+                this.logFailedModelAttempt({
+                    locale: languageLabel,
+                    relativePath: this.debugFailedRelativePath,
+                    model,
+                    modelIndex: mi,
+                    error: e,
+                    systemPrompt,
+                    userContent,
+                    segmentsLabel: "proofread-ui",
+                });
                 continue;
             }
             try {
@@ -590,6 +741,17 @@ export class LlmClient {
                 lastError = e;
                 LlmClient.addDiscarded(discarded, result.usage, result.cost);
                 this.logger?.warn(`proofread-ui batch failed with ${model}: ${e}`);
+                this.logFailedModelAttempt({
+                    locale: languageLabel,
+                    relativePath: this.debugFailedRelativePath,
+                    model,
+                    modelIndex: mi,
+                    error: e,
+                    systemPrompt,
+                    userContent,
+                    rawAssistantContent: result.content,
+                    segmentsLabel: "proofread-ui",
+                });
             }
         }
         throw new Error(`All translation models failed for proofread-ui batch (${this.modelsToTry.slice(start).join(", ")}). Last error: ${lastError}`);
@@ -612,6 +774,7 @@ export class LlmClient {
         const start = Math.max(0, Math.floor(options?.startModelIndex ?? 0));
         let lastError;
         const discarded = LlmClient.emptyDiscarded();
+        let lastFailureDetails;
         for (let mi = start; mi < this.modelsToTry.length; mi++) {
             const model = this.modelsToTry[mi];
             let result;
@@ -623,7 +786,23 @@ export class LlmClient {
                 if (e instanceof BilledCompletionError) {
                     LlmClient.addDiscarded(discarded, e.usage, e.cost);
                 }
+                lastFailureDetails = {
+                    systemPrompt: messages.systemPrompt,
+                    userContent: messages.userContent,
+                    lastModel: model,
+                    lastError: e,
+                };
                 this.logger?.warn(`Plural cardinal batch failed with ${model}: ${e}`);
+                this.logFailedModelAttempt({
+                    locale: options?.targetLocale ?? "unknown",
+                    relativePath: this.debugFailedRelativePath,
+                    model,
+                    modelIndex: mi,
+                    error: e,
+                    systemPrompt: messages.systemPrompt,
+                    userContent: messages.userContent,
+                    segmentsLabel: "plural-batch",
+                });
                 continue;
             }
             try {
@@ -636,7 +815,7 @@ export class LlmClient {
                 }
                 if (options?.targetLocale) {
                     for (const value of Object.values(forms)) {
-                        this.assertExpectedScript(value, options.targetLocale);
+                        this.assertExpectedScript(value, options.targetLocale, options.originalLiteral);
                     }
                 }
                 const folded = LlmClient.foldDiscarded(result.usage, result.cost, discarded);
@@ -651,10 +830,33 @@ export class LlmClient {
             catch (e) {
                 lastError = e;
                 LlmClient.addDiscarded(discarded, result.usage, result.cost);
+                lastFailureDetails = {
+                    systemPrompt: messages.systemPrompt,
+                    userContent: messages.userContent,
+                    lastModel: model,
+                    lastError: e,
+                    lastRawAssistantContent: result.content,
+                };
                 this.logger?.warn(`Plural cardinal batch failed with ${model}: ${e}`);
+                this.logFailedModelAttempt({
+                    locale: options?.targetLocale ?? "unknown",
+                    relativePath: this.debugFailedRelativePath,
+                    model,
+                    modelIndex: mi,
+                    error: e,
+                    systemPrompt: messages.systemPrompt,
+                    userContent: messages.userContent,
+                    rawAssistantContent: result.content,
+                    segmentsLabel: "plural-batch",
+                });
             }
         }
-        throw new Error(`All translation models failed for plural cardinal batch (${this.modelsToTry.slice(start).join(", ")}). Last error: ${lastError}`);
+        throw new LlmAllModelsFailedError(`All translation models failed for plural cardinal batch (${this.modelsToTry.slice(start).join(", ")}). Last error: ${lastError instanceof Error ? lastError.message : String(lastError)}`, lastFailureDetails ?? {
+            systemPrompt: messages.systemPrompt,
+            userContent: messages.userContent,
+            lastModel: this.modelsToTry[Math.max(0, this.modelsToTry.length - 1)],
+            lastError,
+        });
     }
 }
 /** @deprecated Use {@link LlmClient}. Retained for backward-compatible imports. */