#常见问题

通用排查：按 F12 打开浏览器开发者工具，切换到“网络”（Network）查看请求的 Response 详情，绝大多数报错都能在此定位。

#翻译结果为空、仅显示原文、null 怎么办？

先分清两种情况：

只有少数行是原文 —— 这是"失败行回填"：个别行翻译失败时用原文占位，不破坏文件结构。结果区顶部会出现红色提示，点 「再试一次」 只补译失败的行，已成功的内容不会重复扣费。多数是网络抖动或服务临时不稳，再试一两次通常就好。

整篇没翻 / 大面积空白 / null —— 接口没跑通，按顺序排查：

1. 测试连接：点页面顶部的 API 状态徽章 → 「测试连接」，几秒就能确认接口通不通；
2. 看报错提示：工具会把常见错误转成可读文案（Key 无效、额度用尽、超时等），照提示处理即可；
3. 换免费接口对照：切到 GTX (Free) 翻一小段——GTX 能翻，说明问题出在原接口的 Key / 配置 / 额度；GTX 也不行，说明是网络问题（代理、防火墙、地区限制）；
4. 清缓存重试：在设置里清空翻译缓存，排除旧结果干扰。

仍未解决：按 F12 → Network/网络 → 重新点一次"翻译" → 点开最新的翻译请求，把 Status（如 401/429/5xx）和 Response 里的报错带上，到 GitHub 反馈。

#翻译失败会自动重试吗？哪些错误不重试？

会。网络抖动、限流（429）、服务器临时错误（5xx）按"重试次数"自动重试。重试后仍失败的行会回填原文（不留空），并集中到结果区顶部的红色失败面板，点 「再试一次」 一键补译，已完成的内容不重复扣费。

下面这些错误重试也没用，工具会直接标记失败，需要你动手改设置：

完整机制见 功能说明 → 失败行重发。

#翻译速度为什么慢？

最有效的一招：把「并发行数」调大——在当前服务默认值的基础上加 50%–100%，一旦出现 429 报错立即调回来。其他建议：

• 保持缓存开启（默认开）：相同内容直接复用，重跑几乎瞬间完成
• AI 模型开「上下文关联翻译」：连贯性更好，吞吐也更高
• 赶时间就换更快的服务：免费 GTX 比本地小模型快得多；付费 DeepL 比 Claude Opus 快得多
• 本地小模型（14B 以下）相反——要关上下文：小模型在长批次里容易漏行，关掉"上下文关联翻译"改成逐行并发，反而又快又稳

各服务默认并发不同，详见 功能说明 → 并发行数。

#字幕译文错位、几行被合并成一行怎么办？

个别 LLM（实测 Gemini、Mistral 出现较多）会破坏工具用来对齐行序的标记，导致译文串行，或把相邻几条字幕合并翻译成一块。工具已内置多重防护：

• 行标记丢失时不再按行号猜测位置，避免整段错位
• 检测到"一条字幕吞掉后面几条"的合并块时，丢弃该块并整组重译，不会产生重复内容
• 模型收到的指令中已明确禁止合并行

如果某个模型仍频繁出现此问题：

1. 换更守格式的模型：DeepSeek / Claude / GPT 对行标记的遵守度明显更好
2. 在 API 设置中把「上下文并发数」调低（如 3 → 1），单次输出行数越少越不容易乱
3. 出错的行会进失败面板，点 「再试一次」 补齐即可，不会重复扣费

#没有付费 API Key，怎么免费用 AI 翻译？

• 零配置起步：默认的 GTX (Free) 不需要任何 Key，速度也快——纯机器翻译，批量翻字幕、日常文本完全够用。连不上就换同样免费的 Edge (Free) 或 DeepLX (Free)，链路不同互为备胎
• 免费 LLM 额度：服务列表里不少接口提供免费档，常用的有 Google AI Studio（Gemini Flash 系列）、OpenRouter（带 :free 后缀的模型）、Nvidia NIM、GitHub Models（有 GitHub 账号即可，详见 接口指南）、SiliconFlow 等。多翻翻服务列表——很多接口就是因为有免费档才被收录的
• 注意网络环境：Google、OpenRouter 等海外服务需要相应的网络环境，连不上先排查网络而不是配置
• 只有隐私敏感的内容才值得本地部署；否则免费云端 API 比本地小模型又快又稳（见下一条）

#本地部署翻译，怎么选模型？

按"够用优先"排序：

1. 首选翻译专用模型 TranslateGemma（4B 起）：针对翻译训练，质量高于同级通用模型，显存要求低、速度快。注意在服务列表里直接选「TranslateGemma」；它是机器翻译类服务——内置提示词（系统/用户 Prompt 对它不生效），且需要手动指定源语言
2. 通用 LLM 至少 14B：Qwen3-14B / 32B、Gemma 3 27B 等，越大越稳。8B 以下小模型别用来跑大批量翻译——容易漏行、输出错乱，长任务甚至会把模型跑崩
3. 下载渠道：国内从 魔搭 ModelScope 下载，比 LM Studio 内置源 / Hugging Face 直连快得多

本地部署的主要价值是隐私（内容不出本机）。如果内容不敏感，用免费云端 API（见上一条）质量更高、也不占显卡。

#AI 翻译质量不理想怎么办？

按成本从低到高依次尝试：

1. 恢复默认：在"翻译设置"中重置，再用一小段文本复测——很多"翻得怪"是之前改过的参数导致的；
2. 调温度：术语严谨 / 技术文档 0.2 左右；日常内容 0.4–0.7；文学意译 0.8–1.0；
3. 开启上下文关联翻译：对白、长文更连贯；
4. 人名 / 术语不统一：用术语表指定固定译法（见下一条）；
5. 换模型：在线主流模型（DeepSeek / Claude / GPT / Gemini，包括各家 mini / flash 轻量档）翻译能力都足够——输出异常基本是参数或提示词的问题，不是模型不行。本地小模型则确实存在天花板，选型见上文 本地部署翻译，怎么选模型？

#怎么让人名、专有名词固定翻成同一个词？

用术语表——不需要把术语塞进系统提示词，术语表更可靠（按请求注入命中词条、违规自动重译、译后兜底替换），还不浪费 token。

使用方式：翻译设置 → 术语表 → 编辑词条，逐行添加"原文词 → 指定译法"（如 Spike → 斯派克），打开开关后自动对每次翻译生效。

批量导入用 TSV 格式（制表符分隔，可从 Excel / 表格软件直接复制）：

Spike	斯派克
Bebop	比波普

可选第 3 列填目标语言代码（如 zh、ja），一个文件即可导入多语言术语。完整说明见 功能说明 → 术语表。

#自定义 Prompt 需要写"保留时间轴 / 行号 / 格式"吗？

不需要。 工具只把对白文本发给模型——时间轴、序号、ASS/VTT 头等结构信息全部保留在本地，翻译完成后自动回填原位，模型根本看不到这些结构。

Prompt 里写"保留行数 / 编号 / 时间码"不仅没用，还会浪费 token、甚至诱导模型输出多余内容。自定义 Prompt 只需专注翻译风格和质量（语气、领域术语、目标读者等）。

#GTX 连不上或控制台出现 CORS 报错怎么办？

GTX 从浏览器直连 Google 的翻译网关。看到「翻译服务暂时连不上」或控制台 CORS 字样时，先做两步自救，多数情况一步解决：

1. 换网关：URL 输入框上方把网关从 Legacy gtx 切到 translate-pa（默认）。旧版 translate.googleapis.com/translate_a 端点被 Google 收紧了反滥用策略，很多 IP 会被跳转到验证页、浏览器据此报 CORS；默认的 translate-pa 网关跨域规范、可用性更好。
2. 换免费备胎：下拉切到 Edge (Free) 或 DeepLX (Free)——它们走完全不同的链路，零配置即用。

两步都不行，再排查网络环境：

3. 中国大陆直连：相关 Google 域名在大陆可能被屏蔽，表现为超时——需要代理，或改用国内可直连的 Qwen-MT / DeepSeek
4. 公司 / 学校网络：网关拦截请求并返回自己的提示页，浏览器据此报 CORS——换个网络（如手机热点）确认
5. 浏览器拦截扩展：部分广告/隐私扩展会拦截 googleapis.com 域，临时禁用后刷新重试

翻译开始前工具会先探测当前免费服务的可用性，整体不可达时直接提示并阻止运行，不会让任务白跑。限速与自动降速机制见 翻译接口指南 → 免费机器翻译使用要点。

#本地模型提示跨域 (CORS) 或连不上怎么办？

使用 Ollama、LM Studio 等本地模型时，常见失败原因是浏览器 CORS 或广告拦截：

1. 先临时关闭广告/隐私扩展并刷新；
2. 根据 翻译接口指南 启用本地服务的 CORS（如设置 OLLAMA_ORIGINS=*、在 LM Studio 勾选 Enable CORS）；
3. 若仍失败，检查端口占用，并在 Network 面板查看返回状态码。公司/校园网络还需确认防火墙未拦截本地端口。

#用 Ollama 跑 translategemma 模型，速度很慢/漏译怎么办？

多半是把 translategemma 当成普通 LLM 来配置了：选了「Custom (OpenAI-compatible)」+ 填 translategemma-4b-it 之类的模型名。这条路径走的是带批次/上下文标记的 LLM 通用流程，14B 以下的小模型很难稳定还原 prompt 里的结构，容易漏行、跑得也慢。

✅ 正确做法：在服务下拉里直接选「TranslateGemma」，它走的是专门的逐行调用，匹配 Gemma 翻译模型的输入输出格式，对本地小模型最稳定。详见 翻译接口指南 → TranslateGemma。

#本地思考模型翻译很慢、半天不出结果怎么办？

Qwen3 等思考型模型默认先生成一长段思考过程、再输出正式译文——在算力有限的本地设备上（每秒只有几个 token），每行翻译都要先白等几十秒的思考。按效果排序：

1. 关闭思考：在「翻译设置 → 系统提示词」末尾加一行 /no_think（Qwen3 家族的软开关；部分社区微调模型可能不支持）
2. 换非思考模型：选 instruct 变体，或在服务列表直接选翻译专用的 TranslateGemma——无思考环节、4B 起质量就不错，比思考模型快一个数量级
3. 确认 GPU 加载：生成速度只有个位数 token/s，通常是模型大部分跑在 CPU 上——检查 LM Studio / Ollama 的 GPU 层数设置
4. 「测试连接」与正式翻译共用「超时时间」设置（默认 180 秒）——思考时间确实很长时可适当调大

#为什么 DeepL 要经过中转服务器？

DeepL 官方不允许网页直接调用它的 API（浏览器跨域限制），所以工具内置了中转通道代发请求——Nvidia NIM 同理。Hunyuan、YandexGPT 则走可控的「中转 API」开关：官方端点目前无法从浏览器直连，开关默认开启、可随时关闭。所有通道都只做转发、不记录你的内容。

介意经过第三方？在设置里填自定义 API URL（如自建中转），请求就会直连你填的地址、优先级高于一切内置通道。详见 翻译接口指南 → 中转 API 与内置代理。

#API Key 会被保存到服务器吗？

不会。API Key 与所有设置都只存储在本地浏览器，任何服务器都无法读取。

#有没有 CLI、API 或桌面版？

没有，工具是纯网页版：打开即用、始终最新，无需安装和更新；字幕内容和 API Key 只存在你自己的浏览器里，不经过任何服务器。桌面 / 便携版没有计划，CLI / 程序化调用在长期路线图上（欢迎 PR）。

想减少重复手动操作，可以组合这几个现有功能实现"半自动化"：

• 批量模式：一次拖入多个文件，自动排队处理、打包下载
• 导入设置：用 JSON 一次性预置目标语言、API 配置等全部参数（详见 功能说明 → 设置导入/导出）
• 语言代码快速输入：多语言模式下直接粘贴语言代码串（如 zh, de, ru），跳过手动勾选