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 路由模式。
保存文章或页面，为每种已配置的目标语言安排翻译任务。

翻译生命周期

保存文章或页面后，wpt_process_translation Cron 任务会生成翻译。对于插件启用前已发布的内容，请打开 设置 > Btranslate，使用 翻译现有文章和页面 为全部已发布文章和页面安排任务。翻译具有确定性标识，标识由源内容指纹、源语言、目标语言、字段上下文和提供程序版本构成。插件会先在 {$wpdb->prefix}wpt_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 才能解析该语言。

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

安全和数据保留

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

由于 WordPress 选项由数据库保存，请使用 HTTPS 并适当限制数据库访问权限。生产站点应配置真实的 Cron 执行器，确保翻译任务可靠运行。

卸载

卸载 Btranslate 会永久删除其设置和凭据、重新翻译批处理状态、所有待执行的 Btranslate Cron 事件，以及每个站点的 {$wpdb->prefix}wpt_translations 表。这会删除所有已持久化的翻译。停用插件不会删除这些记录。

开发

使用 composer install 安装开发依赖。项目包含用于 Intelephense 的 WordPress API 存根，以及使用伪造提供程序和存储的 PHPUnit 测试；因此测试不需要 WordPress、数据库、凭据或网络访问。

运行测试：

composer test

验证 PHP 语法：

find . -path './.git' -prune -o -type f -name '*.php' -print0 | xargs -0 -n1 php -l

投入生产前，应添加 WordPress PHPUnit 集成测试，并模拟 wp_remote_post 响应。所需覆盖范围包括语言解析、重写行为、持久化复用与失效、百度请求签名和错误处理、内容过滤和回退渲染。

重新翻译

文章和页面列表会显示每种目标语言的状态列，包括最近成功翻译时间和翻译操作。设置页还提供 重新翻译所有内容。它会在为已发布文章、页面、分类和标签安排强制刷新前显示确认警告；此操作会绕过已持久化的翻译并消耗百度 API 配额。

设置页还显示实时进度面板。面板每五秒刷新一次，统计每种已配置目标语言中完成的文章/页面和分类/标签项目。当 重新翻译所有内容 启动批处理时，进度会重置，仅统计该批处理开始后完成的翻译，因此历史翻译不会让新的批处理看似已完成。进度只读取本地 WordPress 和翻译表数据，不会发送额外请求。

已知限制

设置界面接受语言代码，但尚未依据维护中的百度语言代码列表进行验证。
API 调用会翻译原始 WordPress 内容。生产使用前，需要为 HTML、区块、短代码、占位符和 URL 提供受保护令牌处理管线。
分类法和 SEO 值会入队，但当前渲染过滤器只覆盖部分 SEO 插件和术语视图。
域名绑定假定 WordPress 站点和服务器虚拟主机已为每个绑定域名配置完成。
翻译失败会作为失败尝试保存，并显示源值；尚未实现重试管理和后台任务监控器。

6.1 KiB Raw Blame History