Como tornar seus plugins e temas compatíveis com o WPML

Siga nosso guia passo a passo para tornar seus plugins e temas compatíveis com o WPML.

Este guia é destinado a autores de temas e plugins que já participam do nosso programa de compatibilidade – Go Global. Se você ainda não participa, envie sua solicitação antes de seguir este guia.

Como se tornar compatível com o WPML

1. Crie um arquivo de configuração de idioma

Um arquivo de configuração de idioma diz ao WPML quais textos traduzir (e quais não traduzir) no seu plugin ou tema. Isso inclui textos em tipos de post personalizados, taxonomias, campos, telas de administração, widgets e muito mais.

Se você já sabe como criar um arquivo de configuração de idioma, siga as instruções abaixo para testar sua configuração. Caso contrário, consulte nosso guia de configuração de idioma para aprender a criar um.

Configuração de teste
1. Crie alguns posts e taxonomias
2. Envie-os para tradução
3. Verifique se eles aparecem traduzidos no front-end

2. Prepare as Strings para tradução

As Strings são quaisquer textos que aparecem no site e não fazem parte de posts, páginas ou taxonomias. Para permitir que o WPML traduza as strings no seu plugin ou tema, siga as instruções abaixo para cada caso de uso.

À medida que você configura suas strings, use o plugin Multilingual Tools para verificar quais strings são traduzíveis e quais precisam de configuração adicional.

Strings codificadas

As strings codificadas precisam ser registradas com funções gettext. Saiba mais sobre como usar o gettext e preparar seu código.

Strings em wp_options

Se o seu plugin ou tema usa strings da tabela wp_options , registre-as no arquivo wpml-config.xml.

Se as chaves de opção não forem fixas e o seu tema usar um array de entradas que pode crescer com a entrada do usuário, registre essas entradas dinamicamente. Você pode usar as funções da API do WPML para fazer isso.

Strings dinâmicas

Se nenhum dos métodos anteriores se aplicar às suas strings, siga estes guias para preparar as strings para tradução:

Configuração de teste
1. Analise seu plugin / tema em busca de strings em WPML → Localização de temas e plugins
2. Crie uma página com strings
3. Verifique se as strings aparecem na Tradução de Strings
4. Traduza algumas strings e verifique se elas aparecem traduzidas no front-end

3. Registre widgets e blocos personalizados para tradução

Se o seu tema ou plugin inclui widgets personalizados para construtores de páginas, como o Elementor, você precisa registrá-los para tradução.

Consulte os guias a seguir para saber mais sobre como registrar o conteúdo do construtor de páginas:

Configuração de teste
1. Crie uma página com todos os seus widgets personalizados
2. Envie a página para tradução e verifique se os textos dos widgets aparecem no Editor de tradução avançado
3. Verifique se as traduções são exibidas no front-end
4. Repita as etapas para testar configurações diferentes de widgets

4. Busque IDs automaticamente de diferentes idiomas

Se o seu tema ou plugin tiver recursos ou opções que carregam IDs de post diferentes em cada idioma, use o filtro wpml_object_id para buscar automaticamente o ID do post traduzido.

Por exemplo, considere um slider com slides em idiomas diferentes, cada um com um ID exclusivo. Para carregar automaticamente o ID correto do slide em cada idioma, podemos usar o filtro wpml_object_id:

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

Configuração de teste
1. Crie o post / modelo relevante, etc., e adicione uma string de texto
2. Configure seu recurso para usar esse post
3. Traduza o post e defina um valor diferente na string de texto
4. Verifique se o recurso está carregando o ID traduzido no front-end

5. Torne-se compatível com o WooCommerce

O WPML pode traduzir o conteúdo do WooCommerce com seu complemento WPML Multilingual & Multicurrency for WooCommerce. Se o seu tema ou plugin contiver elementos do WooCommerce, siga nosso guia de compatibilidade do WPML Multilingual & Multicurrency for WooCommerce para torná-lo compatível com o WPML.

6. Mostre ou oculte o seletor de idiomas do painel de administração

Por padrão, o WPML adiciona um seletor de idiomas à barra de administração do WordPress. Esse seletor é visível para usuários conectados, tanto no front-end quanto no back-end.

Seletor de idiomas na barra de administração superior

Em alguns casos, você pode querer ocultar o seletor de idiomas em páginas sensíveis, como sua área de configurações. Para fazer isso, adicione o seguinte código ao seu arquivo 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;
}

Como tornar recursos especiais compatíveis

Se o seu tema ou plugin incluir recursos especiais (como o uso de tabelas personalizadas), você precisará usar código personalizado para torná-los compatíveis com o WPML.

Consulte nossos recursos para desenvolvedores para obter informações sobre desenvolvimento personalizado.

Problemas comuns e soluções

Os rótulos de formulário não podem ser traduzidos porque vêm do banco de dados +

Solução:

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

wp_query($args) ou get_posts($args) não filtram os IDs de posts corretos para o idioma atual +

Solução:

Se você usar wp_query($args) ou get_posts($args), precisará adicionar “suppress_filters=0” aos argumentos.

Todos os slides são mostrados em um idioma +

Solução:

// 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] );
	}
}

O ID do slide é diferente em um segundo idioma +

Solução:

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

O slider está usando uma página de administração personalizada e preciso registrar valores de campos personalizados para traduções +

Solução:

// 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);

Um ID de taxonomia personalizada é diferente em um segundo idioma +

Solução:

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

Requisições AJAX personalizadas (não padrão do WordPress) sempre retornam o conteúdo do idioma padrão +

Solução:

Ao criar URLs AJAX personalizadas, use o hook wpml_current_language e adicione o idioma atual como um parâmetro para as URLs 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'
}

Ao manipular requisições AJAX no arquivo handle-ajax.php, antes de gerar a saída do conteúdo, use o hook wpml_switch_language para alternar o idioma do conteúdo.

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

// Run other content queries.

Uso incorreto do valor “id” no(s) argumento(s) WP_Query $args[ ‘tax_query’ ][ ‘field’ ] +

Solução:

O uso do argumento “id” para o parâmetro “field” funciona para o idioma padrão, mas não funciona para o segundo idioma. O exemplo a seguir é de uma consulta incorreta:

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

Os desenvolvedores devem corrigir o parâmetro “field”.

'field'    => 'id',

para:

'field'    => 'term_id',

Referência: https://codex.wordpress.org/Class_Reference/WP_Query#Taxonomy_Parameters. Não há valor “id” para o parâmetro “field”. Seu valor padrão é “term_id”.