consul/nairobi
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

GitBook: [master] 86 pages and 110 assets modified

Browse Source
This commit is contained in:
consuldocs
2020-07-14 22:51:03 +00:00
committed by gitbook-bot
parent 06fe16d6b4
commit 5ed5960428
196 changed files with 5304 additions and 122 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
docs/spanish-documentation/customization/README.md Normal file
View File

@@ -0,0 +1,11 @@
# Personalización
* [Introducción](introduction.md)
* [Textos & Traducciones](translations.md)
* [Imágenes](images.md)
* [Vistas & Estilos](views_and_styles.md)
* [Javascript](javascript.md)
* [Modelos](models.md)
* [Gemas](gems.md)
* [Adaptar la aplicación](overwritting.md)

10
docs/spanish-documentation/customization/gems.md Normal file
View File

@@ -0,0 +1,10 @@
# Gemas
Para agregar librerías \(gems\) nuevas puedes hacerlo en el fichero `Gemfile_custom`. Por ejemplo si quieres agregar la gema [rails-footnotes](https://github.com/josevalim/rails-footnotes) debes hacerlo agregandole
```ruby
gem 'rails-footnotes', '~> 4.0'
```
Y siguiendo el flujo clásico en Ruby on Rails \(`bundle install` y seguir con los pasos específicos de la gema en la documentación\)

18
docs/spanish-documentation/customization/images.md Normal file
View File

@@ -0,0 +1,18 @@
# Imágenes
Si quieres sobreescribir alguna imagen debes primero fijarte el nombre que tiene, por defecto se encuentran en `app/assets/images`. Por ejemplo si quieres modificar `app/assets/images/logo_header.png` debes poner otra con ese mismo nombre en el directorio `app/assets/images/custom`. Los iconos que seguramente quieras modificar son:
* apple-touch-icon-200.png
* icon\_home.png
* logo\_email.png
* logo\_header.png
* map.jpg
* social\_media\_icon.png
* social\_media\_icon\_twitter.png
## Mapa de la ciudad
Puedes encontrar el mapa de la ciudad en [`/app/assets/images/map.jpg`](https://github.com/consul/consul/blob/master/app/assets/images/map.jpg), simplemente reemplazalo con una imagen de los distritos de tu ciudad \([ejemplo](https://github.com/ayuntamientomadrid/consul/blob/master/app/assets/images/map.jpg)\).
Después te recomendamos utilizar una herramienta online como [http://imagemap-generator.dariodomi.de/](http://imagemap-generator.dariodomi.de/) o [https://www.image-map.net/](https://www.image-map.net/) para generar las coordenadas para poder establecer un [image-map](https://www.w3schools.com/tags/tag_map.asp) sobre cada distrito. Estas coordenadas deben ser introducidas en la respectiva Geozona creada en el panel de administración \(`/admin/geozones`\)

112
docs/spanish-documentation/customization/introduction.md Normal file
View File

@@ -0,0 +1,112 @@
# Introducción
Puedes modificar CONSUL y ponerle tu propia imagen, para esto debes primero [crear tu propio fork](../getting_started/create.md).
Hemos creado una estructura específica donde puedes sobreescribir y personalizar la aplicación para que puedas actualizar sin que tengas problemas al hacer merge y se sobreescriban por error tus cambios. Intentamos que CONSUL sea una aplicación Ruby on Rails lo más plain vanilla posible para facilitar el acceso de nuevas desarrolladoras.
## Ficheros y directorios especiales
Para adaptar tu fork de CONSUL puedes utilizar alguno de los directorios `custom` que están en las rutas:
* `config/locales/custom/`
* `app/assets/images/custom/`
* `app/views/custom/`
* `app/controllers/custom/`
* `app/models/custom/`
Aparte de estos directorios también cuentas con ciertos ficheros para:
* `app/assets/stylesheets/custom.css`
* `app/assets/stylesheets/_custom_settings.css`
* `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/services/cognitive-services/translator-text-api/)\) 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 Translator Text API en Microsoft Cognitive Service. 1. Una vez subscrito al servicio de Translator Text, tendrá accesibles 2 api keys en la sección **RESOURCE MANAGEMENT > Keys** 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:
![Add api key to secrets](../../.gitbook/assets/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. 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: ![Active remote translations](../../.gitbook/assets/active-remote-translations-es.png)
### 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_\) ![Display text and button](../../.gitbook/assets/display-text-and-button-es.png)
* 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_\). ![Display notice and text after enqueued translations](../../.gitbook/assets/display-notice-and-text-after-enqueued-es.png)
* 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_\). ![Display text explaining that translations are pending](../../.gitbook/assets/display-text-translations-pending-es.png)
* 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. ![Display translated content](../../.gitbook/assets/display-translated-content-es.png)
### Idiomas disponibles para la traducción remota
Actualmente estos son todos los [idiomas disponibles](https://docs.microsoft.com/es-es/azure/cognitive-services/translator/quickstart-ruby-languages) en el servicio de traducción:
```text
["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"]
```
De todos los idiomas que actualmente tiene Consul definidos\(`available_locales`\) en `config/application.rb` no están incluidos en la lista anterior y por lo tanto no se ofrece servicio de traducción para los siguientes idiomas:
```text
["val", "gl", "sq"]
```
### Costes
El servicio de traducción utilizado tiene los [precios](https://azure.microsoft.com/es-es/pricing/details/cognitive-services/translator-text-api/) más competitivos del mercado. El precio por cada 1 Millón de caracteres traducidos asciende a 8,43 € y sin ningún tipo de coste fijo al mes. La competencia Google y DeepL tienen un precio aproximado de entre 16,00 € y 20,00 € por cada 1 Millón de caracteres más un fijo mensual.
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.
Para crear una Alerta en Azure debemos seguir los siguientes pasos: 1. Inicie sesión en **Azure Portal**. 1. Registrar los proveedores de recursos necesarios para crear Alertas 1. En el menú de Azure Portal, seleccione **Todos los servicios**. 1. En el cuadro **Todos los servicios**, escriba **suscripción** y, a continuación, seleccione **Suscripciones**. 1. Seleccione la suscripción en la lista de suscripciones para verla. 1. Seleccione **Proveedores de recursos** y consulte la lista de proveedores de recursos disponibles. 1. Entre los proveedores de recursos debemos seleccionar **microsoft.insights** y clicar sobre el botón **Registrarse** 1. Crear nueva regla de Alerta: 1. En el menú de Azure Portal, seleccione **Todos los servicios**. 1. En el cuadro **Todos los servicios**, escriba **suscripción** y, a continuación, seleccione **Suscripciones**. 1. Seleccione la suscripción en la lista de suscripciones para verla. 1. Seleccione **Recursos** y acceda al recurso creado de traducciones del tipo **Cognitive Services** 1. En la sección **Supervisión** seleccionamos **Alertas** y accedemos a **Nueva regla de alertas** 1. Seleccionamos el **Recurso** sobre el cual queremos añadir la Alerta \(si hemos seguido los pasos anteriores ya debería estar seleccionado\) 1. Agregamos una **Condición**. En este caso la que nos interesa tiene como nombre `Characters Translated`. 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 **Action Group** 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 **Crear regla de 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 `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 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 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: ![Active interface translations](../../.gitbook/assets/active-interface-translations-es.png)
### 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. ![Translations inteface enabled](../../.gitbook/assets/translations-interface-enabled-es.png)
* 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. ![Translations inteface enabled](../../.gitbook/assets/translations-interface-disabled-es.png)

16
docs/spanish-documentation/customization/javascript.md Normal file
View File

@@ -0,0 +1,16 @@
# Javascript
Si quieres agregar código Javascript puedes hacerlo en el fichero `app/assets/javascripts/custom.js`. Por ejemplo si quieres que salga una alerta puedes poner lo siguiente:
```javascript
$(function(){
alert('foobar');
});
```
Si trabajas con código coffeescript puedes revisarlo con [coffeelint](http://www.coffeelint.org/) \(instalalo con `npm install -g coffeelint`\) :
```bash
coffeelint .
```

76
docs/spanish-documentation/customization/models.md Normal file
View File

@@ -0,0 +1,76 @@
# Modelos
Si quieres agregar modelos nuevos, o modificar o agregar métodos a uno ya existente puedes hacerlo en `app/models/custom`. En el caso de los modelos antiguos debes primero hacer un require de la dependencia.
Por ejemplo en el caso del Ayuntamiento de Madrid se requiere comprobar que el código postal durante la verificación sigue un cierto formato \(empieza con 280\). Esto se realiza creando este fichero en `app/models/custom/verification/residence.rb`:
```ruby
require_dependency Rails.root.join('app', 'models', 'verification', 'residence').to_s
class Verification::Residence
validate :postal_code_in_madrid
validate :residence_in_madrid
def postal_code_in_madrid
errors.add(:postal_code, I18n.t('verification.residence.new.error_not_allowed_postal_code')) unless valid_postal_code?
end
def residence_in_madrid
return if errors.any?
unless residency_valid?
errors.add(:residence_in_madrid, false)
store_failed_attempt
Lock.increase_tries(user)
end
end
private
def valid_postal_code?
postal_code =~ /^280/
end
end
```
No olvides poner los tests relevantes en `spec/models/custom`, siguiendo con el ejemplo pondriamos lo siguiente en `spec/models/custom/residence_spec.rb`:
```ruby
require 'rails_helper'
describe Verification::Residence do
let(:residence) { build(:verification_residence, document_number: "12345678Z") }
describe "verification" do
describe "postal code" do
it "should be valid with postal codes starting with 280" do
residence.postal_code = "28012"
residence.valid?
expect(residence.errors[:postal_code].size).to eq(0)
residence.postal_code = "28023"
residence.valid?
expect(residence.errors[:postal_code].size).to eq(0)
end
it "should not be valid with postal codes not starting with 280" do
residence.postal_code = "12345"
residence.valid?
expect(residence.errors[:postal_code].size).to eq(1)
residence.postal_code = "13280"
residence.valid?
expect(residence.errors[:postal_code].size).to eq(1)
expect(residence.errors[:postal_code]).to include("In order to be verified, you must be registered in the municipality of Madrid.")
end
end
end
end
```

15
docs/spanish-documentation/customization/overwritting.md Normal file
View File

@@ -0,0 +1,15 @@
# Adaptar la aplicación
Cuando necesites extender o modificar el `config/application.rb` puedes hacerlo a través del fichero `config/application_custom.rb`. Por ejemplo si quieres modificar el idioma por defecto al inglés pondrías lo siguiente:
```ruby
module Consul
class Application < Rails::Application
config.i18n.default_locale = :en
config.i18n.available_locales = [:en, :es]
end
end
```
Recuerda que para ver reflejado estos cambios debes reiniciar el servidor de desarrollo.

39
docs/spanish-documentation/customization/translations.md Normal file
View File

@@ -0,0 +1,39 @@
# Textos & Traducciones
## Traducciones
Actualmente Consul esta traducido total o parcialmente a multiples idiomas, visita el proyecto en [Crowdin](https://crowdin.com/project/consul)
[Únete a los traductores](https://crwd.in/consul) para ayudar a completar los existentes, o contacta con nosotros a través del [gitter de consul](https://gitter.im/consul/consul) para convertirte en Revisor y validar las contribuciones de los traductores.
En el caso de que tu lenguage no este presente en el proyecto de Crowdin, por favor [abre una incicencia](https://github.com/consul/consul/issues/new?title=New%20language&body=Hello%20I%20would%20like%20to%20have%20my%20language%20INSERT%20YOUR%20LANGUAGE%20NAME%20added%20to%20consul) y lo añadiremos rápidamente.
Si quieres ver las traducciones de los textos de la web, puedes encontrarlos en los ficheros formato YML disponibles en `config/locales/`. Puedes leer la [guía de internacionalización](http://guides.rubyonrails.org/i18n.html) de Ruby on Rails sobre como funciona este sistema.
## Textos personalizados
Dado que CONSUL está en evolución continua con nuevas funcionalidades, y para que mantener tu fork actualizado sea más sencillo, recomendamos no modificar los ficheros de traducciones, es una mejor idea "sobreescribirlos" usando ficheros personalizados en caso de necesidad de alterar un texto.
Así pues las adaptaciones las debes poner en el directorio `config/locales/custom/`, recomendamos poner solo los textos que quieras personalizar. Por ejemplo si quieres personalizar el texto de "Ayuntamiento de Madrid, 2016" que se encuentra en el footer en todas las páginas, primero debemos ubicar en que plantilla se encuentra \(`app/views/layouts/_footer.html.erb`\), vemos que en el código pone lo siguiente:
```ruby
<%= t("layouts.footer.copyright", year: Time.current.year) %>
```
Y que en el fichero `config/locales/es/general.yml` sigue esta estructura \(solo ponemos lo relevante para este caso\):
```text
es:
layouts:
footer:
copyright: Ayuntamiento de Madrid, %{year}
```
Si creamos el fichero `config/locales/custom/es/general.yml` y modificamos "Ayuntamiento de Madrid" por el nombre de la organización que se este haciendo la modificación. Recomendamos directamente copiar los ficheros `config/locales/` e ir revisando y corrigiendo las que querramos, borrando las líneas que no querramos traducir.
## Mantener tus Textos Personalizados y Lenguajes
CONSUL tiene la gema [i18n-tasks](https://github.com/glebm/i18n-tasks), es una herramienta estupenda para gestionar textos i18n. Prueba en tu consola `i18n-tasks health` para ver un reporte de estado.
Si tienes un lenguaje propio diferente al Inglés, deberias añadirlo al fichero de configuración [i18n-tasks.yml para las variables `base_locale` y `locales`](https://github.com/consul/consul/blob/master/config/i18n-tasks.yml#L4-L7) de forma que los ficheros de tu idioma también sean comprobados.

34
docs/spanish-documentation/customization/views_and_styles.md Normal file
View File

@@ -0,0 +1,34 @@
# Vistas & Estilos
## Vistas \(HTML\)
Si quieres modificar el HTML de alguna página puedes hacerlo copiando el HTML de `app/views` y poniendolo en `app/views/custom` respetando los subdirectorios que encuentres ahí. Por ejemplo si quieres modificar `app/views/pages/conditions.html` debes copiarlo y modificarla en `app/views/custom/pages/conditions.html.erb`
## Estilos CSS con SASS
Si quieres cambiar algun selector CSS \(de las hojas de estilo\) puedes hacerlo en el fichero `app/assets/stylesheets/custom.scss`. Por ejemplo si quieres cambiar el color del header \(`.top-links`\) puedes hacerlo agregando:
```css
.top-links {
background: red;
}
```
Si quieres cambiar alguna variable de [foundation](http://foundation.zurb.com/) puedes hacerlo en el fichero `app/assets/stylesheets/_custom_settings.scss`. Por ejemplo para cambiar el color general de la aplicación puedes hacerlo agregando:
```css
$brand: #446336;
```
Usamos un preprocesador de CSS, [SASS, con la sintaxis SCSS](http://sass-lang.com/guide).
Además puedes comprobar la sintaxis de tus ficheros scss con:
```bash
scss-lint
```
### Accesibilidad
Para mantener el nivel de accesibilidad, si añades colores nuevos utiliza un [Comprobador de contraste de color](http://webaim.org/resources/contrastchecker/) \(WCAG AA es obligatorio, WCAG AAA es recomendable\)