Btranslate

中文|English

Btranslate 是一个 WordPress 插件骨架，使用百度翻译 API 持久化管理多语言内容。

要求

WordPress 6.4 或更高版本。
PHP 8.1 或更高版本。
百度翻译应用 ID 和密钥。
已启用 WordPress Cron，或可调用 WordPress Cron 的服务器定时任务。

安装

将此目录复制到 wp-content/plugins/wp-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。每种语言应只使用一种规范 URL 策略，以避免重复内容。在域名模式下，插件不会注册前端重写规则，因此不会影响主站 URL。

文章、页面、术语和首页链接会按当前语言生成。例如，主题中使用 home_url() 的“返回首页”链接会解析为已绑定语言的域名或语言子目录。

对于已绑定的子域名，请填写类似 en.example.com=en 的值。服务器和 DNS 必须先将该主机名指向同一 WordPress 安装，WordPress 才能解析该语言。

通过已配置目标语言子目录或绑定域名发起的 sitemap 请求，会代理到源站相同路径的 sitemap。插件会改写 sitemap 索引和 URL 集中的标准 <loc> 条目，使索引内的子 sitemap 链接继续使用同一语言路由。源站 sitemap 获取失败时不会造成致命错误，而是交回 WordPress 按普通请求处理。源 sitemap 必须可从 WordPress home 配置的源站访问，且插件不会跟随上游重定向。

路由设置变更后会刷新重写规则。初始实现尚不生成翻译固定链接、规范 URL、hreflang 替代链接或重定向。

安全和数据保留

凭据保存在 WordPress 的 btranslate_settings 选项中，不会在前端输出。插件会存储翻译标识、语言对、字段上下文、源内容指纹、翻译值、状态和时间戳；不会保存完整的百度响应负载。

记录每次百度翻译请求 默认关闭。开启后，每次请求都会向 PHP 错误日志写入安全元数据：语言对、字段上下文、源文本指纹和长度、结果状态以及适用时的错误码。日志绝不会包含凭据、签名、原文、译文或完整 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 站点和服务器虚拟主机已为每个绑定域名配置完成。
翻译失败会作为失败尝试保存，并显示源值；尚未实现重试管理和后台任务监控器。

7.2 KiB Raw Blame History