From d25cb5f996eadee05fd299a29e9f11861aecc30e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20D=C4=85browski?= <64841871+dabrt@users.noreply.github.com> Date: Tue, 25 Jun 2024 08:43:51 +0200 Subject: [PATCH 1/7] IBX-7912: Describe automated translation feature --- .../languages/automated_translations.md | 78 +++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 79 insertions(+) create mode 100644 docs/multisite/languages/automated_translations.md diff --git a/docs/multisite/languages/automated_translations.md b/docs/multisite/languages/automated_translations.md new file mode 100644 index 0000000000..5220f0d117 --- /dev/null +++ b/docs/multisite/languages/automated_translations.md @@ -0,0 +1,78 @@ +--- +description: With the automated translation add-on, users can translate content items into multiple languages with Google Translate and other machine translation engines. +--- + +# Automated content translation + +The automated translation add-on package allows users have content items machine-translated into multiple languages by using external translation engines like Google Translate and DeepL. +The package integrates with [[= product_name =]], and allows users to [request from the UI]([[= user_doc =]]/content_management/translate_content.md#add-translations) that a content item is translated. +However, you can also run an API command to translate a specific content item. +Either way, as a result, a new version of a content item is created with all [translatable fields](languages.md#translatable-and-untranslatable-fields) translated into a target language. + +## Configure automated content translation + +### Install package + +Automated content translation support comes as an additional package that needs to be downloaded and installed separately: + +```bash +composer require ibexa/automated-translation +``` + +!!! caution "Modify the default configuration" + + Flex installs and activates the package. + However, you must modify the `bundles.php` file to change the template loading order: + + ```php + ['all' => true], + Ibexa\Bundle\AdminUi\IbexaAdminUiBundle::class => ['all' => true], + ... + ]; + ``` + +### Configure automated content translation + +Before you can start using the feature you must get access to your Google and/or DeepL account. + +1\. Get the [Google API key](https://developers.google.com/maps/documentation/javascript/get-api-key) and/or [DeepL Pro key](https://support.deepl.com/hc/en-us/articles/360020695820-API-Key-for-DeepL-s-API). + +3\. Set these values in the YAML configuration files, under the `ibexa_automated_translation.system.default.configurations` key: + +``` yaml +ibexa_automated_translation: + system: + default: + configurations: + google: + apiKey: "google-api-key" + deepl: + authKey: "deepl-pro-key" +``` + +!!! note + + The configuration is SiteAccess-aware, therefore, you can configure different engines to be used for different sites. + +## Translate content items with API + +To create a machine translation of a specific content item, run the following command: + +```shell +php bin/console ibexatranslate [contentId] [serviceName] --from=eng-GB --to=fre-FR +``` + +## Add a custom machine translation service + +You can configure the automated translation package 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: + +- create a service that implements the ` Ibexa\AutomatedTranslation\Client\ClientInterface` +- implement the `translate` method +- in `services.yaml` file, tag the service as `ibexa.automated_translation.client` \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index f13d74e640..2d34e70475 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -406,6 +406,7 @@ nav: - Languages: multisite/languages/languages.md - Language API: multisite/languages/language_api.md - Back Office translations: multisite/languages/back_office_translations.md + - Automated content translation: multisite/languages/automated_translations.md - Permissions: - Permissions: permissions/permissions.md - Permission overview: permissions/permission_overview.md From 96dc26284c2a1fd655d44054e436ccb2d124dd51 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20D=C4=85browski?= <64841871+dabrt@users.noreply.github.com> Date: Tue, 25 Jun 2024 08:55:27 +0200 Subject: [PATCH 2/7] Fix wording --- docs/multisite/languages/automated_translations.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/multisite/languages/automated_translations.md b/docs/multisite/languages/automated_translations.md index 5220f0d117..6020683ac3 100644 --- a/docs/multisite/languages/automated_translations.md +++ b/docs/multisite/languages/automated_translations.md @@ -35,9 +35,9 @@ composer require ibexa/automated-translation ]; ``` -### Configure automated content translation +### Configure access to translation services -Before you can start using the feature you must get access to your Google and/or DeepL account. +Before you can start using the feature you must configure access to your Google and/or DeepL account. 1\. Get the [Google API key](https://developers.google.com/maps/documentation/javascript/get-api-key) and/or [DeepL Pro key](https://support.deepl.com/hc/en-us/articles/360020695820-API-Key-for-DeepL-s-API). From 75ffc1ce15c5c6ce5905781cdf6c9ecf678fd6dc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20D=C4=85browski?= <64841871+dabrt@users.noreply.github.com> Date: Tue, 25 Jun 2024 09:01:37 +0200 Subject: [PATCH 3/7] Undo composer.json change --- composer.json | 2 -- 1 file changed, 2 deletions(-) diff --git a/composer.json b/composer.json index 34e5554136..38756bf1d8 100644 --- a/composer.json +++ b/composer.json @@ -12,8 +12,6 @@ } ], "require-dev": { - "ibexa/code-style": "^1.0", - "friendsofphp/php-cs-fixer": "^3.30", "phpstan/phpstan": "^1.10", "phpstan/phpstan-symfony": "^1.3", "ibexa/doctrine-schema": "5.0.x-dev", From 29252fca9ddeb8f6189622ab2818373f4dce9406 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20D=C4=85browski?= <64841871+dabrt@users.noreply.github.com> Date: Wed, 26 Jun 2024 17:17:10 +0200 Subject: [PATCH 4/7] Update the feature description --- .../languages/automated_translations.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/docs/multisite/languages/automated_translations.md b/docs/multisite/languages/automated_translations.md index 6020683ac3..3c55252697 100644 --- a/docs/multisite/languages/automated_translations.md +++ b/docs/multisite/languages/automated_translations.md @@ -1,13 +1,20 @@ --- -description: With the automated translation add-on, users can translate content items into multiple languages with Google Translate and other machine translation engines. +description: With the automated translation add-on, users can translate content items into multiple languages with Google Translate or DeepL. --- # Automated content translation -The automated translation add-on package allows users have content items machine-translated into multiple languages by using external translation engines like Google Translate and DeepL. +The automated translation add-on package allows users have content items machine-translated into multiple languages by using either Google Translate or DeepL external translation engine. The package integrates with [[= product_name =]], and allows users to [request from the UI]([[= user_doc =]]/content_management/translate_content.md#add-translations) that a content item is translated. However, you can also run an API command to translate a specific content item. -Either way, as a result, a new version of a content item is created with all [translatable fields](languages.md#translatable-and-untranslatable-fields) translated into a target language. +Either way, as a result, a new version of the content item is created with the following [translatable fields](languages.md#translatable-and-untranslatable-fields) translated into a target language: + +- in pages: [TextBlock](../../content_management/field_types/field_type_reference//textblockfield.md) and [RichText](../../content_management/field_types/field_type_reference//richtextfield.md) +- in other content types: [TextLine](../../content_management/field_types/field_type_reference//textlinefield.md) and RichText + +!!! 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. ## Configure automated content translation @@ -63,12 +70,12 @@ ibexa_automated_translation: To create a machine translation of a specific content item, run the following command: ```shell -php bin/console ibexatranslate [contentId] [serviceName] --from=eng-GB --to=fre-FR +php bin/console TranslateContentCommand [contentId] [serviceName] --from=eng-GB --to=fre-FR ``` ## Add a custom machine translation service -You can configure the automated translation package to use 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: From d52c55db8bac6356787e9359e6df5220d9194c91 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20D=C4=85browski?= <64841871+dabrt@users.noreply.github.com> Date: Thu, 27 Jun 2024 08:55:22 +0200 Subject: [PATCH 5/7] Tiny wording fixes --- docs/multisite/languages/automated_translations.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/multisite/languages/automated_translations.md b/docs/multisite/languages/automated_translations.md index 3c55252697..a5f0cccadb 100644 --- a/docs/multisite/languages/automated_translations.md +++ b/docs/multisite/languages/automated_translations.md @@ -7,7 +7,7 @@ description: With the automated translation add-on, users can translate content The automated translation add-on package allows users have content items machine-translated into multiple languages by using either Google Translate or DeepL external translation engine. The package integrates with [[= product_name =]], and allows users to [request from the UI]([[= user_doc =]]/content_management/translate_content.md#add-translations) that a content item is translated. However, you can also run an API command to translate a specific content item. -Either way, as a result, a new version of the content item is created with the following [translatable fields](languages.md#translatable-and-untranslatable-fields) translated into a target language: +Either way, as a result, a new version of the content item is created with [translatable fields](languages.md#translatable-and-untranslatable-fields) of the following types translated into a target language: - in pages: [TextBlock](../../content_management/field_types/field_type_reference//textblockfield.md) and [RichText](../../content_management/field_types/field_type_reference//richtextfield.md) - in other content types: [TextLine](../../content_management/field_types/field_type_reference//textlinefield.md) and RichText @@ -20,7 +20,7 @@ Either way, as a result, a new version of the content item is created with the f ### Install package -Automated content translation support comes as an additional package that needs to be downloaded and installed separately: +Automated content translation support comes as an additional package that you must download and install separately: ```bash composer require ibexa/automated-translation @@ -80,6 +80,6 @@ You would do it, for example, when a new service emerges on the market, or your To add a custom engine to a list of available translation services, do the following: -- create a service that implements the ` Ibexa\AutomatedTranslation\Client\ClientInterface` +- create a service that implements ` Ibexa\AutomatedTranslation\Client\ClientInterface` - implement the `translate` method - in `services.yaml` file, tag the service as `ibexa.automated_translation.client` \ No newline at end of file From 9c835d982eaed5b6be75750d0cf351277d49b862 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20D=C4=85browski?= <64841871+dabrt@users.noreply.github.com> Date: Thu, 27 Jun 2024 09:01:29 +0200 Subject: [PATCH 6/7] Command name fix --- docs/multisite/languages/automated_translations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/multisite/languages/automated_translations.md b/docs/multisite/languages/automated_translations.md index a5f0cccadb..0ce8aff6f2 100644 --- a/docs/multisite/languages/automated_translations.md +++ b/docs/multisite/languages/automated_translations.md @@ -70,7 +70,7 @@ ibexa_automated_translation: To create a machine translation of a specific content item, run the following command: ```shell -php bin/console TranslateContentCommand [contentId] [serviceName] --from=eng-GB --to=fre-FR +php bin/console ibexa:automated:translate [contentId] [serviceName] --from=eng-GB --to=fre-FR ``` ## Add a custom machine translation service From eee35a4acf6aa64b874161897d00c2c792f2a034 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20D=C4=85browski?= <64841871+dabrt@users.noreply.github.com> Date: Fri, 28 Jun 2024 15:05:58 +0200 Subject: [PATCH 7/7] Implement reviewer comments --- .../languages/automated_translations.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/docs/multisite/languages/automated_translations.md b/docs/multisite/languages/automated_translations.md index 0ce8aff6f2..5b226bb071 100644 --- a/docs/multisite/languages/automated_translations.md +++ b/docs/multisite/languages/automated_translations.md @@ -7,10 +7,11 @@ description: With the automated translation add-on, users can translate content The automated translation add-on package allows users have content items machine-translated into multiple languages by using either Google Translate or DeepL external translation engine. The package integrates with [[= product_name =]], and allows users to [request from the UI]([[= user_doc =]]/content_management/translate_content.md#add-translations) that a content item is translated. However, you can also run an API command to translate a specific content item. -Either way, as a result, a new version of the content item is created with [translatable fields](languages.md#translatable-and-untranslatable-fields) of the following types translated into a target language: +Either way, as a result, a new version of the content item is created, with the following elements translated into a target language: -- in pages: [TextBlock](../../content_management/field_types/field_type_reference//textblockfield.md) and [RichText](../../content_management/field_types/field_type_reference//richtextfield.md) -- in other content types: [TextLine](../../content_management/field_types/field_type_reference//textlinefield.md) and RichText + +- for pages: blocks that have the `text` or `richtext` [block attributes](../../content_management/pages/page_block_attributes/#block-attribute-types) +- for other content types: Fields of the [TextLine](../../content_management/field_types/field_type_reference//textlinefield.md) and [RichText](../../content_management/field_types/field_type_reference//richtextfield.md) type !!! note "DeepL limitations" @@ -28,8 +29,8 @@ composer require ibexa/automated-translation !!! caution "Modify the default configuration" - Flex installs and activates the package. - However, you must modify the `bundles.php` file to change the template loading order: + Symfony Flex installs and activates the package. + However, you must modify the `config/bundles.php` file to change the template loading order: ```php