HTBD/AGENTS.md

hyx-translator-for-baidu-translate Agent Guide

Project Scope

Build a WordPress multilingual plugin that uses the Baidu Translate API. Support language-specific subdirectory URLs and domain bindings. Translate WordPress posts and pages, interface titles and body text, SEO fields, excerpts, image alt text, tags, and categories.

Unless a user explicitly requests a refresh, each translatable value must be translated once per target language and then persisted on the server for reuse.

Architecture Boundaries

• Keep language routing, translation providers, persistence, caching, rendering, and admin settings in separate components.
• Put Baidu-specific signing and HTTP behavior behind a provider interface so tests can use a fake provider without credentials or network access.
• Use deterministic translation identities that include the source value fingerprint, source and target language, field context, and provider/configuration version.
• Persist source language, target language, source fingerprint, translated value, status, and necessary timestamps. Reuse a valid persisted translation before making an API request.
• Invalidate a translation when its source content or configured translatable field changes. Never translate dynamically on every front-end request.
• Make failed translation requests non-fatal: retain a prior valid translation when available; otherwise render the configured source-language fallback.

WordPress Integration

• Follow WordPress Coding Standards and use WordPress APIs for hooks, settings, options, metadata, rewrite rules, sanitization, escaping, capabilities, nonces, HTTP, and cron/queues.
• Do not modify WordPress core, themes, or third-party plugins.
• Use a single plugin prefix for PHP symbols, options, meta keys, transients, REST routes, and custom database tables; document the chosen prefix once it exists.
• Preserve Gutenberg block markup, HTML structure, shortcodes, placeholders, protected tokens, and URLs when translating content.
• Treat serialized data, executable code, credentials, identifiers, passwords, and arbitrary metadata as non-translatable unless explicitly supported.
• Support classic and block themes without assuming a particular page builder.

Routing And SEO

• Validate every language code against the configured language list; do not trust raw request input.
• Select one canonical URL strategy for each language: subdirectory, domain binding, or an explicitly configured hybrid. Avoid serving the same translation at multiple canonical URLs.
• Generate language-aware permalinks, canonical URLs, hreflang alternates, and compatible sitemap output where applicable.
• Preserve query variables, pagination, previews, and supported REST routes through language resolution.
• Register rewrite rules using WordPress APIs. Flush rewrites only on activation, deactivation, or an explicit routing configuration change.

Security And Privacy

• Store Baidu credentials through WordPress settings APIs and never expose them in front-end output, JavaScript, logs, exports, or ordinary error messages.
• Use wp_remote_* with explicit timeouts and actionable, sanitized error handling.
• Sanitize on write, validate configuration, escape at the rendering boundary, and guard admin actions with capability checks and nonces.
• Do not retain full provider payloads or translated user content in logs unless opt-in debug logging is enabled.

Quality And Documentation

• Add focused tests for language selection, routing, translation cache reuse and invalidation, persistence, provider signing/error handling, and content/meta filtering.
• Mock Baidu API calls in every test. Tests must not require live credentials or outbound network access.
• Keep changes narrow and avoid unrelated refactors or formatting churn.
• After every file change, review .github/workflows/package-plugin.yml and ensure the automated packaging Action includes all runtime files required by the change. Validate the packaging commands locally when practical.
• Plugin slug and PHP prefix: hyx-translator-for-baidu-translate and htbd_/HTBD_. The custom translation table is {$wpdb->prefix}hyx_bd_translations. The current minimum supported PHP version is 8.1 and the current minimum WordPress version is 6.4.
• The repository has no Composer-managed development dependencies or bundled automated test suite. Validate PHP syntax with find . -path './.git' -prune -o -type f -name '*.php' -print0 | xargs -0 -n1 php -l. Any future automated tests must mock WordPress API calls and must not require live credentials, external network access, or a WordPress database.
• Document supported languages, routing modes, data retention, translation lifecycle, and known limitations in the README whenever the implementation changes.

Release Workflow

When the user issues release x.x.x or release vx.x.x:

1. Determine the previous version from the latest Git tag reachable from the current commit and output that tag/version before making release changes. Accept the optional leading v in the requested version and preserve the repository's existing version/tag convention.
2. Search the entire repository, including hidden files such as .github and excluding only Git internals and ignored/generated artifacts, for every occurrence of the previous version. Replace all release-version occurrences with the new version, including but not limited to PHP headers/constants, readme files, documentation, workflows, and issue templates. Report the files changed and verify that no stale release-version occurrence remains where the current release version is expected.
3. Generate release notes from the previous tag through the current release state, using the commits and resulting diff in that range. Output both an English release log and a Chinese release log in Markdown format, with each complete language version enclosed in its own fenced code block. Keep the two logs semantically aligned and organize notable changes, fixes, compatibility notes, and upgrade considerations when applicable.