=== LangRouter for TranslatePress（中文说明）===
作者：Likacloud
标签：translatepress，自动翻译，翻译路由，deepl，qwen，hunyuan，火山方舟，openai
最低 WordPress 版本：5.8
测试到：6.8
最低 PHP 版本：7.4
当前稳定版本：0.4.28
许可证：GPLv2 or later
许可证链接：https://www.gnu.org/licenses/gpl-2.0.html
LangRouter for TranslatePress 是 TranslatePress 的路由扩展插件，用于把自动翻译请求按目标语言分发到不同翻译引擎，并支持默认引擎、语言分配、回退规则、日志和语种支持查询。
= 插件定位 =
这个插件不是 TranslatePress 的替代品，而是挂在 TranslatePress 之上的“翻译路由层”。
TranslatePress 负责：
* 多语言站点框架；
* 自动翻译流程入口；
* 语言与字符串存储。
LangRouter 负责：
* 识别目标语言；
* 根据规则决定使用哪个翻译引擎；
* 在主引擎不可用或不支持时，按回退规则切换；
* 为模型维护、日志排查与新人上手说明提供独立后台入口；
* 在保存路由规则前，用查询框辅助确认语种是否被支持。
= 适用场景 =
这个插件适合以下场景：
* 同一站点内接入多个翻译引擎；
* 不同目标语言分配给不同模型；
* 某些语种走 DeepL，某些语种走 Qwen 或 Hunyuan；
* 主引擎失败时自动回退；
* 通过日志观察运行状态；
* 在正式写入规则之前，先查询某个语言是否被支持。
= 当前已接入的引擎 =
当前包内已包含这些路由子引擎：
* DeepL
* 火山方舟（Volcengine Ark）
* Qwen
* Hunyuan
* OpenAI
* 兼容 OpenAI（OpenAI Compatible）
其中，当前“语种支持查询框”只针对以下四类专业翻译模型：
* DeepL
* 火山方舟
* Qwen
* Hunyuan
OpenAI 与兼容 OpenAI 暂不纳入这个查询工具，因为当前查询工具的目标是帮助你确认“专用翻译模型是否支持某语言”，而不是泛化聊天模型能力判断。
= 当前核心能力 =
== 1. 默认引擎 ==
当某个目标语言没有命中显式规则时，LangRouter 会走默认引擎。
== 2. 按语言分配引擎 ==
你可以按目标语言指定引擎。
示例：
`de_DE = deepl`
== 3. 回退规则 ==
当当前目标引擎不可用、未启用、不支持或返回空结果时，可按回退规则尝试其他引擎。
示例：
`de_DE = qwen`
== 4. 独立模型设置页 ==
各引擎的 API Key、Secret、接口地址、模型参数、账号池或密钥池，与路由规则分开维护。
== 5. 文件日志 ==
支持在后台查看日志、刷新日志、删除日志，并尽量按 WordPress 时区写入新日志。
== 6. 语种支持查询框 ==
在“回退规则”下方提供一个小型查询工具，用于确认某语言当前是否被特定翻译模型支持。
= 后台页面分工 =
== TranslatePress → 自动翻译 ==
这里主要负责：
* 选择 LangRouter 作为自动翻译引擎；
* 设置默认引擎；
* 设置语言分配规则；
* 设置回退规则；
* 使用查询框确认语种支持情况。
== 设置 → 模型设置 ==
这里主要负责：
* 各引擎启用 / 关闭；
* API Key / Secret / Endpoint 维护；
* 火山账号池与 DeepL Key 池维护；
* 模型选择；
* 日志查看、刷新、删除。
= 路由规则的关键要求 =
**语言分配和回退规则，必须使用 TranslatePress 真正的语言代码，不能使用后台可编辑 slug / 别名。**
例如：
* `bs_BA`
* `de_DE`
* `fr_FR`
* `zh_CN`
* `ja`
不要把后台显示用的可编辑别名，误当成实际路由键。
= 查询框说明 =
查询框位置：
**TranslatePress → 自动翻译 → 路由设置 → 回退规则下方**
布局：
* 左边：语言输入框；
* 中间：引擎选择；
* 右边：查询按钮；
* 下方：结果摘要与模型表格。
当前支持：
* 输入后自动查询；
* 点击按钮手动查询；
* 在输入框按 Enter 时，优先执行查询，而不是把整个自动翻译页面直接提交保存。
= 查询框支持的输入方式 =
当前查询框支持多种写法，内部会做归一化处理。
例如：
* 中文名称：`英文`、`粤语`、`繁体中文`
* 英文名称：`English`、`Cantonese`、`Traditional Chinese`
* 语言代码：`en`、`yue`、`ja`
* locale 形式：`en_US`、`zh_Hant`、`bs_BA`
= 查询结果怎么理解 =
查询结果会显示：
* 你的原始输入；
* 插件识别后的语言码；
* 当前选择引擎是否支持该语言；
* 当前引擎下哪些模型支持该语言；
* 所有被纳入查询范围的模型里，还有哪些模型支持该语言。
这个工具主要帮助你回答这类问题：
* `bs_BA` 能不能分配给 DeepL？
* `qwen-mt-lite` 支不支持这个语言？
* 当前有哪些翻译模型支持 `yue`？
它只是“决策辅助”，不会自动改写你的语言分配规则。
= 各引擎在查询框中的显示逻辑 =
== DeepL ==
查询表格中显示为：
**TranslatePress 内置 DeepL**
原因是当前插件复用了 TranslatePress 的 DeepL 路径，并在外层加了路由和语种校验能力。
DeepL 查询特点：
* 会触发 API 支持语言探测；
* 成功结果会缓存；
* 查询结果不是简单静态写死，而是带缓存的 API 判断。
== 火山方舟 ==
查询表格中只按“翻译模型”显示，不把账号池条目当作多个模型。
当前显示模型：
`doubao-seed-translation-250915`
需要特别注意：
* 火山账号池里的多条记录，只是运行凭据；
* 它们不应在查询框里被当成多个不同翻译模型。
== Qwen ==
查询框当前会展开这些模型：
* `qwen-mt-plus`
* `qwen-mt-flash`
* `qwen-mt-lite`
这样你在写语言分配前，可以先看目标语种到底是被 `plus/flash/turbo` 支持，还是 `lite` 也支持。
== Hunyuan ==
查询框当前会展开这些模型：
* `hunyuan-translation-lite`
* `hunyuan-translation`
* `hunyuan-mt-7b`
这样可以避免把某个语言误分配给不支持它的混元模型。
= DeepL 查询缓存 =
DeepL 的语种支持查询采用 API + 缓存策略。
当前行为：
* 首次查询时，在需要时触发支持语言拉取；
* 成功结果缓存 3 天；
* 失败或未知结果缓存 10 分钟；
* 缓存有效期内，重复查询会直接复用结果。
这样可以减少不必要的 API 请求，也能让查询框更快响应。
= 日志说明 =
模型设置页内包含独立日志标签页。
当前日志能力包括：
* 开启 / 关闭文件日志；
* 切换日志文件；
* 刷新当前日志；
* 删除当前日志；
* 新日志尽量按 WordPress 站点时区写入时间。
默认日志目录：
`wp-content/uploads/langrouter-for-translatepress/`
= 安装方法 =
1. 安装并启用 TranslatePress。
2. 上传 `langrouter-for-translatepress` 到 `/wp-content/plugins/`，或在后台直接安装 ZIP。
3. 启用 **LangRouter for TranslatePress**。
4. 打开 **设置 → 模型设置**。
5. 配置你要使用的各个引擎。
6. 打开 **TranslatePress → 自动翻译**。
7. 选择 **LangRouter** 作为自动翻译引擎。
8. 设置默认引擎。
9. 按需填写语言分配规则。
10. 按需填写回退规则。
11. 对不确定的语言，先用查询框确认支持情况。
12. 保存设置并开始测试。
= 快速使用示例 =
假设你要这样配置：
* 默认引擎 = Qwen
* `de_DE = deepl`
* `ja = hunyuan`
* `bs_BA = qwen`
* `bs_BA` 的回退 = `deepl`
推荐流程：
1. 先在 **设置 → 模型设置** 中启用并填好各引擎参数；
2. 在查询框里先查 `de_DE`、`ja`、`bs_BA`；
3. 确认支持后再写入规则；
4. 初次测试阶段建议开启日志。
= 实务建议 =
* 查询框显示“未启用”时，说明模型当前不参与正常翻译，但你仍能看到它的支持信息。
* 火山账号池条目只是凭据，不是多个模型。
* DeepL 查询结果受 API 探测与缓存影响。
* 查询框不会自动替你保存路由规则，仍需手动写入并保存。
= 数据与存储说明 =
插件当前可能使用以下存储：
* WordPress options：保存各引擎设置；
* 文本形式账号池 / Key 池：保存火山和 DeepL 等配置；
* 插件目录下的 `logs` 文件夹：保存文件日志；
* WordPress transient：保存如 DeepL 语种支持缓存之类的短期缓存。
= 常见排查 =
== 1. 查询框显示出来了，但按 Enter 还是保存整个页面 ==
当前版本已经对 Enter 做了拦截。如果仍出现这个问题，优先检查是否浏览器缓存了旧 JS，或是否仍在使用旧插件包。
== 2. 查询结果显示“不支持” ==
优先检查：
* 对应引擎是否启用；
* 识别出来的语言码是不是你想查的那个；
* 你写的是不是真正的 TranslatePress 语言代码；
* 当前模型本身是否支持该语言。
== 3. DeepL 查询异常 ==
优先检查：
* DeepL Key 池是否配置正确；
* 当前站点是否能访问 DeepL API；
* 是否正好命中了短期的未知 / 失败缓存；
* 你输入的是基础语言码，还是更具体的 locale 形式。
== 4. 某语言在别的引擎支持，但当前选中的引擎不支持 ==
这是正常情况。查询框的目的就是避免你把一个语言误分配给不支持它的模型。
= 兼容性要求 =
* WordPress 5.8 及以上；
* PHP 7.4 及以上；
* 必须已安装并启用 TranslatePress。
= 当前版本不以这些为重点 =
当前版本重点是：
* 多引擎翻译路由；
* 语种分配；
* 模型维护；
* 回退规则；
* 查询辅助；
* 日志排查。
当前不以这些为主要目标：
* 完整商业化 TMS；
* 租户 / 计费平台；
* 高度可视化工作流编排；
* 完整企业级治理控制台。
= FAQ =
== 1. 这个插件会替代 TranslatePress 吗？ ==
不会。它依赖 TranslatePress，只是在自动翻译层增加路由能力。
== 2. API Key 应该在哪里配置？ ==
在 **设置 → 模型设置**。
== 3. 路由规则应该在哪里配置？ ==
在 **TranslatePress → 自动翻译**。
== 4. 路由规则用 slug 还是语言代码？ ==
必须用 TranslatePress 真正的语言代码，不要用后台可编辑 slug / 别名。
== 5. 为什么查询框里只有 DeepL、火山、Qwen、Hunyuan？ ==
因为当前查询框专门用于“专用翻译模型语种支持确认”，不纳入聊天类或泛化 LLM 提供器。
== 6. 查询框会自动改写我的路由规则吗？ ==
不会。它只显示支持情况，最终规则仍由你手动填写并保存。
== 7. 为什么 DeepL 显示成“TranslatePress 内置 DeepL”？ ==
因为当前插件复用了 TranslatePress 的 DeepL 翻译路径，并在外层做了路由和语种支持判断。
== 8. 为什么火山方舟只显示一个模型？ ==
因为账号池条目只是凭据，不是多个独立翻译模型。查询框按插件实际使用的翻译模型来判断。
== 9. OpenAI 和兼容 OpenAI 可以同时使用吗？ ==
可以，这正是插件支持的典型用法之一。
== 10. 日志默认存在哪里？ ==
默认目录：
`wp-content/uploads/langrouter-for-translatepress/`
= 截图说明 =
1. TranslatePress 自动翻译页中的“路由设置”区块。
2. 模型设置页与各引擎标签页。
3. 回退规则下方的一行式查询框。
4. 查询结果摘要与模型支持表格。
5. 日志标签页中的日志切换、刷新与删除功能。
= 更新日志 =
== 0.4.34 ==
* 移除了开发期无运行价值的打包内容，包括插件包内的 `docs/` 目录。
* 移除了未使用的兼容模板残留，插件包中只保留当前实际参与后台渲染的模板。
* 简化开发期设置加载逻辑：LangRouter 现在只读取当前 `tpre_router_settings` 结构，不再从更早的预发布测试结构自动回填。
* 保持日志目录兜底继续统一到 WordPress uploads 风格路径。
* 同步更新中英文 readme，把这次清理边界直接写进插件包。
== 0.4.28 ==
* 在“模型设置”页的“日志”旁边新增“帮助”标签页。
* 新增左侧帮助目录与右侧内容区，第一版包含快速开始、基本概念、引擎配置、路由设置、日志与排错、常见问题。
* 本步以后台指引增强为主，不改变现有路由与保存逻辑。
== 0.4.31 ==
* 各引擎设置页右下角新增“本页帮助”直达入口，可直接跳到帮助页对应引擎说明。
* 帮助 → 引擎配置 页面增加各引擎锚点，便于从当前引擎页一键直达对应说明。
== 0.4.30 ==
* 在保存 DeepL 账号池后，同步清理运行状态中的历史条目；已删除的 key 不再继续显示在后台“运行状态”表格中。
* 本步仅处理 DeepL 运行状态清理，不改变路由行为。
== 0.4.29 ==
* 扩展“帮助”标签页内容，补充更完整的新手说明，覆盖快速开始、基本概念、引擎配置、路由设置、日志排错与常见问题。
* 在帮助内容中增加更多直达入口，便于从说明直接跳转到模型设置、路由设置和日志页面。
== 0.4.27 ==
* 修复后台日志动作在普通打开设置页时，未先判断 `tpre_action` 参数导致的 PHP 8 `Undefined array key` 警告。
== 0.4.26 ==
* 新增 `docs/current-structure.md`，用于说明当前分步重构后的结构边界与维护重点。
* 新增 `docs/engine-integration.md`，用于约束后续继续添加新引擎时的接入方式。
* 本步以文档补齐为主，不以改变插件行为为目标。
== 0.4.25 ==
* 将后台页面渲染与日志文件操作拆到 `includes/admin/` 下的独立类中。
* 保持现有 option 结构、保存流程、路由行为与引擎执行逻辑不变。
* 进一步缩小 `TPRE_Admin_Settings` 的职责，方便后续继续按小步方式维护与重构。
== 0.4.24 ==
* 将各引擎的后台默认值与 sanitize 规则拆到 `includes/admin/engines/` 下的独立配置类中。
* 保持现有 option 结构与路由执行链不变，但后续扩展引擎字段会更集中、更容易维护。
* 同步把文档中的默认日志目录更新为 `wp-content/uploads/langrouter-for-translatepress/`。
== 0.4.22 ==
* 新增中心化的引擎注册表，用于统一维护模型设置页的 tabs、引擎选择列表和 section 模板映射。
* 本步不改设置存储、不改 sanitize 流程，也不改变现有路由行为。
* 同步补充开发阶段说明与版本更新记录，后续每次小版本维护都与 readme 一起更新。
== 0.4.21 ==
* 新增并稳定化“语种支持查询框”。
* 将查询框固定到“回退规则”下方。
* 支持输入后自动查询、按钮手动查询与 Enter 拦截。
* 扩展 Qwen 与 Hunyuan 的模型级查询显示。
* 修正火山方舟查询显示，不再把账号池条目误当成模型。
* 修正 DeepL 查询逻辑，使其能正确读取配置 Key 池并走 API + 缓存判断。
* 查询表格中将 DeepL 显示为 **TranslatePress 内置 DeepL**。
== 0.4.16 ==
* 收紧 OpenAI 与兼容 OpenAI 公共客户端的文本预过滤规则，在请求发出前直接跳过明显的代码碎片、oEmbed 标识、配置键名和技术标识。
* 降低兼容 OpenAI 提供器误翻 PHP / JSON / WordPress 技术字符串的概率。
* 版本号更新为 0.4.16。
== 0.4.14 ==
* 优化默认引擎兜底日志，更容易区分默认引擎执行与普通子引擎执行。
== 0.4.13 ==
* 修复回退链：当语言专属回退引擎不支持或返回空结果时，继续尝试默认引擎。
* 优化回退决策日志。
== 0.4.12 ==
* 优化“不支持语言”日志文案。
* 在路由完成日志中加入更清晰的失败类型字段。
image.png (207.1 KB, 下载次数: 0)
下载附件
保存到相册
1小时前 上传
image.png (199.34 KB, 下载次数: 0)
下载附件
保存到相册
1小时前 上传
image.png (236.95 KB, 下载次数: 0)
下载附件
保存到相册
半小时前 上传
image.png (143.26 KB, 下载次数: 0)
下载附件
保存到相册
半小时前 上传
image.png (170.74 KB, 下载次数: 0)
下载附件
保存到相册
半小时前 上传
image.png (358.86 KB, 下载次数: 0)
下载附件
保存到相册
半小时前 上传
