15.5. Catálogos de mensajes (Symfony 2.3, el libro oficial)

Cuando se traduce un mensaje, Symfony2 obtiene el catálogo de mensajes para el locale del usuario y busca en su interior la traducción. Un catálogo de mensajes es como un diccionario de traducciones para un locale específico. Por ejemplo, el catálogo de la configuración regional fr_FR podría contener la siguiente traducción:

Symfony2 is Great => J'aime Symfony2

Es responsabilidad del desarrollador (o del traductor) de una aplicación internacionalizada crear estas traducciones. Las traducciones se almacenan en el sistema de archivos y Symfony utiliza algunas convenciones para encontrarlas.

Truco Cada vez que creas un nuevo recurso de traducción (o instalas un bundle que incluye un recurso de traducción), para que Symfony pueda descubrir el nuevo recurso de traducción, asegúrate de borrar la caché con el siguiente comando:

$ php app/console cache:clear

15.5.1. Ubicación de las traducciones y convenciones para sus nombres

Symfony2 busca archivos de mensajes (es decir, traducciones) en los siguientes lugares:

<directorio raíz del kernel>/Resources/translations/.
<directorio raíz del kernel>/Resources/<nombre del bundle>/translations/
Directorio Resources/translations/ del bundle

Los directorios anteriores se muestran por orden de prioridad. Así que puedes modificar cualquier traducción de cualquier bundle creando un archivo en alguno de los dos primeros directorios.

El mecanismo para redefinir traducciones funciona a nivel de clave: los archivos que redefinen traducciones sólo deben incluir las claves de los mensajes que quieren redefinir. Si no es encuentra una clave en un archivo, se utiliza la clave del archivo de menor prioridad.

El nombre de cada archivo de traducciones también es importante, ya que Symfony2 utiliza una convención para determinar los detalles sobre las traducciones. Cada archivo de mensajes debe nombrarse siguiendo el patrón: dominio.locale.formato:

dominio: sirve para dividir las traducciones de un mismo idioma en varios archivos (por ejemplo, admin para los mensajes de la parte de administración, navigation, para los mensajes del menú principal del sitio web, etc.) Su valor por defecto es messages, que es el nombre que debes utilizar si todas las traducciones de un idioma se encuentran en el mismo archivo.
locale: la configuración regional para la que se aplican estas traducciones. Puede ser un locale completo (por ejemplo, en_GB) o solamente un idioma (por ejemplo, en).
formato: indica el formato en el que se han traducido los contenidos y por tanto, le dice a Symfony qué cargador debe utilizar para procesar los mensajes. Por defecto Symfony2 soporta los siguientes formatos: xliff, php y yml.

Nota También puedes almacenar las traducciones en una base de datos, o en cualquier otro sistema. Para ello debes crear una clase propia que implemente la interfaz LoaderInterface.

15.5.2. Creando traducciones

Crear los archivos de traducción es una parte importante de la localización (palabra que se suele abreviar como L10n). Los archivos de traducción consisten en una serie de pares cadena original + traducción para un determinado dominio y locale.

En cada traducción se puede utilizar como cadena original la propia cadena de texto completa (por ejemplo "Symfony is great") o también puedes utilizar un identificador único para cada texto (por ejemplo, symfony2.great) tal y como se explica más adelante:

<!-- src/Acme/DemoBundle/Resources/translations/messages.fr.xliff -->
<?xml version="1.0"?>
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
    <file source-language="en" datatype="plaintext" original="file.ext">
            <body>
            <trans-unit id="1">
                <source>Symfony2 is great</source>
                <target>J'aime Symfony2</target>
            </trans-unit>
            <trans-unit id="2">
                <source>symfony2.great</source>
                <target>J'aime Symfony2</target>
            </trans-unit>
        </body>
    </file>
</xliff>

// src/Acme/DemoBundle/Resources/translations/messages.fr.php
return array(
    'Symfony2 is great' => 'J\'aime Symfony2',
    'symfony2.great'    => 'J\'aime Symfony2',
);

# src/Acme/DemoBundle/Resources/translations/messages.fr.yml
Symfony2 is great: "J'aime Symfony2"
symfony2.great:    "J'aime Symfony2"

Symfony2 utilizará estos archivos cuando tenga que traducir al francés o bien Symfony2 is great o bien symfony2.great.

Usar mensajes reales o palabras clave Este ejemplo ilustra las dos formas de trabajar con la traducción de mensajes:

$translated = $translator->trans('Symfony2 is great');

$translated = $translator->trans('symfony2.great');

En el primer método, los mensajes están escritos en el idioma por defecto (inglés en este caso). Ese mensaje es el que se utiliza como cadena original al crear las traducciones.

En el segundo método, los mensajes en realidad son palabras clave que identifican el mensaje. Los archivos de traducciones utilizan estas palabras clave como cadena original de la traducción. En este caso, la traducción se debe hacer también para el idioma por defecto (es decir, hay que traducir symfony2.great a Symfony2 is great).

El segundo método es muy interesante porque si cambia la cadena de texto original, no tienes que cambiar todos los archivos de traducción. La elección del método a utilizar es totalmente tuya, pero a menudo se recomienda el formato de palabras clave.

Además, los formatos php y yaml soportan el anidamiento de palabras clave, por lo que te ahorran mucho trabajo:

YAML
PHP

symfony2:
    is:
        great: Symfony2 is great
        amazing: Symfony2 is amazing
    has:
        bundles: Symfony2 has bundles
user:
    login: Login

return array(
    'symfony2' => array(
        'is' => array(
            'great'   => 'Symfony2 is great',
            'amazing' => 'Symfony2 is amazing',
        ),
        'has' => array(
            'bundles' => 'Symfony2 has bundles',
        ),
    ),
    'user' => array(
        'login' => 'Login',
    ),
);

Al procesar los archivos anteriores, Symfony aplana los diferentes niveles añadiendo un punto (.) entre cada nivel. Por lo tanto, los ejemplos anteriores son equivalentes a los siguientes:

YAML
PHP

symfony2.is.great: Symfony2 is great
symfony2.is.amazing: Symfony2 is amazing
symfony2.has.bundles: Symfony2 has bundles
user.login: Login

return array(
    'symfony2.is.great' => 'Symfony2 is great',
    'symfony2.is.amazing' => 'Symfony2 is amazing',
    'symfony2.has.bundles' => 'Symfony2 has bundles',
    'user.login' => 'Login',
);