diff options
| -rw-r--r-- | docs/developers/i18n.md | 12 | ||||
| -rw-r--r-- | es/docs/developers/i18n.md | 176 |
2 files changed, 182 insertions, 6 deletions
diff --git a/docs/developers/i18n.md b/docs/developers/i18n.md index fb7f2930b..128786664 100644 --- a/docs/developers/i18n.md +++ b/docs/developers/i18n.md @@ -11,7 +11,7 @@ title: Internationalisation (for devs) the Alaveteli code. It's mostly aimed at devs who are working on the codebase — if you just want to translate Alaveteli into your own language, see - <a href="{{ site.baseurl }}docs/customising/translation">translating Alaveteli</a> + <a href="{{ page.baseurl }}/docs/customising/translation">translating Alaveteli</a> instead. </p> @@ -21,7 +21,7 @@ Deployed translations for the project live in ``locale/``. We encourage translations to be done on <a href="{{ site.baseurl }}docs/glossary/#transifex" class="glossary__link">Transifex</a> because translators can work through its web interface rather than needing to edit the -<a href="{{ site.baseurl }}docs/glossary/#po" class="glossary__link">`.po` and `.pot` files</a> +<a href="{{ page.baseurl }}/docs/glossary/#po" class="glossary__link">`.po` and `.pot` files</a> directly. Ultimately, Transifex just captures translators' work and turns it into the files that Alaveteli needs (using gettext). @@ -31,7 +31,7 @@ For example, to deploy English and Spanish translations at once: * Ensure their `.po` files are at ```locale/en/app.po``` and ```locale/es/app.po``` (for example, by downloading them from Transifex) - * Set <code><a href="{{ site.baseurl }}docs/customising/config/#available_locales">AVAILABLE_LOCALES</a></code> + * Set <code><a href="{{ page.baseurl }}/docs/customising/config/#available_locales">AVAILABLE_LOCALES</a></code> to <code>en es</code> ### What to do if you don't have complete translations for an older release of Alaveteli @@ -56,7 +56,7 @@ You need to do this if you've added any new strings to the code that need translations (or if you change an existing one). To update the -<a href="{{ site.baseurl }}docs/glossary/#po" class="glossary__link">`.po` or `.pot` files</a> +<a href="{{ page.baseurl }}/docs/glossary/#po" class="glossary__link">`.po` or `.pot` files</a> for each language, run: bundle exec rake gettext:store_model_attributes @@ -69,7 +69,7 @@ If `gettext:find` only creates the file `locale/im-config.pot` then you need to unset the `TEXTDOMAIN` environment variable and try again. For more details about the translations, see the page about -[translating Alaveteli]({{ site.baseurl }}docs/customising/translation/). +[translating Alaveteli]({{ page.baseurl }}/docs/customising/translation/). ## Technical implementation details @@ -173,5 +173,5 @@ The release manager will enforce a translation freeze just before a new release is cut. During such time, you must not introduce new strings to the code if your work is due for inclusion in this release. This is necessary to allow translators time to complete and check their translations against all the known -strings. See more about [translating Alaveteli]({{ site.baseurl }}docs/customising/translation/). +strings. See more about [translating Alaveteli]({{ page.baseurl }}/docs/customising/translation/). diff --git a/es/docs/developers/i18n.md b/es/docs/developers/i18n.md new file mode 100644 index 000000000..5110959fc --- /dev/null +++ b/es/docs/developers/i18n.md @@ -0,0 +1,176 @@ +--- +layout: es/page +title: Internacionalización (para desarrolladores) +--- + +# Internacionalización en el código + +<p class="lead"> + Esta página describe algunos aspectos técnicos de la internacionalización del + código de Alaveteli. Está principalmente dirigida a desarrolladores que están trabajando + en la base del código; si tan solo desea traducir Alaveteli a su idioma, consulte la + <a href="{{ page.baseurl }}/docs/customising/translation">traducción de Alaveteli</a> + en su lugar. +</p> + +## Notas de implementación + +Las traducciones implementadas para el proyecto se hallan en ``locale/``. + +Recomendamos que las traducciones se lleven a cabo en +[Transifex](https://www.transifex.net/projects/p/alaveteli/), +debido a que los traductores pueden trabajar a través de su interfaz gráfica en lugar de tener que editar +<a href="{{ page.baseurl }}/docs/glossary/#po" class="glossary__link">archivos `.po` y `.pot`</a> +directamente. Básicamente, Transifex tan solo captura el trabajo de los traductores y lo convierte +en los archivos que Alaveteli necesita (mediante el uso de gettext). + +### Cómo obtener las últimas traducciones en su sitio web + +Por ejemplo, para implementar traducciones en inglés y español a la vez: + + * Asegúrese de que los archivos `.po` correspondientes se hallan en ```locale/en/app.po``` y ```locale/es/app.po``` + (por ejemplo, descargándolos desde Transifex). + * Asigne a <code><a href="{{ page.baseurl }}/docs/customising/config/#available_locales">AVAILABLE_LOCALES</a></code> + el valor <code>en es</code>. + +### Qué hacer si no dispone de las traducciones completas para una versión anterior de Alaveteli + +Antes de elaborar una nueva versión de Alaveteli los archivos de traducción se +extraen de Transifex y se añaden al directorio ``locale/`` de Alaveteli en +github, donde se hallan las traducciones más completas para la versión anterior. +Después los archivos ubicados en Transifex se actualizan con las nuevas cadenas de texto +que necesitan ser traducidas para la nueva actualización. En este punto también se eliminan las cadenas de texto +anteriores que ya no se utilizan en la nueva versión. La última +[etiqueta de versión](https://github.com/mysociety/alaveteli/releases) +para una actualización en github debería contener las traducciones más completas procedentes de Transifex para dicha +versión. + +Si utiliza una versión antigua de Alaveteli y desea añadir o modificar las traducciones, +puede editar los archivos .po directamente utilizando un programa local, como +[PoEdit](http://poedit.net/). + +### Cómo añadir nuevas cadenas de texto a la traducción + +Necesita hacer esto en caso de que haya añadido al código nuevas cadenas de texto que necesiten traducirse +(o si ha modificado alguna cadena ya existente). + +Para actualizar los +<a href="{{ page.baseurl }}/docs/glossary/#po" class="glossary__link">archivos `.po` o `.pot`</a> +para cada idioma, ejecute el comando: + + bundle exec rake gettext:store_model_attributes + +seguido del comando: + + bundle exec rake gettext:find + +Si `gettext:find` solo crea el archivo `locale/im-config.pot`, necesitará aplicar +la acción unset a la variable de entorno `TEXTDOMAIN` e intentarlo de nuevo. + +Para obtener más información sobre las traducciones, consulte la página de +[traducción de Alaveteli]({{ page.baseurl }}/docs/customising/translation/). + + +## Detalles de implementación técnica + +### Obtener la localización actual + +Este es un tema complejo debido a que existen dos métodos rivales para definir una +combinación de localización y territorio. El método mediante POSIX (y gettext y Transifex) es +de tipo `en_GB` y el método mediante Rails, de tipo `en-US`. Debido a que utilizamos gettext y +Transifex para las traducciones, debemos lidiar con ambos. + + * Para la versión de localización de Rails seleccionada actualmente, utilice `I18n.locale`. + * Para la versión de localización de POSIX, utilice `FastGettext.locale`. + +## I18n en plantillas + +Antes de añadir cadenas de texto i18n a la fuente, debería leer las +[guías de internacionalización](http://mysociety.github.io/internationalization.html) +que se aplican en todos nuestros proyectos. + +Algunos consejos para añadir cadenas de texto al código de Alaveteli: + +* Cadenas simples: ```<% = _("String to translate") %>``` +* Cadenas que incluyen variables: ayude al traductor mediante la inserción de cadenas + que puedan ser interpoladas, de forma que la variable tenga un significado. Por ejemplo, + ```<%= "Nothing found for '" + h(@query) + "'" %>``` puede convertirse en ```<%= + _("Nothing found for '{{search_terms}}'", :search_terms => h(@query)) %>``` +* Cadenas que incluyen números: ```<%= n_('%d request', '%d requests', @quantity) % @quantity %>``` +* Permitimos algo de código HTML entre líneas cuando proporciona un contexto con significado, por ejemplo: + +``` +_('<a href="{{browse_url}}">Browse all</a> or <a href="{{add_url}}">ask us to add it</a>.', + :browse_url => @browse_url, :add_url => @add_url) +``` + +Pueden aplicarse normas similares a cadenas de texto en el código fuente en Ruby. + +## Acceso programático a entidades PublicBody traducidas + +Además de las plantillas, la única área adicional de i18n actualmente implementada es la de entidades +PublicBody. + +La implementación permite obtener distintas localizaciones de una entidad PublicBody, como: + +```ruby + PublicBody.with_locale("es") do + puts PublicBody.find(230).name + end +``` + +Normalmente este es todo el código que necesita conocer. Existe un método +```self.locale_from_params()```, disponible en todos los modelos, que devuelve una localización +especificada como ```locale=xx``` en la cadena de búsqueda y que retorna a la localización +por defecto, que puede utilizar en conjunto con el método ```with_locale``` +superior. Todas las uniones en las tablas internas de traducción deberían ser gestionadas +normalmente de forma automática, pero existen algunas excepciones, indicadas a continuación. + +### Sobrescribir los mutadores de campos del modelo + +Internamente utilizamos el [complemento Globalize](https://github.com/globalize/globalize) +para localizar campos del modelo. Cuando la columna «foo» ha sido marcada en el modelo como +```:translates```, Globalize sobrescribe ```foo.baz = 12``` para establecer el valor en la columna +```baz``` de la tabla ```foo_translations```. + +Uno de los efectos secundarios de la forma en que esta tarea se lleva a cabo consiste en que, si +desea sobrescribir un mutador de atributo específico, necesitará llamar explícitamente a la maquinaria +de Globalize, más o menos de esta manera: + +```ruby + def name=(name) + globalize.write(self.class.locale || I18n.locale, "name", name) + self["name"] = short_name + # your other stuff here + end +``` + +### Búsqueda + +Los métodos mágicos ```find_first_by_<attr>``` y ```find_all_by_<attr>``` +deberían funcionar. Si desea realizar una búsqueda más programática, necesita unir +la tabla de traducción, por ejemplo: + +```ruby + query = "#{translated_attr_name(someattr) = ? AND #{translated_attr_name('locale')} IN (?)" + locales = Globalize.fallbacks(locale || I18n.locale).map(&:to_s) + find( + :first, + :joins => :translations, + :conditions => [query, value, locales], + :readonly => false + ) +``` + +Es posible que también necesite efectuar algunas uniones o condiciones SQL de bajo nivel. Consulte +```PublicBodyController.list``` para ver un ejemplo de una consulta con una condición explícitamente +dependiente de la localización (busque la variable ```locale_condition```) + +## Traducción y actualizaciones + +El gestor de actualizaciones forzará una detención de la traducción justo antes de que se finalice una nueva +versión. Durante este tiempo, si su trabajo está programado para ser incluido en dicha versión, +no debe introducir nuevas cadenas en el código. Esta detención ofrece a los traductores el tiempo necesario +para completar y revisar sus traducciones respecto a todas las cadenas de texto conocidas. +Consulte más información sobre la [traducción de Alaveteli]({{ page.baseurl }}/docs/customising/translation/). + |