Cómo hacer que sus plugins y temas sean compatibles con WPML

Siga nuestra guía paso a paso para hacer que sus plugins y temas sean compatibles con WPML.

Esta guía está dirigida a los autores de temas y plugins que ya se han unido a nuestro programa de compatibilidad: Go Global. Si aún no se ha unido, envíe su solicitud antes de seguir esta guía.

Cómo ser compatible con WPML

1. Cree un archivo de configuración de idioma

Un archivo de configuración de idioma le indica a WPML qué textos traducir (y cuáles no) en su plugin o tema. Esto incluye textos en tipos de contenido personalizado, taxonomías, campos, pantallas del panel de administración, widgets y más.

Si ya sabe cómo crear un archivo de configuración de idioma, siga las instrucciones a continuación para probar su configuración. De lo contrario, consulte nuestra guía de configuración de idioma para aprender a crear uno.

Configuración de prueba
1. Cree algunas entradas y taxonomías
2. Envíelas a traducir
3. Verifique que aparezcan traducidas en el front-end

2. Prepare las cadenas para su traducción

Las cadenas son cualquier texto que aparece en el sitio y no forma parte de entradas, páginas o taxonomías. Para permitir que WPML traduzca las cadenas de su plugin o tema, siga las instrucciones a continuación para cada caso de uso.

A medida que configure sus cadenas, use el plugin Herramientas multilingües para verificar qué cadenas son traducibles y cuáles necesitan configuración adicional.

Cadenas codificadas

Las cadenas codificadas deben registrarse con funciones gettext. Obtenga más información sobre el uso de gettext y la preparación de su código.

Cadenas en wp_options

Si su plugin o tema utiliza cadenas de la tabla wp_options , regístrelas en el archivo wpml-config.xml.

Si sus claves de opciones no son fijas, y su tema utiliza una matriz de entradas que puede crecer con la entrada del usuario, registre estas entradas dinámicamente. Puede usar las funciones de la API de WPML para hacer esto.

Cadenas dinámicas

Si ninguno de los métodos anteriores se aplica a sus cadenas, siga estas guías para preparar las cadenas para su traducción:

Configuración de prueba
1. Analice su plugin/tema en busca de cadenas en WPML → Localización de temas y plugins
2. Cree una página con cadenas
3. Compruebe si las cadenas aparecen en Traducción de cadenas
4. Traduzca algunas cadenas y verifique que aparezcan traducidas en el front-end

3. Registre widgets y bloques personalizados para su traducción

Si su tema o plugin incluye widgets personalizados para maquetadores visuales, como Elementor, debe registrarlos para su traducción.

Consulte las siguientes guías para obtener más información sobre cómo registrar el contenido del maquetador visual:

Configuración de prueba
1. Cree una página con todos sus widgets personalizados
2. Envíe la página a traducir y verifique que los textos de los widgets aparezcan en el Editor de traducción avanzado
3. Compruebe que las traducciones se muestren en el front-end
4. Repita los pasos para probar diferentes configuraciones de los widgets

4. Obtenga automáticamente los ID de diferentes idiomas

Si su tema o plugin tiene características u opciones que cargan diferentes ID de entradas en cada idioma, use el filtro wpml_object_id para obtener automáticamente el ID de la entrada traducida.

Por ejemplo, considere un slider con diapositivas en diferentes idiomas, cada una con un ID único. Para cargar automáticamente el ID de diapositiva correcto en cada idioma, podemos usar el filtro wpml_object_id:

// Loop posts
while (have_posts()): the_post();
$post = get_post( apply_filters( 'wpml_object_id', $post->ID, 'slide' ) );

Configuración de prueba
1. Cree la entrada/plantilla relevante, etc., y añada una cadena de texto
2. Configure su característica para usar esa entrada
3. Traduzca la entrada y establezca un valor diferente en la cadena de texto
4. Compruebe que la característica esté cargando el ID traducido en el front-end

5. Hágase compatible con WooCommerce

WPML puede traducir el contenido de WooCommerce con su complemento WPML Multilingual & Multicurrency for WooCommerce. Si su tema o plugin contiene elementos de WooCommerce, siga nuestra guía de compatibilidad de WPML Multilingual & Multicurrency for WooCommerce para hacerlo compatible con WPML.

6. Muestre u oculte el selector de idiomas del panel de administración

De forma predeterminada, WPML añade un selector de idiomas a la barra de administración de WordPress. Este selector es visible para los usuarios conectados, tanto en el front-end como en el back-end.

Selector de idiomas en la barra de administración superior

En algunos casos, es posible que quiera ocultar el selector de idiomas en páginas confidenciales, como su área de configuración. Para hacer esto, añada el siguiente código a su archivo functions.php:

//Make sure to rename the function before adding to your plugin
add_filter( 'wpml_show_admin_language_switcher', 'compsupp_disable_wpml_admin_lang_switcher' );
 
function compsupp_disable_wpml_admin_lang_switcher( $state ) {
    global $pagenow;
 
    // Add the admin pages that we need to hide the language switcher
    $admin_pages_to_hide_ls = array(
        'admin-page-slug', 'another-admin-page-slug', 'one-more-admin-page-slug'
    );
 
    // We can also have a filter here in case we need to add/remove pages later
    $admin_pages_to_hide_ls = apply_filters( 'compsupp_filter_disable_wpml_lang_switcher_in_admin', $admin_pages_to_hide_ls);
     
    if (
        $pagenow == 'admin.php'
        && isset( $_GET['page'] )
        && in_array( $_GET['page'], $admin_pages_to_hide_ls)
    ) {
        $state = false;
    }
    return $state;
}

Hacer compatibles las características especiales

Si su tema o plugin incluye características especiales (como el uso de tablas personalizadas), tendrá que usar código personalizado para hacerlas compatibles con WPML.

Consulte nuestros recursos para desarrolladores para obtener información sobre el desarrollo personalizado.

Problemas comunes y soluciones

Las etiquetas de los formularios no se pueden traducir porque provienen de la base de datos +

Solución:

$label = esc_html( apply_filters('wpml_translate_single_string', $this->checkout_item->name, 'wpsc', '$this->checkout_item->name .'_checkout_form_label'' ) );

wp_query($args) o get_posts($args) no filtra los ID de entradas correctos para el idioma actual +

Solución:

Si usa wp_query($args) o get_posts($args), debe añadir “suppress_filters=0” a los argumentos.

Todas las diapositivas se muestran en un solo idioma +

Solución:

// Unset not translated slides
foreach( $slides as $k => $slide ) {
	$check = apply_filters( 'wpml_post_language_details', NULL, $slide->ID )
	$slide_language_code = substr( $check['locale'], 0, 2 );

	if( $check['different_language'] ) {
		unset( $slides[$k] );
	}
}

El ID de la diapositiva es diferente en un segundo idioma +

Solución:

// Loop posts
while (have_posts()): the_post();
$post = get_post( apply_filters( 'wpml_object_id', $post->ID, 'slide' ) );

El slider utiliza una página de administración personalizada y necesito registrar valores de campos personalizados para las traducciones +

Solución:

// Adding a new slide code
$slide_id = $this->slide->ID;
$url = $fields['url'];

// Register slide URL to translations
do_action( 'wpml_register_single_string', 'Slider', 'Slide_ID_' . $this->slide->ID, $url);

$this->add_or_update_or_delete_meta($this->slide->ID, 'url', $url);

El ID de una taxonomía personalizada es diferente en un segundo idioma +

Solución:

$taxonomy_id = apply_filters( 'wpml_object_id', $taxonomy_id, 'my_custom_taxonomy' );

Las peticiones AJAX personalizadas (no estándar de WordPress) siempre devuelven el contenido en el idioma predeterminado +

Solución:

Al crear URL AJAX personalizadas, use el hook wpml_current_language y añada el idioma actual como parámetro para las URL AJAX.

$ajax_url = 'http://my-site.com/wp-content/plugins/my-plugin/handle-ajax.php';
$my_current_lang = apply_filters( 'wpml_current_language', NULL ); 
if ( $my_current_lang ) {
	$ajax_url = add_query_arg( 'wpml_lang', $my_current_lang, $ajax_url );
	// $ajax_url will be something like 'http://my-site.com/wp-content/plugins/my-plugin/handle-ajax.php?wpml_lang=es'
}

Al gestionar peticiones AJAX en el archivo handle-ajax.php, antes de generar la salida del contenido, use el hook wpml_switch_language para cambiar el idioma del contenido.

if ( isset( $_GET[ 'wpml_lang' ] ) ) {
    do_action( 'wpml_switch_language',  $_GET[ 'wpml_lang' ] ); // switch the content language
}

// Run other content queries.

Uso incorrecto del valor “id” en los argumentos de WP_Query $args[ ‘tax_query’ ][ ‘field’ ] +

Solución:

El uso del argumento “id” para el parámetro “field” funciona para el idioma predeterminado, pero no funciona para el segundo idioma. El siguiente es un ejemplo de una consulta incorrecta:

$args = array(
    'post_type' => 'post',
    'tax_query' => array(
        array(
            'taxonomy' => 'people',
            'field'    => 'id',
            'terms'    => 'bob',
        ),
    ),
);
$query = new WP_Query( $args );

Los desarrolladores deben corregir el parámetro “field”.

'field'    => 'id',

'field'    => 'term_id',

Referencia: https://codex.wordpress.org/Class_Reference/WP_Query#Taxonomy_Parameters. No hay ningún valor “id” para el parámetro “field”. Su valor predeterminado es “term_id”.