add chinese readme

2026-07-26 10:42:36 +08:00
parent c12e3d699e
commit a00e0e5bbf
2 changed files with 91 additions and 0 deletions
@@ -0,0 +1,89 @@
+# WP Translate
+
+中文|[English](README.md)
+
+WP Translate 是一个 WordPress 插件骨架，使用百度翻译 API 持久化管理多语言内容。
+
+## 要求
+
+- WordPress 6.4 或更高版本。
+- PHP 8.1 或更高版本。
+- 百度翻译应用 ID 和密钥。
+- 已启用 WordPress Cron，或可调用 WordPress Cron 的服务器定时任务。
+
+## 安装
+
+1. 将此目录复制到 `wp-content/plugins/wp-translate`。
+2. 在 WordPress 后台启用 **WP Translate**。
+3. 打开 **设置 > WP Translate**。
+4. 填写百度翻译凭据、源语言、目标语言代码和 URL 路由模式。
+5. 保存文章或页面，为每种已配置的目标语言安排翻译任务。
+
+## 翻译生命周期
+
+保存文章或页面后，`wpt_process_translation` Cron 任务会生成翻译。对于插件启用前已发布的内容，请打开 **设置 > WP Translate**，使用 **翻译现有文章和页面** 为全部已发布文章和页面安排任务。翻译具有确定性标识，标识由源内容指纹、源语言、目标语言、字段上下文和提供程序版本构成。插件会先在 `{$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 执行器，确保翻译任务可靠运行。
+
+## 开发
+
+使用 `composer install` 安装开发依赖。项目包含用于 Intelephense 的 WordPress API 存根，以及使用伪造提供程序和存储的 PHPUnit 测试；因此测试不需要 WordPress、数据库、凭据或网络访问。
+
+运行测试：
+
+```sh
+composer test
+```
+
+验证 PHP 语法：
+
+```sh
+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 站点和服务器虚拟主机已为每个绑定域名配置完成。
+- 翻译失败会作为失败尝试保存，并显示源值；尚未实现重试管理和后台任务监控器。