El proceso de Internacionalización de un Plugin o Tema nos permite que este pueda ser traducido a otros idiomas. En este HowTo para aprenderás paso a paso como internacionalizar tus propios Plugins y Temas de WordPress.
Para que un Plugin o Tema pueda ser internacionalizado primero tendremos que prepararlos. No importa el idioma que utilicemos inicialmente ya que cualquier usuario podrá traducirlo sin problemas.
Este proceso tan sólo nos llevará unas líneas de código.
Habilitando Traducciones
WordPress nos ofrece una gran variedad de funciones para habilitar las traducciones de textos, pero nos vamos a centrar en las más utilizadas:
- __( «texto que deseas traducir», clave_internacionalización )
- _e( «texto que deseas traducir», clave_internacionalización )
- _x( «texto que deseas traducir», clave_internacionalización )
La primera toma la cadena a traducir y devuelve la traducción en caso de que esta exista. Suele ser utilizada en funciones ya que con anterioridad se necesita procesar la traducción.
La segunda, consulta si la cadena existe y la imprime directamente en pantalla.
La tercera nos va a prevenir contra colisiones de textos o palabras coincidentes.
Ambas necesitan que le indiquemos una clave que será la que tengamos definida en nuestro Plugin o Tema como Text Domain. Veamos un ejemplo de aplicación en un Plugin:
|
1 2 3 4 5 6 7 8 9 10 11 12 |
<?php /** * Plugin Name: Privacidad * Plugin URI: https://wwww.artegrafico.net * Description: Controla la Privacidad de tu sitio web * Author: José Luis Rojo Sánchez * Author URI: https://wwww.artegrafico.net * Version: 1.0 * Date: 2019-07-01 * License: GPLv2 * Text Domain: artegrafico-lopdgdd */ |
Traducir textos directamente
Es este ejemplo vamos a traducir directamente código HTML para ser impreso en pantalla.
|
1 |
<p>Opciones de mi plugin</p> |
Para traducir este código HTML tendremos que realizar lo siguiente:
|
1 |
<p><?php echo _e( 'opciones de mi plugin', 'company-tuplugin' ); ?></p> |
Traducción a través funciones
En el siguiente ejemplo estamos incluyendo una nueva página al menú a un Plugin de WordPress por lo que no estamos traduciendo directamente el texto, sino que antes este debe ser procesado. Para ello usaremos la función __():
|
1 2 3 4 5 6 7 |
add_options_page ( __('Opciones de Privacidad', 'artegrafico-lopdgdd'), // titulo del menú __('Opciones de Privacidad', 'artegrafico-lopdgdd'), // atributo title 'manage_options', // cap 'opciones-privacidad', // slug [ $this, 'pageDashboard' ] // callback ); |
Es importante tener claro el uso de __() ya en caso de utilizar la función _e() el texto no será traducido.
Escapando traducciones
Hay varias funciones que nos permiten escapar valores a la hora de realizar traducciones.
- esc_html__() escapa código html para que este pueda ser mostrado
- esc_attr__() recibe la traducción y la escapa para su uso seguro en un atributo.
- esc_attr_e() visualiza la cadena traducida que ha sido escapada en un atributo.
- esc_html_e() visualiza la cadena traducida que ha sido escapada para uso seguro en HTML.
Traduciendo JavaScript
En ocasiones incluimos cadenas de texto en nuestros códigos JavaScript y no sabemos como actuar para poder realizar su traducción.
Para ello WordPress pone a nuestra disposición la función wp_localice_script( manejador, nombre, datos). Esta recibe 3 parámetros:
- El manejador es el identificador que tiene asignado el script.
- El nombre de la variable que contiene los datos y debe ser único.
- Un array de datos.
Veamos un ejemplo de uso:
|
1 2 3 4 5 6 |
$traduccion = array( 'menu_alerta' => __( 'texto a traducir', 'artegrafico-miplugin' ), 'menu_valor' => '10' ); wp_localize_script( 'my-script', 'variable', $traduccion ); wp_enqueue_script('my-script', get_stylesheet_directory_uri() . '/js/menu.js'); |
Implementación de Traducciones
Una vez hemos preparado todos los textos, el siguiente paso será decirle a WordPres dónde se van a ubicar las traducciones de nuestro tema o plugin.
Para poder cargar el Text-Domain de nuestro plugin o tema se usan 2 funciones, una de ellas para temas y otra para plugins:
- load_theme_textdomain( ‘text-domain’ , ‘directorio’ )
Debe ser llamada usando el hook after_setup_theme que es llamado durante cada carga de página después de que el tema ha sido inicializado. - load_child_theme_textdomain( ‘text-domain’ , ‘directorio’ )
Igual que el anterior pero para traducir temas hijos. - load_plugin_textdomain( ‘text-domain’ , ‘directorio’ )
Debe ser llamado usando el hook plugins_loaded que es ejecutado una vez los plugins han sido cargados.
Veamos como proceder con la internacionalización de un Plugin, donde vamos a indicar que el directorio de idiomas esta en languages/. Recuerda que el directorio lo tendrás que crear manualmente:
|
1 2 3 4 5 6 7 8 9 10 11 12 |
/** * Internacionalización del Plugin * @url https://codex.wordpress.org/Function_Reference/load_plugin_textdomain * @return boolean */ function artegrafico_load_plugin_textdomain() { load_plugin_textdomain( 'artegrafico-lopdgdd', // text-domain basename( dirname( __FILE__ ) ) . '/languages/' // path ); } add_action( 'plugins_loaded', 'artegrafico_load_plugin_textdomain' ); |
Lo que hemos hecho …
Hagamos un breve resumen de los pasos que hemos realizado:
- Hemos incluido la palabra clave Text Domain y su valor correspondiente en nuestro Tema o Plugin.
- Hemos procedido a implementar traducciones en todos los textos de nuestros ficheros del Tema o Plugin.
- Y por último hemos incluido la función encargada de la internacionalización de nuestro plugin o tema indicando cuando debe ser cargadas y en qué directorio debe ir a buscar los idiomas.
Finalizando
Por cada idioma dentro de nuestro directorio languages/ tendremos dos 2 ficheros (uno con extensión .mo y otro .po):
- El fichero con extensión .po es legible y se puede leer pero es de un tamaño mayor.
- El fichero con extensión .mo es de menor tamaño e ilegible para el ser humano ya que se ha convertido en binario para ser interpretado por WordPress.
Una vez nuestro tema esté listo para ser traducido ya no tenemos porqué ser nosotros los que realicemos la tarea de traducción sino que el destinatario o la comunidad podrían realizar dicha tarea.
Personalmente suelo utilizar el plugin loco Translate ya que permite realizar una traducción a otro idioma.
Tan solo tendremos que seleccionar el Plugin o Tema que deseamos traducir desde el menú de loco translate y a continuación pulsamos en crear una nueva plantilla. Este nos crea en el directorio languages/ un fichero de plantilla cuyo nombre está asociado a vuestro Text Domain (artegrafico-miPlugin.pot)
A continuación creamos un nuevo idioma e indicamos la ubicación de este dentro de nuestro Plugin o Tema. Pulsamos en «comenzar a traducir» y ya podemos empezar a incluir las traducciones de todas las cadenas que incorporamos anteriormente.
Se nos crearán los ficheros de traducción que hemos visto con anterioridad:
|
1 2 3 4 |
|-- languages/ |-- artegrafico-myplugin-en_US.mo |-- artegrafico-myplugin-en_US.po |-- artegrafico-myplugin.pot |
La localización de las funciones de WordPress están en el directorio wp-includes/110n.php
