=== AI Translator (by ROBOTSTXT) ===
Contributors: robotstxt, javiercasares
Tags: ai, translation, multilingual, multisite, editor
Requires at least: 7.0
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.2.0
License: GPL-3.0-or-later
License URI: https://www.gnu.org/licenses/gpl-3.0.txt

Translate post titles and content from the WordPress editor using the native WordPress AI plugin as backend. Multisite-ready.

== Description ==

AI Translator (by ROBOTSTXT) adds a one-click translation panel to the post editor. It reads the saved post title and content, sends them to the configured AI provider through the official WordPress AI plugin, and writes the translated text back into the editor for review.

The plugin is provider-agnostic: it relies on the WordPress AI plugin to route requests to whichever service the site administrator has configured (OpenAI, Anthropic, Google, etc.). No API keys are stored by this plugin.

Multisite is supported out of the box. When network-activated, the network administrator chooses between a single global configuration shared by every site, or per-site configuration where each subsite owns its own settings.

== Using the plugin ==

= Editor =

On the post edit screen, open the "AI Translator" panel (block editor sidebar or classic editor metabox). Select a target language from the dropdown and click "Translate". The plugin reads the saved version of the post, calls the configured AI provider, and replaces the title and/or content with the translated values. Review the result and save the post.

Only languages installed on the site (via Settings -> General -> Site Language, or the language pack installer) appear in the dropdown.

= WP-CLI =

The plugin exposes a single command, `wp ai-translator translate`, for single-post and bulk translation.

**Flags**

* `--locale=<locale>` (required): WordPress locale code to translate to. The locale must be installed on the site (visible via `wp language core list --status=installed`). The built-in `en_US` is always available.
* `--post-id=<id>` (optional): ID of a single post to translate. When set, `--post-type`, `--status` and `--limit` are ignored.
* `--post-type=<type>` (optional, default `post`): Post type to translate in bulk when `--post-id` is not provided.
* `--status=<status>` (optional, default `publish`): Post status filter in bulk mode.
* `--limit=<n>` (optional, default `50`): Maximum number of posts to process in bulk mode.
* `--dry-run` (optional): Report which posts would be translated **without calling the AI provider and without writing to the database**. Useful for previewing scope and verifying filters before incurring API costs.

The command respects the plugin's site settings (`Translate title` / `Translate content`). If both are disabled in the settings, the command exits with an error.

**Multisite**

Use the standard `--url=<site-url>` and `--path=<wordpress-root>` flags from WP-CLI to target a specific site in the network.

**User context**

Pass the standard WP-CLI global flag `--user=<id|login>` so that post updates are recorded under that user (revisions, audit logs). The command emits a warning when no user context is set.

**Examples**

Translate a single post to Spanish:

`wp ai-translator translate --post-id=42 --locale=es_ES`

Translate the latest ten pages to French, preview only:

`wp ai-translator translate --post-type=page --locale=fr_FR --limit=10 --dry-run`

Translate up to 200 product custom post types to Catalan on a Multisite subsite:

`wp ai-translator translate --post-type=product --locale=ca --limit=200 --url=https://example.com/ca/`

Bulk translate all draft posts (use with caution):

`wp ai-translator translate --post-type=post --status=draft --locale=de_DE --limit=500`

= REST API =

The plugin registers a single REST route in the `ai-translator/v1` namespace:

`POST /wp-json/ai-translator/v1/translate`

**Authentication**

Requires authenticated access to WordPress (cookie + `X-WP-Nonce` header for in-browser use, or Application Passwords for external clients) and the `edit_post` capability on the target post. Unauthorised requests receive `401` or `403` per `rest_authorization_required_code()`.

**Request body** (JSON)

* `post_id` (integer, required): ID of an existing post.
* `fields` (array of strings, required): Which fields to translate. Allowed values: `"title"`, `"content"`. Empty array or fields disabled in settings yield a `400`.
* `target_locale` (string, required): WordPress locale code. Must be installed on the site.

**Response** (200 OK, JSON)

Only includes the keys that were actually translated:

`{ "title": "...", "content": "..." }`

**Errors**

* `400` invalid input (missing post, unknown locale, no enabled fields).
* `403` insufficient capability.
* `404` post not found.
* `502` upstream AI provider error (forwarded from the WordPress AI plugin).

**Important**

The endpoint reads the **saved** title and content from the database, not from the editor's current state. Save the post before translating to ensure the latest content is used.

== Extra Configurations ==

`AI_TRANSLATOR_DELETE_DATA_ON_UNINSTALL` (boolean, default false): when set to `true` in wp-config.php, the uninstall routine removes every option, sitemeta entry, and per-site setting created by the plugin. By default, plugin data is preserved on uninstall.

== Installation ==

= Requirements =

* WordPress 7.0 or higher (the `wp_ai_client_prompt()` function is part of WordPress core since 7.0).
* PHP 7.4 or higher.
* At least one AI provider configured in Settings → AI. The plugin works with any provider registered through the WordPress AI client — no specific AI plugin is required.

= Manual download =

Extract the contents of the ZIP and upload the contents to the `/wp-content/plugins/robotstxt-ai-translator/` directory. Once uploaded, it will appear in your plugin list.

On Multisite, network-activate the plugin and configure it under Network Admin -> Settings -> AI Translator.

== Frequently Asked Questions ==

= Does this plugin call any AI provider directly? =

No. Every AI request goes through `wp_ai_client_prompt()`, WordPress's native AI client (introduced in WP 7.0). The plugin does not talk to any provider directly and does not store API keys. Authentication, model selection, and provider routing are handled by WordPress and whatever AI provider plugin you have configured.

= Does it work with the classic editor? =

Yes. The plugin registers a metabox in the classic editor and a sidebar panel in the block editor. Both share the same REST endpoint and language list.

= Why do I have to save the post before translating? =

The plugin reads the post title and content from the database, not from the editor's current state. This prevents prompt-injection through unsaved editor content. The UI warns you when there are unsaved changes.

== Compatibility ==

* WordPress: 7.0 - 7.1
* PHP: 7.4 - 8.5
* WP-CLI: 2.12 or newer

== Changelog ==

= 1.2.0 =

* Added configurable "Request timeout" setting (default 60 s, minimum 30 s, maximum 300 s) in site and network admin pages.
* Added parallel chunked content translation: long posts are split at Gutenberg block or paragraph boundaries and all chunks are sent to the AI concurrently, eliminating timeout errors on lengthy content.
* Added real-time progress indicator on the Translate button: "Translating… (2/5)" as each chunk resolves.
* Added new REST endpoint `POST /wp-json/ai-translator/v1/translate-text` for raw-text translation; used internally by the chunked content path.
* Changed: content translation now reads from the current editor state (unsaved changes included); title and excerpt continue to read from the saved post.

= 1.1.0 =

* Added excerpt field (`post_excerpt`) as a translatable field, with a dedicated settings toggle.
* Added MultilingualPress integration: when MLP creates a new connected post, the plugin automatically translates the enabled fields into the target site's language (opt-in, disabled by default).
* Removed `Requires Plugins: ai` header — `wp_ai_client_prompt()` is a native WordPress 7.0 function; the plugin now works with any AI provider configured through WordPress core.
* Admin notice now shows when no AI provider is configured for text generation (instead of checking for a function that always exists in WP 7.0+).

= 1.0.0 =

* Initial release. Translation panel for block and classic editors, REST endpoint, WP-CLI command, single-site and Multisite (global / per-site) configuration modes.

= Previous versions =

If you want to see the full changelog, visit the [changelog.txt](https://git.robotstxt.es/ROBOTSTXT/robotstxt-ai-translator/raw/branch/main/changelog.txt) file.

== Compliance ==

This plugin adheres to the following security measures and review protocols for each version:

* [WordPress Plugin Handbook](https://developer.wordpress.org/plugins/)
* [WordPress Plugin Security](https://developer.wordpress.org/plugins/wordpress-org/plugin-security/)
* [WordPress APIs Security](https://developer.wordpress.org/apis/security/)
* [WordPress Coding Standards](https://github.com/WordPress/WordPress-Coding-Standards)
* [Plugin Check (PCP)](https://wordpress.org/plugins/plugin-check/)