Como importar traduções de temas e plugins para o WordPress.org

Dois caminhos colocam os arquivos .po e .mo traduzidos diante dos usuários do WordPress.org. Solicite acesso de CLPTE (4-6 dias) ou inclua os arquivos .mo no seu lançamento (no dia seguinte). Ambos funcionam. O compromisso é entre distribuição canônica e velocidade. Este guia aborda quando usar cada caminho e o passo a passo para ambos.

Você traduziu seu plugin ou tema com a PTC (Private Translation Cloud) e tem os arquivos .po e .mo. Os usuários que instalam seu plugin pelo WordPress.org não veem essas traduções por padrão. Os pacotes de idioma do WordPress.org e os seus arquivos incluídos são dois canais de distribuição separados. Escolha um com base na cadência do seu lançamento e no seu público.

Caminho 1: Publicar traduções por meio dos pacotes de idioma do WordPress.org (CLPTE)

Tempo total: 4-6 dias.

Passo 1: Criar uma conta CLPTE

O papel de CLPTE (Cross-Locale Project Translation Editor) permite que você envie traduções em nome do seu tema ou plugin em todos os idiomas de destino a partir de uma única conta. Uma conta normal de Editor de Tradução é por idioma; o CLPTE não é.

Se você já tem uma conta no WordPress.org, pode encontrar um problema em que sua nova conta CLPTE é desativada. O WordPress não permite múltiplas contas. Para resolver, envie um e-mail para forum-password-resets@wordpress.org e explique que você está tentando criar uma conta CLPTE. Compartilhar a documentação relevante dos Polyglots com o moderador e chamar a equipe dos Polyglots no Slack também ajudam.

Tempo estimado: ~3-5 dias (inclui o tempo de espera se sua nova conta for desativada).

Passo 2: Solicitar acesso de CLPTE no blog dos Polyglots

Com sua conta ativada, poste uma solicitação no blog dos Polyglots do WordPress.org. Siga o modelo deles:

PTE/CLPTE Request

Plugin URL: https://wordpress.org/plugins/my-plugin/
Authors / Editors: @your-wp-username
Type of request: CLPTE

Você recebe uma notificação quando sua solicitação for aprovada.

Tempo estimado: ~1 dia (a Equipe Global dos Polyglots analisa as solicitações em lotes).

Passo 3: Importar os arquivos .po traduzidos

1. Faça login em https://translate.wordpress.org/ usando sua conta CLPTE.
2. Acesse a página do projeto de tradução do seu plugin ou tema (por exemplo, translate.wordpress.org/projects/wp-plugins/{your-plugin-slug}/).
3. Abra o projeto local para cada idioma que você traduziu.
4. Role a página para baixo e clique em Importar traduções.
5. Faça o upload do seu arquivo .po (ou .mo).
6. Marque as strings importadas como “current” no editor de tradução. As strings aprovadas entram na próxima geração de pacotes de idioma (geralmente diária).
7. Repita para cada idioma de destino. Cada locale tem sua própria página de tradução.

Tempo estimado: ~10-30 minutos por idioma.

Após uma janela de 24-48 horas para o pacote de idioma, os sites que executam seu plugin começam a receber as novas traduções por meio das atualizações automáticas de pacotes de idioma do WordPress. Os usuários não veem nenhum aviso de atualização de versão. As traduções simplesmente aparecem.

O que o CLPTE fará e não fará por você

• Você não pode substituir traduções da comunidade existentes. Apenas strings não traduzidas são importadas. Atualizar uma tradução da comunidade existente requer o processo padrão e esperar pela revisão da equipe do locale.
• As atualizações exigem uploads manuais para cada lançamento. Cada novo lançamento significa uma nova rodada de uploads.
• A criação e aprovação da conta geralmente levam de 4 a 6 dias no total.

Caminho 2: Incluir os arquivos .mo dentro do seu plugin ou tema

Se você precisa das traduções em produção mais rápido do que o CLPTE permite, ou se prefere não depender do pipeline de distribuição do WordPress.org, inclua os arquivos .mo diretamente no lançamento do seu plugin ou tema. Tempo total: 15-30 minutos.

Passo 1: Adicionar os arquivos .mo ao diretório /languages/

Coloque seus arquivos .mo compilados dentro do diretório /languages/ do seu plugin ou tema para que o WordPress os encontre ao carregar seu text domain:

my-plugin/
├─ my-plugin.php
├─ readme.txt
├─ languages/
│  ├─ my-plugin-es_ES.mo
│  ├─ my-plugin-es_ES.po
│  ├─ my-plugin-fr_FR.mo
│  ├─ my-plugin-fr_FR.po
│  ├─ my-plugin-de_DE.mo
│  └─ my-plugin-de_DE.po

Use o mesmo text domain nos nomes dos seus arquivos de tradução e nas suas chamadas load_plugin_textdomain() ou load_theme_textdomain().

Passo 2: Preferir seus arquivos incluídos em vez das traduções da comunidade

Por padrão, o WordPress prioriza as traduções da comunidade do WordPress.org em vez das incluídas. Para garantir que seu plugin ou tema use os arquivos .mo incluídos, adicione o filtro load_textdomain_mofile.

Para plugins, adicione ao arquivo principal do seu plugin (ex.: my-plugin.php):

function my_plugin_load_embedded_translation_file( $mofile, $domain ) {
    if ( 'my-domain' === $domain && false !== strpos( $mofile, WP_LANG_DIR . '/plugins/' ) ) {
        $locale = apply_filters( 'plugin_locale', determine_locale(), $domain );
        $local_mofile = WP_PLUGIN_DIR . '/' . dirname( plugin_basename( __FILE__ ) ) .
                        '/languages/' . $domain . '-' . $locale . '.mo';

        if ( file_exists( $local_mofile ) ) {
            return $local_mofile;
        }
    }
    return $mofile;
}
add_filter( 'load_textdomain_mofile', 'my_plugin_load_embedded_translation_file', 10, 2 );

Para temas, adicione ao functions.php do seu tema:

function my_theme_load_embedded_translation_file( $mofile, $domain ) {
    if ( 'my-domain' === $domain && false !== strpos( $mofile, WP_LANG_DIR . '/themes/' ) ) {
        $locale = apply_filters( 'theme_locale', determine_locale(), $domain );
        $local_mofile = get_template_directory() . '/languages/' . $locale . '.mo';

        if ( file_exists( $local_mofile ) ) {
            return $local_mofile;
        }
    }
    return $mofile;
}
add_filter( 'load_textdomain_mofile', 'my_theme_load_embedded_translation_file', 10, 2 );

Confirme também se o seu plugin ou tema carrega o text domain no hook certo:

add_action( 'init', function() {
    load_plugin_textdomain(
        'my-plugin',
        false,
        dirname( plugin_basename( __FILE__ ) ) . '/languages'
    );
} );

Passo 3: Verificar se as traduções incluídas carregam em um site de teste

Instale seu plugin ou tema em um site de teste e mude o WordPress para um dos idiomas que você forneceu:

1. Acesse Configurações > Geral > Idioma do site e selecione um idioma cujo arquivo .mo esteja na sua pasta /languages/.
2. Carregue uma página ou tela que contenha strings que você sabe que estão traduzidas.
3. Confirme se as strings aparecem no idioma correto e correspondem às traduções que você adicionou.

Se você ainda vir traduções da comunidade antigas, revise o trecho de código no Passo 2. Ele precisa apontar corretamente o WordPress para os seus arquivos .mo incluídos.

Faça o commit dos arquivos .mo, crie a tag de um lançamento e faça o push para o wordpress.org via SVN como você faz normalmente.

O compromisso entre velocidade e distribuição canônica

• Pró: instantâneo. As novas traduções entram em produção no momento em que os usuários atualizam seu plugin (ou o instalam pela primeira vez). Sem espera de vários dias pelo CLPTE. Sem ciclo de aprovação da equipe dos Polyglots.
• Pró: você controla o fluxo de trabalho. A cadência de tradução corresponde exatamente à sua cadência de lançamento.
• Pró: sem dependência do selo do plugin. As traduções funcionam independentemente do seu plugin ter permissões de CLPTE.
• Contra: o tamanho do arquivo do plugin cresce. Cada .mo é pequeno (geralmente de 5 a 50 KB), mas 20 idiomas adicionam cerca de 500 KB ao download.
• Contra: sem atualização automática de traduções entre os lançamentos do plugin. Com o CLPTE, as traduções atualizadas no wordpress.org se propagam para os usuários em até 48 horas, mesmo se você não publicar um novo lançamento. Com a inclusão dos arquivos, as traduções só são atualizadas quando você publica um novo lançamento.
• Contra: sem selo de “traduzido”. O WordPress.org exibe um selo de conclusão de tradução nas listagens de plugins com base na cobertura do pacote de idioma, não nos arquivos .mo incluídos. Apenas incluir os arquivos não garante o selo.

Qual caminho corresponde à sua cadência de lançamento?

A abordagem dupla é comum: inclua os arquivos MO para disponibilidade imediata e envie para o CLPTE para distribuição canônica. Os usuários recebem as traduções incluídas na atualização; a sobreposição do pacote de idioma as atualiza entre os lançamentos.

Traduza o próximo lançamento do seu plugin com a PTC

Comece seu teste de 30 dias - 20.000 palavras por nossa conta, sem cartão de crédito. Gere seu arquivo .pot, faça o upload dele para a PTC, obtenha os arquivos .po e .mo traduzidos em minutos, prontos para o CLPTE ou inclusão.

Relacionado:

• Internacionalização do WordPress: como traduzir temas e plugins - o tutorial principal que abrange a geração de POT, text domains e o carregamento de traduções.
• As traduções do plugin do WordPress não aparecem? Corrija traduções ausentes - guia de solução de problemas para os erros de carregamento mais comuns.
• GlotPress vs PTC para tradução de plugins/temas do WordPress - quando escolher a tradução da comunidade vs a PTC.
• Manual de solicitação de PTE/CLPTE dos Polyglots do WordPress.org - o processo canônico de inscrição no CLPTE.