Added examples

Author: mnocon

code_samples/multisite/automated_translation/config/services.yaml

@@ -0,0 +1,31 @@
+services:
+    # default configuration for services in *this* file
+    _defaults:
+        autowire: true      # Automatically injects dependencies in your services.
+        autoconfigure: true # Automatically registers your services as commands, event subscribers, etc.
+
+    # makes classes in src/ available to be used as services
+    # this creates a service per class whose id is the fully-qualified class name
+    App\:
+        resource: '../src/'
+        exclude:
+            - '../src/DependencyInjection/'
+            - '../src/Entity/'
+            - '../src/Kernel.php'
+
+    App\AutomatedTranslation\AiClient:
+        tags:
+            - ibexa.automated_translation.client
+
+    App\AutomatedTranslation\ImageFieldEncoder:
+        tags:
+            - ibexa.automated_translation.field_encoder
+
+ibexa_automated_translation:
+    system:
+        default:
+            configurations:
+                aiclient:
+                    languages:
+                        - 'en_GB'
+                        - 'fr_FR'

code_samples/multisite/automated_translation/src/AutomatedTranslation/AiClient.php

@@ -0,0 +1,68 @@
+<?php declare(strict_types=1);
+
+namespace App\AutomatedTranslation;
+
+use Ibexa\AutomatedTranslation\Exception\ClientNotConfiguredException;
+use Ibexa\Contracts\AutomatedTranslation\Client\ClientInterface;
+use Ibexa\Contracts\ConnectorAi\Action\DataType\Text;
+use Ibexa\Contracts\ConnectorAi\Action\RuntimeContext;
+use Ibexa\Contracts\ConnectorAi\ActionConfigurationServiceInterface;
+use Ibexa\Contracts\ConnectorAi\ActionServiceInterface;
+
+final class AiClient implements ClientInterface
+{
+    /** @var array<string> */
+    private array $supportedLanguages;
+
+    private ActionServiceInterface $actionService;
+
+    private ActionConfigurationServiceInterface $actionConfigurationService;
+
+    public function __construct(ActionServiceInterface $actionService, ActionConfigurationServiceInterface $actionConfigurationService)
+    {
+        $this->actionService = $actionService;
+        $this->actionConfigurationService = $actionConfigurationService;
+    }
+
+    public function setConfiguration(array $configuration): void
+    {
+        if (!array_key_exists('languages', $configuration)) {
+            throw new ClientNotConfiguredException('List of supported languages is missing in the configuration under the "languages" key');
+        }
+        $this->supportedLanguages = $configuration['languages'];
+    }
+
+    public function translate(string $payload, ?string $from, string $to): string
+    {
+        $action = new TranslateAction(new Text([$payload]));
+        $action->setRuntimeContext(
+            new RuntimeContext(
+                [
+                    'from' => $from,
+                    'to' => $to,
+                ]
+            )
+        );
+        $actionConfiguration = $this->actionConfigurationService->getActionConfiguration('translate');
+        $actionResponse = $this->actionService->execute($action, $actionConfiguration)->getOutput();
+
+        assert($actionResponse instanceof Text);
+
+        return $actionResponse->getText();
+    }
+
+    public function supportsLanguage(string $languageCode): bool
+    {
+        return in_array($languageCode, $this->supportedLanguages, true);
+    }
+
+    public function getServiceAlias(): string
+    {
+        return 'aiclient';
+    }
+
+    public function getServiceFullName(): string
+    {
+        return 'Custom AI Automated Translation';
+    }
+}

code_samples/multisite/automated_translation/src/AutomatedTranslation/CustomClient.php

@@ -0,0 +1,39 @@
+<?php declare(strict_types=1);
+
+namespace App\AutomatedTranslation;
+
+use Ibexa\Contracts\AutomatedTranslation\Encoder\Field\FieldEncoderInterface;
+use Ibexa\Contracts\Core\Repository\Values\Content\Field;
+use Ibexa\Core\FieldType\Image\Value;
+
+final class ImageFieldEncoder implements FieldEncoderInterface
+{
+    public function canEncode(Field $field): bool
+    {
+        return $field->fieldTypeIdentifier === 'ezimage';
+    }
+
+    public function canDecode(string $type): bool
+    {
+        return $type === 'ezimage';
+    }
+
+    public function encode(Field $field): string
+    {
+        /** @var \Ibexa\Core\FieldType\Image\Value $value */
+        $value = $field->getValue();
+
+        return $value->alternativeText ?? '';
+    }
+
+    /**
+     * @param string $value
+     * @param \Ibexa\Core\FieldType\Image\Value $previousFieldValue
+     */
+    public function decode(string $value, $previousFieldValue): Value
+    {
+        $previousFieldValue->alternativeText = $value;
+
+        return $previousFieldValue;
+    }
+}

code_samples/multisite/automated_translation/src/AutomatedTranslation/ImageFieldEncoder.php

@@ -0,0 +1,13 @@
+<?php declare(strict_types=1);
+
+namespace App\AutomatedTranslation;
+
+use Ibexa\Contracts\ConnectorAi\Action\TextToText\Action;
+
+final class TranslateAction extends Action
+{
+    public function getActionTypeIdentifier(): string
+    {
+        return 'translate';
+    }
+}

code_samples/multisite/automated_translation/src/AutomatedTranslation/TranslateAction.php

@@ -14,6 +14,7 @@
     "require-dev": {
         "phpstan/phpstan": "^1.10",
         "phpstan/phpstan-symfony": "^1.3",
+        "ibexa/automated-translation": "5.0.x-dev",
         "ibexa/doctrine-schema": "5.0.x-dev",
         "ibexa/search": "5.0.x-dev",
         "ibexa/content-forms": "5.0.x-dev",
@@ -54,7 +55,6 @@
         "ibexa/activity-log": "5.0.x-dev",
         "ibexa/workflow": "5.0.x-dev",
         "ibexa/checkout": "5.0.x-dev",
-        "ibexa/oauth2-server": "5.0.x-dev",
         "ibexa/elasticsearch": "5.0.x-dev",
         "ibexa/oauth2-client": "5.0.x-dev",
         "ibexa/form-builder": "5.0.x-dev",

composer.json

@@ -17,11 +17,7 @@ The following field types are supported out of the box:
 - [Page](pagefield.md):
     - The content of `text` and `richtext` [block attributes](page_block_attributes.md#block-attribute-types)
 
-See [adding a custom field encoder](##add-a-custom-field-encoder) for more information on how to expand this.
-
-!!! note "DeepL limitations"
-
-    At this point a list of languages available when using DeepL is limited to English, German, French, Spanish, Italian, Dutch, Polish and Japanese.
+See [adding a custom field or block attribute encoder](##add-a-custom-field-encoder) for more information how you can extend this list.
 
 ## Configure automated content translation
 
@@ -36,7 +32,7 @@ composer require ibexa/automated-translation
 !!! caution "Modify the default configuration"
 
     Symfony Flex installs and activates the package.
-    However, you must modify the `config/bundles.php` file to change the bundle loading order so that`IbexaAutomatedTranslationBundle` is before `IbexaAdminUiBundle`:
+    However, you must modify the `config/bundles.php` file to change the bundle loading order so tha `IbexaAutomatedTranslationBundle` is loaded before `IbexaAdminUiBundle`:
 
     ```php
     <?php
@@ -72,33 +68,78 @@ The configuration is SiteAccess-aware, therefore, you can configure different en
 
 ## Translate content items with CLI
 
-To create a machine translation of a specific content item, run the following command:
+To create a machine translation of a specific content item, you can use the `ibexa:automated:translate` command.
+
+The following arguments and options are supported:
 
-```shell
-php bin/console ibexa:automated:translate [contentId] [serviceName] --from=eng-GB --to=fre-FR
+- `--from` - the source language
+- `--to` - the target language
+- `contentId` - ID of the content to translate
+- `serviceName` - the service to use for translation
+
+For example, to translate the root content item from the English translation into French with the help of Google Translate, run:
+
+``` bash
+php bin/console ibexa:automated:translate --from=eng-GB --to=fre-FR 52 google
 ```
 
-## Add a custom machine translation service
+## Extend automated content translations
+
+### Add a custom machine translation service
 
 By default, the automated translation package can connect to Google Translate or DeepL, but you can configure it to use a custom machine translation service.
 You would do it, for example, when a new service emerges on the market, or your company requires that a specific service is used.
 
-To add a custom engine to a list of available translation services, do the following:
+The following example adds a new translation service.
+It uses the [AI actions framework](ai_actions_md) and assumes a custom `TranslateAction` AI Action exists.
+To learn how to build custom AI actions see [Extending AI actions](extend_ai_actions.md#custom-action-type-use-case).
 
 1. Create a service that implements the [`\Ibexa\AutomatedTranslation\Client\ClientInterface`](REFERENCE LINK) interface
-1. In `services.yaml` file, tag the service as `ibexa.automated_translation.client`
 
-See the example below:
+``` php
+[[= include_file('code_samples/multisite/automated_translation/src/AutomatedTranslation/AiClient.php') =]]
+```
+
+2\. Tag the service as `ibexa.automated_translation.client` in the Symfony container
+
+``` yaml
+[[= include_file('code_samples/multisite/automated_translation/config/services.yaml', 15, 18) =]]
+```
+
+3\. Specify the configuration under the `ibexa_automated_translation.system.default.configurations` key
+
+``` yaml
+[[= include_file('code_samples/multisite/automated_translation/config/services.yaml', 23, 32) =]]
+```
+
+### Create custom field or block attribute encoder
 
-<example here>
+You can expand the list of supported field types and block attributes for automated translation, adding support for even more use cases than the ones built into [[= product_name =]].
 
 The whole automated translation process consists of 3 phases:
-1. Encoding - the raw data stored in the fieldtype is processed so that it can be translated by the automated translation service. Google and Deepl can h
-1. Translating - the data is translated using an Automated Translatin client.
-1. Decoding - the translated data is decoded back to the original structure so that it can be stored back in [= product_name =]]
 
-## Add a custom field or block encoder
+1. **Encoding** - data is extracted from the field types and block attributes and serialized into XML format
+1. **Translating** - the serialized XML is sent into specified translation service
+1. **Decoding** - the translated response is deserialized into the original data structures for storage in [[= product_name =]]
 
+The following example adds support for automatically translating alternative text in image fields by using the [AI Actions](ai_actions.md).
 
+1. Create a class implementing the [`FieldEncoderInterface`](TODO:Referencelink) and add the required methods:
 
+``` php hl_lines="11-14 16-19 21-27 33-38" 
+[[= include_file('code_samples/multisite/automated_translation/src/AutomatedTranslation/ImageFieldEncoder.php') =]]
+```
+In this example, the methods are responsible for:
+
+- `canEncode` - deciding if the field to be encoded is an [Image](imagefield.md) field.
+- `canDecode` - deciding if the field to be decoded is an [Image](imagefield.md) field.
+- `encode` - extracting the alternative text from the field type.
+- `decode` - saving the translated alternative text in the field type's value object.
+
+2\. Register it as a service. If you're not using [Symfony's autoconfiguration]([[= symfony_doc =]]/service_container.html#the-autoconfigure-option), use the `ibexa.automated_translation.field_encoder` service tag. 
+
+``` yaml
+[[= include_file('code_samples/multisite/automated_translation/config/services.yaml', 19, 22) =]]
+```
 
+For custom block attributes the appropriate interface is [`BlockAttributeEncoderInterface`](TODO: Reference link) and the service tag is `ibexa.automated_translation.block_attribute_encoder`.