=== WPMMCC === Contributors: wpmmcc Tags: multilingual, translation, localization, multisite, seo Requires at least: 5.3 Tested up to: 6.9 Stable tag: 2.0.1 Requires PHP: 7.2 License: GPLv2 or later License URI: https://www.gnu.org/licenses/gpl-2.0.html Automatic multilingual translation for WordPress — posts, pages, media, categories, themes — powered by Google, DeepL, Baidu, Youdao or OpenAI. == Description == WPMMCC is a full-featured multilingual plugin that translates your WordPress content automatically and serves each language at its own URL. It works in two modes: * **Directory mode** — one WordPress site, multiple language prefixes (example.com/en/, example.com/zh/) * **Multisite mode** — each language runs as a separate site in a WordPress Multisite network No page builders required. No manual copying of posts. Configure your language groups, pick a translation provider, and let the background queue handle the rest. = What Gets Translated = **Posts, Pages & Custom Post Types** Title, content, excerpt, and any custom fields you configure. Shadow copies of translated posts are stored on the same WordPress installation and served at the correct language URL automatically. **Media Attachments** Alt text, caption, and description fields for images and other attachments. **Categories & Tags (Taxonomies)** Translate category names, tag names, descriptions, and slugs into each target language. **Theme Strings** Scan your active theme's PHP files, JavaScript, Twig templates, and database-stored strings. Translated strings are served transparently through WordPress filter hooks. **SEO Meta Fields** Translate Yoast SEO, Rank Math, and other SEO plugin fields alongside your content. Scan, add, enable, or disable individual meta fields per site group. = Translation Providers = Choose one or more providers per translation rule. Each rule maps a source language to a target language with a specific vendor: * **Google Translate** — fast, broad language coverage * **DeepL** — high quality, especially for European languages * **Baidu Translate** — optimised for Chinese * **Youdao** — alternative for Chinese language pairs * **OpenAI / compatible LLMs** — context-aware, customisable prompt, supports any OpenAI-compatible endpoint (e.g. Azure OpenAI, local models) = Background Task Queue = Translations run as background jobs so large sites never time out. Built on Action Scheduler (bundled, table-prefixed to avoid conflicts with WooCommerce). Monitor progress, cancel, retry, or manually trigger jobs from the Tasks screen. = SEO & URL Management = * Automatic `hreflang` link tags for every translated page * Canonical URL management with proper trailing-slash handling * Multilingual XML sitemaps — shadow copies are excluded from the main sitemap; child language sitemaps use correct language-prefixed URLs * Compatible with Yoast SEO, Rank Math, and other SEO plugins = Frontend Shortcodes = Use these shortcodes anywhere on your site: * `[wpmmcc_ml_current_language]` — outputs the current page's language code * `[wpmmcc_ml_site_group_type]` — outputs the group type (directory / multisite) * `[wpmmcc_ml_language_switcher]` — renders a language switcher link list * `[wpmmcc_ml_language_items]` — outputs all available languages as a JSON array * `[wpmmcc_ml_canonical]` — outputs the canonical `` tag for the current page * `[wpmmcc_ml_hreflang]` — outputs all `` tags = Admin Enhancements = * Site filter dropdowns on the Posts, Pages, Media, Categories, and Comments admin list screens — filter any list by language site with one click * Translation management screen — view, filter, and delete translation relations * Bulk translation directly from the admin post list = Requirements = * WordPress 5.3 or higher * PHP 7.2 or higher * MySQL 5.7 or MariaDB 10.2 * PHP extensions: openssl, json, mbstring, curl = Compatibility = **Core Platform Compatibility** * Minimum supported WordPress version: 5.3 * Tested up to WordPress 6.9 * Minimum supported PHP version: 7.2 * Works on both single-site WordPress installs and WordPress Multisite networks **Site Mode Compatibility** * **Directory mode** works on a standard single-site WordPress install and serves translated content under language-prefixed URLs such as `/zh/` or `/fr/` * **Multisite mode** requires a WordPress Multisite network and maps each language to its own site in the network **SEO Plugin Compatibility** * Built to work alongside Yoast SEO and Rank Math * SEO meta translation is field-based, so supported meta keys can be scanned, enabled, disabled, and translated from the SEO Fields screen * Canonical and `hreflang` output can be handled either by WPMMCC or by your SEO plugin, depending on your settings * No fixed version matrix is published for third-party SEO plugins; compatibility is maintained at the integration level rather than by pinning specific vendor versions in this readme **Operational Notes** * Translation jobs run through a bundled Action Scheduler build with prefixed tables to reduce conflicts with WooCommerce or other plugins that ship their own Action Scheduler copy * Block themes are supported when the active theme exposes standard WordPress block-theme files such as `theme.json`, `templates`, or `parts` * API-based translation requires outbound HTTPS access from your server to the provider you configure == Installation == = Automatic Installation = 1. Go to **Plugins > Add New** in your WordPress admin 2. Search for "WPMMCC" 3. Click **Install Now** and then **Activate** = Manual Installation = 1. Download the plugin ZIP file 2. Go to **Plugins > Add New > Upload Plugin** 3. Upload the ZIP file and click **Install Now** 4. Activate the plugin = First-Time Setup = 1. Go to **WPMMCC > Sites** and click **Add New** 2. Choose your group type: **Directory** (single site, language prefixes) or **Multisite** 3. Add a site entry for each language. Mark one as the **Main Site** 4. Go to **WPMMCC > Machine translation** or **WPMMCC > LLM translation** and click **Add Rule** 5. Save vendor credentials or LLM model details first, then select source language, target language, and request limits 6. Click **Test Rule** or test the model configuration to verify the remote service works 7. Go to **WPMMCC > Translation Fields** to choose which post fields to translate 8. On any post list screen, select posts and use **Bulk Translate** to start translating 9. Monitor progress at **WPMMCC > Tasks** = Admin Workflow Guide = After activation, the plugin adds a top-level **WPMMCC** menu in the WordPress admin. The main administrator workflow is: 1. Configure site structure in **WPMMCC > Sites** 2. Configure providers and rules in **WPMMCC > Machine translation** or **WPMMCC > LLM translation** 3. Choose translatable fields in **WPMMCC > Translation Fields** 4. Optionally configure SEO fields in **WPMMCC > SEO Fields** 5. Start translations from the post, media, or taxonomy list screens using **Bulk Translate** 6. Monitor or manage queued jobs in **WPMMCC > Tasks** 7. Review relations in **WPMMCC > Translation management** 8. Configure sitemap output in **WPMMCC > Sitemap** 9. Adjust global behavior in **WPMMCC > Parameters** = Admin Pages = **WPMMCC > Sites** * Create and manage site groups * Add, edit, or remove language sites * Configure whether a group runs in **directory** mode or **multisite** mode * Set the main site for each language group **WPMMCC > Machine translation** * Create translation rules for Google, DeepL, Baidu, or Youdao * Save provider credentials on the vendor settings screen, then define source language, target language, and the per-rule **Maximum characters per request** * Long text is split automatically on line, sentence, and word boundaries before sending requests, then merged back into the final translated field * Test rule connectivity before saving **WPMMCC > LLM translation** * Register OpenAI-compatible models and endpoints * Create LLM-based translation rules with model, prompt, temperature, and **Maximum response tokens** * `Maximum response tokens` is passed to the API as the model's response cap; long source content is still chunked automatically before translation and merged back after the response returns * Test model configuration from the admin interface **WPMMCC > Theme** * Scan active-theme strings from PHP, JavaScript, templates, and database-backed theme content * Trigger automatic theme translation for a selected site * Review, search, edit, or manually add theme translation entries **WPMMCC > Tasks** * **Task list** tab: monitor background jobs, inspect status, filter by group or site, and perform operations such as retry, delete, or manual execution where available * **Task settings** tab: adjust queue batch size, concurrency, overwrite behavior, retry behavior, and related execution settings **WPMMCC > Translation management** * Review translation relations across posts, media, and terms * Filter by object type, group, or site * Delete single relations or remove them in bulk **WPMMCC > Sitemap** * Configure sitemap output format and per-group sitemap generation * Verify generated multilingual sitemap links from the admin screen **WPMMCC > Parameters** * Control global plugin behavior such as canonical output, `hreflang`, uninstall retention, logging, and related plugin-wide options = Admin List Screen Operations = The plugin also extends standard WordPress list screens used by administrators and editors: * **Posts / Pages**: select content rows and use **Bulk Translate** to create translation tasks * **Media Library**: bulk translate attachment metadata such as alt text, caption, and description * **Categories / Tags**: bulk translate taxonomy terms and their descriptions/slugs * **Comments, Posts, Pages, Media, Categories**: use the **Site** filter dropdown to view content belonging to a specific translated site * **Post edit screen**: use the WPMMCC meta box to inspect or adjust site-related translation context = Typical Admin Tasks = **Translate posts or pages** 1. Open **Posts** or **Pages** 2. Select one or more items 3. Choose **Bulk Translate** 4. Select the target site/language 5. Confirm and monitor progress in **WPMMCC > Tasks** **Translate theme strings** 1. Open **WPMMCC > Theme** 2. Select the target site 3. Run **Scan and translate** 4. Wait for queue completion in **WPMMCC > Tasks** 5. Return to **WPMMCC > Theme** to review or edit results **Translate SEO fields** 1. Open **WPMMCC > SEO Fields** 2. Scan available meta fields for the selected group 3. Enable the fields you want to translate 4. Run post/page translations as usual **Review translation relations** 1. Open **WPMMCC > Translation management** 2. Filter by type or site if needed 3. Delete stale or unwanted relations 4. Re-run translation for the affected content if you need to recreate them = Site Owner Guide = This section is intended for site owners, operators, and project managers who are responsible for launching and maintaining a multilingual site, but may not work with WordPress internals every day. **Before You Launch** * Confirm your permalink structure is enabled and working correctly before setting up directory-mode language URLs * Decide whether your project should use **directory mode** or **multisite mode** before you begin translating live content * Prepare valid API credentials for your chosen translation provider * Decide which content types need translation first: posts, pages, media, taxonomy terms, theme strings, and SEO fields * If you already use Yoast SEO or Rank Math, decide whether WPMMCC or your SEO plugin should output canonical and `hreflang` tags **Recommended Launch Order** 1. Create the site group and language sites 2. Create and test the translation rule 3. Enable the content fields and SEO fields you want translated 4. Translate a small set of test pages first 5. Check frontend URLs, page titles, metadata, canonical tags, and `hreflang` 6. Scan and translate theme strings 7. Translate the remaining content in batches 8. Review sitemap output before announcing the multilingual site publicly **Daily Use For Site Owners** * Publish or update content on the source site first * Send new or changed content to translation from the relevant list screen * Check **WPMMCC > Tasks** to make sure jobs complete successfully * Review a few translated pages on the frontend, especially high-value landing pages * Re-scan theme strings after theme changes, theme updates, or menu/widget updates **When You Should Re-Run Translation** * After changing the source post title, content, or excerpt * After updating featured image metadata or attachment alt text * After editing category/tag names, descriptions, or slugs * After changing SEO titles, meta descriptions, or enabled SEO fields * After switching themes or updating theme templates, menu labels, widgets, or `theme.json` content **SEO Checklist For Site Owners** * Verify each translated page resolves on its correct language URL * Confirm canonical tags point to the localized page you expect * Confirm `hreflang` tags include the right language variants * Check that translated pages are indexable if you want them in search engines * Review generated sitemap URLs after major translation batches **Operations And Safety** * Keep **Keep data on uninstall** enabled if you want to preserve translation data during maintenance or reinstallation * Use staging first when changing translation providers, queue settings, or site structure on an established production site * Translate in batches for large sites rather than sending all content at once * Monitor provider usage limits, quotas, and billing in the provider's own dashboard **Common Issues To Check First** * If translated pages do not appear, review **WPMMCC > Tasks** for failed or pending jobs * If translated URLs return 404, re-save permalinks and confirm the site group is configured correctly * If SEO metadata is not translated, re-scan and enable the relevant field in **WPMMCC > SEO Fields** * If menus, widgets, or theme labels remain untranslated, run a theme scan again from **WPMMCC > Theme** * If a language variant looks outdated, re-run translation for the affected source content = Admin Roles And Typical Responsibilities = WPMMCC is primarily designed for administrators or site managers with permission to configure translation providers, site groups, queue settings, and SEO behavior. **Administrator responsibilities** * Create site groups and child sites * Configure machine-translation or LLM providers * Enable translatable content fields and SEO fields * Control sitemap, canonical, `hreflang`, uninstall-retention, and queue settings * Review translation relations and remove invalid mappings when necessary * Run theme scans, delete theme translations, and manage manual theme translation entries **Content editor responsibilities** * Publish or update source content * Trigger bulk translation from supported content list screens when permissions allow * Review translated output on the frontend * Report broken links, missing strings, or outdated translations back to the site administrator = Translation Data Flow = At a high level, WPMMCC processes multilingual content in the following order: 1. The administrator defines a **site group**, target sites, and a translation rule 2. Source content is selected from a post, media, or taxonomy list screen 3. WPMMCC creates background tasks in the queue 4. The selected translation provider translates enabled content fields 5. WPMMCC writes translated objects to the target site context 6. WPMMCC records the source-to-target mapping in the translation relations table 7. Frontend hooks resolve the correct translated URL, metadata, and theme strings for the visitor **For posts and pages** * The plugin reads enabled source fields such as title, content, excerpt, and selected SEO meta * A translation task is queued and executed in the background * In directory mode, translated content is stored as a shadow post on the same WordPress install and served under the language-prefixed URL * In multisite mode, translated content is written into the corresponding target site * The translation relation is stored so WPMMCC can connect the source object to the translated object later = Translation Rule Sizing And Long-Content Handling = WPMMCC applies translation-rule sizing differently for machine providers and LLM providers: * **Machine translation rules** use **Maximum characters per request** as the main request-size control * The effective machine-request size is the lower of the rule value and the provider hard limit built into the plugin * **LLM translation rules** use **Maximum response tokens** as the API `max_tokens` value; this affects the model output budget, not the source-text chunk size directly * Long source fields are chunked automatically before dispatch so large posts, excerpts, SEO fields, and theme strings can still be translated safely When long content is translated, WPMMCC currently follows this flow: 1. It calculates the effective per-request character budget for the selected rule/provider 2. It tries to split long plain text on line breaks, sentence boundaries, and word boundaries 3. If the field contains HTML, it keeps tag structure balanced while chunking so translated fragments can be merged back into valid markup 4. It sends the resulting fragments to the provider in order 5. It validates the returned fragment count and fills any missing pieces with original content when necessary 6. It merges translated fragments back into a single field value before saving the translated object This means: * Lowering machine-rule length gives you more conservative, smaller requests * Raising machine-rule length cannot exceed the provider hard limit enforced by the plugin * Increasing LLM response tokens can help with longer answers from the model, but it does not replace the plugin's source-content chunking * Very large HTML fields are translated fragment-by-fragment and then reassembled in order **For media** * The plugin translates attachment metadata such as alt text, caption, and description * The translated media relation is tracked so the translated parent content can resolve the correct localized media information **For categories and tags** * The plugin translates taxonomy names, descriptions, and slugs * Term relations are stored separately so frontend category/tag links can remain localized **For theme strings** * WPMMCC scans the active theme for translatable strings in files, menus, widgets, and selected database-backed theme content * The scan creates theme-translation tasks, which are then translated and cached for frontend use * Theme translations are loaded dynamically for the current site/language combination rather than being treated like normal posts = Managing Translated Content After Translation = WPMMCC does not stop at initial translation. The plugin also provides ongoing translated-content management tools: **Translation management page** * Open **WPMMCC > Translation management** * View source-to-target mappings for posts, pages, media, categories, and tags * Filter by object type, group, or search term * Delete stale relations individually or in bulk **Translated post and term maintenance** * Re-run translation when source content changes significantly * Use the admin **Site** filter on posts, pages, media, categories, and comments to inspect content by language site * Review frontend output after major source edits, taxonomy changes, or SEO-field changes **Queue-based management** * Open **WPMMCC > Tasks** * Inspect pending, running, completed, or failed jobs * Retry or manually run tasks where the interface allows * Tune task settings when you need smaller batches or more conservative execution = Theme Scan, Manual Add, And Edit Workflow = Theme translations have their own management workflow because they are not stored like regular post content. **Theme scan workflow** 1. Open **WPMMCC > Theme** 2. Select the group and child site you want to manage 3. Choose a scan mode: * **Overwrite existing translations**: regenerate and replace existing theme translations for that site * **Only add new content**: keep existing translated entries and only add strings that were not translated before 4. Click **Scan and translate** 5. Track progress in **WPMMCC > Tasks** **Manual theme translation entry** On the Theme page, administrators can click **Add manually** and enter: * **Source identifier**: a label used to distinguish the manual entry * **Original content**: the source text * **Translated content**: the target-language text This is useful when: * a theme string is not discovered automatically * a site owner wants to override an automatic result * a small number of strings should be curated manually **Editing existing theme translations** * Use the Theme page results list to locate an existing translation entry * Open the edit view * Update the original text or translated text * Save the entry so the frontend can use the revised translation **Deleting theme translations** * Administrators can delete all theme translations for the selected child site from **WPMMCC > Theme** * This is useful after a theme switch, a large redesign, or when a full re-scan is preferred over incremental cleanup == Frequently Asked Questions == = What translation providers are supported? = Google Translate, DeepL, Baidu Translate, Youdao, and OpenAI (or any OpenAI-compatible endpoint). You can create multiple rules and use different providers for different language pairs. = Where do I get an API key? = Each provider issues its own key from its developer console: * **Google Translate**: [Google Cloud Console](https://console.cloud.google.com/) — enable the Cloud Translation API, create credentials * **DeepL**: [DeepL Pro](https://www.deepl.com/pro) — the free tier (DeepL API Free) is supported * **Baidu Translate**: [Baidu Fanyi API](https://fanyi-api.baidu.com/) — use the AI Text Translate API (`https://fanyi-api.baidu.com/ait/api/aiTextTranslate`), create an APP ID, and authenticate with either a Secret Key or an API Key * **Youdao**: [Youdao AI Open Platform](https://ai.youdao.com/) — use the Webpage Translation API (`https://openapi.youdao.com/translate_html`), create an app, and obtain App ID and App Secret * **OpenAI**: [OpenAI Platform](https://platform.openai.com/) — create an API key; any OpenAI-compatible endpoint (including self-hosted models) is supported via the configurable API URL field = How should I configure maximum characters and maximum response tokens? = Use the two settings for different purposes: * **Maximum characters per request** applies to machine-translation rules such as Google, DeepL, Baidu, and Youdao * Choose a value that is at or below the vendor's supported request size; smaller values are safer when translating very large or HTML-heavy content * **Baidu AI Text Translate** uses `https://fanyi-api.baidu.com/ait/api/aiTextTranslate`; when HTML is detected the plugin requests `model_type=nmt` with `tag_handling=1` * Baidu AI Text Translate documentation: `https://fanyi-api.baidu.com/doc/21` * Baidu credentials must have the AI Text Translate service enabled before WPMMCC can translate content successfully * **Youdao Webpage Translation** uses `https://openapi.youdao.com/translate_html` for both plain text and HTML, and the account must have the Webpage Translation service enabled * Youdao Webpage Translation documentation: `https://ai.youdao.com/DOCSIRMA/html/trans/api/wyfy/index.html` * **Maximum response tokens** applies to LLM rules only and is sent as `max_tokens` * Set LLM response tokens to `0` if you want the remote model to decide automatically * Long source content is chunked automatically by WPMMCC even when `max_tokens` is `0` = How are bundled language files and translations loaded? = WPMMCC ships bundled language files in the plugin's `/languages` directory. * If you set a plugin locale override in **WPMMCC > Parameters**, WPMMCC first tries to load the bundled `wpmmcc-.mo` file directly * If no override is set, WPMMCC uses the active WordPress locale and falls back to normal `load_plugin_textdomain()` behavior * This means packaged translations can work immediately after install, while external WordPress language packs remain compatible with the normal textdomain flow = Why can a provider test fail even when I entered credentials? = The most common causes are configuration prerequisites rather than a PHP error: * The provider service is not enabled on the vendor side yet, for example **Baidu AI Text Translate** or **Youdao Webpage Translation** * Your server cannot make outbound HTTPS requests to the provider API * The selected source/target language codes are not accepted by that provider * For LLM providers, the model record is incomplete and still misses API URL, API key, or model name = How are long HTML fields translated safely? = WPMMCC does not send a whole long post body blindly in one request. * Plain text is split on line, sentence, and word boundaries * HTML content is chunked with balanced-tag handling so fragments can be reassembled into valid markup * Fragments are sent in order and merged back in order * If a provider returns fewer fragments than expected, WPMMCC keeps the field aligned by falling back to the original fragment where necessary = Can I use this with WordPress Multisite? = Yes. WPMMCC supports two multisite configurations: * **Directory mode**: Single WordPress install, language directories (example.com/en/, example.com/zh/). No Multisite needed. * **Multisite mode**: Each language is a separate site in the network. WPMMCC links them through site groups. = How does directory mode work? = In directory mode, WPMMCC creates "shadow" posts for each translated language. When a visitor goes to `/zh/my-post/`, WordPress serves the shadow post's translated content. Hreflang and canonical tags are injected automatically. Your original content remains untouched. = Does it work with my SEO plugin? = Yes. WPMMCC is tested with Yoast SEO and Rank Math. You can disable WPMMCC's own canonical and hreflang output from **WPMMCC > Parameters** if you prefer your SEO plugin to handle those tags. The SEO Fields screen lets you translate Yoast/Rank Math meta fields alongside post content. = Which WordPress and PHP versions are supported? = WPMMCC requires **WordPress 5.3+** and **PHP 7.2+**. The current release is tested up to **WordPress 6.9**. It supports both standard single-site installations and WordPress Multisite networks. = Which versions of Yoast SEO or Rank Math are supported? = WPMMCC integrates with Yoast SEO and Rank Math at the metadata and frontend output level, but this readme does not promise a strict per-version compatibility matrix for those third-party plugins. Instead, WPMMCC provides an SEO field scanner so supported meta fields can be discovered and translated even as SEO plugin internals evolve. = How does the task queue work? = Translation jobs are processed in the background via WordPress Action Scheduler (a bundled copy with prefixed table names, so it does not conflict with WooCommerce's copy). Each page load triggers a queue check. You can also run tasks manually or adjust batch size and concurrency from the **Task settings** tab under **WPMMCC > Tasks**. = What shortcodes are available? = Six shortcodes are included: * `[wpmmcc_ml_current_language]` — current language code (e.g. `ZH-CN`) * `[wpmmcc_ml_site_group_type]` — group type string (`directory` or `multisite`) * `[wpmmcc_ml_language_switcher]` — language switcher `