GH#162: docs: document gratis ai translations server

docs/addons/gratis-ai-translations-server/index.mdx

@@ -0,0 +1,43 @@
+---
+title: "Gratis AI Translations Server"
+sidebar_position: 1
+---
+
+# Gratis AI Translations Server
+
+Gratis AI Translations Server provides the server-side translation queue used to build addon, plugin, and theme language packages for Ultimate Multisite environments.
+
+The server combines GlotPress project management, imported human translations, and Superdav AI Service gap-filling so sites can request translated packages without translating every string locally.
+
+## Requirements
+
+- WordPress with the Gratis AI Translations Server plugin installed and active.
+- **GlotPress** installed and configured, because the server stores projects, originals, and translation sets in GlotPress.
+- Superdav AI Service credentials configured when AI gap-filling should process untranslated strings.
+- Traduttore package support for building downloadable language packages.
+
+## Translation flow
+
+1. A client site requests translation coverage for a plugin, theme, locale, or batch of packages.
+2. The server creates or updates the matching GlotPress project metadata.
+3. Existing human translations are imported first, including available translations from translate.wordpress.org when the package source is WordPress.org.
+4. Any remaining untranslated strings are queued for Superdav AI Service translation.
+5. An administrator manually approves queued jobs before processing starts.
+6. Completed translations are written back to GlotPress and packaged for download.
+
+Human translations remain the preferred source. AI is used to fill gaps after the import step, which keeps community-reviewed translations intact while still making packages available for languages that are incomplete upstream.
+
+## Basic setup
+
+1. Install and activate GlotPress.
+2. Install and activate Gratis AI Translations Server.
+3. Configure the Superdav AI Service connection if AI translation jobs should run.
+4. Confirm that WordPress.org and premium package sources are identified correctly in the queue.
+5. Review pending translation jobs and approve the jobs that should be processed.
+6. Download completed language packages from the server once package generation finishes.
+
+## Package delivery
+
+The server builds translated packages after translations complete. Packages may contain imported human-only translations, AI gap-filled translations, or fallback POT/PO imports depending on what source material was available for the requested locale.
+
+Client sites can check translation status before downloading packages. Completed packages are served from the server domain and can be installed by the requesting site when the status flow reports that the translation is ready.

docs/developer/rest-api/overview.md

@@ -242,6 +242,73 @@ Typical migration status responses include:
 
 Treat `ready: false` as a pre-launch blocker. Check the verification details, fix the database host binding, queue, user provisioning, or routing issue, then retry verification.
 
+## Translation Status Endpoints
+
+Gratis AI Translations Server 1.3.0 adds status endpoints for client sites that request server-built language packages backed by GlotPress and the Superdav AI Service.
+
+Use the status endpoints before attempting a package download. A client should expect the server to import human translations first, queue AI gap-filling for untranslated strings, wait for manual approval, and then mark the package ready when generation finishes.
+
+### Check a single translation package
+
+```http
+GET /wu/v2/translations/check?slug={plugin_or_theme_slug}&type={plugin|theme}&locale={locale}
+```
+
+Typical responses report the package identity, current status, remaining strings, total strings, and download information when the package is ready:
+
+```json
+{
+    "slug": "example-plugin",
+    "type": "plugin",
+    "locale": "fr_FR",
+    "status": "ready",
+    "source": "wp.org",
+    "remaining_strings": 0,
+    "total_strings": 342,
+    "download_url": "https://example.com/path/to/package.zip"
+}
+```
+
+### Check multiple translation packages
+
+Use the batch translation-check endpoint when a client needs status for several plugins, themes, or locales in one request.
+
+```http
+POST /wu/v2/translations/check/batch
+Content-Type: application/json
+
+{
+    "packages": [
+        {
+            "slug": "example-plugin",
+            "type": "plugin",
+            "locale": "fr_FR"
+        },
+        {
+            "slug": "example-theme",
+            "type": "theme",
+            "locale": "de_DE"
+        }
+    ]
+}
+```
+
+The response returns one status object per requested package. Clients should handle mixed results because one package can be ready while another is still pending approval or processing.
+
+### Expected status flow
+
+| Status | Meaning |
+|---|---|
+| `missing` | The server has not seen this package/locale request yet, or the request could not be matched to a GlotPress project. |
+| `pending_approval` | Human translations and source strings have been prepared, but an administrator must approve the job before processing. |
+| `importing` | The server is importing available human translations, including translate.wordpress.org translations for WordPress.org packages. |
+| `processing` | Remaining untranslated strings are being translated through the Superdav AI Service. |
+| `packaging` | Translations are complete and the server is building the downloadable package. |
+| `ready` | The translated package is available for download. |
+| `failed` | The job failed validation, translation, or package generation. Inspect server logs and queue details before retrying. |
+
+Superdav-backed jobs should not be treated as failed while they are pending approval, importing, processing, or packaging. Poll with backoff and download only when the endpoint reports `ready` with a `download_url`.
+
 ## Error Responses
 
 ```json

docs/user-guide/administration/settings-reference.md

@@ -44,3 +44,16 @@ AI provider connector settings now expose only the supported OAuth account pools
 Cursor Pro is no longer a supported provider. Remove old internal screenshots, runbooks, or onboarding steps that mention Cursor Pro setup fields or connector paths.
 
 When adding or removing provider accounts, enter a valid email address for the account being refreshed or deleted and save the provider settings before testing connector-backed operations.
+
+## Gratis AI Translations Server queue controls
+
+Gratis AI Translations Server exposes queue controls and status context for administrators who manage server-side plugin and theme translation jobs.
+
+| Control or status | Description |
+|---|---|
+| **Delete All Pending** | Removes all jobs that are still pending approval or processing. Use it when the queue contains obsolete requests, test batches, or jobs that should be recreated with updated source data. Completed packages are not the target of this cleanup action. |
+| **Source badges** | Identifies whether each queued package came from WordPress.org or a premium/private source. WordPress.org jobs can import available community translations before AI gap-filling; premium jobs depend on the uploaded or detected package strings. |
+| **Remaining/total string counts** | Shows how many strings still need translation compared with the total string count for the package and locale. Use this to estimate the amount of AI work left after human translations are imported. |
+| **Completed today** | Reports recent queue health by showing how many jobs completed during the current day. A non-zero count confirms that recurring processing is active; a stale value can indicate a cron, approval, or service-connection issue. |
+
+Translation jobs require manual approval before the queue processes them. Review source badges and string counts before approving a batch so WordPress.org packages can benefit from imported human translations and only the remaining gaps are sent for AI translation.

docs/user-guide/localization/translating.md

@@ -32,6 +32,22 @@ Addon plugins are translated separately at:
 
 The addon translations are currently AI-generated as a starting point. They cover all supported languages but may contain awkward phrasing or inaccuracies. We welcome human translators to review and suggest improvements to make them more natural and accurate.
 
+## Server-Side Translation Packages
+
+Gratis AI Translations Server can prepare translated plugin and theme packages from a central translation server instead of requiring every client site to translate strings locally.
+
+The server-side workflow uses this order:
+
+1. Import available human translations first, including approved translations from translate.wordpress.org for WordPress.org packages.
+2. Identify strings that are still untranslated after the human import.
+3. Queue only those remaining gaps for AI translation through the Superdav AI Service.
+4. Require an administrator to manually approve queued jobs before processing.
+5. Build and publish the translated package when the import and AI gap-filling steps finish.
+
+This means community and other human translations are preserved whenever they exist. AI translation is used as a fallback for missing strings, and administrators keep control over when queued jobs are allowed to run.
+
+When a package is complete, the requesting site can check its translation status and download the translated language package from the server.
+
 ## Local Translations
 
 If you prefer to create translations locally for your own project rather than contributing upstream, there are two options:

sidebars.js

@@ -282,6 +282,11 @@ const sidebars = {
       label: 'Gratis AI Agent',
       items: [{type: 'autogenerated', dirName: 'addons/gratis-ai-agent'}],
     },
+    {
+      type: 'category',
+      label: 'Gratis AI Translations Server',
+      items: [{type: 'autogenerated', dirName: 'addons/gratis-ai-translations-server'}],
+    },
     {
       type: 'category',
       label: 'Superdav AI Agent',