HTBD/README.md

Btranslate

中文|English

Btranslate is a WordPress plugin skeleton for persistent multilingual content using the Baidu Translate API.

Requirements

• 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.

Installation

1. Copy this directory to wp-content/plugins/wp-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.

Translation Lifecycle

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.

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.

Supported Content

• 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).

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.

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.

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.

Routing

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. 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 only subdirectory mode is enabled, the domain-binding field is hidden.

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.

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.

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.

After changing routing settings, rewrite rules are refreshed. The initial implementation does not yet generate translated permalinks, canonical URLs, hreflang alternates, or redirects.

Security And Data Retention

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.

The Log every Baidu translation request setting is disabled by default. When enabled, each request writes safe metadata to the PHP error log: language pair, field context, source fingerprint and length, result status, and an error code when applicable. Credentials, signatures, source text, translated text, and complete API responses are never logged.

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.

Uninstalling

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.

Development

The repository has no Composer or PHPUnit dependency. Validate PHP syntax with the PHP executable available on your system:

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

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.

Retranslation

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.

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. 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 清除已翻译的缓存 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.

Known Limitations

• 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; retry management and an admin job monitor are not implemented yet.