IBX-7912: Describe automated translation feature

[dabrt]

Question	Answer
JIRA Ticket	IBX-7912
Versions	master, 4.6
Edition	all

Add a description of the automated translation feature.

PHPStan is passing on 4.6 branch, it's failing because of the v5/Symfony 6 changes right now

Preview:

• https://ez-systems-developer-documentation--2414.com.readthedocs.build/en/2414/multisite/languages/automated_translations/

The PR is expanded to include changes from:

• Add eztext support automated-translation#18 (eztext is supported)
• IBX-7894: Added missing languages for DeepL and bumped API version to v2 automated-translation#15 (DeepL limitations are gone)

I've added examples how to:

• create a custom automated translation client
  • this example contains things that are left as an exercise for the reader (the whole AI Actions custom integration). Please let me know if it's clear enough when reading.
• create a custom Field Encoder/Decored (to support more field types)

Checklist

• Text renders correctly
• Text has been checked with vale
• Description metadata is up to date
• Added link to this PR in relevant JIRA ticket or code PR

[mnocon]

Looks good, thank you! One small remark about the special handling of landing pages

[adamwojs]

IMHO we can add full synopsis here

[dabrt]

@mnocon Please take over.

[github-actions]

Preview of modified Markdown:

• docs/multisite/languages/automated_translations.md

[julitafalcondusza]

Two small remarks.

[github-actions]

code_samples/ change report

Before (on target branch)	After (in current PR)
code_samples/multisite/automated_translation/config/services.yaml	code_samples/multisite/automated_translation/config/services.yaml
	docs/multisite/languages/automated_translations.md@104:``` yaml docs/multisite/languages/automated_translations.md@105:[[= include_file('code_samples/multisite/automated_translation/config/services.yaml', 15, 18) =]] docs/multisite/languages/automated_translations.md@106:``` 001⫶ App\AutomatedTranslation\AiClient: 002⫶ tags: 003⫶ - ibexa.automated_translation.client docs/multisite/languages/automated_translations.md@110:``` yaml docs/multisite/languages/automated_translations.md@111:[[= include_file('code_samples/multisite/automated_translation/config/services.yaml', 23, 32) =]] docs/multisite/languages/automated_translations.md@112:``` 001⫶ibexa_automated_translation: 002⫶ system: 003⫶ default: 004⫶ configurations: 005⫶ aiclient: 006⫶ languages: 007⫶ - 'en_GB' 008⫶ - 'fr_FR' docs/multisite/languages/automated_translations.md@141:``` yaml docs/multisite/languages/automated_translations.md@142:[[= include_file('code_samples/multisite/automated_translation/config/services.yaml', 19, 22) =]] docs/multisite/languages/automated_translations.md@143:``` 001⫶ App\AutomatedTranslation\ImageFieldEncoder: 002⫶ tags: 003⫶ - ibexa.automated_translation.field_encoder
code_samples/multisite/automated_translation/src/AutomatedTranslation/AiClient.php	code_samples/multisite/automated_translation/src/AutomatedTranslation/AiClient.php
	docs/multisite/languages/automated_translations.md@98:``` php hl_lines="35-52" docs/multisite/languages/automated_translations.md@99:[[= include_file('code_samples/multisite/automated_translation/src/AutomatedTranslation/AiClient.php') =]] docs/multisite/languages/automated_translations.md@100:``` 001⫶<?php declare(strict_types=1); 002⫶ 003⫶namespace App\AutomatedTranslation; 004⫶ 005⫶use Ibexa\AutomatedTranslation\Exception\ClientNotConfiguredException; 006⫶use Ibexa\Contracts\AutomatedTranslation\Client\ClientInterface; 007⫶use Ibexa\Contracts\ConnectorAi\Action\DataType\Text; 008⫶use Ibexa\Contracts\ConnectorAi\Action\RuntimeContext; 009⫶use Ibexa\Contracts\ConnectorAi\ActionConfigurationServiceInterface; 010⫶use Ibexa\Contracts\ConnectorAi\ActionServiceInterface; 011⫶ 012⫶final class AiClient implements ClientInterface 013⫶{ 014⫶ /** @var array<string> */ 015⫶ private array $supportedLanguages; 016⫶ 017⫶ private ActionServiceInterface $actionService; 018⫶ 019⫶ private ActionConfigurationServiceInterface $actionConfigurationService; 020⫶ 021⫶ public function __construct(ActionServiceInterface $actionService, ActionConfigurationServiceInterface $actionConfigurationService) 022⫶ { 023⫶ $this->actionService = $actionService; 024⫶ $this->actionConfigurationService = $actionConfigurationService; 025⫶ } 026⫶ 027⫶ public function setConfiguration(array $configuration): void 028⫶ { 029⫶ if (!array_key_exists('languages', $configuration)) { 030⫶ throw new ClientNotConfiguredException('List of supported languages is missing in the configuration under the "languages" key'); 031⫶ } 032⫶ $this->supportedLanguages = $configuration['languages']; 033⫶ } 034⫶ 035❇️ public function translate(string $payload, ?string $from, string $to): string 036❇️ { 037❇️ $action = new TranslateAction(new Text([$payload])); 038❇️ $action->setRuntimeContext( 039❇️ new RuntimeContext( 040❇️ [ 041❇️ 'from' => $from, 042❇️ 'to' => $to, 043❇️ ] 044❇️ ) 045❇️ ); 046❇️ $actionConfiguration = $this->actionConfigurationService->getActionConfiguration('translate'); 047❇️ $actionResponse = $this->actionService->execute($action, $actionConfiguration)->getOutput(); 048❇️ 049❇️ assert($actionResponse instanceof Text); 050❇️ 051❇️ return $actionResponse->getText(); 052❇️ } 053⫶ 054⫶ public function supportsLanguage(string $languageCode): bool 055⫶ { 056⫶ return in_array($languageCode, $this->supportedLanguages, true); 057⫶ } 058⫶ 059⫶ public function getServiceAlias(): string 060⫶ { 061⫶ return 'aiclient'; 062⫶ } 063⫶ 064⫶ public function getServiceFullName(): string 065⫶ { 066⫶ return 'Custom AI Automated Translation'; 067⫶ } 068⫶}
code_samples/multisite/automated_translation/src/AutomatedTranslation/ImageFieldEncoder.php	code_samples/multisite/automated_translation/src/AutomatedTranslation/ImageFieldEncoder.php
	docs/multisite/languages/automated_translations.md@128:``` php hl_lines="11-14 16-19 21-27 33-38" docs/multisite/languages/automated_translations.md@129:[[= include_file('code_samples/multisite/automated_translation/src/AutomatedTranslation/ImageFieldEncoder.php') =]] docs/multisite/languages/automated_translations.md@130:``` 001⫶<?php declare(strict_types=1); 002⫶ 003⫶namespace App\AutomatedTranslation; 004⫶ 005⫶use Ibexa\Contracts\AutomatedTranslation\Encoder\Field\FieldEncoderInterface; 006⫶use Ibexa\Contracts\Core\Repository\Values\Content\Field; 007⫶use Ibexa\Core\FieldType\Image\Value; 008⫶ 009⫶final class ImageFieldEncoder implements FieldEncoderInterface 010⫶{ 011❇️ public function canEncode(Field $field): bool 012❇️ { 013❇️ return $field->fieldTypeIdentifier === 'ezimage'; 014❇️ } 015⫶ 016❇️ public function canDecode(string $type): bool 017❇️ { 018❇️ return $type === 'ezimage'; 019❇️ } 020⫶ 021❇️ public function encode(Field $field): string 022❇️ { 023❇️ /** @var \Ibexa\Core\FieldType\Image\Value $value */ 024❇️ $value = $field->getValue(); 025❇️ 026❇️ return $value->alternativeText ?? ''; 027❇️ } 028⫶ 029⫶ /** 030⫶ * @param string $value 031⫶ * @param \Ibexa\Core\FieldType\Image\Value $previousFieldValue 032⫶ */ 033❇️ public function decode(string $value, $previousFieldValue): Value 034❇️ { 035❇️ $previousFieldValue->alternativeText = $value; 036❇️ 037❇️ return $previousFieldValue; 038❇️ } 039⫶}
code_samples/multisite/automated_translation/src/AutomatedTranslation/TranslateAction.php	code_samples/multisite/automated_translation/src/AutomatedTranslation/TranslateAction.php

Download colorized diff

[adriendupuis]

I found few broken links, I'm fixing them in #2658