Como importar conteúdo multilíngue para o WordPress – WooCommerce, CSV e XML

Introdução

Por que este plugin

A Exportação e importação do WPML funciona em conjunto com o plugin de importação do WordPress que você já usa. O plugin de importação move seus dados. A Exportação e importação do WPML adiciona as informações de idioma no final, para que cada linha fique no idioma certo e cada tradução seja vinculada à sua origem.

Integrações

A Exportação e importação do WPML funciona com estas ferramentas de exportação e importação:

• WP All Export Pro e WP All Import Pro – exportam de um site WordPress com as informações de idioma incluídas automaticamente e importam posts, produtos e taxonomias de CSV ou XML.
• A ferramenta de exportação/importação integrada do WooCommerce (Produtos → Exportar e Produtos → Importar) – move produtos por meio de um único CSV, com as informações de idioma incluídas na exportação.
• A ferramenta de exportação/importação integrada do WordPress – move posts, páginas e tipos de post personalizados por meio de arquivos WXR.
• O plugin WP Import Export.
• Pipelines CSV ou XML personalizados – qualquer ferramenta que possa adicionar as colunas de idioma às suas linhas.

Legado – o plugin WPML All Import

O WPML All Import é o plugin legado que antecede a Exportação e importação do WPML. Ele não é mais suportado nem recomendado. O procedimento nesta página é a maneira atualizada de importar conteúdo multilíngue para um site WordPress – use-o em vez de qualquer fluxo de trabalho descrito na documentação do plugin antigo.

Exportação – obtenha seu arquivo de importação

Tudo o que você importa começa como um arquivo. Há duas maneiras de obter um:

• Exportá-lo de um site WordPress. Use uma ferramenta de exportação compatível e as informações de idioma acompanharão automaticamente.
• Prepará-lo você mesmo. Seus dados estão em uma planilha ou em um sistema externo (PIM, MLS, ERP, plataforma de reservas), e você adiciona as colunas de idioma ao arquivo manualmente – consulte Prepare seu próprio arquivo na seção Importação.

Configuração

Quando você estiver exportando de um site WordPress, instale e ative nele:

• WP All Export Pro (ou outra ferramenta de exportação compatível).
• Exportação e importação do WPML – adiciona as informações de idioma a cada linha exportada.

Quando você está preparando o arquivo por conta própria, não há nada para instalar – o trabalho está no próprio arquivo.

Execute a exportação

Exporte seu conteúdo do WordPress com a ferramenta de exportação de sua escolha. Com a Exportação e importação do WPML ativa, o arquivo de exportação já traz as colunas de idioma para cada linha – não há nada para adicionar manualmente. Continue com a seção Importação.

Importação – traga o conteúdo

Configuração

Instale e ative estes plugins no site para o qual você está importando:

• Um plugin de importação: WP All Import Pro, a ferramenta de importação integrada do WooCommerce, o importador integrado do WordPress ou o WP Import Export.
• WPML e WPML Tradução de Strings.
• Exportação e importação do WPML (o complemento que esta página aborda).
• WPML Multilingual & Multicurrency for WooCommerce se você estiver importando produtos do WooCommerce.

Configure o WPML com todos os idiomas que você planeja importar. Os idiomas de destino já devem existir em WPML → Configurações → Idiomas antes de você executar a importação.

O assistente de primeira importação

A primeira vez que você abre WPML → Exportação e importação, um breve assistente pergunta se você está exportando o conteúdo deste site ou de um site ou sistema diferente.

Quando você exporta deste site, o assistente também pergunta qual ferramenta você está usando – as ferramentas de exportação/importação integradas do WordPress ou do WooCommerce, WP All Export e WP All Import, WP Import Export ou um método diferente.

Com base nas suas respostas, a página mostra um guia de três etapas adaptado à sua configuração: como o seu conteúdo recebe as colunas de idioma (automaticamente para ferramentas compatíveis, manualmente caso contrário), a importação em si e o lembrete para voltar e executar a importação do WPML. Assim que detecta conteúdo importado com informações de idioma, a página relata quantos posts e termos estão aguardando e mostra o botão Executar a importação do WPML.

Não há mais nada para configurar – esta página é toda a interface do plugin.

Prepare seu próprio arquivo – planilhas e sistemas externos

Adicione três colunas a cada linha do seu arquivo. É assim que o WPML agrupa as traduções e marca cada linha com o idioma certo:

• _wpml_import_translation_group. Um valor exclusivo compartilhado por todas as versões de idioma de um conteúdo. Para produtos, use o SKU. Para todo o resto, gere seu próprio ID e reutilize-o para a linha de origem e cada tradução dela.
• _wpml_import_language_code. O código de idioma ISO para a linha (en para inglês, es para espanhol, fr para francês, pt-pt para português europeu e assim por diante).
• _wpml_import_source_language_code. Apenas nas linhas de tradução; o código de idioma do original. Deixe em branco para as linhas do idioma de origem.

Use cada valor de grupo de tradução para apenas um conteúdo. O WPML mantém o grupo de cada item que ele conecta, também após a importação. Uma linha que você importar mais tarde com o mesmo valor de grupo se juntará às traduções desse item.

Mais duas colunas são opcionais nas linhas de post e produto:

• _wpml_import_after_process_post_status. O status que o post recebe após Executar a importação do WPML. Use um nome de status do WordPress: publish, draft, pending ou private. Escreva publish, não published.
• _wpml_import_tea. Defina como 1 em uma linha de origem para enviar esse item para tradução automática. Esta coluna atua apenas quando o modo Traduzir tudo do WPML está ativado – consulte Traduza automaticamente o conteúdo importado.

Deixe um assistente de IA preparar o arquivo

Você não precisa adicionar essas colunas manualmente. Entregue o seu CSV ou arquivo de exportação a um assistente de IA junto com uma instrução como: “Adicione as colunas de importação do WPML _wpml_import_translation_group, _wpml_import_language_code e _wpml_import_source_language_code a este arquivo. As linhas em inglês são as originais; agrupe cada tradução com seu original pelo SKU.” O assistente preencherá as três colunas em segundos. Revise algumas linhas antes de importar.

Aqui está um exemplo prático para posts de blog. O arquivo tem uma coluna language e uma coluna original com o título do post em inglês que uma linha traduz:

title,content,language,original
Summer Sale,Our summer sale starts on June 1.,English,
Soldes d'été,Nos soldes commencent le 1er juin.,French,Summer Sale

A instrução para este arquivo:

Add the columns _wpml_import_translation_group, _wpml_import_language_code and _wpml_import_source_language_code to this CSV. The English rows are the originals. For each English row, make a short ID from its title and use it as the translation group. Give each translation the group of the English row that its original column names. Use the language codes en and fr. Leave the source language empty on English rows, and set it to en on the translations.

O resultado, com o conteúdo resumido:

title,content,language,original,_wpml_import_translation_group,_wpml_import_language_code,_wpml_import_source_language_code
Summer Sale,...,English,,summer-sale,en,
Soldes d'été,...,French,Summer Sale,summer-sale,fr,en

Para o WP All Import Pro e ferramentas semelhantes, prepare duas planilhas: uma para taxonomias (categorias, tags, categorias de produtos) e uma para posts e produtos. A ferramenta de importação integrada do WooCommerce usa uma única planilha porque as categorias de produtos ficam dentro das linhas do produto.

Atributos personalizados do WooCommerce para produtos variáveis

Se você tiver produtos variáveis com atributos personalizados, adicione uma coluna extra às linhas de produtos traduzidos: _wpml_import_wc_local_attribute_labels. O valor é um objeto JSON de pares slug:translation. Para um produto variável em francês com os atributos Tamanho e Cor:

{"size":"Taille","color":"Couleur"}

O slug é o nome do atributo em letras minúsculas com os espaços substituídos por traços.

Importe as taxonomias primeiro, depois os posts

Quando você tiver um arquivo separado para taxonomias, importe-o sempre primeiro. As categorias, tags e quaisquer outras taxonomias precisam existir antes que os posts e produtos possam referenciá-las. Em seguida, importe os posts, páginas, produtos e outros tipos de conteúdo.

Se você dividir seus dados em um arquivo por idioma, importe todos os arquivos de idioma antes de executar a etapa de conexão do WPML.

Você só executa a importação do WPML uma vez, depois que tudo estiver lá. A etapa de conexão processa as taxonomias antes dos posts e, em seguida, reconecta cada post aos termos no seu próprio idioma – para que os posts que foram importados enquanto os termos ainda não estavam conectados saiam anexados aos termos do idioma certo.

Mapeie as colunas de idioma no seu plugin de importação

Cada plugin de importação lida com colunas personalizadas à sua própria maneira. A etapa crítica é mapear as três colunas do WPML para campos personalizados (ou metadado de termo, para taxonomias). No WP All Import Pro, isso acontece no Passo 3 do assistente de importação:

• Para posts e produtos. Abra Custom Fields, adicione três campos, arraste as colunas de idioma para as caixas Value e use os nomes das colunas sem colchetes nas caixas Name.
• Para taxonomias. Abra Term Meta, adicione três campos de metadado de termo e mapeie as colunas de idioma da mesma forma.

Se as colunas não estiverem mapeadas, o WPML não terá nada para ler quando você executar a etapa de conexão.

O que você verá entre a importação e a etapa de conexão

Até que você execute a Exportação e importação do WPML, todo o conteúdo importado fica no seu idioma padrão, e o WPML mantém os posts e produtos automaticamente no status Rascunho para manter o conteúdo em idiomas misturados fora do front-end. Este é o estado intermediário esperado, não um sinal de falha na importação. Após a etapa de conexão, o conteúdo é publicado – ou definido para o status que você colocou na coluna _wpml_import_after_process_post_status.

Para plugins de importação não suportados, você precisará publicar os posts manualmente após a conclusão da etapa de conexão.

Execute a importação do WPML

Quando o plugin de importação terminar:

1. Abra WPML → Exportação e importação no painel de administração do WordPress.
2. Clique em Executar a importação do WPML.

O WPML lê as colunas de idioma de cada linha, atribui o idioma a essa linha e vincula as traduções à sua origem. Em catálogos grandes, isso pode levar vários minutos. Quando terminar, o seu conteúdo importado será publicado no idioma correto com cada tradução conectada à sua origem.

Faça uma verificação por amostragem no back-end e no front-end:

• Abra a lista de tipos de post ou de produtos – confirme se cada linha é exibida sob a bandeira de idioma certa.
• Visite o front-end e alterne os idiomas – cada página traduzida deve carregar a sua versão traduzida, e não voltar ao idioma de origem.

Se uma tradução de taxonomia não foi vinculada, abra o termo no painel de administração do WordPress e use a caixa Idiomas do termo para conectá-lo ao termo do idioma padrão.

O que a importação do WPML não abrange

A importação do WPML define o idioma de cada item e conecta as suas traduções. Ela não altera outros conteúdos. Verifique isto após a importação:

• Páginas ascendentes, menus e posts fixos. O WPML não ajusta o ascendente de uma página traduzida, não adiciona itens importados aos menus e não copia a configuração de fixação entre os idiomas.
• Links e IDs de imagem dentro do conteúdo. O WPML não altera os links, os IDs de imagem ou os campos de imagem dentro do conteúdo importado. Edite-os na tradução.
• Campos copiados. A importação do WPML conecta as traduções, mas não copia campos como preço ou estoque do original para as traduções. Para copiá-los após uma importação de atualização, abra o original e salve-o novamente.
• WooCommerce Bookings. Os produtos reserváveis são importados sem os seus tipos de pessoa (criança, adulto, etc.) e recursos. Adicione os tipos de pessoa e recursos aos produtos traduzidos após a importação.

Automação – execute a importação do WPML sem clicar

Para sincronizações noturnas, feeds de fornecedores, pipelines de implantação ou qualquer importação agendada, a etapa de conexão do WPML pode ser executada sem a interface de administração. Há três maneiras de configurar isso:

Endpoint POST (para importações baseadas em Cron, como WP All Import Scheduled Actions)

Esta é a forma recomendada. Adicione uma chave secreta forte ao wp-config.php:

define( 'WPML_IMPORT_KEY', 'your-strong-secret-key-here' );

Em seguida, adicione um segundo comando à configuração da sua importação agendada. Ele envia uma requisição POST para o seu site e passa a chave no corpo da requisição:

curl -X POST https://yoursite.com/ \
  -d 'wpml_import_trigger=your-strong-secret-key-here'

A mesma chamada com wget:

wget -q -O - \
  --post-data='wpml_import_trigger=your-strong-secret-key-here' \
  https://yoursite.com/

Para o agendamento manual do WP All Import Pro, adicione qualquer um dos comandos logo após o comando de importação.

Quando a etapa de conexão é executada, o seu site responde com o status 200 e esta mensagem:

Import process completed

Outras duas respostas indicam o que aconteceu: 401 significa que a chave não corresponde e 204 significa que não havia mais nada a processar.

O endpoint de URL antigo – removido na versão 5.0.0

Antes da Exportação e importação do WPML 1.2.0, você passava a chave na URL:

https://yoursite.com/?wpml_import_trigger=your-strong-secret-key-here

Desde a Exportação e importação do WPML 5.0.0, esta URL não executa mais a importação. Uma requisição que carrega a chave na URL recebe o status 405. Mude as suas importações agendadas para a chamada POST acima.

O motivo é a chave. Uma URL viaja pelos logs do servidor, histórico do navegador e análises, e a sua chave viaja com ela. Uma requisição POST mantém a chave no corpo da requisição.

Action hook (para importações agendadas por PHP)

Se você estiver agendando importações do PHP com o Action Scheduler ou wp_schedule_single_event, acione a etapa do WPML com uma chamada de ação:

do_action( 'wpml_import_process' );

Para executá-la como uma tarefa única em segundo plano logo após a sua ação de importação:

wp_schedule_single_event( time(), 'wpml_import_process' );

Se uma importação não terminar, consulte Depuração do WPML.

WP-CLI

Para scripts de implantação, builds de contêiner ou qualquer pipeline onde a interface de administração não esteja disponível, execute a etapa de conexão a partir do WP-CLI:

wp wpml import process

O comando informa quantas traduções foram conectadas. É um substituto direto para o botão Executar a importação do WPML.

Traduza automaticamente o conteúdo importado

Você pode fazer com que o WPML traduza o conteúdo importado automaticamente. Sem isso, você importaria o conteúdo em um idioma e depois – com o Traduzir tudo automaticamente ativado – selecionaria todos os itens importados e os enviaria para tradução por conta própria, o que consome muito tempo para grandes lotes e importações repetidas. Em vez disso, adicione mais uma coluna ao seu arquivo:

• _wpml_import_tea. Defina como 1 nas linhas do idioma de origem que você quer traduzir automaticamente.

Quando você executa a importação do WPML, o WPML cria trabalhos de tradução automática para cada post sinalizado, para cada um dos idiomas do seu site que ainda não tenha uma tradução. As linhas para as quais você importou traduções são deixadas intactas.

Isso exige que o modo Traduzir tudo automaticamente do WPML esteja ativado – sem ele, a sinalização é ignorada.

Armadilhas comuns

• O arquivo de importação não tem as três colunas de idioma. O conteúdo é importado, mas chega como linhas do idioma de origem não marcadas; Executar a importação do WPML não tem nada para conectar. Solução: adicione as colunas aos seus dados de origem, exporte novamente e importe novamente.
• O mapeamento de Custom Fields / Term Meta do WP All Import foi ignorado. O mesmo formato de colunas ausentes. Os dados estão no arquivo, mas o plugin de importação não os armazenou no post. Execute novamente a importação com os campos mapeados.
• Os idiomas de destino não estão configurados no site de importação. Linhas importadas para um idioma não configurado chegam no idioma padrão. Adicione os idiomas ausentes em WPML → Configurações → Idiomas primeiro, depois execute novamente.
• Plugin de importação não suportado. Os posts importados permanecem em Rascunho após a etapa de conexão. Publique-os manualmente ou mude para um plugin suportado.
• Scripts de importação personalizados que não passam os dados de idioma. A correção é no nível do script. As três colunas de idioma (e a coluna de atributos do WooCommerce, quando aplicável) precisam chegar à linha.
• O conteúdo que o seu próprio código adiciona não é mantido em Rascunho. O WPML mantém o conteúdo em Rascunho apenas para os plugins de importação suportados. O conteúdo que o seu código adiciona com wp_insert_post, ou uma importação do WooCommerce que é executada a partir do PHP ou WP-CLI, mantém o status que o código atribui a ele. Crie você mesmo o novo conteúdo como rascunhos e defina _wpml_import_after_process_post_status como publish.
• wp export descarta as colunas de idioma dos termos. O WP-CLI 2.12.0 é fornecido com o export-command 2.1.14, que não grava metadado de termo. Após wp import, cada categoria e tag perde as suas colunas de idioma. Atualize o export-command para a versão 2.1.15 ou posterior, ou exporte a partir de Ferramentas → Exportar no painel de administração do WordPress.

Se as importações continuarem esbarrando no mesmo problema, a equipe de suporte do WPML responde a dúvidas de suporte sobre importação 24 horas por dia, 7 dias por semana.

Casos de uso

Mova conteúdo multilíngue para um novo site

O cenário mais comum: exportar o conteúdo de um site com WPML e trazê-lo – total ou parcialmente – para outro.

1. No site de origem, instale a Exportação e importação do WPML junto com a sua ferramenta de exportação e exporte o conteúdo que você quer mover (consulte Exportação). As colunas de idioma acompanham automaticamente.
2. No novo site, conclua a configuração de importação – plugins instalados, todos os idiomas do site de origem configurados.
3. Importe as taxonomias e, em seguida, o conteúdo, com a sua ferramenta de importação.
4. Execute a importação do WPML. O seu conteúdo sai nos idiomas certos com cada tradução conectada, exatamente como no site de origem.

Redefina o WPML e importe novamente as traduções para o mesmo site

Pense na exportação como uma cópia de segurança da conexão de idiomas do seu site: o idioma de cada linha e quais linhas pertencem juntas como um grupo de tradução. Você pode manter essa cópia atualizada automaticamente – por exemplo, uma exportação noturna agendada na sua ferramenta de exportação, salva no seu próprio arquivo. Se os dados de idioma do WPML entrarem em um estado ruim, você redefine o WPML e importe novamente a exportação mais recente feita enquanto os dados ainda estavam bons, seguindo as etapas abaixo. Uma coisa que isso não pode fazer: reparar uma exportação feita após o problema – o arquivo preserva o estado em que os dados estavam quando foram exportados.

1. Exporte enquanto os dados de idioma estiverem intactos – ou pegue a sua exportação agendada mais recente. Exporte cada tipo de conteúdo que você se importa com as suas traduções (consulte Exportação). As três colunas de idioma capturam o que você precisará restaurar: o idioma de cada linha e quais linhas pertencem juntas como traduções umas das outras.
2. Redefina o WPML. Siga Redefinir WPML. A redefinição remove todos os dados do WPML – os idiomas, o idioma de cada item, os links entre as traduções, as traduções de strings e os trabalhos de tradução – e desativa o WPML. Os seus posts, páginas, produtos e taxonomias permanecem. Ative o WPML novamente.
3. Configure os idiomas novamente – o mesmo idioma padrão e os mesmos idiomas secundários que o site tinha antes da redefinição.
4. Importe novamente o mesmo arquivo, atualizando o conteúdo existente. Esta é a etapa que difere de uma migração para um novo site: os posts já existem, então a importação deve atualizá-los em vez de criar novos. Use o WP All Import com record matching (correspondência por ID) ou a opção update existing products do importador do WooCommerce. O importador padrão do WordPress não pode fazer isso – ele apenas cria novo conteúdo, então duplicaria cada linha.
5. Execute a importação do WPML. As atribuições de idioma e os grupos de tradução do arquivo são conectados de volta ao conteúdo existente.

Apenas o idioma de cada item e os links entre as traduções retornam. As traduções de strings, os trabalhos de tradução e as configurações do WPML não estão no arquivo de exportação. Configure-os novamente após a importação.

Adicione um idioma posteriormente

Você importou seu catálogo em inglês e espanhol e agora adiciona o francês. Prepare um arquivo apenas com as linhas em francês. Dê a cada linha o grupo de tradução do seu original, o código de idioma fr e o idioma de origem en. Importe o arquivo e clique em Executar a importação do WPML. O WPML mantém o grupo de cada item que conectou, para que cada linha em francês se junte às traduções do seu original.

Sincronize um feed de fornecedor todas as noites

Seu fornecedor envia um feed de produtos todas as noites. Os produtos originais estão em inglês e o feed tem as três colunas de idioma. Agende a importação no WP All Import Pro e adicione a chamada POST logo em seguida. Defina _wpml_import_tea como 1 nas linhas de novos produtos. A cada noite, os novos produtos recebem seus idiomas e o WPML os envia para tradução automática para os seus outros idiomas.