Internacionalización en el código

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 traducción de Alaveteli en su lugar.

Notas de implementación

Las traducciones implementadas para el proyecto se hallan en locale/.

Recomendamos que las traducciones se lleven a cabo en Transifex, debido a que los traductores pueden trabajar a través de su interfaz gráfica en lugar de tener que editar archivos .po y .pot 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 AVAILABLE_LOCALES el valor en es.

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 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.

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 archivos .po o .pot 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.

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 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 => 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 all</a> or <a href="">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:

    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 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:

    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:

          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.