From e0b56d423daadae76bc10138ac81f2d3778d906b Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Sun, 29 Sep 2024 16:30:04 +0200 Subject: [PATCH 1/3] document how to use Google Translate to translate content --- docs/i18n-l10n/index.md | 1 + .../use-an-external-translation-service.md | 91 +++++++++++++++++++ 2 files changed, 92 insertions(+) create mode 100644 docs/i18n-l10n/use-an-external-translation-service.md diff --git a/docs/i18n-l10n/index.md b/docs/i18n-l10n/index.md index efd6ce6de..c80dee7a5 100644 --- a/docs/i18n-l10n/index.md +++ b/docs/i18n-l10n/index.md @@ -160,5 +160,6 @@ language-negotiation-volto translating-content contributing-translations resync-translations +use-an-external-translation-service ``` diff --git a/docs/i18n-l10n/use-an-external-translation-service.md b/docs/i18n-l10n/use-an-external-translation-service.md new file mode 100644 index 000000000..ba1a36390 --- /dev/null +++ b/docs/i18n-l10n/use-an-external-translation-service.md @@ -0,0 +1,91 @@ +--- +myst: + html_meta: + "description": "When translating content items in Plone you can connect to an external translation service to have your content translated." + "property=og:description": "When translating content items in Plone you can connect to an external translation service to have your content translated." + "property=og:title": "Use an external translation service to translate content" + "keywords": "Plone, Internationalization, i18n, language, translate, content, localization" +--- + +(use-an-external-translation-service-label)= + +# Use an external translation service to translate content + +When translating content items in Plone you can connect to an external translation service to have your content translated. + + +## Using Google Cloud Translation API + +The plone.app.multilingual product that turns Plone into a multilingual-content site, supports [Google Cloud Translation API](https://cloud.google.com/translate/docs/reference/rest), which allows the content editor to use its translations. + +The site administrator, needs to create a project in Google Cloud, enable the Cloud Translation API, and create an API key under the Credentials of the Google Cloud Console. + +This API key, can be entered in the Multilingual Settings Control Panel in Plone. + +After doing so, when the content editor is editing a translation of a given content page, an icon will be shown next to the original content. + +When clickin on such icon, the Google Cloud Translation API will be invoked, and the translation obtained through the service entered automatically in the corresponding field. + +```{note} +The usage of Google Cloud Translation API may create extra cost for the site administrator. +``` + + +## Using other translation services + +If the site administrator doesn't want to use Google Cloud Translation API but some other service, they will need to override the view that makes the call to Google Cloud Translation API. + +To do so plone.app.multilingual registers a view called `gtranslation_service`, its code lies on [plone.app.multilingual.brwoser.translate.gtranslation_service_dexterity](https://github.com/plone/plone.app.multilingual/blob/master/src/plone/app/multilingual/browser/translate.py#L52) + +This view gets 3 parameters: + +- context_uid: the UID of the object to be translated. +- field: the name of the field of the object that needs to be translated. It's this view's job to extract the value of that field from the object. +- lang_source: the source language code. + +The first part of the view (the one that gets the object and the field content to be translated), can be copied from the original code, only the call to the translation service will need to be written. + +The required code would be something like this: + +```python + +class TranslateUsingMyService(BrowserView): + def __call__(self): + if self.request.method != "POST" and not ( + "field" in self.request.form.keys() + and "lang_source" in self.request.form.keys() + ): + return _("Need a field") + else: + manager = ITranslationManager(self.context) + context_uid = self.request.form.get("context_uid", None) + if context_uid is None: + # try with context if no translation uid is present + manager = ITranslationManager(self.context) + else: + catalog = getToolByName(self.context, "portal_catalog") + brains = catalog(UID=context_uid) + if len(brains): + context = brains[0].getObject() + manager = ITranslationManager(context) + else: + manager = ITranslationManager(self.context) + + registry = getUtility(IRegistry) + settings = registry.forInterface( + IMultiLanguageExtraOptionsSchema, prefix="plone" + ) + lang_target = ILanguage(self.context).get_language() + lang_source = self.request.form["lang_source"] + orig_object = manager.get_translation(lang_source) + field = self.request.form["field"].split(".")[-1] + if hasattr(orig_object, field): + question = getattr(orig_object, field, "") + if hasattr(question, "raw"): + question = question.raw + else: + return _("Invalid field") + + # And here do the call to the external translation service + return call_to_my_service(question, lang_target, lang_source) +``` From f85a96a43b7246174019eb78c6314af360b3cd9d Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Sun, 29 Sep 2024 19:11:43 +0200 Subject: [PATCH 2/3] add a note saying that one needs to enter something in the API key field --- docs/i18n-l10n/use-an-external-translation-service.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/i18n-l10n/use-an-external-translation-service.md b/docs/i18n-l10n/use-an-external-translation-service.md index ba1a36390..8e91e9307 100644 --- a/docs/i18n-l10n/use-an-external-translation-service.md +++ b/docs/i18n-l10n/use-an-external-translation-service.md @@ -89,3 +89,8 @@ class TranslateUsingMyService(BrowserView): # And here do the call to the external translation service return call_to_my_service(question, lang_target, lang_source) ``` + + +```{note} +Due to the way that the Google Translate integration is built in plone.app.multilingual, you will need to enter something in the Google Translate API Key field, in the Multilingual Settings of your site. It doesn't need to be a valid Google Translate API Key, it can be a random string. +``` From 1076f2797e140854283b675e57a8ffd8f6a98ade Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 30 Sep 2024 04:45:41 -0700 Subject: [PATCH 3/3] Review of PR --- .../use-an-external-translation-service.md | 49 ++++++++++--------- 1 file changed, 27 insertions(+), 22 deletions(-) diff --git a/docs/i18n-l10n/use-an-external-translation-service.md b/docs/i18n-l10n/use-an-external-translation-service.md index 8e91e9307..f396ca82f 100644 --- a/docs/i18n-l10n/use-an-external-translation-service.md +++ b/docs/i18n-l10n/use-an-external-translation-service.md @@ -1,54 +1,58 @@ --- myst: html_meta: - "description": "When translating content items in Plone you can connect to an external translation service to have your content translated." - "property=og:description": "When translating content items in Plone you can connect to an external translation service to have your content translated." + "description": "When translating content items in Plone, you can connect to an external translation service to translate your content." + "property=og:description": "When translating content items in Plone, you can connect to an external translation service to translate your content." "property=og:title": "Use an external translation service to translate content" - "keywords": "Plone, Internationalization, i18n, language, translate, content, localization" + "keywords": "Plone, Internationalization, i18n, language, translate, content, localization, l10n" --- (use-an-external-translation-service-label)= # Use an external translation service to translate content -When translating content items in Plone you can connect to an external translation service to have your content translated. +When translating content items in Plone, you can connect to an external translation service to translate your content. ## Using Google Cloud Translation API -The plone.app.multilingual product that turns Plone into a multilingual-content site, supports [Google Cloud Translation API](https://cloud.google.com/translate/docs/reference/rest), which allows the content editor to use its translations. +The `plone.app.multilingual` product that turns Plone into a multilingual-content site supports [Google Cloud Translation API](https://cloud.google.com/translate/docs/reference/rest), which allows the content editor to use its translations. -The site administrator, needs to create a project in Google Cloud, enable the Cloud Translation API, and create an API key under the Credentials of the Google Cloud Console. +To use this service as a site administrator, you need to create a project in Google Cloud, enable the Cloud Translation API, and create an API key under the Credentials of the Google Cloud Console. +You should enter this API key in the {guilabel}`Multilingual Settings` control panel in Plone. -This API key, can be entered in the Multilingual Settings Control Panel in Plone. - -After doing so, when the content editor is editing a translation of a given content page, an icon will be shown next to the original content. - -When clickin on such icon, the Google Cloud Translation API will be invoked, and the translation obtained through the service entered automatically in the corresponding field. +After doing so, as a content editor, when you edit a translation of a given content page, an icon will display next to the original content. +When you click this icon, it invokes the Google Cloud Translation API, and the translation obtained through the service will be entered automatically in the corresponding field. ```{note} The usage of Google Cloud Translation API may create extra cost for the site administrator. +See [Cloud Translation pricing](https://cloud.google.com/translate/pricing) for details. ``` ## Using other translation services -If the site administrator doesn't want to use Google Cloud Translation API but some other service, they will need to override the view that makes the call to Google Cloud Translation API. +If you want to use another service beside Google Cloud Translation API, you will need to override the view that calls Google Cloud Translation API. -To do so plone.app.multilingual registers a view called `gtranslation_service`, its code lies on [plone.app.multilingual.brwoser.translate.gtranslation_service_dexterity](https://github.com/plone/plone.app.multilingual/blob/master/src/plone/app/multilingual/browser/translate.py#L52) +To do so, `plone.app.multilingual` registers a view called `gtranslation_service`. +Its code is in [`plone.app.multilingual.brwoser.translate.gtranslation_service_dexterity`](https://github.com/plone/plone.app.multilingual/blob/7aedd0ab71d3edf5d1fb4cb86b9f611d428ed76b/src/plone/app/multilingual/browser/translate.py#L52). +This view gets three parameters: -This view gets 3 parameters: +`context_uid` +: The UID of the object to be translated. -- context_uid: the UID of the object to be translated. -- field: the name of the field of the object that needs to be translated. It's this view's job to extract the value of that field from the object. -- lang_source: the source language code. +`field` +: The name of the field of the object that needs to be translated. + This view's job is to extract the value of that field from the object. -The first part of the view (the one that gets the object and the field content to be translated), can be copied from the original code, only the call to the translation service will need to be written. +`lang_source` +: The source language code. -The required code would be something like this: +The first part of the view—that which gets the object and the field content to be translated—can be copied from the original code. +You need to write only the call to the translation service. +The required code would be something like the following example: ```python - class TranslateUsingMyService(BrowserView): def __call__(self): if self.request.method != "POST" and not ( @@ -90,7 +94,8 @@ class TranslateUsingMyService(BrowserView): return call_to_my_service(question, lang_target, lang_source) ``` - ```{note} -Due to the way that the Google Translate integration is built in plone.app.multilingual, you will need to enter something in the Google Translate API Key field, in the Multilingual Settings of your site. It doesn't need to be a valid Google Translate API Key, it can be a random string. +Due to the way that the Google Translate integration is built in `plone.app.multilingual`, you will need to enter something in the {guilable}`Google Translate API Key` field in the {guilable}`Multilingual Settings` +control panel of your site. +It doesn't need to be a valid Google Translate API Key; it can be a random string. ```