8.0 KiB
Btranslate
中文|English
Btranslate 是一个 WordPress 插件骨架，使用百度翻译 API 持久化管理多语言内容。
WordPress 后台界面会跟随当前 WordPress 语言：默认显示英文，WordPress 设为 zh_CN 时使用插件内置的简体中文翻译。
要求
- WordPress 6.4 或更高版本。
- PHP 8.1 或更高版本。
- 百度翻译应用 ID 和密钥。
- 已启用 WordPress Cron，或可调用 WordPress Cron 的服务器定时任务。
安装
- 将此目录复制到
wp-content/plugins/btranslate。 - 在 WordPress 后台启用 Btranslate。
- 打开 设置 > Btranslate。
- 填写百度翻译凭据、源语言、目标语言代码和 URL 路由模式。
- 保存文章或页面，为每种已配置的目标语言安排翻译任务。
翻译生命周期
保存文章或页面后，btranslate_process_translation Cron 任务会生成翻译。对于插件启用前已发布的内容，请打开 设置 > Btranslate，使用 翻译现有文章和页面 为全部已发布文章和页面安排任务。翻译具有确定性标识，标识由源内容指纹、源语言、目标语言、字段上下文和提供程序版本构成。插件会先在 {$wpdb->prefix}btranslate_translations 表中查找已完成的结果；只有缓存未命中时才会向百度发起请求。
源文本变更会生成新的指纹，因此会安排新的翻译任务，而不会删除此前有效的翻译。前端渲染不会请求百度 API；它只读取表中已完成的值，若不存在则回退显示源文本。内容入队后必须运行 WordPress Cron；生产环境应配置真实的服务器 Cron，定期调用 WordPress Cron。
支持的内容
- 文章和页面的标题、正文及摘要。
- 附件图片的
alt文本。 - 已分配的分类和标签，包括其描述。
- Yoast SEO 的标题和描述字段。
- Rank Math 的标题和描述字段。
- All in One SEO 与 SEOPress 的标题和描述输出过滤器。
只有列出的 SEO 元字段，以及受支持 SEO 插件生成的标题/描述输出会被发送翻译。通过 WordPress 文档标题 API 生成的浏览器标题会使用已持久化的文章标题翻译。任意元数据、序列化数据、凭据和代码均会被排除。
当文章内容包含 HTML 链接时，插件会保留每个链接的 href 和属性，将可见文本作为独立值翻译，再把翻译后的文本写回原始链接。升级后，请重新翻译包含链接的文章以重新生成内容。
分类和标签名称会在创建、编辑或完整重新翻译时进行翻译。在翻译站点上，用于归档、导航和文章元数据的术语对象会使用已持久化的翻译名称和描述。
路由
子目录 模式会解析配置语言对应的路径，例如 /en/example-post/。子域名 模式通过主机名映射语言：在设置中每行填写一条 domain=language。两种模式可以同时启用，也可以同时关闭。链接会保持当前请求的入口模式：从语言子目录打开的页面继续生成子目录链接，从绑定域名打开的页面继续生成该域名下的链接。关闭子域名模式时，域名绑定字段不会显示。
文章、页面、术语和首页链接会按当前语言生成。例如，主题中使用 home_url() 的“返回首页”链接会解析为已绑定语言的域名或语言子目录。
对于已绑定的子域名，请填写类似 en.example.com=en 的值。服务器和 DNS 必须先将该主机名指向同一 WordPress 安装，WordPress 才能解析该语言。
插件只处理目标语言的 sitemap.xml 请求：子目录模式为 /{语言}/sitemap.xml，域名绑定模式为绑定域名上的 /sitemap.xml。它始终获取源站根路径的 /sitemap.xml，并将 XML 文本节点和属性中指向源站的完整 URL 改写为当前语言 URL；其他 sitemap 文件及外部 URL 不会被改写。源站 sitemap 获取失败时不会造成致命错误，而是交回 WordPress 按普通请求处理。源 sitemap 必须可从 WordPress home 配置的源站访问，且插件不会跟随上游重定向。
路由设置变更后会刷新重写规则。初始实现尚不生成翻译固定链接、规范 URL、hreflang 替代链接或重定向。
安全和数据保留
凭据保存在 WordPress 的 btranslate_settings 选项中，不会在前端输出。插件会存储翻译标识、语言对、字段上下文、源内容指纹、翻译值、状态和时间戳；不会保存完整的百度响应负载。
记录每次百度翻译请求 默认关闭。开启后，每次请求都会触发 btranslate_translation_request_logged 操作，并提供语言对、字段上下文、源文本指纹和长度、结果状态以及适用时的错误码。站点可通过自定义日志集成订阅该操作。操作数据绝不会包含凭据、签名、原文、译文或完整 API 响应。
由于 WordPress 选项由数据库保存，请使用 HTTPS 并适当限制数据库访问权限。生产站点应配置真实的 Cron 执行器，确保翻译任务可靠运行。
卸载
卸载 Btranslate 会永久删除其设置和凭据、重新翻译批处理状态、所有待执行的 Btranslate Cron 事件，以及每个站点的 {$wpdb->prefix}btranslate_translations 表。这会删除所有已持久化的翻译。停用插件不会删除这些记录。
开发
仓库不依赖 Composer 或 PHPUnit。使用系统中可用的 PHP 可执行文件验证 PHP 语法：
find . -path './.git' -prune -o -type f -name '*.php' -print0 | xargs -0 -n1 php -l
投入生产前，应在 WordPress 预发布环境中测试插件，覆盖语言解析、重写行为、持久化复用与失效、百度请求签名和错误处理、内容过滤和回退渲染。任何自动化测试都应模拟 wp_remote_post 响应，避免依赖真实凭据、数据库或外部网络访问。
重新翻译
文章和页面列表会显示每种目标语言的状态列，包括最近成功翻译时间和翻译操作。设置页提供 重新翻译所有内容、翻译所有文章 和 翻译所有分类标签。它们会在为相应内容安排强制刷新前显示确认警告；此操作会绕过已持久化的翻译并消耗百度 API 配额。
第一次保存设置后，需要手动执行 重新翻译所有内容，为已有内容安排翻译。设置页还显示实时进度面板。面板每五秒刷新一次，显示最近一次翻译任务的进度，覆盖全量翻译、文章和页面翻译、分类和标签翻译，以及单篇文章翻译。进度仅统计该任务启动后、且属于其已入队内容和目标语言的完成项目，因此历史翻译不会让新的任务看似已完成。失败的文章、页面、分类或标签会显示在进度条下方，并可逐项重新翻译。强制重翻任务会立即开始，并按两秒间隔排队；单次 WP-Cron 请求最多处理一个内容项，避免一次处理全部内容而超时。进度只读取本地 WordPress 和翻译表数据，不会发送额外请求。
设置页的 清除已翻译的缓存 会删除所有持久化翻译记录、取消待执行的翻译任务并重置进度。清除后前台将显示源文，需使用相应翻译操作重新生成翻译；重新生成会再次消耗百度 API 配额。
已知限制
- 设置界面接受语言代码，但尚未依据维护中的百度语言代码列表进行验证。
- API 调用会翻译原始 WordPress 内容。生产使用前，需要为 HTML、区块、短代码、占位符和 URL 提供受保护令牌处理管线。
- 分类法和 SEO 值会入队，但当前渲染过滤器只覆盖部分 SEO 插件和术语视图。
- 域名绑定假定 WordPress 站点和服务器虚拟主机已为每个绑定域名配置完成。
- 翻译失败会作为失败尝试保存并显示源值；设置页可逐项重新翻译，但尚未实现自动重试和完整的后台任务监控器。
许可证
Btranslate 使用 GNU 通用公共许可证第 3 版授权。