edit readme

README.zh-CN.md

@@ -1,101 +1,187 @@
-# Btranslate
+# Btranslate：基于百度翻译 API 的免费开源 Wordpress 多语言插件
 
-中文|[English](README.md)
+BTranslate 是一款 WordPress 多语言翻译插件，通过百度翻译开放平台 API，将网站中的文章、页面及其他内容翻译为不同语言，并为译文生成独立的语言访问地址。
 
-[GitHub 仓库](https://github.com/hanyixuanten/btranslate)
+插件会将翻译结果保存在服务器中。除非用户主动刷新翻译，否则同一内容在同一目标语言下只需翻译一次，无需在每次访问页面时重复调用翻译 API，有助于减少 API 请求量并提高页面加载速度。
 
-Btranslate 是一个 WordPress 插件骨架，使用百度翻译 API 持久化管理多语言内容。
+## 项目地址
 
-WordPress 后台界面会跟随当前 WordPress 语言：默认显示英文，WordPress 设为 `zh_CN` 时使用插件内置的简体中文翻译。
+- GitHub 仓库：[https://github.com/hanyixuanten/btranslate](https://github.com/hanyixuanten/btranslate)
+- WordPress 插件主页：[https://wordpress.org/plugins/btranslate/](https://wordpress.org/plugins/btranslate/)
 
-## 要求
+> **审核状态：** BTranslate 目前尚未通过 WordPress.org 插件目录审核，因此暂时无法直接通过 WordPress 后台插件市场安装。现阶段请从 GitHub 仓库下载并手动安装。
 
-- WordPress 6.4 或更高版本。
-- PHP 8.1 或更高版本。
-- 百度翻译应用 ID 和密钥。
-- 已启用 WordPress Cron，或可调用 WordPress Cron 的服务器定时任务。
+## 主要功能
 
-## 安装
+### 百度翻译 API 集成
 
-1. 将此目录复制到 `wp-content/plugins/btranslate`。
-2. 在 WordPress 后台启用 **Btranslate**。
-3. 打开 **设置 > Btranslate**。
-4. 填写百度翻译凭据、源语言、目标语言代码和 URL 路由模式。
-5. 保存文章或页面，为每种已配置的目标语言安排翻译任务。
+BTranslate 使用百度翻译开放平台提供的翻译 API。用户可以在 WordPress 后台配置自己的 App ID 和密钥，由插件完成请求签名、翻译调用及错误处理。
 
-## 翻译生命周期
+### 文章和页面翻译
 
-保存文章或页面后，`btranslate_process_translation` Cron 任务会生成翻译。对于插件启用前已发布的内容，请打开 **设置 > Btranslate**，使用 **翻译现有文章和页面** 为全部已发布文章和页面安排任务。翻译具有确定性标识，标识由源内容指纹、源语言、目标语言、字段上下文和提供程序版本构成。插件会先在 `{$wpdb->prefix}btranslate_translations` 表中查找已完成的结果；只有缓存未命中时才会向百度发起请求。
+插件支持翻译 WordPress 文章与页面中的主要内容，包括：
 
-源文本变更会生成新的指纹，因此会安排新的翻译任务，而不会删除此前有效的翻译。前端渲染不会请求百度 API；它只读取表中已完成的值，若不存在则回退显示源文本。内容入队后必须运行 WordPress Cron；生产环境应配置真实的服务器 Cron，定期调用 WordPress Cron。
+- 标题
+- 正文
+- 摘要
+- SEO 字段
+- 图片替代文本
+- 标签
+- 分类目录
+- 部分界面文本
 
-## 支持的内容
+### 多语言访问地址
 
-- 文章和页面的标题、正文及摘要。
-- 附件图片的 `alt` 文本。
-- 已分配的分类和标签，包括其描述。
-- Yoast SEO 的标题和描述字段。
-- Rank Math 的标题和描述字段。
-- All in One SEO 与 SEOPress 的标题和描述输出过滤器。
+BTranslate 可以为不同语言生成独立的访问地址，支持：
 
-只有列出的 SEO 元字段，以及受支持 SEO 插件生成的标题/描述输出会被发送翻译。通过 WordPress 文档标题 API 生成的浏览器标题会使用已持久化的文章标题翻译。任意元数据、序列化数据、凭据和代码均会被排除。
+- 语言子目录，例如 `/en/`、`/ja/`
+- 不同语言绑定不同域名
+- 根据配置生成对应语言的固定链接
 
-当文章内容包含 HTML 链接时，插件会保留每个链接的 `href` 和属性，将可见文本作为独立值翻译，再把翻译后的文本写回原始链接。升级后，请重新翻译包含链接的文章以重新生成内容。
+### 翻译结果持久化
 
-分类和标签名称会在创建、编辑或完整重新翻译时进行翻译。在翻译站点上，用于归档、导航和文章元数据的术语对象会使用已持久化的翻译名称和描述。
+翻译完成后，结果会保存在 WordPress 服务器中。后续访问相同译文时，插件优先读取已经保存的结果，而不是重新请求百度翻译 API。
 
-## 路由
+当原文发生变化时，对应译文会被标记为需要更新，从而避免继续使用与原文不一致的旧译文。
 
-**子目录** 模式会解析配置语言对应的路径，例如 `/en/example-post/`。**子域名** 模式通过主机名映射语言：在设置中每行填写一条 `domain=language`。两种模式可以同时启用，也可以同时关闭。链接会保持当前请求的入口模式：从语言子目录打开的页面继续生成子目录链接，从绑定域名打开的页面继续生成该域名下的链接。关闭子域名模式时，域名绑定字段不会显示。
+### WordPress 内容兼容
 
-文章、页面、术语和首页链接会按当前语言生成。例如，主题中使用 `home_url()` 的“返回首页”链接会解析为已绑定语言的域名或语言子目录。
+插件在翻译内容时会尽量保留：
 
-对于已绑定的子域名，请填写类似 `en.example.com=en` 的值。服务器和 DNS 必须先将该主机名指向同一 WordPress 安装，WordPress 才能解析该语言。
+- Gutenberg 区块标记
+- HTML 结构
+- Shortcode 短代码
+- 占位符
+- URL
+- 受保护的特殊内容
 
-插件只处理目标语言的 `sitemap.xml` 请求：子目录模式为 `/{语言}/sitemap.xml`，域名绑定模式为绑定域名上的 `/sitemap.xml`。它始终获取源站根路径的 `/sitemap.xml`，并将 XML 文本节点和属性中指向源站的完整 URL 改写为当前语言 URL；其他 sitemap 文件及外部 URL 不会被改写。源站 sitemap 获取失败时不会造成致命错误，而是交回 WordPress 按普通请求处理。源 sitemap 必须可从 WordPress `home` 配置的源站访问，且插件不会跟随上游重定向。
+### 多语言 SEO
 
-路由设置变更后会刷新重写规则。初始实现尚不生成翻译固定链接、规范 URL、`hreflang` 替代链接或重定向。
+BTranslate 为多语言页面提供必要的 SEO 支持，包括：
 
-## 安全和数据保留
+- 多语言固定链接
+- Canonical URL
+- `hreflang` 多语言链接
+- 站点地图兼容
+- SEO 字段翻译
 
-凭据保存在 WordPress 的 `btranslate_settings` 选项中，不会在前端输出。插件会存储翻译标识、语言对、字段上下文、源内容指纹、翻译值、状态和时间戳；不会保存完整的百度响应负载。
+### 失败回退
 
-**记录每次百度翻译请求** 默认关闭。开启后，每次请求都会触发 `btranslate_translation_request_logged` 操作，并提供语言对、字段上下文、源文本指纹和长度、结果状态以及适用时的错误码。站点可通过自定义日志集成订阅该操作。操作数据绝不会包含凭据、签名、原文、译文或完整 API 响应。
+如果百度翻译 API 请求失败，插件不会使网站页面报错：
 
-由于 WordPress 选项由数据库保存，请使用 HTTPS 并适当限制数据库访问权限。生产站点应配置真实的 Cron 执行器，确保翻译任务可靠运行。
+- 如果没有可用译文，则显示网站的源语言内容。
+- 如果存在以前成功保存的译文，则继续使用旧译文。
 
-## 卸载
+## 快速开始
 
-卸载 Btranslate 会永久删除其设置和凭据、重新翻译批处理状态、所有待执行的 Btranslate Cron 事件，以及每个站点的 `{$wpdb->prefix}btranslate_translations` 表。这会删除所有已持久化的翻译。停用插件不会删除这些记录。
+### 一、获取百度翻译 API
 
-## 开发
+1. 打开[百度翻译开放平台](https://fanyi-api.baidu.com/)。
+2. 注册或登录百度账号。
+3. 进入管理控制台。
+4. 开通通用文本翻译 API 服务。
+5. 创建应用并填写应用信息。
+6. 在应用管理页面获取 **APP ID** 和 **密钥**。
 
-仓库不依赖 Composer 或 PHPUnit。使用系统中可用的 PHP 可执行文件验证 PHP 语法：
+> APP ID 和密钥属于敏感信息，请勿提交到公开的 GitHub 仓库，也不要通过网页前端代码或公开日志暴露。
 
-```sh
-find . -path './.git' -prune -o -type f -name '*.php' -print0 | xargs -0 -n1 php -l
+百度翻译 API 的具体开通方式、计费规则和调用限制，请参考[百度翻译 API 官方文档](https://fanyi-api.baidu.com/doc/23)。
+
+### 二、安装插件
+
+由于插件目前尚未通过 WordPress.org 审核，需要从 GitHub 手动安装。
+
+#### 方法一：上传 ZIP 压缩包
+
+1. 访问 [BTranslate GitHub 仓库](https://github.com/hanyixuanten/btranslate)。
+2. 点击 **Releases**。
+3. 从最新版本下载 zip 文件 **btranslate-*.zip**
+4. 登录 WordPress 管理后台。
+5. 打开“插件” → “安装插件”。
+6. 点击“上传插件”。
+7. 选择下载的 ZIP 文件并开始安装。
+8. 安装完成后启用 BTranslate。
+
+#### 方法二：上传到服务器
+
+1. 访问 [BTranslate GitHub 仓库](https://github.com/hanyixuanten/btranslate)。
+2. 点击 **Releases**。
+3. 从最新版本下载 zip 文件 **btranslate-*.zip**
+4. 将 `btranslate` 目录上传到 WordPress 的插件目录： `wp-content/plugins/btranslate/`
+5. 登录 WordPress 管理后台。
+6. 打开“插件” → “已安装插件”。
+7. 找到 BTranslate 并点击“启用”。
+
+### 三、配置插件
+
+1. 登录 WordPress 管理后台。
+2. 打开 BTranslate 设置页面。
+3. 填写百度翻译开放平台提供的 **APP ID** 和 **密钥**。
+4. 设置网站的源语言。
+5. 添加需要启用的目标语言。
+6. 选择语言 URL 模式，例如语言子目录或域名绑定。
+7. 保存设置。
+
+修改语言路由设置后，建议在 WordPress 后台打开“设置” → “固定链接”，确认固定链接配置已经正确生效。
+
+### 四、开始使用
+
+1. 在 WordPress 后台打开需要翻译的文章或页面。
+2. 保存或更新内容。
+3. 使用 BTranslate 提供的翻译功能生成目标语言译文。
+4. 等待翻译任务完成。
+5. 通过对应语言的访问地址检查译文。
+
+例如，假设源语言页面地址为：
+
+```txt
+https://example.com/about/
 ```
 
-运行 `./build.sh build` 可在本地构建可安装的 ZIP。该命令会编译简体中文翻译目录，在仓库根目录生成带版本号的 `btranslate-<版本>.zip`，并校验压缩包内容。运行 `./build.sh clean` 可删除构建目录和生成的插件 ZIP。构建依赖 `gettext`、`zip` 和 `unzip`。
+英语使用 `/en/` 子目录时，译文地址为：
 
-投入生产前，应在 WordPress 预发布环境中测试插件，覆盖语言解析、重写行为、持久化复用与失效、百度请求签名和错误处理、内容过滤和回退渲染。任何自动化测试都应模拟 `wp_remote_post` 响应，避免依赖真实凭据、数据库或外部网络访问。
+```txt
+https://example.com/en/about/
+```
 
-## 重新翻译
+日语使用 `/ja/` 子目录时，译文地址为：
 
-文章和页面列表会显示每种目标语言的状态列，包括最近成功翻译时间和翻译操作。设置页提供 **重新翻译所有内容**、**翻译所有文章** 和 **翻译所有分类标签**。它们会在为相应内容安排强制刷新前显示确认警告；此操作会绕过已持久化的翻译并消耗百度 API 配额。
+```txt
+https://example.com/ja/about/
+```
 
-第一次保存设置后，需要手动执行 **重新翻译所有内容**，为已有内容安排翻译。设置页还显示实时进度面板。面板每五秒刷新一次，显示最近一次翻译任务的进度，覆盖全量翻译、文章和页面翻译、分类和标签翻译，以及单篇文章翻译。进度仅统计该任务启动后、且属于其已入队内容和目标语言的完成项目，因此历史翻译不会让新的任务看似已完成。失败的文章、页面、分类或标签会显示在进度条下方，并可逐项重新翻译。强制重翻任务会立即开始，并按两秒间隔排队；单次 WP-Cron 请求最多处理一个内容项，避免一次处理全部内容而超时。进度只读取本地 WordPress 和翻译表数据，不会发送额外请求。
+插件会优先使用已保存的译文。只有在原文发生变化、译文失效或用户主动要求刷新时，才需要重新调用翻译 API。
 
-设置页的 **清除已翻译的缓存** 会删除所有持久化翻译记录、取消待执行的翻译任务并重置进度。清除后前台将显示源文，需使用相应翻译操作重新生成翻译；重新生成会再次消耗百度 API 配额。
+## 使用建议
 
-## 已知限制
+- 正式启用前，请先在测试环境中检查固定链接和多语言路由。
+- 为百度翻译 API 设置合理的调用额度和安全策略。
+- 不要在源代码、前端 JavaScript或公开日志中保存 API 密钥。
+- 发布译文前，建议人工检查品牌名、专业术语和重要页面。
+- 修改原文后，应检查对应语言的译文是否需要更新。
+- 配置域名绑定时，需要同时完成 DNS、HTTPS 证书和服务器域名设置。
+- 修改语言路由后，请检查 Canonical URL、`hreflang` 和站点地图是否正确。
 
-- 设置界面接受语言代码，但尚未依据维护中的百度语言代码列表进行验证。
-- API 调用会翻译原始 WordPress 内容。生产使用前，需要为 HTML、区块、短代码、占位符和 URL 提供受保护令牌处理管线。
-- 分类法和 SEO 值会入队，但当前渲染过滤器只覆盖部分 SEO 插件和术语视图。
-- 域名绑定假定 WordPress 站点和服务器虚拟主机已为每个绑定域名配置完成。
-- 翻译失败会作为失败尝试保存并显示源值；设置页可逐项重新翻译，但尚未实现自动重试和完整的后台任务监控器。
+## 系统要求
 
-## 许可证
+- WordPress 6.4 或更高版本
+- PHP 8.1 或更高版本
+- 可正常访问百度翻译 API 的服务器网络环境
+- 有效的百度翻译开放平台 APP ID 和密钥
 
-Btranslate 使用 [GNU 通用公共许可证第 3 版](LICENSE)授权。
+## 问题反馈与贡献
+
+如果在使用过程中遇到问题，或者希望提交功能建议，可以前往 GitHub 仓库反馈：
+
+[https://github.com/hanyixuanten/btranslate](https://github.com/hanyixuanten/btranslate)
+
+提交问题时，建议提供以下信息：
+
+- WordPress 版本
+- PHP 版本
+- BTranslate 版本
+- 使用的语言和路由模式
+- 问题复现步骤
+- 已隐藏敏感信息的错误日志
+
+欢迎通过 Issue 或 Pull Request 参与 BTranslate 的改进。