IBX-10684: Document translation management

docs/api/event_reference/event_reference.md

@@ -37,6 +37,7 @@ For example, copying a content item is connected with two events: `BeforeCopyCon
     "api/event_reference/segmentation_events",
     "api/event_reference/site_events",
     "api/event_reference/taxonomy_events",
+    "api/event_reference/translations_management_events",
     "api/event_reference/trash_events",
     "api/event_reference/twig_component_events",
     "api/event_reference/url_events",

docs/api/event_reference/translations_management_events.md

@@ -0,0 +1,29 @@
+---
+description: Events that are triggered when working with taxonomy.
+edition: lts-update
+page_type: reference
+---
+
+# Translations management events
+
+The [Translations management](configure_translations_management.md) package dispatches events at two levels.
+
+## Translation events
+
+Translation events are thrown once per field value per translation operation.
+They are used for logging, analytics, and observability.
+Both events are read-only, you can't use them to override the translation result.
+
+| Event | Dispatched by | Dispatched when | Properties | 
+|---|---|---|----|
+[`BeforeTranslateEvent`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-TranslationsManagement-AutoTranslate-Event-BeforeTranslateEvent.html) | `TranslationService` | Before a translation request is sent to the provider | `TranslationProviderInterface $provider`</br>`string $text`</br>`string $sourceLanguage`</br>`string $targetLanguage` |
+| [`TranslateEvent`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-TranslationsManagement-AutoTranslate-Event-TranslateEvent.html) | `TranslationService` | After a translation response is received | `string $result`</br>`TranslationProviderInterface $provider`</br>`string $text`</br>`string $sourceLanguage`</br>`string $targetLanguage` |
+
+## Side-by-side creation events
+
+Side-by-side creation events are dispatched when a new translation draft is being prepared.
+
+| Event | Dispatched by | Dispatched when | Properties |
+|---|---|---|---|
+| [`OnContentSideBySideTranslationCreateEvent`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-TranslationsManagement-SideBySide-Event-OnContentSideBySideTranslationCreateEvent.html) | `SideBySideTranslationService` | When a draft side-by-side translation of a content item is being created | `Request $request`</br>`Content $sourceContent`</br>`string $sourceLanguageCode`</br>`string $targetLanguageCode`</br>`?Content $targetDraft` |
+| [`OnProductSideBySideTranslationCreateEvent`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-TranslationsManagement-SideBySide-Event-OnProductSideBySideTranslationCreateEvent.html) | `SideBySideTranslationService` | When a draft side-by-side translation of a product is being created | `Request $request`</br>`ContentAwareProductInterface $sourceProduct`</br>`ContentAwareProductInterface $targetProduct`</br>`string $sourceLanguageCode`</br>`string $targetLanguageCode`</br>`?ProductUpdateData $productUpdateData` |

docs/ibexa_products/editions.md

@@ -71,3 +71,4 @@ The features brought by LTS Updates become standard parts of the next LTS releas
 | [Integrated help](integrated_help.md) | ✔ | ✔ | ✔ |
 | [MCP servers](mcp_guide.md) | ✔ | ✔ | ✔ |
 | [Shopping list](shopping_list_guide.md) |  |  | ✔ |
+| [Translations management](translations_management_guide.md) | ✔ | ✔ | ✔ |

docs/multisite/img/diagram_source/translations_management_flow.drawio

@@ -0,0 +1 @@
+<mxfile host="Electron" modified="2026-06-16T10:51:05.860Z" agent="5.0 (Macintosh; Intel Mac OS X 26_3_1) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/14.6.13 Chrome/89.0.4389.128 Electron/12.0.7 Safari/537.36" etag="j-W4lXxHCJBOFpcNCibg" version="14.6.13" type="device"><diagram id="1kQWOgmGZ1G1xJNYzsRM" name="Page-1">5Zptc6M2EIB/DTPtB2d4MRh/tB3Hcc5pPfW0l/uUkUEG9WTkCuGX+/WVQNiAyJn0iJ1cZzxjWEmw++xqWQk0a7TeTyjYhI/Eh1gzdX+vWbeaaRqGaWrip/sHKbFtJ5MEFPlSdhIs0DcohbqUJsiHcakjIwQztCkLPRJF0GMlGaCU7MrdVgSX77oBAVQECw9gVfoZ+SzMDdP1U8M9REEob+3asmEN8s5SEIfAJ7uCyBpr1ogSwrKj9X4EsaCXc8nG3b3QelSMwog1GTDIBmwBTqRtA3+NIqEZZDH/SzYCLgVRjAFDRLRsKNly/jSWJrBDzoWSJPKhuLShWcNdiBhcbIAnWnc8FLgsZGssm1cI4xHBhKZjLR9Ad+Vxecwo+QoLLY7nwuWKt6jGSXu3kDK4L4iksRNI1pDRA+8iW007GyEjr2PkIbUr+NGVsrDgQkfKgAyd4HjpE11+IAHXwx4qsMc+YtxMU6fwnwTGKfEI7qrI28RsQ9fv1mF2zaXlOC1h7l+T80jh/AeMCd7CuBC9mulgfs/hUhwF4ugXDKIg4VO3swFIOEXckM+AWHTm8wHzVMLd8Wur/litVqZXG/a+s3TslvxhdPWKP1R3HHNS0R29Ftxxp4b9noe3l0Z7HudgyWnyVIwg9ttNLJchXEks/QuG+0Thu4CRn8IlLybvj4i4fz3G9zUpxYMoSyk5YU5PIKUoCj5iCBvlHGFahpoj9DfiO1X4jijkRFO8gAaQdfLsLApHClbsAxI23Ssifvhe9bFFcBenj7zqUxFEIqrXxEc8N6fuCOGHr0+MbjmVWOYFHfFJzddgC7OLvkVsXwhpObS7NUQNu4ao3QLRmUo05LbE6e353fMIb/mxdyGwPfs82d4bkX1UyM6TJUZxCFte/V0EpeU0CNK6MrgNlLBmcS5FMUmol6+/M1H20NOK6xnol3YlVCspFAl5W96k+CGVzUYqD9+TylYjlUeqyndtq5wOHVAKDoUOG4IiFheuPBeC4jqiPNtdvWJ9dsETi6NmzfB0G+G5U/FMruZRW8lB2sjUBr1GlrSudr3bjlt/x8qukjEylHLUyfjXhofllsPD6Ff2987oVen/4/HkNPLCvRpP06vFU7PAmaoqP7yLDGFVFhF57dqaS91GfB5UPp+u5tL+f1V5djWV83r59To/XktnFPT8ER3iu0n09LsxGuyecNLJi7BCdq4WhnEINuLQSyg+DCnwvgpTzlWI5XJyhdHmXh5r9WVfDcsXK0G7slzpHMu+0gpQUyrBrtlCKVgL0vopQFp63Upa5Wj0+m/EsatwnM/+nEx/U2i+ClsbqKwyKkeNuNrFRxt7DrWkHIXUYno77gy/dMQ/b/lrOv787rDxRdyNfWVy7vm5KmxGHsAzsIR4TmKUbpVZt0vCGFlzNHmHAUaBaGCkQjKf7et9IN6j3yxBjLyb7nNaIDzH/JHwzLEN0/fq+o3bDu3jZD2+m3cU1k4N6jZeFNWi7v9/UNckhLqofrMnUJ7KC2hFkbGQp4SykAQkAnh8khbmu87PTn1mREBO6f4NGTvIrzhAwkiZPdwj9pRyteXZl0LL7V5eOT05FE7mkCJuN6RSptVVRWfrq+9N72LR9XK/qxVeDSqvn2RmHLfi258Z/PT0tU22Wjp9tGSN/wU=</diagram></mxfile>

docs/multisite/translations_management/translations_management_guide.md

@@ -0,0 +1,89 @@
+---
+description: Translations management helps managers, developers and localization teams with multilingual content delivery.
+edition: lts-update
+month_change: true
+---
+
+# Translations management product guide
+
+## What is Translations management
+
+Content managers, translators and proofreaders who work with multilingual content in [[= product_name =]] often face a common set of challenges:
+
+- context is lost when the source text isn't visible alongside the translation
+- translation of long and complex content items is time consuming
+- quality assurance is slow and error-prone without a direct comparison view
+- switching between tools or tabs to cross-reference languages disrupts focus and slows down publishing
+
+Translations management package addresses these pain points through a side-by-side view, machine translation and ability to invite reviewers to collaborate on content item or product translation.
+
+The package integrates with the [AI Actions framework](ai_actions.md) to support machine translation providers such as Google Translate and DeepL, and AI powered translation services like OpenAI, Anthropic, and Google Gemini.
+
+Administrators can manage providers and configure default provider-to-language-pair mappings directly in [[= product_name =]]'s user interface, while editors can trigger machine translation from the content editing interface.
+
+!!! note
+
+    Translations management is a standalone set of features.
+    Although some views are similar to those delivered by the [Automated translations](automated_translations.md) opt-in package, Translations management does not require the `ibexa/automated-translation` package to run.
+    These two packages use different namespaces, service tags, and provider interfaces.
+
+## Availability
+
+Translations management is an [LTS Update](editions.md#lts-updates) available in all [[= product_name =]] editions.
+
+## How it works
+
+Before the translation flow can happen, an administrator sets up the translation providers and assigns language pairs to them.
+Then, when an editor opens a content item and requests a new machine translation, the plugin resolves which provider to use.
+It falls back from a language-pair rule to the user's manual selection if necessary.
+The plugin then extracts the translatable fields from the source language version of a content item and sends them to the configured provider's API.
+The translated strings are written into a target-language draft version of a content item, which opens in a side-by-side view for the editor to review and refine.
+The editor can save the result as draft, share it with a reviewer or publish it.
+
+![Translations management flow](translations_management_flow.png "Translations management flow")
+
+## Capabilities
+
+### Translation provider management
+
+Administrators can manage translation providers and configure [language pair defaults](configure_translations_management.md#manage-language-pairs).
+This way they can define which provider handles which language combination.
+Editors see the configured default pre-selected when creating a new translation, but can override the selection if needed.
+
+Translations management supports several built-in translation providers, for example Google Translate, which is accessed through its REST API, or OpenAI, accessed through AI Actions.
+
+### Side-by-side translation view
+
+Translations management introduces a [side-by-side translation view]([[= user_doc =]]/content_management/translate_content/#side-by-side-translation-view) that displays the source language read-only next to an editable target language form.
+In this view, editors can provide and review translations in context, without having to leave the content editing interface.
+
+![Side-by-side translation view](managing_translations_sxs_view.png "Side-by-side translation view")
+
+Editors can:
+
+- access the side-by-side view when creating a new translation, reviewing an existing one, or editing a draft
+- compare source and target content field by field while editing
+- copy all content from the source column to the target column with a single action
+- provide localized versions of media assets
+- use the distraction-free mode for focused editing of individual fields, with AI actions available inline
+- choose whether the source column appears on the left or right in user settings
+
+!!! note "Excluded content types"
+
+    Content types that are editable in Page builder or Form builder are excluded from side-by-side editing.
+
+    Products are editable in the side-by-side view, but product attributes are not translatable.
+
+### CLI translation
+
+Translations management package exposes a [console command](configure_translations_management.md#translate-content-items-with-cli) for translating content items from the command line,
+useful for batch processing or CI/CD workflows.
+
+### Extensibility
+
+Developers can [extend the translations management](extend_translations_management.md) package:
+
+- create custom translation providers
+- add support for custom fields
+- add custom content type exclusion rules
+- tap into the translation lifecycle with [events](translations_management_events.md)

mkdocs.yml

@@ -105,6 +105,7 @@ nav:
             - Discounts events: api/event_reference/discounts_events.md
             - Collaboration events: api/event_reference/collaboration_events.md
             - Integrated help events: api/event_reference/integrated_help_events.md
+            - Translations management events: api/event_reference/translations_management_events.md
             - Other events: api/event_reference/other_events.md
         - Notification channels: api/notification_channels.md
     - Administration:
@@ -479,6 +480,11 @@ nav:
             - Language API: multisite/languages/language_api.md
             - Back office translations: multisite/languages/back_office_translations.md
             - Automated content translation: multisite/languages/automated_translations.md
+            - Translations management:
+                - Translations management: multisite/translations_management/translations_management.md
+                - Translations management product guide: multisite/translations_management/translations_management_guide.md
+                - Configure translations management: multisite/translations_management/configure_translations_management.md
+                - Extend translations management: multisite/translations_management/extend_translations_management.md
     - Permissions:
         - Permissions: permissions/permissions.md
         - Permission overview: permissions/permission_overview.md