> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 常见问题

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

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

先分清两种情况：

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

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

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

仍未解决：按 **F12** → **Network/网络** → 重新点一次"翻译" → 点开最新的翻译请求，把 **Status**（如 401/429/5xx）和 **Response** 里的报错带上，[到 GitHub 反馈](https://github.com/rockbenben/subtitle-translator/issues)。

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

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

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

| 报错                            | 怎么办                               |
| ----------------------------- | --------------------------------- |
| Key 无效（401 / 403）             | 重新核对或更换 API Key                   |
| 超时                            | 把「超时时间」调大，或换个更快的服务                |
| 文本太长（context length exceeded） | 把「上下文行数」调小，或把文件拆小                 |
| 输出被截断（max_tokens reached）     | 把「最大输出 tokens」调大（或设 0 不限制），或把文件拆小 |

完整机制见 [功能说明 → 失败行重发](/guide/translation/info.md#失败行重发)。

## 翻译速度为什么慢？

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

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

各服务默认并发不同，详见 [功能说明 → 并发行数](/guide/translation/info.md#并发行数)。

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

个别 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` 后缀的模型）、**OpenCode Zen**（带 `(free)` 后缀的 SKU，注册绑账单信息即可，不预付费）、**Cerebras**（每日 100 万 token）、**Nvidia NIM**、**SiliconFlow** 等，详见 [接口指南](/guide/translation/api.md#部分接口的特别说明)。多翻翻服务列表——很多接口就是因为有免费档才被收录的

  > GitHub Models 已于 2026-07-30 被官方整家下线，工具里也已移除，别再找它了。
- **注意网络环境**：Google、OpenRouter 等海外服务需要相应的网络环境，连不上先排查网络而不是配置
- 只有**隐私敏感**的内容才值得本地部署；否则免费云端 API 比本地小模型又快又稳（见下一条）

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

按"够用优先"排序：

1. **首选翻译专用模型**（4B 起）：针对翻译训练，质量高于同级通用模型，显存要求低、速度快。两个选择，都要在服务列表里**直接选**（不是在 Custom 里填模型名），且都是机器翻译类服务——内置提示词（系统/用户 Prompt 对它们不生效）、无术语表、需要手动指定源语言：

   - [TranslateGemma](/guide/translation/api.md#translategemma)（Google，53 种语言）：含**乌克兰语、塞尔维亚语、立陶宛/拉脱维亚/爱沙尼亚语**与多数印度语系（马拉地、泰卢固、喀纳达……）
   - [MiLMMT](/guide/translation/api.md#milmmt)（小米，47 种语言）：含**粤语**与哈萨克/乌兹别克/阿塞拜疆/老挝/缅甸/高棉/马来语；**不含乌克兰语与塞尔维亚语**

   两家共同支持 39 种。常见语对（英↔中/日/韩/法/德/西/俄）两家都行，按你实际要的语种选就好
2. **通用 LLM 至少 14B**：Qwen3-14B / 32B、Gemma 3 27B 等，越大越稳。**8B 以下小模型别用来跑大批量翻译**——容易漏行、输出错乱，长任务甚至会把模型跑崩
3. **下载渠道**：国内从 [魔搭 ModelScope](https://www.modelscope.cn/models) 下载，比 LM Studio 内置源 / Hugging Face 直连快得多

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

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

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

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

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

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

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

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

```text
Spike	斯派克
Bebop	比波普
```

可选第 3 列填目标语言代码（如 `zh`、`ja`），一个文件即可导入多语言术语。完整说明见 [功能说明 → 术语表](/guide/translation/info.md#术语表glossary)。

## 自定义 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` 域，临时禁用后刷新重试

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

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

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

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

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

两个独立的原因，往往同时中招。

**① 换掉 Ollama。** TranslateGemma 与 MiLMMT 都是把提示词**预渲染**后打 `/v1/completions`，前提是服务端不再套模板；而 **Ollama 在这个端点上仍然会套 Modelfile 模板**（`FromCompleteRequest` 不设 `Raw`，`routes.go` 里 `if !req.Raw` 就套模板），提示词被再包一层，译文质量莫名其妙地差**而且不报错**。改用 **LM Studio / llama.cpp / koboldcpp**——这也是为什么这两个服务的快捷地址里没有 Ollama。详见 [翻译接口指南 → 本地模型接入](/guide/translation/api.md#本地模型接入)。

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

✅ 正确做法：在服务下拉里直接选「**TranslateGemma**」或「**MiLMMT**」，它们走专门的逐行调用，匹配翻译模型的输入输出格式，对本地小模型最稳定。

> 顺带：这两个服务频繁**超时**通常不是模型的问题，而是并发数超过了本地服务器的并行槽位——见 [本地模型接入](/guide/translation/api.md#本地模型接入) 里的说明。

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

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

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

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

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

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

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

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

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

**CLI 有。** 三个翻译工具的引擎是平台无关的纯 TypeScript，仓库里自带命令行入口，克隆后 `yarn cli` 即可用——它复用**同一条流水线和同一份格式解析/装配代码**，批处理、并发、重试、429 冷却、术语表、上下文翻译、逐行缓存的行为与网页端一致，只是把浏览器依赖换成了 Node 实现。字幕 / Markdown / JSON 三类格式都带，还能直接读网页端「导出设置」下载的那个 JSON。完整用法见 [命令行翻译](/guide/translation/cli.md)。

**对外的托管 API 没有**，**可下载的桌面版目前也没有**：网页版打开即用、始终最新，无需安装和更新；字幕内容和 API Key 只存在你自己的浏览器里，不经过任何服务器。

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

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