Las opciones pueden usarse con todos los adaptadores. Por supuesto las opciones son diferentes para cada adaptador. Puede establecer opciones al crear el adaptador. En realidad hay una opción que está disponible para todos los adaptadores: 'clear' establece si los datos de traducción deben añadirse a los ya existentes o no. El comportamiento estándar es añadir los nuevos datos de traducción a los existentes. Pero los datos de traducción sólo se limpian para el idioma seleccionado. Así que otros idiomas permanecen intactos.

Puede establecer opciones temporalmente pasándolas a addTranslation(). Y puede usar el método setOptions() para establecer opciones de forma permanente.

// define ':' as separator for the translation source files
$translate = new Zend_Translate(
    array(
        'adapter' => 'csv',
        'content' => '/path/to/mytranslation.csv',
        'locale'  => 'de',
        'delimiter' => ':'
    )
);

...

// clear the defined language and use new translation data
$translate->addTranslation(
    array(
        'content' => '/path/to/new.csv',
        'locale'  => 'fr',
        'clear'   => true
    )
);

Aquí puede encontrar todas las opciones disponibles para los diferentes adaptadores con una descripción de su uso:

Cuando quiera tener opciones definidas por usted mismo, también puede usarlas dentro de todos los adaptadores. El método setOptions() puede usarse para definir su opción. setOptions() necesita un array con las opciones que quiere establecer. Si una opción dada existe será sobrescrita. Puede definir tantas opciones como necesite ya que no serán comprobadas por el adaptador. Sólo asegúrese de no sobrescribir ninguna opción existente que sea usada por un adaptador.

Para devolver la opción puede usar el método getOptions(). Cuando getOptions() se llama sin parámetro devolverá todas las opciones establecidas. Cuando se da el parámetro opcional sólo obtendrá la opción especificada.

Cuando se trabaja con diferentes idiomas hay algunos métodos que serán útiles.

El método getLocale() puede usarse para obtener el idioma establecido actualmente. Puede contener una instancia de Zend_Locale o el identificador de un locale.

El método setLocale() establece un nuevo idioma estándar para la traducción. Esto evita la necesidad de establecer el parámetro opcional de idioma más de una vez al método translate(). Si el idioma dado no existe, o no hay datos de traducción disponibles para el idioma, setLocale() intenta degradarlo al idioma sin la región si se dio alguna. Un idioma en_US se degradaría a en. Cuando ni siquiera el idioma degradado se puede encontrar se lanzará una excepción.

El método isAvailable() comprueba si un idioma dado ya está disponible. Devuelve TRUE si existen datos para el idioma dado.

Y por último el método getList() puede usarse para obtener todos los idiomas actualmente establecidos para un adaptador, devueltos como array.

// returns the currently set language
$actual = $translate->getLocale();

// you can use the optional parameter while translating
echo $translate->_("my_text", "fr");
// or set a new language
$translate->setLocale("fr");
echo $translate->_("my_text");
// refer to the base language
// fr_CH will be downgraded to fr
$translate->setLocale("fr_CH");
echo $translate->_("my_text");

// check if this language exist
if ($translate->isAvailable("fr")) {
    // language exists
}

// Let's expect the browser returns these language settings:
// HTTP_ACCEPT_LANGUAGE = "de_AT=1;fr=1;en_US=0.8";

// Example 1:
// When no fitting language is found, the message ID is returned
$translate = new Zend_Translate(
    array(
        'adapter' => 'gettext',
        'content' => 'my_it.mo',
        'locale'  => 'auto',
        'scan' => Zend_Translate::LOCALE_FILENAME
    )
);

// Example 2:
// Best found fitting language is 'fr'
$translate = new Zend_Translate(
    array(
        'adapter' => 'gettext',
        'content' => 'my_fr.mo',
        'locale'  => 'auto',
        'scan' => Zend_Translate::LOCALE_FILENAME
    )
);

// Example 3:
// Best found fitting language is 'de' ('de_AT' will be degraded)
$translate = new Zend_Translate(
    array(
        'adapter' => 'gettext',
        'content' => 'my_de.mo',
        'locale'  => 'auto',
        'scan' => Zend_Translate::LOCALE_FILENAME
    )
);

// Example 4:
// Returns 'it' as translation source and overrides the automatic settings
$translate = new Zend_Translate(
    array(
        'adapter' => 'gettext',
        'content' => 'my_it.mo',
        'locale'  => 'auto',
        'scan' => Zend_Translate::LOCALE_FILENAME
    )
);

$translate->addTranslation(array('content' => 'my_ru.mo', 'locale' => 'ru'));
$translate->setLocale('it_IT');

// in your bootstrap file
$locale = new Zend_Locale();
Zend_Registry::set('Zend_Locale', $locale);

// default language when requested language is not available
$defaultlanguage = 'en';

// somewhere in your application
$translate = new Zend_Translate(
    array('adapter' => 'gettext', 'content' => 'my_de.mo')
);

if (!$translate->isAvailable($locale->getLanguage())) {
    // not available languages are rerouted to another language
    $translate->setLocale($defaultlanguage);
}

$translate->getLocale();

74.5.2.2. Uso de un país como idioma

También puede usar un país como parámetro de locale. Esto puede ser útil cuando proporciona a su usuario banderas, que representan el país en el que vive, y cuando selecciona su bandera, obtendría automáticamente el idioma por defecto para ese país.

Por ejemplo, cuando el usuario selecciona US obtendría en_US a cambio como locale usado. Esto lleva automáticamente al idioma en que es el idioma por defecto para el país US.

$translate = new Zend_Translate(
    array(
        'adapter' => 'gettext',
        'content' => 'my_de.mo',
        'locale'  => 'US'
    )
);

Los países siempre en mayúsculas

Usando esta sintaxis debería siempre poner en mayúsculas la entrada cuando sepa que se trata de un país. La razón es que también hay idiomas que tienen las mismas letras que un país. Tome por ejemplo om. Podría esperar obtener ar_OM cuando se refiere al país "Omán", o podría esperar el idioma "Oromo" que se habla en Kenia por ejemplo. Como Zend_Translate está relacionado con idiomas siempre usará el idioma en este caso. Por lo tanto, ponga siempre en mayúsculas el locale cuando quiera que sea reconocido como país.

Zend_Translate puede detectar orígenes de traducción automáticamente. Así que no tiene que declarar cada archivo de origen manualmente. Puede dejar que Zend_Translate haga este trabajo y escanee la estructura completa de directorios en busca de archivos de origen.

	Nota
	La detección automática de origen está disponible desde la versión 1.5 de Zend Framework.

El uso es bastante similar a iniciar un único origen de traducción con una diferencia. Debe dar un directorio que debe ser escaneado en lugar de un archivo.

// assuming we have the following structure
//  /language/
//  /language/login/login.tmx
//  /language/logout/logout.tmx
//  /language/error/loginerror.tmx
//  /language/error/logouterror.tmx

$translate = new Zend_Translate(
    array('adapter' => 'tmx', 'content' => '/language')
);

Así que Zend_Translate no sólo busca en el directorio dado, sino también en todos los subdirectorios en busca de archivos de origen de traducción. Esto hace que el uso sea bastante sencillo. Pero Zend_Translate ignorará todos los archivos que no sean orígenes o que produzcan errores al leer los datos de traducción. Así que debe asegurarse de que todos sus orígenes de traducción son correctos y legibles porque no obtendrá ningún fallo si un archivo es incorrecto o no se puede leer.

	Nota
	Dependiendo de la profundidad de su estructura de directorios y de cuántos archivos haya dentro de esta estructura puede llevar mucho tiempo a Zend_Translate completarlo.

En nuestro ejemplo hemos usado el formato TMX que incluye el idioma a usar dentro del origen. Pero muchos de los otros formatos de origen no son capaces de incluir el idioma dentro del archivo. Incluso estos orígenes pueden usarse con el escaneo automático si realiza algunos prerrequisitos como se describe a continuación:

74.5.3.1. Idioma a través del nombrado de directorios

Una forma de incluir la detección automática de idioma es nombrar los directorios según el idioma que se usa para los orígenes dentro de ese directorio. Esta es la forma más sencilla y se usa por ejemplo en implementaciones estándar de gettext.

Zend_Translate necesita la opción 'scan' para saber que debe buscar idiomas en los nombres de todos los directorios. Vea el siguiente ejemplo para más detalles:

Ejemplo 74.11. Escaneo de directorios en busca de idiomas

// assuming we have the following structure
//  /language/
//  /language/de/login/login.mo
//  /language/de/error/loginerror.mo
//  /language/en/login/login.mo
//  /language/en/error/loginerror.mo

$translate = new Zend_Translate(
    array(
        'adapter' => 'gettext',
        'content' => '/language',
        'scan' => Zend_Translate::LOCALE_DIRECTORY
    )
);

	Nota
	Esto sólo funciona para adaptadores que no incluyan el idioma dentro del archivo de origen. Usar esta opción por ejemplo con TMX será ignorado. Además las definiciones de idioma dentro del nombre de archivo serán ignoradas cuando se use esta opción.

	Nota
	Debe tener en cuenta si tiene varios subdirectorios bajo la misma estructura. Suponiendo que tenemos una estructura como /language/module/de/en/file.mo. En este caso la ruta contiene varias cadenas que se detectarían como locale. Podría ser de o en. En tal caso el comportamiento no está definido y se recomienda usar la detección por archivo en tales situaciones.

// assuming we have the following structure
//  /language/
//  /language/login/login_en.mo
//  /language/login/login_de.mo
//  /language/error/loginerror_en.mo
//  /language/error/loginerror_de.mo

$translate = new Zend_Translate(
    array(
        'adapter' => 'gettext',
        'content' => '/language',
        'scan' => Zend_Translate::LOCALE_FILENAME
    )
);

/languages/
/languages/en.mo
/languages/de.mo
/languages/es.mo

/languages/
/languages/view.en
/languages/view.de
/languages/view.es

/languages/
/languages/view_en.mo -> detects english
/languages/view_de.mo -> detects german
/languages/view_it.mo -> detects italian

/languages/
/languages/view_en_de.mo -> detects english
/languages/view_en_es.mo -> detects english and overwrites the first file
/languages/view_it_it.mo -> detects italian

/languages/
/languages/view_en-it.mo -> detects english because '_' will be used before '-'
/languages/view-en_it.mo -> detects italian because '_' will be used before '-'
/languages/view_en.it.mo -> detects italian because '.' will be used before '_'

74.5.3.3. Ignorar archivos y directorios especiales

A veces es útil excluir archivos o incluso directorios de ser añadidos automáticamente. Para ello puede usar la opción ignore que acepta 3 posibles usos.

74.5.3.3.1. Ignorar un directorio o archivo especial

Por defecto Zend_Translate está establecido para ignorar todos los archivos y directorios que comiencen con '/.'. Esto significa que todos los archivos SVN serán ignorados.

Puede establecer su propia sintaxis dando una cadena para la opción ignore. El separador de directorio se adjuntará automáticamente y debe omitirse.

$options   = array('ignore' => 'test');
$translate = new Zend_Translate(
    array(
        'adapter' => $adapter,
        'content' => $content,
        'locale'  => $locale,
        'ignore'  => 'test'
    )
);

El ejemplo anterior ignorará todos los archivos y directorios que comiencen con test. Esto significa por ejemplo /test/en.mo, /testing/en.mo y /dir/test_en.mo. Pero aún así añadiría /mytest/en.mo o /dir/atest.mo.

	Evitar que se busque en los archivos SVN
	Cuando establece esta opción, el valor por defecto '/.' se borrará. Esto significa que Zend_Translate entonces añadirá todos los archivos de los directorios SVN ocultos. Cuando esté trabajando con SVN, debería usar la sintaxis de array descrita en la siguiente sección.

74.5.3.3.2. Ignorar varios directorios o archivos

También puede ignorar varios archivos y directorios. En lugar de una cadena, puede simplemente dar un array con todos los nombres deseados que se ignorarán.

$options = array('ignore' => array('.', 'test', 'old'));
$translate = new Zend_Translate(
    array(
        'adapter' => $adapter,
        'content' => $content,
        'locale'  => $locale,
        'ignore'  => array('.', 'test', 'old')
    )
);

En el caso anterior las 3 sintaxis serán ignoradas. Pero aún así deben comenzar con la sintaxis para ser detectadas e ignoradas.

74.5.3.3.3. Ignorar nombres específicos

Para ignorar archivos y directorios que no comienzan con una sintaxis definida pero tienen una sintaxis especial en cualquier parte de su nombre puede usar una expresión regular.

Para usar una expresión regular la clave del array de la opción ignore debe comenzar con regex.

$options = array(
    'ignore' => array(
        'regex' => '/test/u',
        'regex_2' => '/deleted$/u'
    )
);
$translate = new Zend_Translate(
    array(
        'adapter' => $adapter,
        'content' => $content,
        'locale'  => $locale,
        'ignore'  => array('regex' => '/test/u', 'regex_2' => '/deleted$/u')
    )
);

En el caso anterior hemos definido 2 expresiones regulares. Los archivos y directorios siempre se buscarán con todas las expresiones regulares dadas. En nuestro ejemplo esto significa que cualquier archivo que contenga test en cualquier parte de su nombre será ignorado. Adicionalmente todos los archivos y directorios que terminen con deleted no se añadirán como traducción.

No todos los ID de mensaje pueden traducirse. Pero a veces puede ser útil mostrar la traducción de otro idioma en lugar de devolver el propio ID de mensaje. Puede lograr esto usando la opción route.

Puede añadir una ruta para cada idioma. Vea el siguiente ejemplo:

$translate = new Zend_Translate(
    array(
        'adapter' => $adapter,
        'content' => $content,
        'locale'  => $locale,
        'route'   => array('fr' => 'en', 'de' => 'fr')
    )
);

Lo anterior devuelve una traducción en inglés para todos los mensajes que no puedan traducirse al francés. Y devuelve una traducción en francés para todos los mensajes que no puedan traducirse al alemán. Incluso devolverá una traducción en inglés para todos los mensajes que no se puedan traducir ni al alemán ni al francés. Así que incluso puede definir una cadena completa de traducción.

Esta característica puede parecer interesante para cualquiera. Pero tenga en cuenta que devolver traducciones para idiomas incorrectos u otros idiomas puede ser problemático cuando el usuario no entiende ese idioma. Así que siempre debería usar esta característica con moderación.

Cuando trabaja con múltiples traducciones puede llegar a una situación en la que quiera usar diferentes tipos de origen. Por ejemplo los archivos de recursos que proporciona el framework y sus propias traducciones que están disponibles usando el adaptador gettext.

Al combinar múltiples adaptadores de traducción puede usarlos dentro de una instancia. Vea el siguiente ejemplo:

$translate = new Zend_Translate(
    array(
        'adapter' => 'gettext',
        'content' => '\path\to\translation.mo',
        'locale'  => 'en'
    )
);

$translate_second = new Zend_Translate(
    array(
        'adapter' => 'array',
        'content' => '\resources\languages\en\Zend_Validate.php',
        'locale'  => 'en'
    )
);

$translate->addTranslation(array('content' => $translate_second));

Ahora la primera instancia contiene todas las traducciones de la segunda instancia y puede usarla dentro de la aplicación incluso si usó diferentes tipos de origen.

	Ahorro de memoria
	Como habrá notado, la segunda instancia ya no se usa una vez que ha sido añadida a la primera instancia. Para ahorrar algo de memoria puede querer eliminarla.

Cuando esté escaneando directorios puede además querer usar sólo un idioma definido. Los recursos predefinidos por ejemplo están disponibles en más de 10 idiomas. Pero su aplicación no está disponible en todos esos idiomas. Por lo tanto también puede añadir sólo un idioma del segundo adaptador.

$translate->addTranslation(
    array(
        'content' => $translate_second,
        'locale'  => 'en'
    )
);

Esto le permite seguir escaneando los directorios y aun así añadir sólo aquellos idiomas que sean relevantes para su aplicación.

Normalmente el texto se traducirá sin ningún cómputo. Pero a veces es necesario saber si un texto está traducido o no, para ello puede usarse el método isTranslated().

isTranslated($messageId, $original = false, $locale = null) toma el texto que quiere comprobar como su primer parámetro, y como tercer parámetro opcional el locale para el que quiere hacer la comprobación. El segundo parámetro opcional declara si la traducción está fijada al idioma declarado o si se puede usar un conjunto inferior de traducciones. Si tiene un texto que puede devolverse para 'en' pero no para 'en_US' normalmente obtendrá la traducción devuelta, pero al establecer $original a TRUE, isTranslated() devolverá FALSE.

$english = array(
    'message1' => 'Nachricht 1',
    'message2' => 'Nachricht 2',
    'message3' => 'Nachricht 3');

$translate = new Zend_Translate(
    array(
        'adapter' => 'array',
        'content' => $english,
        'locale' => 'de_AT'
    )
);

if ($translate->isTranslated('message1')) {
    print "'message1' can be translated";
}

if (!($translate->isTranslated('message1', true, 'de'))) {
    print "'message1' can not be translated to 'de'"
        . " as it's available only in 'de_AT'";
}

if ($translate->isTranslated('message1', false, 'de')) {
    print "'message1' can be translated in 'de_AT' as it falls back to 'de'";
}

Cuando tiene un sitio más grande o está creando los archivos de traducción manualmente, a menudo tiene el problema de que algunos mensajes no están traducidos. Pero hay una solución fácil para usted cuando usa Zend_Translate.

Debe seguir dos o tres pasos sencillos. Primero, debe crear una instancia de Zend_Log. Luego debe adjuntar esta instancia a Zend_Translate. Vea el siguiente ejemplo:

$translate = new Zend_Translate(
    array(
        'adapter' => 'gettext',
        'content' => $path,
        'locale' => 'de'
    )
);

// Create a log instance
$writer = new Zend_Log_Writer_Stream('/path/to/file.log');
$log    = new Zend_Log($writer);

// Attach it to the translation instance
$translate->setOptions(
    array(
        'log'             => $log,
        'logUntranslated' => true
    )
);

$translate->translate('unknown string');

Ahora tendrá un nuevo aviso en el log: Untranslated message within 'de': unknown string.

	Nota
	Debe tener en cuenta que cualquier traducción que no se pueda encontrar se registrará. Esto significa todas las traducciones cuando un usuario solicita un idioma que no está soportado. También cada solicitud de un mensaje que no se pueda traducir se registrará. Tenga en cuenta, que 100 personas solicitando la misma traducción, dará como resultado 100 avisos registrados.

Esta característica no sólo puede usarse para registrar mensajes sino también para adjuntar estos mensajes no traducidos en un archivo de traducción vacío. Para hacerlo tendrá que escribir su propio escritor de log que escriba el formato que quiera tener y elimine el prefijo "Untranslated message".

También puede establecer la opción 'logMessage' cuando quiera tener su propio mensaje de log. Use el token '%message%' para colocar el messageId dentro de su mensaje de log, y el token '%locale%' para el locale solicitado. Vea el siguiente ejemplo para un mensaje de log autodefinido:

$translate = new Zend_Translate(
    array(
        'adapter' => 'gettext',
        'content' => $path,
        'locale'  => 'de'
    )
);

// Create a log instance
$writer = new Zend_Log_Writer_Stream('/path/to/file.log');
$log    = new Zend_Log($writer);

// Attach it to the translation instance
$translate->setOptions(
    array(
        'log'             => $log,
        'logMessage'      => "Missing '%message%' within locale '%locale%'",
        'logUntranslated' => true
    )
);

$translate->translate('unknown string');

Adicionalmente también puede cambiar la prioridad que se usa para escribir el mensaje en el log. Por defecto se usa la prioridad Zend_Log::NOTICE. Equivale a 5. Cuando quiera cambiar la prioridad puede usar cualquiera de las prioridades de Zend_Log. Vea el siguiente ejemplo:

// Create a log instance
$writer = new Zend_Log_Writer_Stream('/path/to/file.log');
$log    = new Zend_Log($writer);

$translate = new Zend_Translate(
    array(
        'adapter' => 'gettext',
        'content' => $path,
        'locale'  => 'de',
        'log'             => $log,
        'logMessage'      => "Missing '%message%' within locale '%locale%'",
        'logPriority'     => Zend_Log::ALERT,
        'logUntranslated' => true
    )
);

$translate->translate('unknown string');

A veces es útil tener acceso a los datos de origen de traducción. Para ello se proporcionan las dos funciones siguientes.

El método getMessageIds($locale = null) devuelve todos los ID de mensaje conocidos como array.

Cuando quiera saber el ID de mensaje para una traducción dada puede usar el método getMessageId().

El método getMessages($locale = null) devuelve el origen de traducción completo como un array. El ID de mensaje se usa como clave y los datos de traducción como valor.

Ambos métodos aceptan un parámetro opcional $locale que, si se establece, devuelve los datos de traducción para el idioma especificado. Si este parámetro no se da, se usará el idioma establecido actualmente. Tenga en cuenta que normalmente todas las traducciones deberían estar disponibles en todos los idiomas. Lo que significa que en una situación normal no tendrá que establecer este parámetro.

Adicionalmente el método getMessages() puede usarse para devolver el diccionario de traducción completo usando el pseudo-locale 'all'. Esto devolverá todos los datos de traducción disponibles para cada locale añadido.

	Nota
	Atención: el array devuelto puede ser muy grande, dependiendo del número de locales añadidos y de la cantidad de datos de traducción.

// returns all known message IDs
$messageIds = $translate->getMessageIds();
print_r($messageIds);

// or just for the specified language
$messageIds = $translate->getMessageIds('en_US');
print_r($messageIds);

// returns all the complete translation data
$source = $translate->getMessages();
print_r($source);