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: el programa 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 que 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.

Mientras configura sus cadenas, utilice el plugin Herramientas multilingües para verificar qué cadenas son traducibles y cuáles necesitan configuración adicional.

Cadenas codificadas de forma rígida

Las cadenas codificadas de forma rígida 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 las claves de sus opciones no son fijas y su tema utiliza una matriz de entradas que puede crecer con la información que introduce el usuario, registre estas entradas de forma dinámica. Puede utilizar las funciones de la API de WPML para hacerlo.

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. Escanee su plugin o 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, necesita registrarlos para su traducción.

Consulte las siguientes guías para obtener más información sobre cómo registrar el contenido de los maquetadores visuales:

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, utilice el filtro wpml_object_id para obtener automáticamente el ID de la entrada traducida.

Por ejemplo, considere un carrusel con diapositivas en diferentes idiomas, cada una con un ID único. Para cargar automáticamente el ID de la diapositiva correcta en cada idioma, podemos utilizar 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, etc. correspondiente y añada una cadena de texto
2. Configure su característica para que utilice 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. Obtenga la compatibilidad 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 que han iniciado sesión, 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 hacerlo, 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;
}

Cómo hacer compatibles las características especiales

Si su tema o plugin incluye características especiales (como el uso de tablas personalizadas), necesitará 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 filtran los ID de las entradas correctas para el idioma actual +

Solución:

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

Todas las diapositivas se muestran en un 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 idioma secundario +

Solución:

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

El carrusel está utilizando una página de administración personalizada y necesito registrar los valores de los campos personalizados en 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 idioma secundario +

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 del idioma predeterminado +

Solución:

Al crear URL de AJAX personalizadas, utilice el hook wpml_current_language y añada el idioma actual como parámetro para las URL de 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 de contenido, utilice el hook wpml_switch_language para cambiar el idioma del contenido. Cierre el ámbito del idioma cuando termine. A partir de WPML 5.0, los cambios de idioma se anidan, por lo que cada cambio necesita su propia restauración.

if ( ! empty( $_GET[ 'wpml_lang' ] ) ) {
    // Opens a language scope. Only a non-empty language code switches the language.
    do_action( 'wpml_switch_language', sanitize_text_field( $_GET[ 'wpml_lang' ] ) );

    try {
        // Run other content queries.
    } finally {
        // Closes the scope that the call above opened.
        do_action( 'wpml_switch_language', null );
    }
}

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 idioma secundario. 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”.