Move user translations docs to the features section
The documentation of user content translations doesn't really belong in the customization introduction.
This commit is contained in:
Javi Martín
@@ -45,6 +45,7 @@
|
||||
* [Configure Census Connection](features/census_configuration.md)
|
||||
* [Local Census](features/local_census.md)
|
||||
* [Multitenancy](features/multitenancy.md)
|
||||
* [User content translations](features/user_content_translations.md)
|
||||
|
||||
* [Open Source project](open_source/open_source.md)
|
||||
* [Code of conduct](open_source/code_of_conduct.md)
|
||||
|
||||
@@ -21,125 +21,3 @@ Also these are the files where you can apply some customization:
|
||||
* `app/assets/javascripts/custom.js`
|
||||
* `Gemfile_custom`
|
||||
* `config/application.custom.rb`
|
||||
|
||||
## Remote translations on demand by the user
|
||||
|
||||
The aim of this service is to be able to offer all the dynamic contents of the application (proposals, debates, budget investments and comments) in different languages without the need for a user or administrator to have created each one of their translations.
|
||||
|
||||
When a user visits a page with a language where there is untranslated content, they will have a button to request the translation of all the content. This content will be sent to an automatic translator (in this case [Microsoft TranslatorText](https://azure.microsoft.com/en-us/products/cognitive-services/translator/)) and as soon as the response is obtained, all these translations will be available to any user.
|
||||
|
||||
### Getting started
|
||||
|
||||
In order to use this functionality, the following steps are necessary:
|
||||
|
||||
1. Have an api key to connect to the translation service. For this we need an [Azure account](https://azure.microsoft.com/en-us/)
|
||||
1. Once you are logged into the Azure portal, subscribe to the Translator in Cognitive Service.
|
||||
1. Once you have subscribed to the Translator Text service, you will have access to 2 api keys in the section **Resource Management > Keys and Endpoint** that will be necessary for the configuration of the translation service in your application.
|
||||
|
||||
### Configuration
|
||||
|
||||
To activate the translation service in your application you must complete the following steps:
|
||||
|
||||
#### Add api key in the application
|
||||
|
||||
In the previous section we have commented that once subscribed to the translation service we have 2 api keys. To configure the service correctly in our application we must add one of the two api keys in the file `secrets.yml` in section `apis:` with the key `microsoft_api_key` as we can see in the following image:
|
||||
|
||||
|
||||
|
||||
#### Activate module
|
||||
|
||||
Once we have the new key in the `secrets.yml` we can now proceed to activate the module. To activate the functionality you must follow 2 steps:
|
||||
|
||||
1. Execute the following command `bin/rake settings:create_remote_translations_setting RAILS_ENV=production`
|
||||
1. Accessing through the administration panel of your application to the section **Configuración > Funcionalidades** and activate module **Traducciones Remotas** as shown below:
|
||||
|
||||
|
||||
### Use Cases
|
||||
|
||||
Once we have the api key in our `secrets.yml` and the activated module, users will already be able to use the functionality.
|
||||
We attach some screenshots of how the application interacts with our users:
|
||||
|
||||
* When a user visits a page in a language without translated content, an informative text will appear at the top of the page and a button to request the translation. (**Note:** *If user visit page with a language not supported by the translation service, no text or translation button will be displayed. See section: Available languages for remote translation*)
|
||||
|
||||
|
||||
* Once the user click the `Translate page` button, the translations are enqueued and the page is reloaded with a notice (*Informing that the translations have been requested correctly*) and an informative text in the header (*explaining when you will be able to see these translations*).
|
||||
|
||||
|
||||
* If an user visit a page that does not have translations but have already been requested by another user. The application will not show you the translate button, but an informative text in the header (*explaining when you will be able to see these translations*).
|
||||
|
||||
|
||||
* The translation request, response processing and data saving are delegated to `Delayed Jobs` and as soon as they are processed, the user will be able to read them after page refresh.
|
||||
|
||||
|
||||
### Available languages for remote translation
|
||||
|
||||
Currently these are all the [available languages](https://api.cognitive.microsofttranslator.com/languages?api-version=3.0) in the translation service:
|
||||
|
||||
```yml
|
||||
["af", "am", "ar", "as", "az", "ba", "bg", "bn", "bo", "bs", "ca", "cs", "cy", "da", "de", "dv", "el", "en", "es", "et", "eu", "fa", "fi", "fil", "fj", "fo", "fr", "fr-CA", "ga", "gl", "gu", "ha", "he", "hi", "hr", "hsb", "ht", "hu", "hy", "id", "ig", "ikt", "is", "it", "iu", "iu-Latn", "ja", "ka", "kk", "km", "kmr", "kn", "ko", "ku", "ky", "ln", "lo", "lt", "lug", "lv", "lzh", "mg", "mi", "mk", "ml", "mn-Cyrl", "mn-Mong", "mr", "ms", "mt", "mww", "my", "nb", "ne", "nl", "nso", "nya", "or", "otq", "pa", "pl", "prs", "ps", "pt", "pt-PT", "ro", "ru", "run", "rw", "sk", "sl", "sm", "sn", "so", "sq", "sr-Cyrl", "sr-Latn", "st", "sv", "sw", "ta", "te", "th", "ti", "tk", "tlh-Latn", "tlh-Piqd", "tn", "to", "tr", "tt", "ty", "ug", "uk", "ur", "uz", "vi", "xh", "yo", "yua", "yue", "zh-Hans", "zh-Hant", "zu"]
|
||||
```
|
||||
|
||||
Of all the languages that Consul Democracy currently has defined (`available_locales`) in `config/application.rb` the only one that is not listed above and therefore no translation service is offered is Valencian `["val"]`.
|
||||
|
||||
### Pricing
|
||||
|
||||
The translation service used has the most competitive [pricing](https://azure.microsoft.com/en-us/pricing/details/cognitive-services/translator/).
|
||||
The price for each 1 Million characters translated is $10 and there is no fixed cost per month.
|
||||
|
||||
Although technical measures have been taken to prevent misuse of this service, we recommend the creation of Alerts offered by Azure so that an Administrator can be notified in the event of detecting unusual use of the service. This service has a cost of $0.10 per month.
|
||||
|
||||
To create an Alert in Azure we must follow the following steps:
|
||||
|
||||
1. Sign in to the **Azure Portal**.
|
||||
1. Access the **Translator** service created earlier.
|
||||
1. Go to **Monitoring > Alerts** in the side menu:
|
||||
1. Go to **Create alert rule**.
|
||||
1. In **Select a signal** select `Text Characters Translated`.
|
||||
1. Once selected we must define the logic of the Alert to suit our needs. Ex: Fill "Operator" field with "Greater than" option, fill "Aggregation type" field with "Total" option and fill "Threshold value" field with the number of characters we consider should be translated before being notified. In this section you can also set the time period and frequency of evaluation.
|
||||
1. In order to be notified we have to create an **Action Group** and associate it with this Alert we're creating. To do this, access the button **Create** and fill out the form. As you can see there are different types of actions, we must select **Email/SMS/Push/Voice** and configure the option that we consider convenient according to our needs.
|
||||
1. Once this group of actions has been created, it is directly associated with the rule we are creating.
|
||||
1. Finally, all you have to do is add a name and click on the **Review + create**
|
||||
|
||||
### Add a new translation service
|
||||
|
||||
If you want to integrate more translation services for any reason (new translation service appears, you want to change to include languages that are currently not supported, etc.) the code is ready to be added.
|
||||
This is made possible by the `RemoteTranslations::Caller` class which is an intermediate layer between untranslated content management and the currently used Microsoft Translation Client.
|
||||
A good solution for adding another translation service would be to replace the call to the `MicrosoftTranslateClient` in the `translations` method of `RemoteTranslations::Caller` with the new service implemented.
|
||||
If you want to coexist with both should only be managed in which case we want to use one or the other, either through specific conditions in the code or through a management in the Settings of the application.
|
||||
|
||||
```ruby
|
||||
class RemoteTranslationsCaller
|
||||
|
||||
...
|
||||
def translations
|
||||
@translations ||= RemoteTranslations::Microsoft::Client.new.call(fields_values, locale)
|
||||
# Add new RemoteTranslations Client
|
||||
# @translations = RemoteTranslations::NewTranslateClient::Client.new.call(fields_values, locale_to)
|
||||
end
|
||||
...
|
||||
|
||||
end
|
||||
```
|
||||
|
||||
## Translation interface
|
||||
|
||||
The aim of this feature is to allow users the introduction of dynamic contents in many languages at the same time. From the administration panel you can activate or deactivate it. If you deactivate this feature (default configuration) users will be able to enter one single translation.
|
||||
|
||||
### Enable module
|
||||
|
||||
To activate this feature you must follow 2 steps:
|
||||
|
||||
1. Execute the following command `bin/rake settings:create_translation_interface_setting RAILS_ENV=production` (This is only required for already existing intallations, for new Consul Democracy installations this step is not needed).
|
||||
2. Accessing as administrator user to the administration panel of your Consul Democracy application to the section **Configuration > Features** and activating the feature called **Translation Interface** as you can see next:
|
||||
|
||||
|
||||
### Use Cases
|
||||
|
||||
* When the translation interface is active:
|
||||
As you can see in the image below translation interface has two selectors, the firt one "Select language" is to switch between enabled languages and the second one "Add language" is to add new languages to the form. Translatable fields appears with a blue background to facilitate users to distinguish between translatable and not translatable fields. Additionally interface provides a link `Remove language` to delete the current language shown at "Select language". If a user accidentally removes a translation he can recover it re-adding it to the form.
|
||||
This feature is visible during creation and edition of translatable resources.
|
||||
|
||||
|
||||
* When the translation interface is disabled:
|
||||
When this feature is deactivated users will see standard forms without translation interface and without translation highlight.
|
||||
|
||||
|
||||
123
docs/en/features/user_content_translations.md
Normal file
123
docs/en/features/user_content_translations.md
Normal file
@@ -0,0 +1,123 @@
|
||||
# Translations of user content
|
||||
|
||||
## Remote translations on demand by the user
|
||||
|
||||
The aim of this service is to be able to offer all the dynamic contents of the application (proposals, debates, budget investments and comments) in different languages without the need for a user or administrator to have created each one of their translations.
|
||||
|
||||
When a user visits a page with a language where there is untranslated content, they will have a button to request the translation of all the content. This content will be sent to an automatic translator (in this case [Microsoft TranslatorText](https://azure.microsoft.com/en-us/products/cognitive-services/translator/)) and as soon as the response is obtained, all these translations will be available to any user.
|
||||
|
||||
### Getting started
|
||||
|
||||
In order to use this functionality, the following steps are necessary:
|
||||
|
||||
1. Have an api key to connect to the translation service. For this we need an [Azure account](https://azure.microsoft.com/en-us/)
|
||||
1. Once you are logged into the Azure portal, subscribe to the Translator in Cognitive Service.
|
||||
1. Once you have subscribed to the Translator Text service, you will have access to 2 api keys in the section **Resource Management > Keys and Endpoint** that will be necessary for the configuration of the translation service in your application.
|
||||
|
||||
### Configuration
|
||||
|
||||
To activate the translation service in your application you must complete the following steps:
|
||||
|
||||
#### Add api key in the application
|
||||
|
||||
In the previous section we have commented that once subscribed to the translation service we have 2 api keys. To configure the service correctly in our application we must add one of the two api keys in the file `secrets.yml` in section `apis:` with the key `microsoft_api_key` as we can see in the following image:
|
||||
|
||||
|
||||
|
||||
#### Activate module
|
||||
|
||||
Once we have the new key in the `secrets.yml` we can now proceed to activate the module. To activate the functionality you must follow 2 steps:
|
||||
|
||||
1. Execute the following command `bin/rake settings:create_remote_translations_setting RAILS_ENV=production`
|
||||
1. Accessing through the administration panel of your application to the section **Configuración > Funcionalidades** and activate module **Traducciones Remotas** as shown below:
|
||||
|
||||
|
||||
### Use Cases
|
||||
|
||||
Once we have the api key in our `secrets.yml` and the activated module, users will already be able to use the functionality.
|
||||
We attach some screenshots of how the application interacts with our users:
|
||||
|
||||
* When a user visits a page in a language without translated content, an informative text will appear at the top of the page and a button to request the translation. (**Note:** *If user visit page with a language not supported by the translation service, no text or translation button will be displayed. See section: Available languages for remote translation*)
|
||||
|
||||
|
||||
* Once the user click the `Translate page` button, the translations are enqueued and the page is reloaded with a notice (*Informing that the translations have been requested correctly*) and an informative text in the header (*explaining when you will be able to see these translations*).
|
||||
|
||||
|
||||
* If an user visit a page that does not have translations but have already been requested by another user. The application will not show you the translate button, but an informative text in the header (*explaining when you will be able to see these translations*).
|
||||
|
||||
|
||||
* The translation request, response processing and data saving are delegated to `Delayed Jobs` and as soon as they are processed, the user will be able to read them after page refresh.
|
||||
|
||||
|
||||
### Available languages for remote translation
|
||||
|
||||
Currently these are all the [available languages](https://api.cognitive.microsofttranslator.com/languages?api-version=3.0) in the translation service:
|
||||
|
||||
```yml
|
||||
["af", "am", "ar", "as", "az", "ba", "bg", "bn", "bo", "bs", "ca", "cs", "cy", "da", "de", "dv", "el", "en", "es", "et", "eu", "fa", "fi", "fil", "fj", "fo", "fr", "fr-CA", "ga", "gl", "gu", "ha", "he", "hi", "hr", "hsb", "ht", "hu", "hy", "id", "ig", "ikt", "is", "it", "iu", "iu-Latn", "ja", "ka", "kk", "km", "kmr", "kn", "ko", "ku", "ky", "ln", "lo", "lt", "lug", "lv", "lzh", "mg", "mi", "mk", "ml", "mn-Cyrl", "mn-Mong", "mr", "ms", "mt", "mww", "my", "nb", "ne", "nl", "nso", "nya", "or", "otq", "pa", "pl", "prs", "ps", "pt", "pt-PT", "ro", "ru", "run", "rw", "sk", "sl", "sm", "sn", "so", "sq", "sr-Cyrl", "sr-Latn", "st", "sv", "sw", "ta", "te", "th", "ti", "tk", "tlh-Latn", "tlh-Piqd", "tn", "to", "tr", "tt", "ty", "ug", "uk", "ur", "uz", "vi", "xh", "yo", "yua", "yue", "zh-Hans", "zh-Hant", "zu"]
|
||||
```
|
||||
|
||||
Of all the languages that Consul Democracy currently has defined (`available_locales`) in `config/application.rb` the only one that is not listed above and therefore no translation service is offered is Valencian `["val"]`.
|
||||
|
||||
### Pricing
|
||||
|
||||
The translation service used has the most competitive [pricing](https://azure.microsoft.com/en-us/pricing/details/cognitive-services/translator/).
|
||||
The price for each 1 Million characters translated is $10 and there is no fixed cost per month.
|
||||
|
||||
Although technical measures have been taken to prevent misuse of this service, we recommend the creation of Alerts offered by Azure so that an Administrator can be notified in the event of detecting unusual use of the service. This service has a cost of $0.10 per month.
|
||||
|
||||
To create an Alert in Azure we must follow the following steps:
|
||||
|
||||
1. Sign in to the **Azure Portal**.
|
||||
1. Access the **Translator** service created earlier.
|
||||
1. Go to **Monitoring > Alerts** in the side menu:
|
||||
1. Go to **Create alert rule**.
|
||||
1. In **Select a signal** select `Text Characters Translated`.
|
||||
1. Once selected we must define the logic of the Alert to suit our needs. Ex: Fill "Operator" field with "Greater than" option, fill "Aggregation type" field with "Total" option and fill "Threshold value" field with the number of characters we consider should be translated before being notified. In this section you can also set the time period and frequency of evaluation.
|
||||
1. In order to be notified we have to create an **Action Group** and associate it with this Alert we're creating. To do this, access the button **Create** and fill out the form. As you can see there are different types of actions, we must select **Email/SMS/Push/Voice** and configure the option that we consider convenient according to our needs.
|
||||
1. Once this group of actions has been created, it is directly associated with the rule we are creating.
|
||||
1. Finally, all you have to do is add a name and click on the **Review + create**
|
||||
|
||||
### Add a new translation service
|
||||
|
||||
If you want to integrate more translation services for any reason (new translation service appears, you want to change to include languages that are currently not supported, etc.) the code is ready to be added.
|
||||
This is made possible by the `RemoteTranslations::Caller` class which is an intermediate layer between untranslated content management and the currently used Microsoft Translation Client.
|
||||
A good solution for adding another translation service would be to replace the call to the `MicrosoftTranslateClient` in the `translations` method of `RemoteTranslations::Caller` with the new service implemented.
|
||||
If you want to coexist with both should only be managed in which case we want to use one or the other, either through specific conditions in the code or through a management in the Settings of the application.
|
||||
|
||||
```ruby
|
||||
class RemoteTranslationsCaller
|
||||
|
||||
...
|
||||
def translations
|
||||
@translations ||= RemoteTranslations::Microsoft::Client.new.call(fields_values, locale)
|
||||
# Add new RemoteTranslations Client
|
||||
# @translations = RemoteTranslations::NewTranslateClient::Client.new.call(fields_values, locale_to)
|
||||
end
|
||||
...
|
||||
|
||||
end
|
||||
```
|
||||
|
||||
## Translation interface
|
||||
|
||||
The aim of this feature is to allow users the introduction of dynamic contents in many languages at the same time. From the administration panel you can activate or deactivate it. If you deactivate this feature (default configuration) users will be able to enter one single translation.
|
||||
|
||||
### Enable module
|
||||
|
||||
To activate this feature you must follow 2 steps:
|
||||
|
||||
1. Execute the following command `bin/rake settings:create_translation_interface_setting RAILS_ENV=production` (This is only required for already existing intallations, for new Consul Democracy installations this step is not needed).
|
||||
2. Accessing as administrator user to the administration panel of your Consul Democracy application to the section **Configuration > Features** and activating the feature called **Translation Interface** as you can see next:
|
||||
|
||||
|
||||
### Use Cases
|
||||
|
||||
* When the translation interface is active:
|
||||
As you can see in the image below translation interface has two selectors, the firt one "Select language" is to switch between enabled languages and the second one "Add language" is to add new languages to the form. Translatable fields appears with a blue background to facilitate users to distinguish between translatable and not translatable fields. Additionally interface provides a link `Remove language` to delete the current language shown at "Select language". If a user accidentally removes a translation he can recover it re-adding it to the form.
|
||||
This feature is visible during creation and edition of translatable resources.
|
||||
|
||||
|
||||
* When the translation interface is disabled:
|
||||
When this feature is deactivated users will see standard forms without translation interface and without translation highlight.
|
||||
|
||||
@@ -45,6 +45,7 @@
|
||||
* [Configurar conexión con el Censo](features/census_configuration.md)
|
||||
* [Local Census](features/local_census.md)
|
||||
* [Multitenancy](features/multitenancy.md)
|
||||
* [Traducciones de contenido de usuario](features/user_content_translations.md)
|
||||
|
||||
* [Proyecto Open Source](open_source/open_source.md)
|
||||
* [Código de conducta](open_source/code_of_conduct.md)
|
||||
|
||||
@@ -21,127 +21,3 @@ Aparte de estos directorios también cuentas con ciertos ficheros para:
|
||||
* `app/assets/javascripts/custom.js`
|
||||
* `Gemfile_custom`
|
||||
* `config/application.custom.rb`
|
||||
|
||||
## Traducciones remotas bajo demanda del usuario
|
||||
|
||||
Este servicio tiene como objetivo poder ofrecer todos los contenidos dinámicos de la aplicación (propuestas, debates, inversiones presupuestarias y comentarios) en diferentes idiomas sin la necesidad de que un usuario ó un administrador haya creado cada una de sus traducciones.
|
||||
|
||||
Cuando un usuario accede a una pantalla con un idioma donde parte del contenido dinámico que esta visualizando no tiene traducciones, dispondrá de un botón para solicitar la traducción de todo el contenido. Este contenido se enviará a un traductor automático (en este caso [Microsoft TranslatorText](https://azure.microsoft.com/es-es/products/cognitive-services/translator/)) y en cuanto se obtenga la respuesta, todas estas traducciones estarán disponibles para cualquier usuario.
|
||||
|
||||
### Como empezar
|
||||
|
||||
Para poder utilizar esta funcionalidad es necesario realizar los siguientes pasos:
|
||||
|
||||
1. Disponer de una api key para conectarse con el servicio de traducción. Para ello necesitamos una [cuenta en Azure](https://azure.microsoft.com/es-es/)
|
||||
1. Una vez que haya iniciado sesión en el portal de Azure, subscríbase a Traductor en Cognitive Services.
|
||||
1. Una vez subscrito al servicio de Translator Text, tendrá accesibles 2 api keys en la sección **Administración de recursos > Claves y punto de conexión** que serán necesarias para la configuración del servicio de traducciones en su aplicación.
|
||||
|
||||
### Configuración
|
||||
|
||||
Para activar el servicio de traducciones en su aplicación debe completar los siguientes pasos
|
||||
|
||||
#### Añadir api key en la aplicación
|
||||
|
||||
En el apartado anterior hemos comentado que una vez subscritos al servicio de traducciones disponemos de 2 api keys. Para configurar el servicio correctamente en nuestra aplicación deberemos añadir una de las dos api keys en el archivo `secrets.yml` en la sección `apis:` con la key `microsoft_api_key` como podemos ver en la siguiente imágen:
|
||||
|
||||
|
||||
|
||||
#### Activar funcionalidad
|
||||
|
||||
Una vez disponemos de la nueva key en el `secrets.yml` ya podemos proceder a activar la funcionalidad. Para activar la funcionalidad deberá realizar 2 pasos:
|
||||
|
||||
1. Ejecutar el siguiente comando `bin/rake settings:create_remote_translations_setting RAILS_ENV=production`
|
||||
1. Acceder a través del panel de administración de su aplicación a la sección **Configuración > Funcionalidades** y activar el módulo de **Traducciones Remotas** como se puede ver a continuación:
|
||||
|
||||
|
||||
### Funcionalidad
|
||||
|
||||
Una vez tenemos la api key en nuestro `secrets.yml` y el módulo activado, los usuarios ya podrán utilizar la funcionalidad.
|
||||
Para aclarar el funcionamiento, se adjuntan unos pantallazos de como interactua la aplicación con nuestros usuarios:
|
||||
|
||||
* Cuando un usuario accede a una pantalla en un idioma en el que no están disponibles todas las traducciones, le aparecerá un texto en la parte superior de la pantalla y un botón para poder solicitar la traducción. (**Nota:** *En el caso de acceder con un idioma no soportado por el servicio de traducción no se mostrará ningún texto ni botón de traducción. Ver sección: Idiomas disponibles para la traducción remota*)
|
||||
|
||||
|
||||
* Una vez el usuario pulsa el botón de `Traducir página` se encolan las traducciones y se recarga la pantalla con un notice (*informando que se han solicitado correctamente las traducciones*) y un texto informativo en la cabecera (*explicando cuando podrá ver estas traducciones*).
|
||||
|
||||
|
||||
* Si un usuario accede a una pantalla que no dispone de traducciones pero ya han sido solicitadas por otro usuario. La aplicación no le mostrará el botón de traducir, pero si un texto informativo en la cabecera (*explicando cuando podrá ver estas traducciones*).
|
||||
|
||||
|
||||
* Las peticiones de traducción se delegan a `Delayed Job` y en cuanto haya sido procesada, el usuario después de refrescar su página podrá ver el contenido traducido.
|
||||
|
||||
|
||||
### Idiomas disponibles para la traducción remota
|
||||
|
||||
Actualmente estos son todos los [idiomas disponibles](https://api.cognitive.microsofttranslator.com/languages?api-version=3.0) en el servicio de traducción:
|
||||
|
||||
```yml
|
||||
["af", "am", "ar", "as", "az", "ba", "bg", "bn", "bo", "bs", "ca", "cs", "cy", "da", "de", "dv", "el", "en", "es", "et", "eu", "fa", "fi", "fil", "fj", "fo", "fr", "fr-CA", "ga", "gl", "gu", "ha", "he", "hi", "hr", "hsb", "ht", "hu", "hy", "id", "ig", "ikt", "is", "it", "iu", "iu-Latn", "ja", "ka", "kk", "km", "kmr", "kn", "ko", "ku", "ky", "ln", "lo", "lt", "lug", "lv", "lzh", "mg", "mi", "mk", "ml", "mn-Cyrl", "mn-Mong", "mr", "ms", "mt", "mww", "my", "nb", "ne", "nl", "nso", "nya", "or", "otq", "pa", "pl", "prs", "ps", "pt", "pt-PT", "ro", "ru", "run", "rw", "sk", "sl", "sm", "sn", "so", "sq", "sr-Cyrl", "sr-Latn", "st", "sv", "sw", "ta", "te", "th", "ti", "tk", "tlh-Latn", "tlh-Piqd", "tn", "to", "tr", "tt", "ty", "ug", "uk", "ur", "uz", "vi", "xh", "yo", "yua", "yue", "zh-Hans", "zh-Hant", "zu"]
|
||||
```
|
||||
|
||||
De todos los idiomas que actualmente tiene Consul Democracy definidos (`available_locales`) en `config/application.rb` el único que no está en la lista anterior y por lo tanto no se ofrece servicio de traducción es el valenciano `["val"]`.
|
||||
|
||||
### Costes
|
||||
|
||||
El servicio de traducción utilizado tiene los [precios](https://azure.microsoft.com/es-es/pricing/details/cognitive-services/translator/) más competitivos del mercado.
|
||||
El precio por cada 1 Millón de caracteres traducidos asciende a 10 $ y sin ningún tipo de coste fijo al mes.
|
||||
|
||||
Aunque se han tomado medidas técnicas para evitar un mal uso de este servicio, recomendamos la creación de Alertas que ofrece Azure para que un Administrador pueda ser notificado en el caso de detectar un uso fuera de lo común del servicio. Este servicio tiene un coste de 0,10 $ al mes.
|
||||
|
||||
Para crear una Alerta en Azure debemos seguir los siguientes pasos:
|
||||
|
||||
1. Inicie sesión en **Azure Portal**.
|
||||
1. Accede al servicio **Traductor** creado anteriormente.
|
||||
1. Accede en el menu lateral a **Supervisión > Alertas**:
|
||||
1. Accedemos a **Crear regla de alertas**
|
||||
1. En **Selección de una señal** seleccionamos `Text Characters Translated`
|
||||
1. Una vez seleccionada debemos definir la lógica de la Alerta para que se ajuste a nuestras necesidades. Ej: Rellene el campo "Operador" con el valor "Mayor que", rellene el campo "Tipo de Agregación" con el valor "Total" y por último rellene el campo "Valor del umbral" por el número de caracteres que consideramos que deben traducirse antes de ser notificados. En esta sección también se puede configurar el periodo de tiempo y la frecuencia de evaluación.
|
||||
1. Para poder ser notificados tenemos que crear un **Grupo de Acciones** y asociarla a esta Alerta que estamos creando. Para ello accedemos al botón de **Crear** y rellenamos el formulario. Como se puede observar hay diferentes tipos de acciones, debemos seleccionar **Correo electrónico/SMS/Insertar/Voz** y configurar la opción que consideremos conveniente según nuestras necesidades.
|
||||
1. Una vez creado este grupo de acciones, ya queda directamente asociado a la regla que estamos creando.
|
||||
1. Por último ya solo queda añadir un nombre y clicar sobre el botón **Revisar y crear**
|
||||
|
||||
### Añadir un nuevo servicio de traducción
|
||||
|
||||
En el caso de que se quieran integrar más servicios de traducción por cualquier motivo (aparece un nuevo en el mercado más competitivo, se quiere cambiar para contemplar los idiomas que actualmente no tienen soporte, etc) se ha dejado preparado el código para poder añadirlo con las mínimas modificaciones posibles.
|
||||
Esto es posible gracias a la class `RemoteTranslations::Caller` que es una capa intermedia entre la gestión de los contenidos sin traducir y el Cliente de traducción de Microsoft utilizado actualmente.
|
||||
Una buena solución para añadir otro servicio de traducción sería sustituir la llamada al `MicrosoftTranslateClient` dentro del método `translations` del `RemoteTranslations::Caller` por el nuevo servicio implementado.
|
||||
En caso de querer convivir con ambos sólo debería gestionarse en que caso queremos utilizar uno u otro, ya sea mediante condiciones especificas en el código o mediante una gestión en los Settings de la aplicación.
|
||||
|
||||
```ruby
|
||||
class RemoteTranslationsCaller
|
||||
|
||||
...
|
||||
def translations
|
||||
@translations ||= RemoteTranslations::Microsoft::Client.new.call(fields_values, locale)
|
||||
# Add new RemoteTranslations Client
|
||||
# @translations = RemoteTranslations::NewTranslateClient::Client.new.call(fields_values, locale_to)
|
||||
end
|
||||
...
|
||||
|
||||
end
|
||||
```
|
||||
|
||||
## Interfaz de traducción
|
||||
|
||||
Esta funcionalidad permite a los usuarios introducir contenidos dinámicos en diferentes idiomas a la vez. Cualquier usuario administrador de Consul Democracy puede activar o desactivar esta funcionalidad a través del panel de administración de la aplicación. Si desactivas esta funcionalidad (configuración de la funcionalidad por defecto) los usuarios sólo podrán introducir un idioma.
|
||||
|
||||
### Activar funcionalidad
|
||||
|
||||
Para activar la funcionalidad deberá realizar 2 pasos:
|
||||
|
||||
1. Ejecutar el siguiente comando `bin/rake settings:create_translation_interface_setting RAILS_ENV=production` (Este paso sólo es necesario para instalaciones de Consul Democracy existentes que incorporan esta funcionalidad, para nuevas instalaciones no es necesario)
|
||||
1. Accedediendo como usuario administrador a través del panel de administración de su aplicación a la sección **Configuración > Funcionalidades** y activando el módulo de **Interfaz de traducción** como se puede ver a continuación:
|
||||
|
||||
|
||||
### Casos de uso
|
||||
|
||||
Dependiendo de si activamos o desactivamos el módulo de **Interfaz de traducción** veremos los formularios accesibles por el usuario de la siguiente manera:
|
||||
|
||||
* Cuando la interfaz de traducción esta activa:
|
||||
Como podemos ver en la imagen a continuación la interfaz de traducción tiene 2 selectores, el primero "Seleccionar idioma" permite cambiar entre los lenguajes activos y el segundo selector "Añadir idioma" permite añadir nuevos idiomas al formulario. Los campos traducibles se pueden distinguir fácilmente mediante un fondo azul de los que no lo son. También disponemos de un botón `Eliminar idioma` para eliminar un idioma en caso de necesitarlo. Si un usuario elimina accidentalmente un idioma puede recuperarlo añadiendo dicho idioma otra vez al formulario.
|
||||
Esta funcionalidad está visible tanto para las páginas de creación como para las páginas de edición.
|
||||
|
||||
|
||||
* Cuando la interfaz de traducción esta desactivada:
|
||||
Cuando esta funcionalidad está desactivada los formularios se renderizan sin la interfaz de traducción y sin resaltar los campos traducibles con fondo azul.
|
||||
|
||||
|
||||
125
docs/es/features/user_content_translations.md
Normal file
125
docs/es/features/user_content_translations.md
Normal file
@@ -0,0 +1,125 @@
|
||||
# Traducciones de contenido de usuario
|
||||
|
||||
## Traducciones remotas bajo demanda del usuario
|
||||
|
||||
Este servicio tiene como objetivo poder ofrecer todos los contenidos dinámicos de la aplicación (propuestas, debates, inversiones presupuestarias y comentarios) en diferentes idiomas sin la necesidad de que un usuario ó un administrador haya creado cada una de sus traducciones.
|
||||
|
||||
Cuando un usuario accede a una pantalla con un idioma donde parte del contenido dinámico que esta visualizando no tiene traducciones, dispondrá de un botón para solicitar la traducción de todo el contenido. Este contenido se enviará a un traductor automático (en este caso [Microsoft TranslatorText](https://azure.microsoft.com/es-es/products/cognitive-services/translator/)) y en cuanto se obtenga la respuesta, todas estas traducciones estarán disponibles para cualquier usuario.
|
||||
|
||||
### Como empezar
|
||||
|
||||
Para poder utilizar esta funcionalidad es necesario realizar los siguientes pasos:
|
||||
|
||||
1. Disponer de una api key para conectarse con el servicio de traducción. Para ello necesitamos una [cuenta en Azure](https://azure.microsoft.com/es-es/)
|
||||
1. Una vez que haya iniciado sesión en el portal de Azure, subscríbase a Traductor en Cognitive Services.
|
||||
1. Una vez subscrito al servicio de Translator Text, tendrá accesibles 2 api keys en la sección **Administración de recursos > Claves y punto de conexión** que serán necesarias para la configuración del servicio de traducciones en su aplicación.
|
||||
|
||||
### Configuración
|
||||
|
||||
Para activar el servicio de traducciones en su aplicación debe completar los siguientes pasos
|
||||
|
||||
#### Añadir api key en la aplicación
|
||||
|
||||
En el apartado anterior hemos comentado que una vez subscritos al servicio de traducciones disponemos de 2 api keys. Para configurar el servicio correctamente en nuestra aplicación deberemos añadir una de las dos api keys en el archivo `secrets.yml` en la sección `apis:` con la key `microsoft_api_key` como podemos ver en la siguiente imágen:
|
||||
|
||||
|
||||
|
||||
#### Activar funcionalidad
|
||||
|
||||
Una vez disponemos de la nueva key en el `secrets.yml` ya podemos proceder a activar la funcionalidad. Para activar la funcionalidad deberá realizar 2 pasos:
|
||||
|
||||
1. Ejecutar el siguiente comando `bin/rake settings:create_remote_translations_setting RAILS_ENV=production`
|
||||
1. Acceder a través del panel de administración de su aplicación a la sección **Configuración > Funcionalidades** y activar el módulo de **Traducciones Remotas** como se puede ver a continuación:
|
||||
|
||||
|
||||
### Funcionalidad
|
||||
|
||||
Una vez tenemos la api key en nuestro `secrets.yml` y el módulo activado, los usuarios ya podrán utilizar la funcionalidad.
|
||||
Para aclarar el funcionamiento, se adjuntan unos pantallazos de como interactua la aplicación con nuestros usuarios:
|
||||
|
||||
* Cuando un usuario accede a una pantalla en un idioma en el que no están disponibles todas las traducciones, le aparecerá un texto en la parte superior de la pantalla y un botón para poder solicitar la traducción. (**Nota:** *En el caso de acceder con un idioma no soportado por el servicio de traducción no se mostrará ningún texto ni botón de traducción. Ver sección: Idiomas disponibles para la traducción remota*)
|
||||
|
||||
|
||||
* Una vez el usuario pulsa el botón de `Traducir página` se encolan las traducciones y se recarga la pantalla con un notice (*informando que se han solicitado correctamente las traducciones*) y un texto informativo en la cabecera (*explicando cuando podrá ver estas traducciones*).
|
||||
|
||||
|
||||
* Si un usuario accede a una pantalla que no dispone de traducciones pero ya han sido solicitadas por otro usuario. La aplicación no le mostrará el botón de traducir, pero si un texto informativo en la cabecera (*explicando cuando podrá ver estas traducciones*).
|
||||
|
||||
|
||||
* Las peticiones de traducción se delegan a `Delayed Job` y en cuanto haya sido procesada, el usuario después de refrescar su página podrá ver el contenido traducido.
|
||||
|
||||
|
||||
### Idiomas disponibles para la traducción remota
|
||||
|
||||
Actualmente estos son todos los [idiomas disponibles](https://api.cognitive.microsofttranslator.com/languages?api-version=3.0) en el servicio de traducción:
|
||||
|
||||
```yml
|
||||
["af", "am", "ar", "as", "az", "ba", "bg", "bn", "bo", "bs", "ca", "cs", "cy", "da", "de", "dv", "el", "en", "es", "et", "eu", "fa", "fi", "fil", "fj", "fo", "fr", "fr-CA", "ga", "gl", "gu", "ha", "he", "hi", "hr", "hsb", "ht", "hu", "hy", "id", "ig", "ikt", "is", "it", "iu", "iu-Latn", "ja", "ka", "kk", "km", "kmr", "kn", "ko", "ku", "ky", "ln", "lo", "lt", "lug", "lv", "lzh", "mg", "mi", "mk", "ml", "mn-Cyrl", "mn-Mong", "mr", "ms", "mt", "mww", "my", "nb", "ne", "nl", "nso", "nya", "or", "otq", "pa", "pl", "prs", "ps", "pt", "pt-PT", "ro", "ru", "run", "rw", "sk", "sl", "sm", "sn", "so", "sq", "sr-Cyrl", "sr-Latn", "st", "sv", "sw", "ta", "te", "th", "ti", "tk", "tlh-Latn", "tlh-Piqd", "tn", "to", "tr", "tt", "ty", "ug", "uk", "ur", "uz", "vi", "xh", "yo", "yua", "yue", "zh-Hans", "zh-Hant", "zu"]
|
||||
```
|
||||
|
||||
De todos los idiomas que actualmente tiene Consul Democracy definidos (`available_locales`) en `config/application.rb` el único que no está en la lista anterior y por lo tanto no se ofrece servicio de traducción es el valenciano `["val"]`.
|
||||
|
||||
### Costes
|
||||
|
||||
El servicio de traducción utilizado tiene los [precios](https://azure.microsoft.com/es-es/pricing/details/cognitive-services/translator/) más competitivos del mercado.
|
||||
El precio por cada 1 Millón de caracteres traducidos asciende a 10 $ y sin ningún tipo de coste fijo al mes.
|
||||
|
||||
Aunque se han tomado medidas técnicas para evitar un mal uso de este servicio, recomendamos la creación de Alertas que ofrece Azure para que un Administrador pueda ser notificado en el caso de detectar un uso fuera de lo común del servicio. Este servicio tiene un coste de 0,10 $ al mes.
|
||||
|
||||
Para crear una Alerta en Azure debemos seguir los siguientes pasos:
|
||||
|
||||
1. Inicie sesión en **Azure Portal**.
|
||||
1. Accede al servicio **Traductor** creado anteriormente.
|
||||
1. Accede en el menu lateral a **Supervisión > Alertas**:
|
||||
1. Accedemos a **Crear regla de alertas**
|
||||
1. En **Selección de una señal** seleccionamos `Text Characters Translated`
|
||||
1. Una vez seleccionada debemos definir la lógica de la Alerta para que se ajuste a nuestras necesidades. Ej: Rellene el campo "Operador" con el valor "Mayor que", rellene el campo "Tipo de Agregación" con el valor "Total" y por último rellene el campo "Valor del umbral" por el número de caracteres que consideramos que deben traducirse antes de ser notificados. En esta sección también se puede configurar el periodo de tiempo y la frecuencia de evaluación.
|
||||
1. Para poder ser notificados tenemos que crear un **Grupo de Acciones** y asociarla a esta Alerta que estamos creando. Para ello accedemos al botón de **Crear** y rellenamos el formulario. Como se puede observar hay diferentes tipos de acciones, debemos seleccionar **Correo electrónico/SMS/Insertar/Voz** y configurar la opción que consideremos conveniente según nuestras necesidades.
|
||||
1. Una vez creado este grupo de acciones, ya queda directamente asociado a la regla que estamos creando.
|
||||
1. Por último ya solo queda añadir un nombre y clicar sobre el botón **Revisar y crear**
|
||||
|
||||
### Añadir un nuevo servicio de traducción
|
||||
|
||||
En el caso de que se quieran integrar más servicios de traducción por cualquier motivo (aparece un nuevo en el mercado más competitivo, se quiere cambiar para contemplar los idiomas que actualmente no tienen soporte, etc) se ha dejado preparado el código para poder añadirlo con las mínimas modificaciones posibles.
|
||||
Esto es posible gracias a la class `RemoteTranslations::Caller` que es una capa intermedia entre la gestión de los contenidos sin traducir y el Cliente de traducción de Microsoft utilizado actualmente.
|
||||
Una buena solución para añadir otro servicio de traducción sería sustituir la llamada al `MicrosoftTranslateClient` dentro del método `translations` del `RemoteTranslations::Caller` por el nuevo servicio implementado.
|
||||
En caso de querer convivir con ambos sólo debería gestionarse en que caso queremos utilizar uno u otro, ya sea mediante condiciones especificas en el código o mediante una gestión en los Settings de la aplicación.
|
||||
|
||||
```ruby
|
||||
class RemoteTranslationsCaller
|
||||
|
||||
...
|
||||
def translations
|
||||
@translations ||= RemoteTranslations::Microsoft::Client.new.call(fields_values, locale)
|
||||
# Add new RemoteTranslations Client
|
||||
# @translations = RemoteTranslations::NewTranslateClient::Client.new.call(fields_values, locale_to)
|
||||
end
|
||||
...
|
||||
|
||||
end
|
||||
```
|
||||
|
||||
## Interfaz de traducción
|
||||
|
||||
Esta funcionalidad permite a los usuarios introducir contenidos dinámicos en diferentes idiomas a la vez. Cualquier usuario administrador de Consul Democracy puede activar o desactivar esta funcionalidad a través del panel de administración de la aplicación. Si desactivas esta funcionalidad (configuración de la funcionalidad por defecto) los usuarios sólo podrán introducir un idioma.
|
||||
|
||||
### Activar funcionalidad
|
||||
|
||||
Para activar la funcionalidad deberá realizar 2 pasos:
|
||||
|
||||
1. Ejecutar el siguiente comando `bin/rake settings:create_translation_interface_setting RAILS_ENV=production` (Este paso sólo es necesario para instalaciones de Consul Democracy existentes que incorporan esta funcionalidad, para nuevas instalaciones no es necesario)
|
||||
1. Accedediendo como usuario administrador a través del panel de administración de su aplicación a la sección **Configuración > Funcionalidades** y activando el módulo de **Interfaz de traducción** como se puede ver a continuación:
|
||||
|
||||
|
||||
### Casos de uso
|
||||
|
||||
Dependiendo de si activamos o desactivamos el módulo de **Interfaz de traducción** veremos los formularios accesibles por el usuario de la siguiente manera:
|
||||
|
||||
* Cuando la interfaz de traducción esta activa:
|
||||
Como podemos ver en la imagen a continuación la interfaz de traducción tiene 2 selectores, el primero "Seleccionar idioma" permite cambiar entre los lenguajes activos y el segundo selector "Añadir idioma" permite añadir nuevos idiomas al formulario. Los campos traducibles se pueden distinguir fácilmente mediante un fondo azul de los que no lo son. También disponemos de un botón `Eliminar idioma` para eliminar un idioma en caso de necesitarlo. Si un usuario elimina accidentalmente un idioma puede recuperarlo añadiendo dicho idioma otra vez al formulario.
|
||||
Esta funcionalidad está visible tanto para las páginas de creación como para las páginas de edición.
|
||||
|
||||
|
||||
* Cuando la interfaz de traducción esta desactivada:
|
||||
Cuando esta funcionalidad está desactivada los formularios se renderizan sin la interfaz de traducción y sin resaltar los campos traducibles con fondo azul.
|
||||
|
||||
Reference in New Issue
Block a user