=== AI Translator (by ROBOTSTXT) ===
Contributors: robotstxt, javiercasares
Tags: ai, translation, multilingual, multisite, editor
Requires at least: 7.0
Tested up to: 7.0
Requires PHP: 7.4
Requires Plugins: ai
Stable tag: 1.0.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.
* PHP 7.4 or higher.
* The official WordPress AI plugin (https://wordpress.org/plugins/ai/) installed, active, and configured with valid provider credentials.

= 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 is delegated to the official WordPress AI plugin, which handles authentication, model selection, and provider routing. This plugin does not store API keys.

= 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
* PHP: 7.4 - 8.5
* WP-CLI: 2.10 or newer

== Changelog ==

= 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/)