失败（文档翻译）

“失败”选项卡仅用于文档翻译。它读取在段落无法成功翻译到某个区域设置时写入 SQLite 的失败记录，例如，模型输出为空或无效、翻译后验证错误（AST mismatch、占位符泄漏和类似的质量检查），或阻止进度的致命条件。

它能帮助您回答：哪个源段落出了问题，针对哪个区域设置和模型，以及记录了什么错误文本？

何时使用

• 在 translate-docs 或 sync 处理完错误、部分语言环境或混乱的日志后 — 排序和过滤失败，而不是仅仅滚动终端输出。
• 当你想要 优先处理重做时：按 # 失败 排序，以便重复失败的段落在重试中优先出现；这些是 简化或重新格式化 源 markdown 的强有力候选项。
• 当你需要 确切段落 — 文件路径、行提示、源哈希和完整源文本 — 以便在你的代码库中编辑正确的段落。

源编辑为何重要

密集的内联标记（粗体与 `code` 混合、嵌套强调、包含许多跨度的长句）使得模型更难返回仍通过结构检查的翻译。具有多个记录失败的段落通常通过重写或拆分源（或将示例移到围栏代码块中）比通过对未更改的文本重新运行翻译更能得到改进。这与复杂的 Markdown 和失败的质量检查一致。

如何使用此选项卡

1. 在仪表板中打开失败。
2. 阅读摘要条带 — 包含任何失败的段落，以及包含1、2或3+ 失败记录的段落计数。
3. 按部分文件名、区域设置、模型、质量错误（值来自您的缓存）、仅致命以及可选的源哈希、源文本或错误消息子字符串进行筛选 — 然后单击应用。
4. 选择排序：# 失败（默认）或排序：文件路径 + 行号。
5. 使用表格顶部或底部的分页。单击一行以展开完整的源文本。模型列显示失败模型，如果可用，则显示来自稍后成功缓存条目的模型。
6. 🔗 链接控件将文件/行提示记录到运行 ai-i18n-tools dashboard 的终端。
7. 修复项目中的源文件，然后再次运行 translate-docs 或 sync。如果列表在成功运行后看起来过时，请运行 ai-i18n-tools sync --force-update 并重新加载仪表板。

为了与 UI 并行进行基于文件的调试，请在 translate-docs、translate-ui、translate-json、translate-svg 或 sync 上传入全局 --debug-failed，以便在 cacheDir 下为每次被丢弃的模型尝试（提示词、原始输出、验证错误）写入一个 FAILED-TRANSLATION 文件，包括脚本回退警告——而不仅仅是在所有模型都失败时。参见缓存行为和 translate-docs 标志。

失败与 Markdown 问题

	失败	Markdown 问题
记录时间	翻译期间（按区域设置）	翻译之前（源扫描）
典型原因	错误的模型输出、验证错误	不成对的强调、未闭合的代码跨度、链接外的粗体
修复	编辑源并重新翻译	修复源 Markdown，然后重新翻译

有关翻译前静态检查，请参阅Markdown 问题。