Merge pull request #5699 from consuldemocracy/multitenancy_docs

Update multitenancy documentation

docs/en/features/multitenancy.md

@@ -4,13 +4,13 @@
 
 The multitenancy feature allows managing several independent institutions ("tenants") using the same application. For example, in our case, a user who signs up for a certain tenant will only be able to sign in on that tenant, and that user's data won't be available from any other tenant.
 
-Which tenant we're accessing depends on the URL we're using in the browser to access the application. In Consul Democracy, the current tenant is established by the subdomain used in this URL. For example, if we used the domain `solarsystemexample.org` to manage the planets in the Solar System, using the URL `https://mercury.solarsystemexample.org` we'd access data from the planet Mercury while using the URL `https://venus.solarsystemexample.org` we'd access data from the planet Venus. It's also be possible to use different domains per tenant (for example, `earthexample.org`).
+Which tenant we're accessing depends on the URL we're using in the browser to access the application. In Consul Democracy, the current tenant is established by the subdomain used in this URL. For example, if we used the domain `solarsystemexample.org` to manage the planets in the Solar System, using the URL `https://mercury.solarsystemexample.org` we'd access data from the planet Mercury, while using the URL `https://venus.solarsystemexample.org` we'd access data from the planet Venus. It's also possible to use different domains per tenant (for example, `earthexample.org`).
 
 ## Enabling multitenancy
 
 ### Preliminary steps after upgrading from Consul Democracy version 1.5.0
 
-If you're upgrading a Consul Democracy installation to version 2.0.0 from version 1.5.0, you'll have to follow these steps before enabling multitenancy. These steps aren't necessary on new Consul Democracy installations.
+If you're upgrading a Consul Democracy installation to version 2.0.0 from version 1.5.0, you'll have to follow these steps before enabling multitenancy. These steps aren't necessary on Consul Democracy installations that used version 2.0.0 or later as their initial version.
 
 First, after deploying version 2.0.0 to your production server, execute the release tasks:
 
@@ -18,7 +18,7 @@ First, after deploying version 2.0.0 to your production server, execute the rele
 RAILS_ENV=production bin/rails consul:execute_release_tasks
 ```
 
-After runing this command, you might get the following warning:
+After running this command, you might get the following warning:
 
 > The database search path has been updated. Restart the application to apply the changes.
 
@@ -86,7 +86,7 @@ In order to make it possible to access the application using secure HTTPS/SSL co
 
 If you've installed Consul Democracy using the installer and are using Certbot to manage these certificates, you have two options.
 
-One option would be adding each certificate manually every time you create a tenant. For example, in orer to add a tenant using the `mars` subdomain in the `solarsystemexample.org` domain, run:
+One option would be adding each certificate manually every time you create a tenant. For example, in order to add a tenant using the `mars` subdomain in the `solarsystemexample.org` domain, run:
 
 ```bash
 sudo certbot certonly --nginx --noninteractive --agree-tos --expand -d solarsystemexample.org,mars.solarsystemexample.org
@@ -104,7 +104,7 @@ After doing so, update your web server configuration file (by default `/etc/ngin
 
 ### Sending e-mails
 
-In order to reduce the chance your application sends emails which are erronously identified as spam, you might want to edit the fields "Sender email name" and "Sender email address" in the administration panel of the new tenant. The default values for these fields are the name and subdomain introduced when creating the tenant.
+In order to reduce the chance your application sends emails which are erroneously identified as spam, you might want to edit the fields "Sender email name" and "Sender email address" in the administration panel of the new tenant. The default values for these fields are the name and subdomain introduced when creating the tenant.
 
 ![Fields to edit sender email name and address](../../img/multitenancy/email-settings-en.png)
 
@@ -158,13 +158,37 @@ production:
 
 After editing this file, restart the application.
 
+### Enabling different languages for different tenants
+
+In Consul Democracy 2.2.0 or later, it's possible to display the application in different languages for different tenants.
+
+By default, every tenant uses all the languages defined in `config/application.rb`. You can (optionally) overwrite this value by [customizing your application configuration](../customization/application.md). Note that **if you overwrite this value, tenants will only be able to enable the languages you define here**. So, for instance, with this code in the `config/application_custom.rb` file:
+
+```ruby
+module Consul
+  class Application < Rails::Application
+    config.i18n.available_locales = ["de", "en", "es", "fr", "it", "ru", "zh-CN"]
+  end
+end
+```
+
+After restarting the application, tenants will be able to choose which language is the default and which ones are enabled among German, English, Spanish, French, Italian, Russian and Simplified Chinese. However, they'll no longer be able to enable any other language.
+
+To define the default and the enabled languages for a tenant, go the administration area of that tenant. Then, on the side navigation menu, click on "Settings" and then click on "Languages". Note that **this section is not present if you only have one language in `available_locales`**.
+
+On this page you'll find a form to choose the default and the enabled languages for this tenant (note: this form changes slightly when only a few languages are available):
+
+![Form with a select control for the default language and a list of checkboxes to choose which ones to enable](../../img/multitenancy/languages-en.png)
+
+Choose the ones you'd like, save the changes, and the language selector at the top of the web will be updated immediately.
+
 ## Information to take into account during development
 
 ### Maintenance of the schema.rb file
 
-When Consul Democracy creates a tenant, it loads the content of the `db/schema.rb` file to create a new database schema for the new tenant. This means that if for some reason this file doesn't contain the same database structure you'd get by creating a new database and running the migrations with `rake db:migrate`, you could end up with different database table or columns on different tenants. This could result in a disastrous situation.
+When Consul Democracy creates a tenant, it loads the content of the `db/schema.rb` file to create a new database schema for the new tenant. This means that if for some reason this file doesn't contain the same database structure you'd get by creating a new database and running the migrations with `rake db:migrate`, you could end up with different database tables or columns on different tenants. This could result in a disastrous situation.
 
-In order to avoid it, we recommend checking the integrity of the `db/schema.rb` file in your continuous integration system. If you're doing continuous intergration using GitHub Actions, you can use the workflow already included in Consul Democracy. Pull requests adding this check on GitLab CI or other continuous intergration environments are welcome.
+In order to avoid it, we recommend checking the integrity of the `db/schema.rb` file in your continuous integration system. If you're doing continuous integration using GitHub Actions, you can use the workflow already included in Consul Democracy. Pull requests adding this check on GitLab CI or other continuous integration environments are welcome.
 
 ### Using custom styles for a tenant with CSS
 
@@ -227,13 +251,7 @@ However, this will only work for images which can already be configured through
 
 In Consul Democracy 2.0.0, data from all tenants is stored in the same database and so it isn't possible to use several databases on different servers.
 
-If this feature is requested often, it'll be possible to include it in Consul Democracy in the future. However, Consul Democracy 2.0.0 uses Rails 6.0 and this feature will require upgrading to Rails 6.1 or even Rails 7.0.
+If this feature is requested often, it'll be possible to include it in Consul Democracy in the future, since Rails 6.1 and Rails 7.0 added better support for it.
-
-### Different languages per tenant
-
-In Consul Democracy 2.0.0, every tenant is available in the same languages, so it wouldn't be possible (for instance) to enable French in one tenant and German in a different one; you'd have to enable both languages in both tenants.
-
-Implementing this feature is planned for Consul Democracy 2.1.0.
 
 ### Deleting tenants
 

docs/es/features/multitenancy.md

@@ -22,7 +22,7 @@ Es posible que, tras ejecutar esta orden, veas el siguiente aviso:
 
 > The database search path has been updated. Restart the application to apply the changes.
 
-Si es así, reincia la aplicación. Si no has recibido este aviso, comprueba que el fichero `config/database.yml` contiene la línea `schema_search_path: "public,shared_extensions"` y, de no ser así, añádela por ejemplo bajo la línea que dice `adapter: postgresql` y reincia la aplicación.
+Si es así, reinicia la aplicación. Si no has recibido este aviso, comprueba que el fichero `config/database.yml` contiene la línea `schema_search_path: "public,shared_extensions"` y, de no ser así, añádela por ejemplo bajo la línea que dice `adapter: postgresql` y reinicia la aplicación.
 
 Una vez hecho esto, deberás abrir una consola de base de datos utilizando un usuario que tenga permisos para crear y modificar extensiones de base de datos:
 
@@ -158,6 +158,30 @@ production:
 
 Tras editar el fichero, reinicia la aplicación.
 
+### Habilitar idiomas distintos para distintas entidades
+
+En Consul Democracy 2.2.0 o posterior, es posible mostrar la aplicación en diferentes idiomas para diferentes entidades.
+
+Por defecto, todas las entidades utilizan todos los idiomas definidos en `config/application.rb`. Puedes (de forma opcional) sobrescribir este valor [personalizando la configuración de tu aplicación](../customization/application.md). Ten en cuenta que **si sobrescribes este valor, las entidades solamente podrán habilitar los idiomas que definas**. Por ejemplo, si ponemos este código en el fichero `config/application_custom.rb`:
+
+```ruby
+module Consul
+  class Application < Rails::Application
+    config.i18n.available_locales = ["de", "en", "es", "fr", "it", "ru", "zh-CN"]
+  end
+end
+```
+
+Tras reiniciar la aplicación, con esto las entidades podrán escoger cuál es el idioma por defecto y cuáles están habilitados entre alemán, inglés, español, francés, italiano, ruso y chino simplificado. Sin embargo, ya no podrán habilitar ningún otro idioma.
+
+Para definir el idioma por defecto y los idiomas habilitados en una entidad, accede al área de administración de esa entidad. Una vez allí, en el menú de navegación, pincha en "Configuración" y a continuación pincha en "Idiomas". Ten en cuenta que **está sección no aparecerá si solamente tienes un idioma en `available_locales`**.
+
+En esta página encontrarás un formulario para elegir el idioma por defecto y los idiomas habilitados para esta entidad (nota: el formulario es un tanto distinto cuando hay pocos idiomas disponibles):
+
+![Formulario con un selector para el idioma por defecto y una lista de casillas para seleccionar qué idiomas habilitar](../../img/multitenancy/languages-es.png)
+
+Tras elegir los idiomas, guarda los cambios, y el selector de idiomas en la parte superior de la página se actualizará de forma inmediata.
+
 ## Información a tener en cuenta al realizar desarrollos
 
 ### Mantenimiento del fichero schema.rb
@@ -229,12 +253,6 @@ En la versión 2.0.0 de Consul Democracy, los datos de todas las entidades se al
 
 En caso de que esta funcionalidad sea suficientemente solicitada, podrá incluirse en Consul Democracy en el futuro. Hay que tener en cuenta que la versión 2.0.0 de Consul Democracy utiliza Rails 6.0 y que para esta funcionalidad será necesario usar Rails 6.1 o incluso Rails 7.0.
 
-### Idiomas distintos para distintas entidades
-
-En la versión 2.0.0 de COSNSUL, todas las entidades están disponibles en los mismos idiomas, con lo que no sería posible (por ejemplo) que una entidad estuviera disponible en francés y otra en alemán, sino que ambas tendrían que estar disponibles en ambos idiomas.
-
-Implementar esta posibilidad está planeado para la versión 2.1.0 de Consul Democracy.
-
 ### Borrado de entidades
 
 Dado que eliminar una entidad borraría **todos** los datos relacionados con esa entidad y no se podrían restaurar, Consul Democracy no ofrece la opción de eliminar una entidad ya creada desde el panel de administración y solamente permite deshabilitarlas para que no sea posible acceder a ellas. Para eliminar una entidad, utiliza la consola de Rails.