Criar bloco personalizado do Gutenberg – Parte 8: suporte à tradução

Nesta parte, vamos nos concentrar em como traduzir os textos e valores em nosso bloco Gutenberg personalizado. Usamos o WP-CLI para gerar os arquivos necessários para que o Gutenberg possa carregar nossas traduções ao alternar o idioma do WordPress.

Antes de prosseguir com isso, você precisa ter o WP CLI (interface de linha de comando para WordPress) instalado. Se você não tiver, basta seguir o guia no WordPress Handbook for CLI.

Para explicar resumidamente como traduzir para scripts Javascript (Gutenberg): WordPress requer .moarquivos para tradução de arquivos PHP, mas para Javascript o WordPress requer um .jsonarquivo. Cada arquivo Javascript precisa de um arquivo JSON para tradução. O JSON deve ter um formato específico (o WP CLI o gerará para nós) com nossas strings traduzidas. Precisamos de um arquivo JSON por idioma para o qual desejamos traduzir.

Então o que precisamos fazer é primeiro adicionar as funções gettext (__(), _e()etc.) em nossos arquivos Javascript e gerar um arquivo PO como de costume para nosso tema ou plugin. Como envolvemos os textos em nossos arquivos de script com, por exemplo __(),, o arquivo PO deve ser capaz de incluí-los. Em seguida, fazemos a tradução como de costume em nosso arquivo PO. E, finalmente, usamos WP CLI para extrair as strings necessárias do arquivo PO e gerar arquivos JSON para todos os nossos arquivos Javascript.

Lembre-se de que os arquivos / – do seu tema ou plug-in .ponunca .moterão efeito em seus arquivos Javascript – mesmo que contenham strings traduzidas de nossos arquivos Javascript.

Implementando a tradução em Javascript

O primeiro passo é agrupar todos os textos em nosso arquivo Javascript dentro das funções de tradução. Se você já lidou com a tradução para WordPress em PHP, provavelmente está muito familiarizado com as funções __(), _e(), esc_html__()e assim por diante. O WordPress possui um pacote wp.i18nque contém essas funções, que funcionam exatamente como no PHP.

Assim como no PHP, você precisa fornecer um domínio de domínio de texto (nome/identificador). Pode ser o que você quiser, mas mantenha-o curto, pois você provavelmente precisará digitá-lo com muita frequência. Para o meu tema, configurei meu textdomain com o domínio awhitepixel. Então dentro do PHP eu vou fazer __('My string', 'awhitepixel')para traduzir strings, e vai ser exatamente igual nos arquivos Javascript.

Vamos começar a editar nosso arquivo Javascript. Primeiro precisamos desestruturar a função __and _edo wp.i18npacote. Por causa da natureza do React, provavelmente você usará principalmente ou talvez apenas a __função.

const { __, _e } = wp.i18n;

E então é uma questão de encontrar todos os nossos textos codificados no arquivo Javascript e atualizá-los. Tenha em mente que as funções __e _erequerem contexto Javascript. Isso significa que quando digitamos strings como, por exemplo, valores de propriedades de objetos, usamos __()imediatamente, mas como valores para, por exemplo, props, precisamos envolver tudo dentro { }para significar que este é um código Javascript.

Por exemplo, nosso registerBlockTypecom suporte para tradução ficará assim:

registerBlockType('awp/firstblock', {
    title: __('My first block', 'awhitepixel'), 
    category: 'common',
    icon: 'smiley',
    description: __('Learning in progress', 'awhitepixel'),
    keywords: [__('example', 'awhitepixel'), __('test', 'awhitepixel')],
    attributes: {
        ...

E quanto aos adereços, ou seja, em InspectorControls:

Enrole todos os textos para os quais você deseja apoiar a tradução em __()e _e(). Se você seguiu este tutorial passo a passo, não deve ter nenhum caso em que precise usar _e(). Quando terminar, recompile o Javascript e nos afastaremos do Javascript.

Configurando arquivos po e/ou pot

Esta etapa varia um pouco dependendo do que você já fez e configurou para o seu tema ou plugin. Você pode estar escrevendo seus scripts Gutenberg em um plugin novo e vazio que não foi configurado para tradução PHP, ou dentro de um tema que já tenha um domínio de texto registrado. Você pode ter arquivos PO (e MO) prontos ou pode ter apenas um arquivo POT. Vou tentar o meu melhor para cobrir todas as bases.

Meu tema ou plugin já tem um arquivo po(t)

Se você já tem um arquivo PO ou POT em seu projeto, provavelmente também tem a função PHP load_theme_textdomain(), load_child_theme_textdomain()ou load_plugin_textdomain()em algum lugar em seu código. Certifique-se de que o domínio registrado é o mesmo que você usou em seus arquivos Javascript.

Tudo o que você precisa fazer é carregar o arquivo PO para o idioma que deseja traduzir (ou gerar um a partir do arquivo POT) em, por exemplo , PoEdit. Clique em "Atualizar do código" (ou similar em outros programas) para que o programa possa verificar todos os arquivos do projeto (incluindo nossos arquivos Javascript atualizados recentemente) e atualizar o conjunto de strings para tradução. As strings em nosso arquivo Javascript devem aparecer. Em seguida, você só precisa traduzi-los normalmente e salvar.

PS: Se você não conseguir clicar em “Atualizar do código" ou redigitalizar os arquivos, o arquivo PO provavelmente não foi configurado corretamente. Procure dicas na próxima seção.

Não tenho nenhum arquivo de tradução

Se o seu tema ou projeto não foi configurado com tradução, você precisa gerar um arquivo POT usando WP-CLI ou criar manualmente um arquivo PO.

Eu tenho um guia completo sobre como criar um arquivo PO no meu Tutorial de Tema para Iniciantes – parte 8. A postagem descreve como você pode criar o arquivo e configurá-lo corretamente para pesquisar seus arquivos de tema e as palavras-chave para pesquisar (__, _e, etc.).

Se você preferir criar um arquivo POT, você pode usar o comando wp i18n make-pot no WP-CLI e, em seguida, criar um arquivo PO usando, por exemplo, PoEdit. Lembre-se de que você precisará gerar novamente o arquivo POT (e, em seguida, o arquivo PO) toda vez que atualizar qualquer string em seu código.

Resultado final

O que você precisa é de um arquivo PO que encontrou suas strings Javascript onde elas foram traduzidas. Eu recomendo colocar seus arquivos de tradução em uma pasta separada em seu tema ou plugin. Quando começarmos a gerar arquivos JSON, teremos alguns arquivos para tradução e será bom mantê-los todos juntos em sua própria pasta.

Como ponto de referência, estou colocando todos os arquivos de tradução no meu arquivo theme/assets/lang/. Adicionei uma tradução norueguesa para o meu tema, chamada nb_NO.po, que contém as strings traduzidas do nosso arquivo Javascript de bloco personalizado.

Gerando arquivos JSON a partir do arquivo po

O próximo passo é usar o WP-CLI para gerar arquivos JSON do nosso arquivo po. Para isso usamos o comando wp i18n make-json.

Esteja ciente de que, por padrão, este comando retirará as strings traduzidas do seu arquivo PO para uso na geração do arquivo JSON. Isso pode ser complicado no meio do desenvolvimento do seu tema ou plugin. Porque quando você adiciona novas strings ou ajusta strings, você terá que redigitalizar os arquivos e traduzir todas as strings novamente (e novamente e novamente). Felizmente, há um sinalizador no comando para evitar isso.

Vamos começar! No seu terminal, navegue até o diretório de idioma do seu projeto. Execute o seguinte comando e consulte o seu arquivo po (como mencionado, eu tenho um nb_NO.poarquivo pronto).

wp i18n make-json nb_NO.po --no-purge

Se você não tiver nenhum problema em remover as strings traduzidas do seu arquivo PO (por exemplo, se estiver fazendo sua compilação final), pule o --no-purgesinalizador.

O terminal deve solicitar “Sucesso” e indicar quantos arquivos JSON foram criados. Se você vir que ele gerou dois arquivos JSON, é porque ele leu nosso arquivo Javascript de código-fonte e o arquivo de compilação e gerou um para cada um. Se você tiver mais arquivos Javascript em seu projeto, terá ainda mais arquivos JSON.

No momento em que escrevo isso (WordPress v 5.3.2 e WP-CLI versão 2.4.0), os arquivos JSON são gerados com o código do idioma e um hash – uma string enigmática como nomes de arquivos. Precisamos encontrar o caminho certo e renomeá-lo.

Renomeando o arquivo JSON e carregando-o em PHP

Sua pasta de idioma provavelmente se parece com isso:

Lembre-se de que o comando gerou um arquivo JSON por arquivo Javascript – e como na verdade temos dois arquivos para nosso bloco personalizado (o código-fonte e o build), ele gerou dois arquivos. Se o seu código Javascript for dividido em vários arquivos, cada um receberá dois de seus próprios arquivos JSON.

Se você está sentado com apenas dois arquivos JSON (porque nenhum outro arquivo Javascript foi encontrado), você pode excluir um deles agora. Se você tiver mais de dois, precisará abrir os arquivos JSON e ver para qual arquivo eles são. Os arquivos JSON contêm uma propriedade ” source” que informa para qual arquivo Javascript este arquivo JSON se destina. Use isso para descobrir qual arquivo JSON manter. Eu recomendo encontrar o arquivo de compilação final (em oposição aos arquivos dev), pois ele deve conter todas as strings de todos os arquivos.

Quando você encontrar o correto, precisamos renomeá-lo. Precisamos renomeá-lo para seguir este padrão:

[textdomain]-[language code]-[script handle].json

Use o textdomain que você usou em todos os lugares (por exemplo __('My string', 'awhitepixel'), ), adicione um traço e o código do idioma. Em seguida, forneça um traço e o identificador de script que você usou para registrar seu arquivo Javascript do Gutenberg (wp_register_script()). Como referência, meu textdomain é awhitepixel, meu código de idioma é nb_NO, e meu identificador de script para o script Gutenberg é awp-myfirstblock-js. Então eu renomeio o arquivo JSON para:

awhitepixel-nb_NO-awp-myfirstblock-js.json

Diga ao WordPress para carregar nosso JSON

Tudo o que resta agora é a etapa final – dizer ao WordPress para carregar nosso arquivo JSON. Precisamos usar a função [wp_set_script_translations](https://developer.wordpress.org/reference/functions/wp_set_script_translations/)(). Esta é uma função muito nova do WordPress, então eu recomendo envolvê-la dentro de um arquivo function_exists(). Aceita três parâmetros; o identificador de script para nosso bloco, o textdomain e o caminho para nossa pasta de tradução (observação: o caminho, não o URL).

Dentro da nossa função hooked to init, onde registramos nosso script de bloco e chamamos register_block_type, também podemos chamar essa nova função para carregar nosso arquivo de tradução JSON. PS: Tenha em mente que o gancho enqueue_block_assetsnão funcionará para registrar traduções.

add_action('init', function() {
    wp_register_script('awp-myfirstblock-js', ....);
    register_block_type('awp/firstblock', ....
 
    if (function_exists('wp_set_script_translations')) {
        wp_set_script_translations('awp-myfirstblock-js', 'awhitepixel', get_template_directory(). '/assets/lang');
    }
});

E isso é tudo! Seu bloco agora deve ser traduzido. Mude o idioma do WordPress para o idioma para o qual você traduziu e verifique por si mesmo. Quando mudo meu idioma do WordPress para norueguês e adiciono meu bloco, o nome e tudo dentro dele são traduzidos: