=== LinguaRank AI ===
Contributors: irbiscss
Tags: translation, multilingual, polylang, ai, seo
Requires at least: 7.0
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.2.2
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Translate Polylang posts, Gutenberg and Elementor content, ACF fields, and SEO metadata with WordPress AI Client or a supported AI provider.

== Description ==

LinguaRank AI helps WordPress administrators create translated versions of posts, pages, and supported public post types.

The plugin is made for sites that already use Polylang. Choose a source item, select the target languages, and start the translation. LinguaRank AI creates a separate WordPress item for each language and connects it to the original through Polylang.

The source can be written in any language configured in Polylang. It does not have to be Ukrainian, Russian, English, or Polish.

LinguaRank AI works only in the WordPress admin area. It does not add a public language switcher or change the language buttons on your site. Polylang remains responsible for front-end language switching and language relationships.

= What can be translated =

* Post titles, excerpts, and readable text inside Gutenberg blocks.
* Elementor pages, standard and third-party widgets, repeaters, nested containers, Atomic widgets, and referenced saved templates.
* URL slugs and supported SEO titles, descriptions, keywords, and social fields.
* Selected categories, tags, reusable blocks, internal links, and text-based custom fields.
* ACF blocks and ACF field groups, including text, textarea, WYSIWYG, repeater, group, flexible content, and link labels.
* Registered Polylang strings when they are available in the current WordPress setup.
* WooCommerce product text, safe product data, attributes, and variation descriptions when WooCommerce support is enabled.

The plugin recognizes Yoast SEO fields and common metadata used by Rank Math, AIOSEO, SEOPress, and UAS SEO. Unsupported technical values, IDs, layout settings, and binary data are left unchanged.

= One click for large pages =

Large Gutenberg and Elementor pages are split into smaller translation batches. The plugin processes those batches in sequence, checks the document structure, and saves the completed language version as one translation job. You do not need to click the translation button for every part of the page.

Progress and the current stage are shown in the editor and in the LinguaRank AI dashboard.

= Large sites and existing translations =

The dashboard loads a limited, paginated set of source items and provides server-side search, so existing sites with hundreds or thousands of posts do not need to load every item at once. Bulk translations are processed sequentially. Background jobs use a shared worker lock and short cooldown to avoid launching many provider requests at the same time.

Maintenance work, such as marking completed translations for review after glossary changes, runs in small batches. Existing Polylang translations are left in place unless an administrator explicitly translates or clears the related source item.

= AI providers =

WordPress AI Client is the recommended option on WordPress 7.0 and newer. It uses the provider configured under WordPress Settings > Connectors, so LinguaRank AI does not need to store that provider's key.

OpenAI and Google are configured through WordPress Settings > Connectors. DeepSeek and OpenRouter can be added in LinguaRank AI as optional direct backups. An administrator can also enable an OpenAI-compatible endpoint such as Ollama running on the web server or a trusted LiteLLM gateway. The first provider and fallback behavior can be selected in the plugin settings.

= Translation tools =

* A language-aware structured glossary for required translations and protected names, abbreviations, legal terms, and project-specific wording, including CSV import/export.
* Translation memory for repeated text fragments.
* A queue for translating several items one after another.
* A preflight estimate for approximate tokens, request count, and optional provider cost.
* Quality checks and a deterministic score for structure, SEO fields, slugs, completeness, and glossary compliance.
* Review statuses, reviewer assignments, and snapshots before an existing generated translation is replaced.
* Automatic locks that protect manually edited translations from an accidental AI overwrite.
* A local Elementor compatibility report and an adapter API for unusual third-party widgets.
* A redacted diagnostics export for support without exposing API keys or glossary text.
* A Clear Translations action that removes generated translations without deleting the source item.

Images are reused instead of duplicated. Text stored in image alt text or captions can be translated, but LinguaRank AI does not edit text that is part of the image itself.

For ACF content, LinguaRank AI translates reader-facing text and preserves field references, row order, layouts, URLs, media IDs, relationship values, and other technical data. ACF is optional and is not bundled with this plugin.

AI translation can contain mistakes. Review important legal, financial, medical, or business content before publishing or relying on it.

== Requirements ==

* WordPress 7.0 or newer.
* PHP 7.4 or newer.
* Polylang installed and configured with the required languages.
* A configured WordPress AI Client connector, a DeepSeek/OpenRouter backup key, or an enabled OpenAI-compatible endpoint.

Yoast SEO and other recognized SEO fields are optional. The translation workflow still works when an SEO plugin is not installed.

== External Services ==

LinguaRank AI does not run its own translation service. When an administrator starts a translation or enables automatic translation, the plugin sends the required text to the configured AI provider.

Depending on the selected settings, the request may include post content, titles, excerpts, selected SEO metadata, taxonomy or custom-field text, glossary instructions, and the target language. Images and other binary files are not sent for translation.

Requests can be sent through the provider selected in WordPress AI Client, or directly to the optional DeepSeek and OpenRouter backups. Common WordPress AI Client connectors include OpenAI and Google Gemini:

* OpenAI: https://openai.com/policies/terms-of-use/ and https://openai.com/policies/privacy-policy/
* Google Gemini: https://ai.google.dev/terms and https://policies.google.com/privacy
* DeepSeek: https://cdn.deepseek.com/policies/en-US/deepseek-terms-of-use.html and https://cdn.deepseek.com/policies/en-US/deepseek-privacy-policy.html
* OpenRouter: https://openrouter.ai/terms and https://openrouter.ai/privacy

An administrator may enter a custom OpenAI-compatible Chat Completions endpoint. Public endpoints must use HTTPS. Plain HTTP is accepted only for loopback addresses on the WordPress server (`localhost`, `127.0.0.1`, or `::1`). The custom service receives the same selected text and translation instructions described above. Its operator's terms and privacy policy apply. A local Ollama address refers to the server that runs WordPress, not automatically to the administrator's personal computer.

No translation request is sent until an administrator configures a provider and starts a translation or enables automatic translation. LinguaRank AI does not load remote JavaScript, CSS, tracking pixels, advertisements, license checks, or plugin updates from these providers.

Direct DeepSeek, OpenRouter, and optional custom-provider keys are stored in the current WordPress database and are excluded from settings exports and diagnostics. When OpenSSL is available, saved keys are encrypted before storage. OpenAI and Google keys remain under WordPress Settings > Connectors and are not stored by LinguaRank AI.

== Installation ==

1. Install and configure Polylang.
2. Add the languages you want to use in Polylang.
3. Install and activate LinguaRank AI.
4. Open LinguaRank AI in the WordPress admin menu.
5. Configure WordPress AI Client or add a direct provider API key.
6. Choose the target languages and content types, then save the settings.
7. Open a post or page and click the translation button, or use Quick Translate in the plugin dashboard.

== Frequently Asked Questions ==

= Does the source need to use a specific language? =

No. Any language configured in Polylang can be the source language. The source language is skipped when target translations are created.

= Does the plugin work without Polylang? =

No. Polylang provides the language definitions and connects the translated WordPress items.

= Can it translate a long Gutenberg landing page? =

Yes. Long pages are processed in smaller batches during one translation job. Gutenberg comments, block names, nesting, classes, IDs, links, and layout data are preserved and checked before saving.

= Can I use it on a site with hundreds of existing posts? =

Yes. The dashboard uses pagination and server-side search, bulk work runs sequentially, and maintenance tasks are split into bounded batches. For reliable unattended processing, make sure WP-Cron is enabled or triggered by a real server cron job.

= Does it translate ACF blocks and fields? =

Yes. When ACF is active, LinguaRank AI detects supported field types and translates reader-facing values in ACF blocks and post fields. Repeaters, groups, flexible content rows, and link labels are supported. URLs, images, files, IDs, field keys, layout names, and relationship values are preserved.

= Does it translate Elementor pages? =

Yes. LinguaRank AI translates reader-facing controls in standard and registered third-party Elementor widgets, repeaters, nested containers, Atomic widgets, and referenced saved templates. It validates the complete Elementor JSON document before saving and preserves element IDs, layout, responsive settings, CSS, links, media references, and dynamic tags.

Unusual third-party widgets can register a small adapter through `LinguaRank_AI_Elementor::register_adapter()`. The Compatibility screen lists registered widgets and the reader-facing controls detected locally.

= Does it translate WooCommerce products? =

Yes, when WooCommerce support is enabled. LinguaRank AI copies safe pricing and product configuration, translates product text, purchase notes, custom attributes, and variation descriptions, and maps translated taxonomy attributes where Polylang provides translated terms. Product images are reused and SKUs are not duplicated.

= How are manual edits protected? =

LinguaRank AI records a fingerprint after generation. When a person edits the generated translation, the plugin locks that language version and refuses to overwrite it until an authorized reviewer explicitly allows AI overwrite.

= Will it change or duplicate my images? =

No. Translated pages reuse the original media files. You can replace an image manually if it contains language-specific text.

= Is the glossary actually used? =

Yes. The built-in glossary, selected preset, and custom rules are included in translation prompts for Gutenberg, Elementor, titles, excerpts, supported SEO fields, and selected custom fields. Exact preservation rules written as `Term = Term`, plus ESW/E-SW, are also protected with temporary placeholders and restored after translation.

= What does Clear Translations remove? =

It deletes translated posts or pages generated for the selected source item and clears their LinguaRank AI status data. It does not delete the source item.

= Where are direct API keys stored? =

They are stored in the current WordPress database and are never included in the plugin files or settings export. Leaving a saved key field empty does not erase the existing key.

== Privacy ==

Translation requires sending selected site text to the AI provider chosen by the administrator. The provider's terms, privacy policy, account settings, and billing rules apply to that request.

LinguaRank AI does not collect analytics, create an external LinguaRank account, or send data to a separate service operated by the plugin author.

== Third-party assets ==

The Manrope font is bundled locally for the LinguaRank AI admin interface. Copyright 2018 The Manrope Project Authors. Manrope is licensed under the SIL Open Font License 1.1; the full license is included at `assets/fonts/OFL.txt`. No font is loaded from a remote service.

== Changelog ==

= 1.2.2 =
* Reorganized Settings into five focused sections with persistent navigation, change tracking, and responsive layouts.
* Replaced the overview status-card grid with compact Connections and Translation summaries.
* Added direct overview links to provider settings and translated materials.
* Completed English, Russian, and Ukrainian labels for the refreshed interface.

= 1.2.1 =
* Added a cohesive admin design system based on the refreshed LinguaRank workspace concept.
* Unified navigation, panels, cards, tables, forms, status badges, and responsive layouts across every plugin section.
* Added a compact version badge and AI connection status to the product header.
* Refined section spacing and kept help tooltips in normal sentence case for easier reading.

= 1.2.0 =
* Split translation, provider, content-adapter, and admin responsibilities into smaller internal modules.
* Added a language-aware structured glossary with preserve/required-translation rules and CSV import/export.
* Added preflight token/request/cost estimates and configurable pricing rates.
* Added manual-edit protection, reviewer assignments, reviewer access, and deterministic QA scores.
* Added WooCommerce product and variation synchronization with safe SKU and taxonomy handling.
* Added an Elementor adapter API and a lazily loaded local widget compatibility matrix.
* Added a redacted support diagnostics export.
* Added an optional secured OpenAI-compatible provider for server-local Ollama or trusted LiteLLM gateways.

= 1.1.3 =
* Added progressive Elementor translation for standard and third-party widgets, repeaters, nested containers, Atomic widgets, and referenced saved templates.
* Added strict Elementor document validation, template ID remapping, source-change detection, cache regeneration, and snapshot restoration.
* Fixed string fragment IDs in batched provider responses so Elementor text stays mapped to the correct controls.
* Hardened the Elementor fallback classifier to preserve layout, responsive, CSS, link, media, and technical settings.
* Added deterministic protection for ESW/E-SW and exact `Term = Term` glossary rules.
* Improved language catalog flag and checkbox sizing and alignment.

= 1.1.2 =
* Added the locally bundled Manrope variable font for the admin interface without remote font requests.
* Added paginated material browsing and server-side search for sites with hundreds or thousands of posts.
* Added a shared translation worker lock, cooldown, and bounded maintenance batches to prevent provider request bursts.
* Simplified provider setup around WordPress AI Client with optional DeepSeek and OpenRouter backups.
* Improved dynamic Polylang language detection, language cards, queue progress layout, help text, and translation catalog.

= 1.1.1 =
* Fixed translation of ACF blocks registered with custom namespaces such as theme/testimonial.
* Added reliable ACF block detection through the ACF registry and field-reference attributes.
* Improved fallback detection for testimonial roles, positions, quotes, notes, and other reader-facing fields.

= 1.1.0 =
* Added automatic translation for ACF blocks and ACF post fields.
* Added safe support for repeaters, groups, flexible content, WYSIWYG fields, and link labels.
* Preserved ACF field references, media, URLs, IDs, layout data, and other technical values.
* Fixed Gutenberg validation for block JSON that contains HTML from ACF WYSIWYG fields.

= 1.0.0 =
* Initial public release.
