LLM-Subtrans

LLM-Subtrans 是一款开源字幕翻译工具，它利用大语言模型（LLM）作为翻译服务。该工具支持在语言模型所支持的任意语种对之间进行字幕翻译。

应用程序通过插件式架构支持多种字幕格式。目前支持 .srt、.ssa/.ass 和 .vtt 文件。

注意：LLM-Subtrans 需要有效的互联网连接。字幕会被发送到提供商的服务器进行翻译，因此适用其隐私政策。

安装

对于大多数用户来说，使用打包发布的版本是最简单的方式。请从 发布页面 下载一个压缩包，解压到任意文件夹并运行 gui-subtrans。首次运行时，程序会提示您进行一些基本设置。

如果您希望使用命令行工具、修改源代码，或者更倾向于对安装过程有更多控制权，则需要 从源码安装。

Windows

每个发布版本都为 Windows 打包成 (gui-subtrans-x.x.x.zip)。

MacOS

通常会为搭载 Apple Silicon 芯片的 Mac 提供打包好的构建版本 (gui-subtrans-x.x.x.macos-arm64.zip)。如果您使用的是 Intel 芯片的 Mac，则需要 从源码安装。

Linux

不提供预编译的 Linux 包，因此您需要 从源码安装。

LLM-Subtrans Web

基于 Gemini 的 LLM-Subtrans Web 可免费使用，但由于这对我个人而言会产生费用，现在需要注册邮箱地址，并且每位用户每天仅限 2 次翻译。

翻译提供商

OpenRouter

https://openrouter.ai/privacy

OpenRouter 是一项聚合了来自众多提供商的 模型 的服务。您需要一个 OpenRouter API 密钥 才能使用该服务，并且账户需有一定余额（尽管也有一些功能相当强大的模型是免费提供的）。

您可以选择让 OpenRouter 自动选择模型（GUI 中的“使用默认模型”选项或命令行中的 --auto 参数），也可以指定特定的模型。模型偏好还可以在 OpenRouter 控制面板中进行设置。

由于可用的模型多达数百种，它们被按模型家族分组。默认情况下，可用模型列表是从“Translation”类别中提取的，但这排除了许多完全具备翻译能力的模型（包括大多数免费选项）。

Google Gemini

https://ai.google.dev/terms

请注意，可能存在地区限制：https://ai.google.dev/available_regions

截至撰写本文时，Gemini 2.5 Flash 或许是翻译速度和流畅性方面的领先模型，尽管存在一定的内容审查；而 Preview 版本通常可以免费使用。

您需要从 https://ai.google.dev/ 或者在 https://console.cloud.google.com/ 上创建的项目中获取 Google Gemini API 密钥。务必确保为该 API 密钥和项目启用生成式 AI 功能。

遗憾的是，Gemini 有时会拒绝翻译包含某些特定词汇或短语的内容，即使安全设置已调至最低。如果遇到这种情况，您需要改用其他提供商，或者将字幕分批处理，手动翻译那些含有违禁内容的行。

OpenAI

https://openai.com/policies/privacy-policy

您需要从 https://platform.openai.com/account/api-keys 获取 OpenAI API 密钥，才能使用 OpenAI 的 GPT 模型。如果该 API 密钥关联的是免费试用账户，翻译速度将会 严重 受限。

您可以使用自定义的 api_base 参数来接入自定义的 OpenAI 实例（或任何其他兼容 OpenAI 协议的端点），不过使用“自定义服务器”选项能提供更多的控制。

您也可以将 OpenAI Azure 部署作为翻译提供商，但只有在您非常熟悉相关配置的情况下才建议这样做——在这种情况下，相信您已经清楚如何设置 Azure 提供商的相关参数。

DeepSeek

https://platform.deepseek.com/downloads/DeepSeek%20Open%20Platform%20Terms%20of%20Service.html

您需要从 https://platform.deepseek.com/api_keys 获取 DeepSeek API 密钥才能使用该提供商。

• API 基础 URL：您可以选择指定自定义的 URL，例如当您自行托管 DeepSeek 实例时。若未设置，则将使用官方的 DeepSeek API 端点。

• 模型：默认模型为 deepseek-chat，推荐用于翻译任务。对于存在 OCR 或转录错误的源字幕，deepseek-reasoner 可能会给出更好的结果，因为它会花更多时间尝试推断错误所在。

DeepSeek 的配置相对简单，性能尚可且价格低廉，不过翻译并非其强项。

Anthropic

https://support.anthropic.com/en/collections/4078534-privacy-legal

您需要从 https://console.anthropic.com/settings/keys 获取 Anthropic API 密钥，才能使用 Claude 作为翻译提供商。翻译并不是 Claude 的强项，而且与其他提供商相比，它的 API 费用较高。

该 API 根据您的信用等级设定了严格的 速率限制，分别针对每分钟请求数和每日令牌数。

Mistral

https://mistral.ai/terms/

您需要从 https://console.mistral.ai/api-keys/ 获取 Mistral API 密钥才能使用该提供商。

• 服务器 URL：如果您使用的是自定义部署的 Mistral API，可以通过 --server_url 参数指定服务器 URL。

• 模型：推荐使用 mistral-large-latest 进行翻译。较小的模型表现通常较差，可能无法很好地遵循系统指令。

Mistral AI 的设置较为简单，但其作为翻译工具的表现并不算出色。

自定义服务器

LLM-Subtrans 可以直接与任何支持 OpenAI 兼容 API 的服务器对接，包括本地托管的模型，例如 LM Studio。

这主要用于研究目的，不应期望本地模型能带来特别好的翻译效果。大语言模型的强大能力很大程度上源于其规模，因此您在消费级 GPU 上运行的小型量化模型，很可能会产生质量不佳的翻译、无法生成有效响应，甚至陷入无限循环。如果您发现某个模型能够稳定地生成高质量翻译，请在讨论区分享相关信息！聊天和完成端点均受支持——请根据服务器上运行的模型类型来配置设置和端点（例如，经过指令微调的模型可能更适合使用完成端点而非聊天端点）。如果使用的模型需要特定的格式，可以在 GUI 中编辑提示模板；务必在模板中至少包含 {prompt} 标记，因为每一批次待翻译的字幕都会被填充到此处！

Amazon Bedrock

https://aws.amazon.com/service-terms/

不建议大多数用户使用 Bedrock：其设置过程较为复杂，需要 AWS 凭证、正确的 IAM 权限以及区域配置。此外，并非 Bedrock 上的所有模型都支持翻译任务或能提供可靠的结果。预打包版本将不会包含 Bedrock 支持——如果您能够自行配置 AWS，那么您也可以从源代码安装 llm-subtrans。

要使用 Bedrock，您必须：

1. 创建一个具有适当权限的 IAM 用户 或 角色（例如 bedrock:InvokeModel、bedrock:ListFoundationModels）。
2. 确保您希望使用的模型在所选的 AWS 区域中可用，并且已为该 IAM 用户启用访问权限（参阅 AWS 官方文档）。

从源代码安装

如果您希望使用命令行工具或对程序进行修改，您需要在系统上安装 Python 3.10 及以上版本和 pip，然后按照以下步骤操作。

使用以下命令或您偏好的工具将 LLM-Subtrans 仓库克隆到本地：

```sh
git clone https://github.com/machinewrapped/llm-subtrans.git
```

设置脚本

最简单的设置方法是运行统一的安装脚本：

• Windows：运行 install.bat
• macOS/Linux：运行 install.sh

这些脚本会创建一个虚拟环境，并提供“带 GUI 的安装”或“仅命令行安装”选项，同时还可选择添加对特定提供商的支持。脚本会引导您完成设置，并生成用于启动应用程序的命令脚本。

在安装过程中，您可以根据提示为每个选定的提供商输入 API 密钥，这些密钥将保存在 .env 文件中，这样您每次运行程序时就不必重复输入。不过，如果您只打算使用 GUI，这一步就显得有些多余，因为密钥可以直接保存在应用设置中。

手动配置

如果您已经运行了安装脚本，则可以跳过剩余步骤。仅当您希望手动配置环境时，才继续阅读以下内容。

1. 在项目的根目录下创建一个名为 .env 的文件。将您选择的提供商所需的所有设置添加到 .env 文件中，格式如下：

   OPENROUTER_API_KEY=<您的 OpenRouter API 密钥>
   OPENAI_API_KEY=<您的 OpenAI API 密钥>
   GEMINI_API_KEY=<您的 Gemini API 密钥>
   AZURE_API_KEY=<您的 Azure API 密钥>
   CLAUDE_API_KEY=<您的 Claude API 密钥>
   

   如果您使用的是 Azure：

   AZURE_API_BASE=<您的 API 基础地址，例如 https://something.openai.azure.com>
   AZURE_DEPLOYMENT_NAME=<部署名称>
   

   如果您使用的是 Bedrock：

   AWS_ACCESS_KEY_ID=您的访问密钥 ID
   AWS_SECRET_ACCESS_KEY=您的秘密访问密钥
   AWS_REGION=您的区域
   

   对于 OpenAI 的推理模型，您可以设置推理力度（默认为低）：

   OPENAI_REASONING_EFFORT=low/medium/high
   

2. 在项目根目录下运行以下命令创建一个虚拟环境，为 Python 解释器提供一个本地环境（可选，但强烈建议这样做以避免与其他 Python 应用程序发生依赖冲突）：

   python -m venv envsubtrans
   

3. 根据您的操作系统运行相应的命令激活虚拟环境。每次运行应用程序前都需要执行此操作。

   .\envsubtrans\Scripts\activate      # Windows
   source ./envsubtrans/bin/activate   # Mac/Linux
   

4. 安装项目（如果您想修改代码，可以添加 -e 参数以进行可编辑安装）：

   pip install -e .                   # 仅安装命令行工具，支持 OpenRouter 或自定义服务器
   pip install -e ".[gui]"            # 核心模块及默认提供商，附带 GUI 模块
   pip install -e ".[gui,openai,gemini,claude,mistral,bedrock]"   # 完整安装，包含可选提供商（可根据需求删减）
   

使用方法

该程序的工作原理是将字幕分成若干批次，依次发送至翻译服务。

根据批次大小的不同，它可能会为每个字幕文件发起多次 API 调用。速度主要取决于所选的模型。

默认情况下，翻译后的字幕会写入同一目录下的新文件，文件名会在原文件名后附加目标语言标识。

GUI

Subtrans GUI 是使用该程序的最佳且最简单的方式。

安装完成后，通过 gui-subtrans 命令或 shell 脚本启动 GUI，其余操作应该都非常直观易懂。

有关如何使用该程序的更多详细信息，请参阅项目 Wiki。

命令行

LLM-Subtrans 可以作为控制台命令或 shell 脚本使用。安装脚本会在项目根目录下为每个提供商创建一个 cmd 或 sh 文件，这些文件会负责激活虚拟环境并调用相应的翻译脚本。

最基本的用法如下：

# 使用 OpenRouter 并自动选择模型
llm-subtrans --auto -l <语言> <字幕文件路径>

# 使用 OpenRouter 并指定模型
llm-subtrans --model google/gemini-2.5-flash -l <语言> <字幕文件路径>

# 在翻译的同时转换格式（本例中将 ASS 转换为 SRT）
llm-subtrans -l <语言> -o output.srt input.ass

# 使用任何兼容 OpenAI API 的服务器
llm-subtrans -s <服务器地址> -e <端点> -k <API 密钥> -l <语言> <字幕文件路径>

# 使用特定提供商
gpt-subtrans --model gpt-5-mini --target_language <目标语言> <字幕文件路径>
gemini-subtrans --model gemini-2.5-flash-latest --target_language <目标语言> <字幕文件路径>
claude-subtrans --model claude-3-5-haiku-latest --target_language <目标语言> <字幕文件路径>

# 列出支持的字幕格式
llm-subtrans --list-formats

# 批量处理文件夹中的文件（请先激活虚拟环境）
python scripts/batch_translate.py ./subtitles ./translated --provider openai --model gpt-5-mini --apikey sk-... --language Spanish

输出文件的格式由文件扩展名推断得出。如需在不同格式之间转换，请提供带有目标扩展名的输出路径。

如果未指定目标语言，默认为英语。

其他可在命令行中指定的选项详见下文。

项目文件

注意：GUI 中默认已启用项目文件。

--project 参数或 .env 文件中的 PROJECT_FILE 设置控制是否为命令行创建项目文件并保存到磁盘。

如果启用，当加载字幕文件时，将创建一个扩展名为 .subtrans 的文件，其中包含项目的详细信息。随着翻译的进行，该文件会不断更新。编写项目文件的好处之一是允许恢复中断的翻译任务。强烈建议使用此功能。

# 使用 OpenRouter 并创建持久化项目
llm-subtrans --project --auto -l <语言> <字幕文件路径>

# 使用 OpenRouter 并恢复持久化项目
llm-subtrans --project --auto -l <语言> <subtrans 项目文件路径>
llm-subtrans --project --auto -l <语言> <字幕文件路径>  # 如果项目文件在同一目录下，将自动检测到

格式转换

LLM-Subtrans 主要是一个翻译应用程序，格式转换最好由专门的工具来处理。不过，该工具也支持读取一种格式并输出另一种格式。

# 使用 OpenRouter 将 .ass 转换为 .srt
llm-subtrans --project --auto -l <语言> -o <输出文件.srt路径> <输入字幕文件.ass路径>

高级用法

命令行提供了一些参数，可以更精细地控制翻译过程。

要使用这些参数，只需在源文件路径之后添加即可。例如：

llm-subtrans path/to/my/subtitles.srt --moviename "我的精彩电影" --ratelimit 10 --substitution cat::dog

许多设置的默认值可以在 .env 文件中以大写形式（NAME_IN_CAPS）进行配置。完整的参数列表请参阅 Options.py 和各个 Provider_XXX 文件。

• -l, --target_language: 指定要翻译成的目标语言。

• -o, --output: 指定翻译后字幕的输出文件名。

• --project: 读取或写入当前翻译字幕的项目文件（详情见上文）。

• --ratelimit: 每分钟向翻译服务发送的最大请求数（主要适用于使用 OpenAI 免费试用账户的情况）。

• --moviename: 可选地指定源素材名称，为翻译者提供上下文信息。

• --description: 对源素材的简要描述，提供更多背景信息。通常内容越简洁越好，否则 AI 可能会开始自行发挥。

• --name, --names: 可选地提供用于翻译的人名列表（更强大的 AI 模型更有可能实际使用这些名字）。

• --substitution: 由 :: 分隔的字符串对，用于在原文或译文中进行替换；也可以指定包含此类替换对的文件。

• --scenethreshold: 认为属于新场景的两行字幕之间的时间间隔（秒数）。

• --minbatchsize: 开始向翻译器发送新批次所需的最小字幕行数。较高的值通常会使翻译更快且成本更低，但也会增加不同步的风险。

• --maxbatchsize: 强制开始新批次之前的最大字幕行数。此值需要考虑所用模型的令牌限制，但“最佳”值取决于多种因素，因此建议多做实验。较大的批次更具成本效益，但也增加了 AI 出现不同步、导致昂贵重试的风险。

• --preprocess: 在分批之前对字幕进行预处理。此操作会执行多种步骤，以使字幕更适合高效翻译，例如将过长的字幕行拆分为多行。主要用于通过 Whisper 等工具自动生成的字幕。

• --postprocess: 对翻译后的字幕进行后处理。例如，在过长的字幕行中添加换行符，并在翻译请求完成后规范化对话标签。

• --instruction: 向 AI 提供的额外指令，指示其如何进行翻译。

• --instructionfile: 从指定文件加载 AI 系统指令（若未指定，则使用默认的 instructions.txt）。

• --maxlines: 最多处理的批次数量。可用于在达到一定行数后结束翻译，例如检查结果。

• --temperature: 较高的温度会增加翻译结果的随机性。默认值为 0。

• --reload: 将从源文件重新加载字幕，而不是使用项目文件中保存的字幕（注意：此选项要求同时启用 --project）。

• --retranslate: 忽略现有翻译，重新翻译所有字幕（注意：此选项要求同时启用 --project）。

• --reparse: 不会再次将现有翻译发送给翻译器，而是重新处理翻译器的响应以提取翻译结果。这在修复错误版本后非常有用，也可用于重置已被手动编辑过的翻译（注意：此选项要求同时启用 --project）。

• --preview: 字幕将被加载并分批，翻译流程也会运行，但不会向翻译器发起任何调用。仅适用于调试目的。

供应商特定参数

某些特定供应商还提供额外的参数。

OpenRouter

• -k, --apikey: 您的 OpenRouter API 密钥（如果未提供此参数，程序将从环境变量中查找 OPENROUTER_API_KEY）

• --auto 自动选择要使用的模型（选择标准可在 OpenRouter 控制面板 中配置）

OpenAI

• -k, --apikey: 您的 OpenAI API 密钥（如果未提供此参数，程序将从环境变量中查找 OPENAI_API_KEY）

• -b, --apibase: 如果您使用的是自定义实例，则指定 API 基础 URL。若未设置，则使用默认 URL。

• -httpx: 使用 HTTPX 库 发起请求（仅在指定了 apibase 时支持）

• -m, --model: 指定用于翻译的 AI 模型

Gemini

• -k, --apikey: 您的 Google Gemini API 密钥（如果未提供此参数，程序将从环境变量中查找 GEMINI_API_KEY）

• -m, --model: 指定用于翻译的 AI 模型

Claude

• -k, --apikey: 您的 Anthropic API 密钥（如果未提供此参数，程序将从环境变量中查找 ANTHROPIC_API_KEY）

• -m, --model: 指定用于翻译的 AI 模型。应使用完整的模型名称，例如 claude-3-haiku-20240307

DeepSeek

• -k, --apikey: 您的 DeepSeek API 密钥（如果未提供此参数，程序将从环境变量中查找 DEEPSEEK_API_KEY）

• -b, --apibase: 如果您使用的是 DeepSeek 的自定义部署，则指定基础 URL。若未设置，则使用官方 URL。

• -m, --model: 指定用于翻译的 模型。通常情况下，deepseek-chat 是唯一合理的选择（也是默认值）。

Mistral AI

• -k, --apikey: 您的 Mistral API 密钥（如果未提供此参数，程序将从环境变量中查找 MISTRAL_API_KEY）

• --server_url: 如果您使用的是 Mistral 的自定义部署，则指定 URL。若未设置，则使用官方 URL。

• -m, --model: 指定用于翻译的 模型。推荐使用 mistral-large-latest，小型模型的可靠性较低。

OpenAI Azure

• --deploymentname: Azure 部署名称

• -k, --apikey: 您的 Azure 部署 API 密钥。

• -b, --apibase: API 后端基础地址。

• -a, --apiversion: Azure API 版本。

Amazon Bedrock

• -k, --accesskey: 您的 AWS 访问密钥 ID。如果已在 .env 文件中设置，则无需提供。

• -s, --secretkey: 您的 AWS 秘密访问密钥。如果已在 .env 文件中设置，则无需提供。

• -r, --region: Bedrock 可用的 AWS 区域。您可以在此处查看区域列表：AWS 全球基础设施区域和可用区。例如：us-east-1 或 eu-west-1。

• -m, --model: 指定用于翻译的 Bedrock 模型 ID。示例包括 amazon.titan-text-lite-v1 或 amazon.titan-text-express-v1。

自定义服务器特定参数

• -s, --server: 服务器运行的地址，包含端口（例如：http://localhost:1234）。应由服务器提供。

• -e, --endpoint: 要在服务器上调用的 API 函数，例如 /v1/completions。请根据服务器上运行的模型选择合适的端点。

• -k, --apikey: 如果需要 API 密钥，则提供。本地服务器通常不需要 API 密钥。

• -m, --model: 如果需要，指定用于翻译的模型（对于本地服务器，这通常由服务器决定）。

• --chat: 如果端点期望以对话格式接收请求，则指定此参数；否则，默认为完成端点。

• --systemmessages: 如果使用对话端点，且指定了此标志，则会将翻译指令作为“系统”用户发送。

代理支持

LLM-Subtrans 支持大多数供应商的代理功能。

配置

您可以通过以下参数配置代理：

• --proxy <URL>: 指定代理 URL。支持 HTTP 和 SOCKS 代理。 示例：--proxy http://127.0.0.1:8888 或 --proxy socks5://127.0.0.1:1080

• --proxycert <PATH>: 自定义 CA 证书包的路径（PEM 格式）。当使用拦截式代理（如 mitmproxy 或 Fiddler）且该代理使用自签名证书时，需要此参数。 示例：--proxycert C:\Users\name\.mitmproxy\mitmproxy-ca-cert.pem

使用示例

# 对 OpenRouter 使用 SOCKS 代理
llm-subtrans --auto -l Spanish input.srt --proxy socks5://127.0.0.1:1080

# 使用 mitmdump 并指定自定义证书
llm-subtrans --auto -l French input.srt --proxy http://127.0.0.1:8080 --proxycert ./mitmproxy-ca-cert.pem

批量处理

您可以按照以下目录结构处理文件：

  #   -SRT
  #   --fold1
  #   ---1.srt
  #   ---2.srt
  #   ...
  #   --fold2
  #   ---1.srt
  #   ---2.srt
  #   ...

使用 batch_translate.py 脚本来处理多个字幕文件：

您可以在脚本文件中直接修改 DEFAULT_OPTIONS 的值，也可以结合脚本默认值与命令行覆盖来使用。

# 预览模式，测试设置而不进行 API 调用
python scripts/batch_translate.py --preview

# 基本用法，通过命令行参数指定
python scripts/batch_translate.py ./subtitles ./translated --provider openai --model gpt-5-mini --apikey sk-... --language Spanish

# 覆盖输出格式
python scripts/batch_translate.py ./subtitles ./translated --provider openai --output-format srt

# 使用附加选项
python scripts/batch_translate.py ./subtitles ./translated --provider openai --option max_batch_size=40 --option preprocess_subtitles=false

开发者

建议从源代码安装后，使用 Visual Studio Code 等 IDE 运行程序，并设置 launch.json 文件以指定参数。 注意：每次处理项目时，请务必激活虚拟环境。

贡献

我们欢迎社区的贡献！要参与贡献，请按照以下步骤操作：

1. 将仓库 Fork 到您自己的 GitHub 账户。
2. 使用以下命令将仓库克隆到您的本地机器：

   git clone https://github.com/your_username/llm-subtrans.git
   

3. 使用以下命令为您的更改创建一个新分支：

   git checkout -b feature/your-new-feature
   

4. 安装 pyright 作为 pre-commit 钩子（可选但推荐）：

   # 安装 pyright 进行类型检查
   pip install pyright
   
   # 安装 Git 钩子（在提交前运行类型检查）
   # Windows:
   hooks\install.bat
   
   # Linux/Mac:
   ./hooks/install.sh
   

5. 对代码进行修改，并使用描述性的提交信息提交更改。
6. 将您的更改推送到您 Fork 的仓库。
7. 向 LLM-Subtrans 主仓库提交 Pull Request。

本地化

LLM-Subtrans 使用 GNU gettext 进行 UI 本地化。

• 模板文件 (POT)：locales/gui-subtrans.pot
• 各语言目录：locales/<lang>/LC_MESSAGES/gui-subtrans.po
• 编译后的目录：locales/<lang>/LC_MESSAGES/gui-subtrans.mo

代码中的字符串使用辅助函数标记：

• _("text") 用于简单字符串
• tr("context", "text") 用于上下文相关的字符串

非常欢迎本地化贡献——您可以在几分钟内添加一种新的本地化语言！详细说明（工具、工作流程等）请参阅 docs/localization_contributing.md。

致谢

本项目使用了多个有用的库：

• srt (https://github.com/cdown/srt)
• pysubs2 (https://github.com/tkarabela/pysubs2)
• requests (https://github.com/psf/requests)
• regex (https://github.com/mrabarnett/mrab-regex)
• httpx (https://github.com/projectdiscovery/httpx)
• babel (https://github.com/python-babel/)

翻译服务提供商：

• openai (https://platform.openai.com/docs/libraries/python-bindings)
• google-genai (https://github.com/googleapis/python-genai)
• anthropic (https://github.com/anthropics/anthropic-sdk-python)
• mistralai (https://github.com/mistralai/client-python)
• boto3 (Amazon Bedrock) (https://github.com/boto/boto3)

GUI 相关：

• pyside6 (https://wiki.qt.io/Qt_for_Python)
• blinker (https://pythonhosted.org/blinker/)
• darkdetect (https://github.com/albertosottile/darkdetect)
• appdirs (https://github.com/ActiveState/appdirs)

打包版本相关：

• python (https://www.python.org/)
• pyinstaller (https://pyinstaller.org/)

版本历史

• 1.3 版 添加了 OpenRouter 作为默认的翻译服务，从而开放了更多选择。
• 1.2 版 增加了 GUI 的本地化支持，并引入了对 GPT-5 系列模型的支持。
• 1.1 版 支持更灵活的翻译格式，方便用户使用自定义指令。
• 1.0 版 是一次小更新，但由于项目已稳定运行了一段时间，因此将主版本号提升至 1.0。
• 0.7 版 引入了可选的翻译字幕后处理功能，以尝试修复 LLM 翻译字幕中常见的问题（如添加换行符），并提供了新的默认指令，以减少错误率。
• 0.6 版 将架构改为基于服务提供商的系统，允许使用多种 AI 服务作为翻译工具。每个服务提供商的设置被独立管理。首次发布时，仅支持 OpenAI。
• 0.5 版 增加了对 gpt-instruct 模型的支持，并重构了代码库以适应不同的翻译引擎。对于大多数用户来说，仍然建议使用 gpt-3.5-turbo-16k 模型，批量大小控制在 10 到 100 行之间，以获得最佳的性能、成本和翻译质量。
• 0.4 版 对 GUI 进行了显著优化，使其响应更快、更易用，并修复了许多 bug。
• 0.3 版 大力提升了 GUI 的功能性和可用性，增加了选项对话框等功能，并修复了大量 bug。
• 0.2 版 采用了一种新的提示方法，大大减少了由于 GPT 在翻译过程中合并源文本行而导致的字幕不同步问题。虽然这种方法可能会降低源语言与目标语言语法差异较大时的自然度，但它为人工润色输出提供了更好的基础。 此外，指令变得更加详细，提供了多个正确输出示例供 GPT 参考，并改进了摘要生成机制，使 GPT 更好地理解当前批次的上下文。现在，双击场景或批次即可手动编辑摘要，这可以显著提高重新翻译以及后续批次或场景的效果。单个字幕行也可以通过双击进行编辑。

许可证

LLM-Subtrans 采用 MIT 许可证授权。第三方库的许可证信息请参阅 LICENSE 文件。

LLM-Subtrans 快速上手指南

LLM-Subtrans 是一款开源字幕翻译工具，利用大语言模型（LLM）将字幕文件在任意支持的语言对之间进行翻译。支持 .srt、.ssa/.ass 和 .vtt 格式。

环境准备

系统要求

• 操作系统：Windows、macOS (Apple Silicon) 或 Linux。
  • 注意：Intel Mac 和 Linux 用户需从源码安装。
• 网络：需要稳定的互联网连接（字幕将发送至服务商服务器）。
• 运行环境（源码安装必需）：
  • Python 3.10+
  • pip

前置依赖

• API 密钥：需准备至少一个 LLM 服务商的 API Key（如 OpenRouter, Google Gemini, DeepSeek, OpenAI 等）。
  • 推荐：对于国内开发者，DeepSeek 或 OpenRouter（可聚合多种模型）通常具有更好的访问稳定性和性价比。
  • 注意：Google Gemini 和 OpenAI 免费版可能存在区域限制或速度限制。

安装步骤

方式一：使用预编译包（推荐 Windows / Apple Silicon Mac 用户）

1. 访问 Releases 页面 下载对应系统的压缩包。
   • Windows: gui-subtrans-x.x.x.zip
   • macOS (ARM): gui-subtrans-x.x.x.macos-arm64.zip
2. 解压到任意文件夹。
3. 运行 gui-subtrans 启动图形界面，首次运行会引导配置基本设置。

方式二：从源码安装（Linux / Intel Mac / 高级用户）

1. 克隆仓库

   git clone https://github.com/machinewrapped/llm-subtrans.git
   cd llm-subtrans
   

2. 运行自动安装脚本（最简单的方式）

   • Windows:

     install.bat
     

   • macOS / Linux:

     ./install.sh
     

   脚本将自动创建虚拟环境，并引导选择安装 GUI 版本或仅命令行版本，同时支持配置特定服务商。

3. 手动配置（可选） 若未使用脚本，需手动创建 .env 文件配置 API Key：

   # 在项目根目录创建 .env 文件
   OPENROUTER_API_KEY=<your_openrouter_api_key>
   DEEPSEEK_API_KEY=<your_deepseek_api_key>
   # 其他服务商配置参考 README
   

   创建并激活虚拟环境：

   python -m venv envsubtrans
   # Windows
   .\envsubtrans\Scripts\activate
   # Mac/Linux
   source ./envsubtrans/bin/activate
   

   安装依赖（按需选择）：

   # 最小化安装（仅命令行 + OpenRouter/自定义服务）
   pip install -e .
   
   # 完整安装（含 GUI 及主流服务商支持）
   pip install -e ".[gui,openai,gemini,claude,mistral,bedrock]"
   

基本使用

图形界面 (GUI) - 推荐新手

启动程序后，界面操作直观：

gui-subtrans

1. 加载字幕文件。
2. 选择源语言和目标语言。
3. 选择翻译服务商（Provider）及模型。
4. 点击开始翻译，结果将保存为同名文件（附带目标语言后缀）。

命令行 (CLI)

适用于批量处理或自动化脚本。安装脚本会在根目录生成便捷的启动脚本，或直接使用以下命令：

基础示例（使用 OpenRouter 自动选择模型）：

subtrans-openrouter --auto input.srt --target-lang zh

指定 DeepSeek 模型翻译：

subtrans-deepseek --model deepseek-chat input.srt --target-lang en

参数说明：

• input.srt: 输入字幕文件路径。
• --target-lang: 目标语言代码（如 zh, en, ja）。
• --model: 指定具体模型名称（若不指定则使用默认值）。
• 输出文件默认保存在原目录下，文件名格式为 input_target_lang.srt。

提示：翻译速度取决于所选模型的响应速度及批次大小设置。