hanyixuanten/HTBD
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 8 Wiki Activity

edit readme

Browse Source
This commit is contained in:
hanyixuanten
2026-07-29 14:24:23 +08:00
parent 16d8f16b25
commit 9424411b12
2 changed files with 290 additions and 119 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+145 -60
View File
@@ -1,102 +1,187 @@
# Btranslate
# Btranslate: A Free and Open-Source WordPress Multilingual Plugin Powered by the Baidu Translate API
[中文](README.zh-CN.md)|English
BTranslate is a multilingual translation plugin for WordPress. It uses the Baidu Translate API to translate posts, pages, and other website content into different languages, with a dedicated URL for each translated version.
[GitHub Repository](https://github.com/hanyixuanten/btranslate)
Translations are stored on the server. Unless a user explicitly refreshes a translation, the same content is translated only once for each target language. This avoids calling the translation API on every page visit, reducing API usage and improving page load performance.
Btranslate is a WordPress plugin skeleton for persistent multilingual content using the Baidu Translate API.
## Project Links
The WordPress admin interface follows the current WordPress locale. English is the default, and a bundled Simplified Chinese translation is used when WordPress is set to `zh_CN`.
- GitHub repository: [https://github.com/hanyixuanten/btranslate](https://github.com/hanyixuanten/btranslate)
- WordPress plugin page: [https://wordpress.org/plugins/btranslate/](https://wordpress.org/plugins/btranslate/)
## Requirements
> **Review status:** BTranslate has not yet been approved for the WordPress.org Plugin Directory, so it cannot currently be installed directly from the WordPress admin plugin marketplace. For now, download it from GitHub and install it manually.
- WordPress 6.4 or later.
- PHP 8.1 or later.
- A Baidu Translate application ID and secret key.
- WordPress cron enabled, or a real server cron that calls WordPress cron.
## Key Features
## Installation
### Baidu Translate API Integration
1. Copy this directory to `wp-content/plugins/btranslate`.
2. Activate **Btranslate** in WordPress Admin.
3. Open **Settings > Btranslate**.
4. Enter the Baidu credentials, source language, target-language codes, and URL routing mode.
5. Save a post or page to schedule translation jobs for every configured target language.
BTranslate uses the translation API provided by the Baidu Translate Open Platform. Users can configure their own App ID and secret key in WordPress Admin, and the plugin handles request signing, API calls, and error handling.
## Translation Lifecycle
### Post and Page Translation
Translations are generated by the `btranslate_process_translation` cron task after a post or page is saved. For content published before the plugin was activated, open **Settings > Btranslate** and use **Translate existing posts and pages** to schedule all published posts and pages. A translation has a deterministic identity based on the source fingerprint, source language, target language, field context, and provider version. The plugin first looks up a completed result in the `{$wpdb->prefix}btranslate_translations` table. Only a cache miss causes a request to Baidu.
The plugin supports translating the main content of WordPress posts and pages, including:
Changing source text produces a new fingerprint and therefore schedules a new translation without deleting a valid prior translation. Front-end rendering never contacts Baidu; it reads a completed value from the table and otherwise falls back to the source value. WordPress cron must run after queuing content; production sites should configure a real server cron to call WordPress cron regularly.
- Titles
- Body content
- Excerpts
- SEO fields
- Image alternative text
- Tags
- Categories
- Selected interface text
## Supported Content
### Multilingual URLs
- Post and page titles, content, and excerpts.
- Attached image `alt` text.
- Assigned categories and tags, including their descriptions.
- Yoast SEO title and description fields.
- Rank Math title and description fields.
- All in One SEO and SEOPress title and description output filters.
- WordPress AI plugin fallback meta description (`wpai_meta_description`).
BTranslate can generate dedicated URLs for different languages, with support for:
Only the listed SEO meta fields and the generated title/description output from supported SEO plugins are sent for translation. Browser titles generated through the WordPress document-title API use the persisted translated post title. Arbitrary metadata, serialized data, credentials, and code are excluded.
- Language subdirectories such as `/en/` and `/ja/`
- A separate domain for each language
- Language-specific permalinks based on the configured routing mode
When post content contains HTML links, the plugin preserves each link's `href` and attributes, translates its visible text as a separate value, and inserts that translated text back into the original link. Re-run a post translation after upgrading to regenerate previously translated content that contains links.
### Persistent Translations
Category and tag names are translated when they are created, edited, or included in a full retranslation. On a translated site, term objects used by archives, navigation, and post metadata use the persisted translated name and description.
After a translation is generated, it is stored on the WordPress server. Future requests for the same translation use the stored result instead of calling the Baidu Translate API again.
## Routing
When the source content changes, the corresponding translation is marked as requiring an update, preventing an outdated translation from being used for changed content.
The **Subdirectory** mode resolves configured language paths such as `/en/example-post/`. The **Domain binding** mode maps a request host to a language using one `domain=language` entry per line in Settings. Both modes can be enabled together or disabled together. Links keep the active request mode: pages opened through a language subdirectory continue linking within that subdirectory, while pages opened through a bound domain continue linking within that domain. When domain mode is disabled, the domain-binding field is hidden.
### WordPress Content Compatibility
Post, page, term, and home links are generated for the active language. For example, a theme's "back to home" link that uses `home_url()` resolves to the bound language domain or language subdirectory.
When translating content, the plugin makes every effort to preserve:
For a bound subdomain, enter a value such as `en.example.com=en`. The server and DNS must route that hostname to the same WordPress installation before WordPress can resolve the language.
- Gutenberg block markup
- HTML structure
- Shortcodes
- Placeholders
- URLs
- Protected special content
The plugin handles only the target language's `sitemap.xml` request: `/{language}/sitemap.xml` in subdirectory mode and `/sitemap.xml` on a bound domain. It always fetches `/sitemap.xml` from the source site's origin and rewrites complete source-site URLs in XML text nodes and attributes to the current language URL. Other sitemap filenames and external URLs remain unchanged. Source sitemap failures remain non-fatal and fall back to normal WordPress request handling. The source sitemap must be available from the WordPress `home` origin; upstream redirects are not followed.
### Multilingual SEO
After changing routing settings, rewrite rules are refreshed. The initial implementation does not yet generate translated permalinks, canonical URLs, `hreflang` alternates, or redirects.
BTranslate provides essential SEO support for multilingual pages, including:
## Security And Data Retention
- Multilingual permalinks
- Canonical URLs
- `hreflang` alternate links
- Sitemap compatibility
- SEO field translation
Credentials are stored in the WordPress `btranslate_settings` option and are not rendered on the front end. The plugin stores the translation identity, language pair, field context, source fingerprint, translated value, status, and timestamps. It does not store full Baidu response payloads.
### Failure Fallback
The **Log every Baidu translation request** setting is disabled by default. When enabled, each request fires the `btranslate_translation_request_logged` action with safe metadata: language pair, field context, source fingerprint and length, result status, and an error code when applicable. A site-specific logging integration can subscribe to this action. Credentials, signatures, source text, translated text, and complete API responses are never included.
If a Baidu Translate API request fails, the plugin does not cause the website page to fail:
Use HTTPS and restrict database access appropriately because WordPress options are database-backed. Production sites should configure a real cron runner for reliable translation processing.
- If no translation is available, the website's source-language content is displayed.
- If a previously saved successful translation exists, the previous translation continues to be used.
## Uninstalling
## Quick Start
Uninstalling Btranslate permanently deletes its settings and credentials, retranslation batch state, all pending Btranslate cron events, and every site's `{$wpdb->prefix}btranslate_translations` table. This removes all persisted translations. Deactivating the plugin does not delete these records.
### 1. Get Access to the Baidu Translate API
## Development
1. Open the [Baidu Translate Open Platform](https://fanyi-api.baidu.com/).
2. Register or sign in with a Baidu account.
3. Open the management console.
4. Activate the General Text Translation API service.
5. Create an application and enter the required application information.
6. Obtain the **APP ID** and **secret key** from the application management page.
The repository has no Composer or PHPUnit dependency. Validate PHP syntax with the PHP executable available on your system:
> Your APP ID and secret key are sensitive credentials. Do not commit them to a public GitHub repository or expose them in front-end code or public logs.
```sh
find . -path './.git' -prune -o -type f -name '*.php' -print0 | xargs -0 -n1 php -l
For activation instructions, pricing, and usage limits, see the [official Baidu Translate API documentation](https://fanyi-api.baidu.com/doc/23).
### 2. Install the Plugin
Because the plugin has not yet been approved for the WordPress.org Plugin Directory, it must currently be installed manually from GitHub.
#### Method 1: Upload the ZIP Package
1. Visit the [BTranslate GitHub repository](https://github.com/hanyixuanten/btranslate).
2. Select **Releases**.
3. Download the **btranslate-*.zip** file from the latest release.
4. Sign in to WordPress Admin.
5. Open **Plugins > Add New Plugin**.
6. Select **Upload Plugin**.
7. Choose the downloaded ZIP file and start the installation.
8. Activate BTranslate after installation is complete.
#### Method 2: Upload to the Server
1. Visit the [BTranslate GitHub repository](https://github.com/hanyixuanten/btranslate).
2. Select **Releases**.
3. Download the **btranslate-*.zip** file from the latest release.
4. Upload the `btranslate` directory to the WordPress plugin directory: `wp-content/plugins/btranslate/`.
5. Sign in to WordPress Admin.
6. Open **Plugins > Installed Plugins**.
7. Find BTranslate and select **Activate**.
### 3. Configure the Plugin
1. Sign in to WordPress Admin.
2. Open the BTranslate settings page.
3. Enter the **APP ID** and **secret key** provided by the Baidu Translate Open Platform.
4. Set the website's source language.
5. Add the target languages you want to enable.
6. Select a language URL mode, such as language subdirectories or domain binding.
7. Save the settings.
After changing language routing settings, open **Settings > Permalinks** in WordPress Admin and confirm that the permalink configuration is working correctly.
### 4. Start Translating
1. Open the post or page you want to translate in WordPress Admin.
2. Save or update the content.
3. Use the translation feature provided by BTranslate to generate translations for the target languages.
4. Wait for the translation tasks to finish.
5. Check each translation at its language-specific URL.
For example, suppose the source-language page is available at:
```txt
https://example.com/about/
```
Build the installable ZIP locally with `./build.sh build`. The command compiles the Simplified Chinese translation catalog, creates a versioned `btranslate-<version>.zip` in the repository root, and validates its contents. Run `./build.sh clean` to remove the build directory and generated plugin ZIP files. The build requires `gettext`, `zip`, and `unzip`.
When English uses the `/en/` subdirectory, its translated URL is:
Before production use, test the plugin in a WordPress staging environment. Cover language resolution, rewrite behavior, persistence reuse and invalidation, Baidu request signing and errors, content filtering, and fallback rendering. Mock `wp_remote_post` responses for any automated tests so they do not need live credentials, a database, or outbound network access.
```txt
https://example.com/en/about/
```
## Retranslation
When Japanese uses the `/ja/` subdirectory, its translated URL is:
The Posts and Pages lists show a status column for every target language, including the latest successful translation time and a translation action. The Settings page provides **重新翻译所有内容**, **翻译所有文章**, and **翻译所有分类标签**. Each action shows a confirmation before scheduling a forced refresh of all supported content, only published posts and pages, or only categories and tags; this bypasses persisted translations and consumes Baidu API quota.
```txt
https://example.com/ja/about/
```
After saving settings for the first time, manually run **Retranslate all content** to queue existing content. The Settings page also shows a live progress panel. It refreshes every five seconds and reports the latest translation task: full translation, post/page translation, category/tag translation, or a single-post translation. It counts only completed items that belong to that task's queued content and target languages after the task began, so historical translations cannot make a new task appear complete. Failed posts, pages, categories, or tags appear below the progress bar with an individual retranslation action. Forced retranslation jobs begin immediately and are scheduled two seconds apart, so a single WP-Cron request processes at most one task item instead of timing out while processing every post. Progress reads only local WordPress and translation-table data; it does not send additional requests to Baidu.
The plugin prioritizes saved translations. It calls the translation API again only when the source content changes, a translation becomes invalid, or a user explicitly requests a refresh.
The **清除已翻译的缓存** action deletes every persisted translation, cancels pending translation jobs, and resets batch progress. The front end then falls back to source content until translations are explicitly queued again; regenerating them consumes Baidu API quota.
## Recommendations
## Known Limitations
- Test permalinks and multilingual routing in a staging environment before enabling the plugin in production.
- Set appropriate usage quotas and security policies for the Baidu Translate API.
- Do not store API credentials in source code, front-end JavaScript, or public logs.
- Manually review brand names, technical terminology, and important pages before publishing translations.
- After changing source content, check whether the corresponding translations need to be updated.
- When configuring domain binding, also configure DNS, HTTPS certificates, and the server's domain settings.
- After changing language routing, verify that canonical URLs, `hreflang` links, and sitemaps are correct.
- The settings UI accepts language codes but does not yet validate them against a maintained Baidu language-code list.
- API calls translate raw WordPress content. HTML, blocks, shortcodes, placeholders, and URLs need a protected-token pipeline before production use.
- Taxonomy and SEO values are queued but the current rendering filters cover only a subset of SEO plugins and term views.
- Domain binding assumes the WordPress site and server virtual hosts are already configured for every bound domain.
- Translation failures are stored as failed attempts and render the source value. The Settings page supports individual retries, but automatic retries and a full admin job monitor are not implemented yet.
## System Requirements
## License
- WordPress 6.4 or later
- PHP 8.1 or later
- A server environment that can connect to the Baidu Translate API
- A valid Baidu Translate Open Platform APP ID and secret key
Btranslate is licensed under the [GNU General Public License version 3](LICENSE).
## Feedback and Contributions
To report a problem or suggest a feature, visit the GitHub repository:
[https://github.com/hanyixuanten/btranslate](https://github.com/hanyixuanten/btranslate)
When opening an issue, consider including the following information:
- WordPress version
- PHP version
- BTranslate version
- Languages and routing mode in use
- Steps to reproduce the problem
- Error logs with sensitive information removed
Contributions through issues and pull requests are welcome.
README.zh-CN.md
+145 -59
View File
@@ -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 的改进。