Add Remote Translations docs(EN)

docs/en/customization/introduction.md

@@ -21,3 +21,82 @@ 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 an user visit a page with a language where there is untranslated content, he will has 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/services/cognitive-services/translator-text-api/)) 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 Text API in Microsoft 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** 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:
+
+![Add api key to secrets](../../img/translations/remote_translations/add-api-key-to-secrets.png)
+
+##### 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:
+![Active remote translations](../../img/translations/remote_translations/active-remote-translations-es.png)
+
+#### 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*)
+![Display text and button](../../img/translations/remote_translations/display-text-and-button-es.png)
+
+* 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*).
+![Display notice and text after enqueued translations](../../img/translations/remote_translations/display-notice-and-text-after-enqueued-es.png)
+
+* 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*).
+![Display text explaining that translations are pending](../../img/translations/remote_translations/display-text-translations-pending-es.png)
+
+* 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.
+![Display translated content](../../img/translations/remote_translations/display-translated-content-es.png)
+
+
+#### Available languages for remote translation
+Currently these are all the [available languages](https://docs.microsoft.com/en-us/azure/cognitive-services/translator/quickstart-ruby-languages) in the translation service:
+```yml
+["af", "ar", "bg", "bn", "bs", "ca", "cs", "cy", "da", "de", "el", "en", "es", "et", "fa", "fi", "fil", "fj", "fr", "he", "hi", "hr", "ht", "hu", "id", "is", "it", "ja", "ko", "lt", "lv", "mg", "ms", "mt", "mww", "nb", "nl", "otq", "pl", "pt", "ro", "ru", "sk", "sl", "sm", "sr-Cyrl", "sr-Latn", "sv", "sw", "ta", "te", "th", "tlh", "to", "tr", "ty", "uk", "ur", "vi", "yua", "yue", "zh-Hans", "zh-Hant"]
+```
+Of all the languages that Consul currently has defined(`available_locales`) in `config/application.rb` are not included in the above list and no translation service is offered for the following languages:
+```yml
+["val", "gl", "sq"]
+```
+
+#### Pricing
+The translation service used has the [pricing](https://azure.microsoft.com/en-us/pricing/details/cognitive-services/translator-text-api/) the most competitive.
+The price for each 1 Million characters translated is 8.43 € and there is no fixed cost per month.
+Google and DeepL have an approximate price of between 16.00 € and 20.00 € for each 1 million characters and a fixed monthly cost.
+
+Alerts can be created on several parameters, including the `Number of translated characters` within the Azure administration panel in the **Supervision** section.
+
+#### 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
+```   

docs/es/customization/introduction.md

@@ -24,7 +24,7 @@ Aparte de estos directorios también cuentas con ciertos ficheros para:
 
 ## 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.
+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/services/cognitive-services/translator-text-api/)) y en cuanto se obtenga la respuesta, todas estas traducciones estarán disponibles para cualquier usuario.
 
@@ -43,12 +43,10 @@ En el apartado anterior hemos comentado que una vez subscritos al servicio de tr
 ![Add api key to secrets](../../img/translations/remote_translations/add-api-key-to-secrets.png)
 
 ##### Activar funcionalidad
-Una vez disponemos de la nueva key en el `secrets.yml` ya podemos proceder a activar la funcionalidad. Podemos activarla de dos maneras diferentes con idéntico resultado:
+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. Accediendo a través del panel de administración de su aplicación en la sección **Configuración > Funcionalidades** y activar el módulo de **Traducciones Remotas** como se puede ver a continuación:
+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:
 ![Active remote translations](../../img/translations/remote_translations/active-remote-translations-es.png)
-1. O bien ejecutando el siguiente comando `bin/rake settings:enable_remote_translations RAILS_ENV=production`
-
-Con ambas opciones se activa el módulo y empezará a estar operativa la funcionalidad para nuestros usuarios.
 
 #### Funcionalidad
 Una vez tenemos la api key en nuestro `secrets.yml` y el módulo activado, los usuarios ya podrán utilizar la funcionalidad.
@@ -85,28 +83,19 @@ Aunque el precio parece asequible para un Ayuntamiento, se pueden crear Alertas
 
 #### 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 `RemoteTranslationsCaller` que es una capa intermedia entre la gestión de los contenidos sin traducir y el Cliente de traducción de Microsoft utilizado actualmente.
+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 `call` del `RemoteTranslationsCaller` por el nuevo servicio implementado.
+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
-  attr_accessor :available_remote_locales
 
-  def call(remote_translation)
+  ...
-    resource = remote_translation.remote_translatable
+  def translations
-    fields_values = prepare_fields_values(resource)
+    @translations ||= RemoteTranslations::Microsoft::Client.new.call(fields_values, locale)
-    locale_to = remote_translation.locale
+    # Add new RemoteTranslations Client
-
+    # @translations = RemoteTranslations::NewTranslateClient::Client.new.call(fields_values, locale_to)
-    translations = MicrosoftTranslateClient.new.call(fields_values, locale_to)
-    #Add new Translate Client
-    #translations = NewTranslateClient.new.call(fields_values, locale_to)
-
-
-    update_resource(resource, translations, locale_to)
-    destroy_remote_translation(resource, remote_translation)
   end
-
   ...
 
 end