Internacionalización de WordPress: cómo traducir temas y plugins de WordPress

Preparación de su tema o plugin de WordPress para la traducción

Antes de poder traducir nada, debe configurar su código correctamente. Esto significa definir un dominio de texto, envolver todas las cadenas orientadas al usuario en funciones gettext y generar un archivo POT.

Nada de esto es complicado, pero los detalles importan. Un dominio de texto que no coincida o una cadena sin envolver significan que ese texto nunca aparecerá en su versión traducida.

Cada tema o plugin necesita un dominio de texto. Es un identificador único que indica a WordPress qué archivos de traducción pertenecen a su proyecto, y debe coincidir exactamente con el slug de su plugin o tema.

Declárelo en la cabecera del archivo principal de su plugin:

/**
 * Plugin Name: My Plugin
 * Text Domain: my-plugin
 * Domain Path: /languages
 */

/**
 * Plugin Name: My Plugin
 * Text Domain: my-plugin
 * Domain Path: /languages
 */

O en el style.css de su tema:

/*
Theme Name: My Theme
Text Domain: my-theme
Domain Path: /languages
*/

/*
Theme Name: My Theme
Text Domain: my-theme
Domain Path: /languages
*/

La ruta del dominio indica a WordPress dónde residen sus archivos de traducción en relación con la raíz del plugin o tema. El directorio /languages es el estándar.

Cualquier cadena que desee hacer traducible debe estar envuelta en una de las funciones gettext de WordPress. En tiempo de ejecución, estas funciones buscan la traducción correcta y recurren a la cadena original si no se encuentra ninguna traducción.

Cadenas básicas

Utilice __() cuando necesite devolver una cadena. Para la salida HTML (que es casi siempre el caso), utilice las variantes con escape:

// Return a translated string
$label = __( 'Settings', 'my-plugin' );

// Echo a translated string, escaped for HTML
echo esc_html__( 'Settings saved.', 'my-plugin' );

// Return a translated string
$label = __( 'Settings', 'my-plugin' );

// Echo a translated string, escaped for HTML
echo esc_html__( 'Settings saved.', 'my-plugin' );

Los estándares de codificación de WordPress recomiendan echo esc_html__() en lugar de _e() porque hace que el escape de salida sea explícito. Es una buena práctica aplicarla de forma consistente.

Cadenas con variables

Si concatenas una variable directamente en una cadena, los traductores solo ven los fragmentos, no la frase completa. Eso hace imposible traducir correctamente, especialmente en idiomas donde el orden de las palabras es diferente. En su lugar, usa printf() o sprintf() con un placeholder, y añade un comentario para traductores para que sepan qué representa %s:

printf(
    /* translators: %s: the user's display name */
    esc_html__( 'Welcome back, %s.', 'my-plugin' ),
    esc_html( $display_name )
);

printf(
    /* translators: %s: the user's display name */
    esc_html__( 'Welcome back, %s.', 'my-plugin' ),
    esc_html( $display_name )
);

Formas plurales

En inglés, los plurales son simples: one comment, two comments. Otros idiomas no son tan sencillos. Algunos tienen múltiples formas plurales según el número. Usa _n() para gestionar esto correctamente independientemente del idioma al que se traduzca tu plugin:

printf(
    esc_html( _n(
        '%s comment',
        '%s comments',
        $count,
        'my-plugin'
    ) ),
    number_format_i18n( $count )
);

printf(
    esc_html( _n(
        '%s comment',
        '%s comments',
        $count,
        'my-plugin'
    ) ),
    number_format_i18n( $count )
);

Cadenas que necesitan contexto

Algunas palabras significan cosas diferentes según el lugar donde aparezcan. Utilice _x() para dar a los traductores el contexto que necesitan para realizar la traducción correctamente:

// "Export" as a noun (the file) vs. a verb (the action)
echo esc_html_x( 'Export', 'button label', 'my-plugin' );

// "Export" as a noun (the file) vs. a verb (the action)
echo esc_html_x( 'Export', 'button label', 'my-plugin' );

WordPress proporciona el paquete wp-i18n para que pueda utilizar en JavaScript las mismas funciones gettext que utiliza en PHP. Al registrar su script, declare wp-i18n como una dependencia:

wp_register_script(
    'my-plugin-script',
    plugins_url( 'js/app.js', __FILE__ ),
    array( 'wp-i18n' ),
    '1.0.0',
    true
);

wp_register_script(
    'my-plugin-script',
    plugins_url( 'js/app.js', __FILE__ ),
    array( 'wp-i18n' ),
    '1.0.0',
    true
);

Después, en su archivo JavaScript:

const { __, _n, sprintf } = wp.i18n;

const message = __( 'Settings saved.', 'my-plugin' );

const { __, _n, sprintf } = wp.i18n;

const message = __( 'Settings saved.', 'my-plugin' );

Si utiliza un empaquetador como Webpack, utilice @wordpress/babel-plugin-makepot para extraer las cadenas traducibles de su paquete como parte de su proceso de compilación.

Una vez envueltas las cadenas, debe generar un archivo POT (Portable Object Template). Este es el archivo fuente a partir del cual trabaja PTC (o cualquier traductor). Contiene todas sus cadenas traducibles pero aún ninguna traducción.

Ejecute este comando desde el directorio raíz de su plugin o tema:

wp i18n make-pot . languages/my-plugin.pot

wp i18n make-pot . languages/my-plugin.pot

WP-CLI escanea sus archivos PHP, JavaScript y block.json en busca de llamadas gettext y las compila en un único archivo POT. Si utiliza Composer, puede añadir esto como un script de Composer para que el comando sea coherente en todo su equipo y no requiera una instalación global de WP-CLI.

La suite completa wp i18n incluye todo lo demás que necesitará más adelante en el flujo de trabajo: