Joomla! Documentation™

Introducción a la traducción de plantillas

Joomla! es una aplicación realmente internacional y soporta la traducción de todas las cadenas de texto que contiene. Las plantillas no son una excepción, e invertir algo de tiempo extra en asegurar que las cadenas que usa su plantilla son traducibles se amortizará solo.

El sistema de traducción de idiomas ha sido diseñado para ser tan simple y a prueba de errores como sea posible. Por ejemplo, incluso si faltara un archivo, o una cadena en particular no hubiera sido traducida, Joomla mostrará la cadena sin traducir de forma transparente al usuario. Hay también algunas herramientas útiles integradas en Joomla para ayudar a los traductores a crear una nueva traducción.

En este capítulo aprenderá cómo construir archivos de definición de idioma para su plantilla y cómo incluir traducciones en su paquete de idioma. También aprenderá cómo asegurarse de que todas las cadenas usadas en su plantilla son traducibles y cómo depurar una nueva traducción.

Ubicación de archivos de definición de idioma de la plantilla

Los archivows de de definición de idioma de la plantilla del lado cliente se almacenan en

[path-to-Joomla]/language/[ln-LN]

donde [ln-LN] es el código de idioma. Los códigos de idioma se definen en RFC3066 El archivo debe ser nombrado

[ln-LN].tpl_[template-name].ini

donde [plantilla-nombre] es el nombre de la plantilla (en minúsculas). Por ejemplo, el archivo de idioma Inglés Británico para la plantilla Beez es

[path-to-Joomla]/language/en-GB/en-GB.tpl_beez.ini

También debes crear un archivo de idioma para traducir tu plantilla del Administrador de lado servidor. Este será almacenado en

[path-to-Joomla]/administrator/language/[ln-LN]

pero la convención de nomenclatura de archivos es la misma.

Para el administrador de plantillas, que son distintas de las plantillas del lado cliente, el segundo de estos archivos es el único necesario. Por ejemplo, los archivo de idioma Inglés Británico para la plantilla del administrador Khepri se encuentra en

[path-to-Joomla]/administrator/language/en-GB/en-GB.tpl_khepri.ini

Crear un archivo de definición de idioma

Joomla! 

3.x

series

This Article Needs Your Help

Los archivos de definición de idioma de Joomla! se escriben en un formato de archivo INI muy básico. Deben ser guardados usando la codificación UTF-8. Las líneas en blanco y las líneas que comienzan con ; son ignoradas y estos últimos puede ser utilizados para añadir comentarios al archivo. Cada línea consta de un par clave-valor, separados por un signo igual que este:

CLAVE="valor"

donde CLAVE es una cadena a traducir y valor es la traducción de la cadena. Por ejemplo:

ADDITIONAL_INFORMATION="Información Adicional"

Diferentes versiones de Joomla! han utilizado formas ligeramente distintas para leer los archivos de idioma (es decir, un analizador personalizado y el analizador nativo de PHP INI, el último de los cuales tenia errores en PHP 5.2 y mayores), que conducen a diferentes reglas de lo que está exactamente permitido en las claves y valores. Los archivos de idioma que se rigen por las siguientes reglas deben trabajar en distintas versiones de Joomla, pero al menos con Joomla y más reciente.

La CLAVE debe utilizar sólo caracteres ASCII. Sólo debe contener letras mayúsculas, dígitos, guiones bajos o guiones medios, y debe empezar con una letra mayúscula. (Puntos (.) están permitidos oficialmente, pero parecen no ser totalmente compatibles.) Es una convención para reemplazar cualquier espacio en blanco en la cadena a traducir con caracteres de subrayado. Si hay más de una entrada que tiene la misma clave, la última que se ha encontrado es el que será utilizada. Cuando se utiliza la clave en una llamada JText::_, no importa si las cadenas son mayúsculaso minúsculas, pues las mismas se llevan a mayúsculas antes de que la búsqueda se lleve a cabo. Así additional_information, Additional_Information o incluso AdDiTiOnAl_InFoRmAtIoN será igualado.

El valor debe ser siempre rodeado de caracteres de comillas dobles ("), como en el ejemplo. El valor en sí mismo no puede incluir caracteres de comillas dobles ("), aunque solo caracteres de comillas (') son válidos. Usar "_QQ_", incluyendo las comillas dobles, para poner un carácter de comillas dobles en valor. Por ejemplo, para adjuntar el valor <span class="red">Advertencia!</span> a la clave WARNING_TEXT, utiliza la siguiente línea:

WARNING_TEXT="<span class=\"red\">Warning!</span>"

Ten en cuenta que estas reglas son más estrictas que las requeridas por el analizador PHP INI. Por ejemplo, el analizador PHP INI permite omitir las comillas dobles alrededor del valor siempre y cuando no contenga ciertos caracteres. El uso de las reglas de arriba debería hacer mucho más fácil para evitar errores como olvidar las comillas dobles cuando ellas "son" necesarios.

Información acerca de los cambios en el formato del archivo de idioma entre las series 1.5, 2.5 y 3.x de Joomla! puede ser encontrada en la página de Especificación de los archivos de idioma.

Modificar el archivo templateDetails.xml

Para asegurarse de que tsu plantilla esta totalmente internacionalizada, debes asegurarse de que ciertos elementos XML son traducibles y que los archivos de definición del idioma se enumeran en el archivo templateDetails.xml.

Traducción de templateDetails.xml

Un par de los elementos en el archivo templateDetails.xml que se utiliza en el Gestor de Plantillas y son traducibles. La descripción debe siempre ser traducida.

nombre	Nombre de la plantilla. Por ejemplo, Beez
descripción	Descripción de la plantilla

Estos campos también se muestran al usuario durante la instalación de la plantilla.

Agregar archivo de definiciones de idiomas templateDetails.xml

Todos los archivos de idioma deben ser declarados en el archivo templateDetails.xml. Esto se hace mediante la adición de dos elementos <language> para cada idioma que se incluye con la plantilla; uno para las cadenas del lado cliente; el otro para las cadenas delel administrador del lado servidor. Por ejemplo, los dos archivos en idioma Inglés Británico y los dos archivos de Idioma Alemán para la plantilla Beez se declaran de la siguiente manera:

<?xml version=”1.0” encoding=”utf-8” ?>
<install version=”1.5” type=”template”>

     .........

    <languages>
        <language tag=”en-GB”>en-GB.tpl_beez.ini</language>
        <language tag=”de-DE”>de-DE.tpl_beez.ini</language>
    </languages>

     .........

    <administration>
        <languages folder=”admin”>
            <language tag=”en-GB”>en-GB.tpl_beez.ini</language>
            <language tag=”de-DE”>de-DE.tpl_beez.ini</language>
        </languages>
    </administration>

</install>

Tenga en cuenta que en la administración con la etiqueta <languages> se utiliza el atributo carpeta. Esto es debido a que los archivos de idioma para el lado cliente y lado servidor tienen los mismos nombres de archivo y por lo tanto no pueden existir en el mismo directorio dentro del paquete de archivos de la plantilla. En este ejemplo, los archivos de idioma de la administración se han colocado en un sub-directorio llamado admin para separarlos de los archivos de idioma del lado cliente.

Incluir cadenas traducibles en la plantilla

En la plantilla misma las traducciones son manejadas usando la clase estática JText. Se la conoce como "estática", ya que no requiere la creación de instancias como un objeto antes que sus métodos se puedan usar.

Cadenas de texto Simple

La mayoría de las cadenas de texto se puede traducir mediante el método "_" (guión bajo). Por ejemplo, supón que tu plantilla contiene el texto en inglés "Welcome" que necesitas ser hecho traducible.

<?php
    echo 'Welcome';
?>

Entonces, habría que reemplazar la cadena estática por una como esta

<?php
    echo JText::_( 'Welcome' );
?>

Esto provocaría que el sistema de traducción busque el archivo de idioma adecuado para "WELCOME" del lado izquierdo de un signo de igual. La búsqueda es sensible a las mayúsculas. Si se encuentra esta cadena de definición de idioma

WELCOME=Welcome!

entonces el efecto será la salida de la cadena "Welcome!" en el navegador. Si el usuario cambia al idioma Alemán, a continuación, en el archivo de definición del idioma alemán se buscará "WELCOME" y esta vez podría encontrar la cadena

WELCOME=Willkommen

y así "Willkommen" será enviado al navegador. Es importante destacar que, si el usuario cambia al alemán, pero no hay ningún archivo de idioma alemán en ese momento o la cadena correspondiente no aparece en el archivo de idioma alemán, Joomla!, a continuación, volverá a enviar la cadena de texto sin traducir "Welcome" al navegador, además preserva el caso original.

Campos con formato en las cadenas de idioma

En ocasiones es necesario incluir campos con un formato especial dentro de una cadena a traducir. Esto habitualmente ocurre cuando hay números implicados pero puede ocurrir con fechas y horas o cuando se requieren instrucciones de formato específicas. Si las cadenas no van a ser traducidas, pueden usarse las funciones estándar de PHP printf o sprintf. La función printf muestra una cadena formateada usando instrucciones incluidas; la función sprintf devuelve una cadena formateada utilizando las mismas instrucciones de formateo incluidas.

La clase JText proporciona métodos de contenedor para las funciones printf y sprintf permitiendo texto estático para ser traducidos, además también permite campos formateados para ser incorporado utilizando la misma sintaxis que las funciones de PHP.

Por ejemplo, suponga que tiene la cadena "Donations of 12.45 GBP have been received", donde la cantidad proviene de una variable, $donations. Se podría dividir la cadena en dos como estas:

JText::_( 'Donations of' ) . “ $donations GBP “ . JText::_( 'have been received' )

con cadenas de definición de idiomas

DONATIONS OF=Donations of
HAVE BEEN RECEIVED=have been received

pero esto no funciona bien en los idiomas donde los datos insertados no están en un lugar similar en la cadena traducida. En su lugar utilice el método de "sprintf" de esta forma

JText::sprintf( 'Donations have been received', $donations )

con cadena de definición de idioma

DONATIONS HAVE BEEN RECEIVED=Donations of %.2f GBP have been received

Se puede incluir más de un especificador de formato en una cadena de traducción. Las sustituciones se realizan en orden, de manera que esto funcionara como se espera

JText::sprintf( 'String with numbers in it', $num1, $num2, $num3 )

con cadena de definición de idioma

STRING WITH NUMBERS IN IT=First %d, second %d, third %d

Sintaxis de los especificadores de formato

El especificador de formato consta de un signo de porcentaje (%), seguido por uno o más de estos elementos, en orden:

Orden	Tipo	Valores	Descripción
1.	Símbolo	+ ó -	Opcional. Fuerza un símbolo (+ ó -) en un número. De forma predeterminada sólo se utiliza el símbolo - en un número si es negativo. Este especificador fuerza que los números positivos tengan el símbolo + también.
2.	Relleno	<space> o 0 or '<char>	Opcional. Carácter que se utilizará para el relleno de los resultados para el correcto tamaño de la cadena. Puede ser un carácter de espacio o un 0 (número cero). El valor predeterminado es para rellenar con espacios en blanco. Una alternativa de relleno de caracteres puede ser especificado por el prefijo con una comilla simple ( ' ).
3.	Alineación	<null> or -	Opcional. Determina si el resultado debe ser justificado a la izquierda o justificado a la derecha. El valor predeterminado es justificado a la derecha; un carácter - aquí indica justificado a la izquierda.
4.	Ancho	Número	Opcional. Número de caracteres (como mínimo) que deben resultar de la conversión.
5.	Precisión	Número	Opcional. Número de dígitos decimales que se deben mostrar para los números de punto flotante. Cuando se utiliza este especificador en una cadena, actúa como punto de corte, estableciendo un límite máximo de caracteres de la cadena.
6.	Tipo	Obligatorio. El tipo de los datos argumento. Los tipos posibles son:
		%	Un carácter de porcentaje literal. No requiere argumento
		b	El argumento se trata como un entero y se presenta como un número binario.
		c	El argumento es tratado como un entero y presentado como el carácter del valor ASCII.
		d	El argumento es tratado como un entero y presentado como un número decimal con signo.
		e	El argumento es tratado como notación científica (por ejemplo, 1.2 e+2). El especificador de precisión es el número de dígitos después del punto decimal desde PHP 5.2.1. En versiones anteriores, se tomaba como el número de dígitos significativos (menos uno).
		u	El argumento es tratado como un entero y presentado como un número decimal sin signo.
		f	El argumento es tratado como un float, y presentado como un número de punto flotante (considera la configuración local).
		F	El argumento es tratado como un float, y presentado como un número de punto flotante (no considera la configuración local).
		o	El argumento es tratado como un entero y presentado como un número octal.
		s	El argumento de que se trata y se presenta como una cadena.
		x	El argumento es tratado como un entero y presentado como un número hexadecimal (en minúsculas).
		X	El argumento es tratado como un entero y presentado como un número hexadecimal (en mayúsculas).

Intercambio de argumento del formato

La cadena de formato admite el argumento de numeración e incluso de intercambio. Esto es útil cuando dos o más elementos de datos deben ser integrados en una cadena, pero las diferencias en la estructura de la lengua significa que el orden de uso de los elementos de datos no es el mismo.

Por ejemplo, supongamos que tenemos el siguiente código:

echo JText::sprintf( 'Balls in the bucket', $number, $location );

con esta traducción de la cadena de idioma

BALLS IN THE BUCKET=There are %d balls in the %s

Entonces si

$number = 3
$location = 'hat'

esto resultará en "Hay 3 bolas en el sombrero". Pero considere si quiere cambiar la traducción a

BALLS IN THE BUCKET=The %s contains %d balls

Este sería ahora la salida de "El 3 contiene sombrero bolas", que es claramente absurdo. En lugar de cambiar el código, se puede indicar en la cadena de traducción la posición de referencia del argumento de cada uno de los marcadores. Cambiar la traducción a

BALLS IN THE BUCKET=The %2$s contains %1$d balls

Y el resultado será ahora "El sombrero contiene 3 pelotas" tal y como esperábamos.

Una ventaja añadida de poder numerar los argumentos es que puede repetir los contenedores sin añadir más argumentos al código. For ejemplo, cmabie la traducción a

BALLS IN THE BUCKET=The %2$s contains %1$d balls, so there are %1$d balls in the %2$s

Y esto mostrará "El sombrero contiene 3 pelotas, por lo que hay 3 pelotas en el sombrero".

Depurar una traducción

Joomla! es compatible con algunosmecanismos de depuración útiles que pueden facilitar la localización de cadenas sin traducir y diagnosticar los problemas con las traducciones en las extensiones instaladas.

Depurar el Idioma

Activa la depuración del idioma a través de la Administración del Lado Servidor, entra en Configuración Global y has clic en la pestaña Sistema. Encuentra el campo la Depuración de Idioma, cambia el valor a "Sí" y guardar los cambios.

Con esta opción activa todas las cadenas traducibles se muestra rodeado de caracteres especiales que indican su estado

Código	Estado
**Joomla CMS**	(El texto rodeado por asteriscos) indica que la clave ha sido encontrada en el archivo de definición de idioma y la cadena valor ha sido traducida.
??Joomla CMS??	(texto rodeado por pares de signos de interrogación) indica que la cadena es traducible, pero no se encontró concordancia de clave en el archivo de definición de idioma.
Joomla CMS	(texto sin caracteres adyacentes) indica que la cadena no es traducible.

Depurar el Sistema

Información adicional para depuración del idioma puede ser obtenida mediante la activación de la depuración del sistema. Esto se hace yendo a la Configuración Global y has clic en la pestaña Sistema. Encuentra el campo Depuración del Sistema, cambia el valor a "Sí" y guarda los cambios.

Con esta opción activa todas las pantallas tienen información de depuración adicional al final de cada página. Actualmente, esto incluye

• Información del perfil. Esta el tiempo necesario para ejecutar código en diferentes puntos marcados en el código.
• Uso de la memoria. La cantidad de RAM del sistema utilizada.
• Consultas SQL ejecutadas. Todas las consultas SQL ejecutadas en el proceso de construcción de la página.
• Archivos de idioma cargados. Una lista de todos los archivos de idioma cargado en el proceso de construcción de la página, incluyendo la información de la ruta de acceso completa. Esto puede ser útil para comprobar que los archivos se han cargado. El número después de cada ruta de acceso del archivo es el número de veces que se hace referencia al archivo.
• Diagnóstico de cadenas no traducidas. Una lista de todas las cadenas sin traducir encontradas y la probable ubicación del archivo donde JText realizó la llamada.
• Diseño de las cadenas no traducidas. Una lista de todas las cadenas sin traducir pero aparece en un formato CLAVE=Valor, de manera que se pueda copiar y pegar directamente en un archivo de definición de idioma (INI).

Depurar los Plugin

Este plugin del sistema controla lo que se muestra cuando la depuración está activada en Configuración Global. Está activado por defecto. Puedes acceder a los parámetros del plugin en Extensiones → Gestor de plugins. Busque el plugin "Sistema - Depurador" y has clic en él. Hay tres opciones de interés para los traductores.

• Mostrar archivos de idioma. Si se establece en "Sí", a continuación, la información de depuración incluye una lista de los archivos de idioma que se intentaron cargar cuando la página actual se generó.
• Mostrar cadenas de idioma. Si se establece en "modo de diagnóstico", a continuación, una lista de cadenas sin traducir y la ubicación del archivo que contiene la llamada a "'JText"' se incluye en la información de depuración. Si se establece en "modo de diseñador", a continuación, una lista de cadenas sin traducir en un formato que se puede copiar y pegar directamente en un archivo de definición de idioma se incluye en la información de depuración. Es decir, se muestra la lista en formato CLAVE=Valor. Si se establece a "Todos los modos", a continuación, tanto las listas en modo de diagnóstico y diseñador se incluyen en la información de depuración.
• Quitar la primera palabra. Sólo se utiliza cuando "'Mostrar cadenas de idioma"' está establecido en "modo Diseñador" o "Todos los modos". Esto permite que usar un prefijo de la cadena para formar la clave. Esto es útil si el diseñador utiliza un prefijo común para sus extensiones al usar métodos JText. Ver el ejemplo de abajo.

Ten en cuenta que la pantalla de cadenas sin traducir sólo mostrará el valor pasado al adecuado método JText. Por ejemplo, con el siguiente código:

echo JText::_( 'Reports Import Configuration' );

Si no es traducida, Diseñador de modo mostrará esto:

# /administrator/components/com_reports/views/reports/tmpl/default.php
REPORTS IMPORT CONFIGURATION=Reports Import Configuration

Si la Quitar la primera palabra se establece en "Informes", a continuación, la pantalla podría cambiar ligeramente a:

# /administrator/components/com_reports/views/reports/tmpl/default.php
REPORTS IMPORT CONFIGURATION=Import Configuration

Ten en cuenta que la ruta que se muestra es sólo una conjetura basada en una llamada a la función "debug_backtrace" de PHP. A veces es preciso, a veces no lo es y también hay casos donde no se puede determinar. En esos casos, tienes que utilizar tu mejor juicio.

---