Como traduzir campos personalizados do ACF no WordPress – Grupos de campos, Repetidores, Páginas de opções

Antes de começar

Instale e ative estes plugins:

• Advanced Custom Fields ou ACF Pro.
• WPML e WPML Tradução de Strings.
• ACFML (o complemento que esta página abrange).

Seus Grupos de campos já devem estar configurados no ACF. Você pode alterar as preferências de tradução por campo depois, então a ordem das operações não importa. Configure os Grupos de campos e depois volte para o ACFML.

Escolha uma opção de tradução para cada Grupo de campos

Os Grupos de campos do ACF não se comportam todos da mesma maneira durante a tradução. O ACFML oferece três opções de tradução para cada Grupo de campos. Para escolher uma:

1. Vá para ACF → Grupos de campos e edite o Grupo de campos.
2. Na seção Configuração multilíngue, em Selecione uma opção de tradução para este grupo de campos, clique em Escolher na opção que você quer.
3. Salve o Grupo de campos.

O ACFML marca a opção que sugere para o seu site como recomendado para este site. Para escolher outra opção depois, clique em Alterar opção. Versões mais antigas do ACFML chamam as duas primeiras opções de Mesmos campos entre idiomas e Campos diferentes entre idiomas.

O mesmo conteúdo em todos os idiomas, traduzido

A configuração típica para a maioria dos sites com ACF. Os visitantes em todos os idiomas veem as mesmas páginas, em seu próprio idioma. O texto é traduzido, e o layout e as configurações permanecem os mesmos. A página Nossa equipe é o exemplo comum. Sua equipe é a mesma em todos os idiomas, então o nome e a biografia de cada membro da equipe são traduzidos, e a estrutura dos campos permanece a mesma. Você insere a equipe no idioma padrão e, em seguida, envia o post para tradução em WPML → Traduções → Painel. Os valores traduzidos retornam para os mesmos campos. Esta opção funciona com a tradução automática e com o Traduzir tudo.

Cada idioma tem seu próprio conteúdo

Use esta opção quando cada idioma mostrar um conteúdo diferente no mesmo Grupo de campos. O exemplo comum é uma empresa que realiza eventos locais. A página Eventos em inglês mostra eventos para um público inglês, e a página em francês mostra eventos para um público francês. Os campos começam como uma cópia do original. Depois disso, cada idioma mantém seus próprios valores. Você edita cada idioma no editor do WordPress: abra o post, clique no ícone de adição para o idioma de destino na caixa Idioma, preencha os valores para esse idioma e publique. O WPML não sincroniza as versões de idioma depois disso, e a tradução automática não se aplica.

Especialista

Use esta opção quando você precisar de uma mistura: alguns campos são traduzidos, alguns permanecem os mesmos, e alguns são copiados uma vez e depois mudam em cada idioma. Escolha Especialista e defina a preferência de tradução de cada campo manualmente. No exemplo de Eventos, o título e a descrição usam Traduzir, e o preço, a data e o endereço usam Copiar. O ACFML não recomenda esta opção para novos Grupos de campos. Um Grupo de campos definido em PHP ou Local JSON pode não ter nenhuma opção de tradução. Nesse caso, ele usa Especialista apenas quando o Grupo de campos existe antes do seu site ser atualizado para o WPML 5.2.

Preferências de tradução para cada tipo de campo do ACF

Todo campo que armazena um valor tem uma de quatro preferências de tradução:

• Traduzir. Os visitantes veem o valor em seu próprio idioma. O WPML o preenche com a tradução. Você o edita no editor de tradução.
• Copiar. Os visitantes em todos os idiomas veem exatamente o que o original mostra. O campo fica bloqueado nos outros idiomas.
• Copiar uma vez. O valor começa como uma cópia do original. Depois disso, você o edita em cada idioma manualmente. Se você esvaziar o campo em uma tradução, ele permanecerá vazio. O WPML não copia o valor original para ele novamente.
• Não traduzir. As traduções começam sem este valor. Você pode preenchê-lo em cada idioma manualmente.

Quando você escolhe O mesmo conteúdo em todos os idiomas, traduzido ou Cada idioma tem seu próprio conteúdo, o ACFML dá a cada campo a preferência recomendada para o seu tipo de campo. As tabelas abaixo mostram essas preferências recomendadas. Para definir uma preferência diferente para um campo, use Especialista. Para alterar a preferência recomendada de um tipo de campo em todo o site, use o filtro acfml_field_group_mode_field_translation_preference (veja Hooks de desenvolvedor para casos extremos abaixo).

Os campos Aba, Acordeão, Mensagem e Separador não armazenam um valor, então eles não têm preferência de tradução. Um tipo de campo que não está nas tabelas, por exemplo, um tipo de campo de outro plugin, recebe Copiar com ambas as opções de tradução.

Campos Repetidor, Conteúdo flexível, Grupo e Clone

Esses campos contêm outros campos. A preferência recomendada do campo contêiner é Copiar ou Copiar uma vez. O ACFML não oferece Traduzir para o próprio campo contêiner. Cada subcampo tem sua própria preferência de tradução.

Com O mesmo conteúdo em todos os idiomas, traduzido, as linhas dos campos Repetidor e Conteúdo flexível permanecem na mesma ordem que no idioma padrão. Com Especialista, ou quando um post usa Grupos de campos com opções diferentes, o editor do post mostra uma caixa Sincronizar traduções do ACFML. Ela aparece no post original quando o post tem traduções e um campo Repetidor ou Conteúdo flexível. Selecione Manter o repetidor e os subcampos flexíveis na mesma ordem que o idioma padrão para manter as linhas alinhadas em todos os idiomas.

Campos básicos

Campos de conteúdo

Campos de escolha

Campos jQuery

Campos de layout

Campos relacionais

Para um campo de Link, a tradução abrange o texto do link e a URL. Quando a URL aponta para uma página no seu site e você não a altera, o WPML mostra a página no idioma do visitante.

Campos de URL e link

A partir do ACFML 5.0, os campos de URL e Link usam a preferência Traduzir por padrão.

Relacionamentos bidirecionais

Desde o ACF 6.2, os campos Relacionamento, Objeto de post, Taxonomia e Usuário podem ser bidirecionais. Quando você seleciona um destino no campo, o ACF adiciona seu post ao campo emparelhado do destino. Por exemplo, o livro Duna define seu campo Autor como Frank Herbert. O ACF então adiciona Duna ao campo Livros de Frank Herbert.

O ACFML mantém o par em cada idioma:

• Quando o WPML copia o campo para uma tradução, o ACFML aponta o campo para o destino no mesmo idioma. Em seguida, o ACFML adiciona a tradução ao campo emparelhado desse destino. O Dune em espanhol mostra o Frank Herbert em espanhol, e o Frank Herbert em espanhol lista o Dune em espanhol.
• Quando o campo usa Copiar e você altera o destino no post original, o WPML atualiza a tradução. O ACFML adiciona a tradução ao novo destino nesse idioma e a remove do destino antigo.
• O ACFML altera apenas os destinos no idioma da tradução. Os posts no idioma original mantêm seu próprio par.
• Quando o destino ainda não tem tradução, a tradução aponta para o destino original, e o ACFML não altera o destino original. Quando você traduz o destino mais tarde, o ACFML aponta o campo para a nova tradução e adiciona o post ao seu campo emparelhado. O campo lista o destino uma vez.
• Os usuários não têm traduções, então o ACFML não adiciona traduções ao campo emparelhado de um usuário. Esse campo mantém o post original. Em outro idioma, o ACFML mostra a tradução desse post, a menos que o campo use Copiar.

Isso funciona para as preferências Copiar e Copiar uma vez, que são as preferências recomendadas para esses tipos de campo. Também funciona quando você duplica um post com o WPML.

Traduzir blocos do ACF

Por padrão, os blocos do ACF salvam os valores dos seus campos dentro do bloco, no conteúdo do post, e não como campos personalizados. O ACFML envia esses valores para tradução junto com o restante do post, no mesmo trabalho de tradução.

• O bloco usa a opção de tradução e as preferências de campo do Grupo de campos cuja regra de localização é esse bloco.
• O ACFML envia apenas os campos que usam Traduzir. Os campos que usam Copiar, Copiar uma vez ou Não traduzir mantêm o valor do bloco original.
• Os campos Repetidor e Conteúdo flexível dentro de um bloco também são traduzidos, inclusive quando estão aninhados. Cada subcampo usa sua própria preferência de tradução.
• Um bloco com "usePostMeta": true na seção acf do seu block.json salva seus valores como campos personalizados do post, e não no bloco. Esses valores são traduzidos como qualquer outro campo personalizado do post, com a opção de tradução e as preferências de campo do Grupo de campos.
• Quando você altera uma preferência de tradução em um Grupo de campos que você usa em blocos, o WPML pergunta se você quer atualizar as traduções existentes. Se você confirmar, o WPML marca as traduções desses posts como precisando de atualização. Envie-os para tradução novamente para aplicar a alteração. Uma alteração para Não traduzir não os marca.

Campos declarados no block.json

Desde o ACF 6.8.1, um bloco pode declarar seus campos em seu arquivo block.json, em acf.fields. O ACF cria um Grupo de campos para esses campos, e você não pode editar esse Grupo de campos no painel de administração. O ACFML dá a ele a opção Mesmo conteúdo em todos os idiomas, traduzido e a preferência recomendada para cada tipo de campo, como um Grupo de campos registrado em PHP.

Para usar outra opção para o grupo inteiro, adicione acfml_field_group_mode à seção acf do block.json, ou ao acf_register_block_type(). Os valores aceitos são translation (Mesmo conteúdo em todos os idiomas, traduzido), localization (Cada idioma tem seu próprio conteúdo) e advanced (Especialista). O ACFML ignora qualquer outro valor.

{
    "name": "acme/event-card",
    "title": "Event Card",
    "acf": {
        "mode": "preview",
        "acfml_field_group_mode": "localization",
        "fields": [ ... ]
    }
}

Para definir a preferência de um campo, adicione wpml_cf_preferences a esse campo. O ACFML mantém essa preferência com todas as opções. Com Especialista, apenas os campos que declaram wpml_cf_preferences recebem uma preferência.

Quando block.json não nomeia uma opção, o ACFML armazena a opção que dá ao grupo na primeira vez que vê o grupo, e a mantém depois disso. Em sites que usaram esses blocos com uma versão mais antiga do ACFML, a opção armazenada é Especialista.

Definir preferências para campos registrados em PHP ou JSON

Os grupos de campos do ACF registrados em PHP (com acf_add_local_field_group()) ou por meio do recurso JSON local do ACF não recebem as preferências de tradução das telas do painel de administração, porque o painel de administração não os gerencia. Defina as preferências no mesmo lugar em que você registra os campos.

Para definir a opção de tradução do grupo de campos, adicione a chave acfml_field_group_mode à definição, com translation, localization ou advanced (Expert). Quando a definição não estabelece nenhuma opção de tradução, o ACFML dá ao grupo de campos a opção Mesmo conteúdo em cada idioma, traduzido na primeira vez que vê o grupo. O ACFML armazena essa opção e a mantém depois disso. Os grupos de campos que existiam antes de o seu site ser atualizado para o WPML 5.2 mantêm a opção Expert.

Para cada campo na definição do grupo de campos, adicione uma chave wpml_cf_preferences. O valor é um número inteiro que mapeia para as quatro preferências de tradução: 0 para Não traduzir (o WPML ignora o campo), 1 para Copiar (o valor permanece sincronizado entre os idiomas), 2 para Traduzir (o valor passa pela tradução) e 3 para Copiar uma vez (o valor é copiado para novas traduções e, em seguida, cada idioma pode ser editado independentemente).

Um exemplo mínimo:

acf_add_local_field_group( [
    'key'    => 'group_1',
    'title'  => 'My Group',
    'fields' => [
        [
            'key'                 => 'field_1',
            'label'               => 'Sub Title',
            'name'                => 'sub_title',
            'type'                => 'text',
            'wpml_cf_preferences' => 2, // Translate.
        ],
    ],
    // ...rest of the field-group config
] );

Depois de definir os campos no código, sincronize as preferências no WPML para que o painel de administração as reconheça:

1. Vá para ACF → Ferramentas.
2. Role até Translate ACF Local JSON and PHP-Registered Fields.
3. Em Sync Translation Preferences for Local Fields, selecione Sync once now e clique em Aplicar.

O WPML lê as preferências de suas definições de campo e as armazena. O Sync once now é executado uma vez. Se você alterar as definições com frequência, selecione Sync on every request (may affect performance) em vez disso. Essa opção executa a sincronização em cada requisição do painel de administração.

Se você usar o recurso JSON local do ACF para compartilhar grupos de campos entre sites, o ACFML gravará as preferências de tradução nos arquivos JSON automaticamente. Exporte um arquivo JSON de um site, importe-o em outro, e o site de destino adotará as preferências assim que o ACFML estiver ativo em ambas as pontas.

Os grupos de campos que o ACF cria com o comando WP-CLI wp acf json import, ou por meio de sua API Abilities para ferramentas de IA, são armazenados no banco de dados. O ACFML dá a eles a opção Mesmo conteúdo em cada idioma, traduzido e a preferência recomendada para cada tipo de campo. Quando o JSON importado já tem uma chave acfml_field_group_mode, o ACFML usa essa opção em vez disso.

Grupos de campos em arquivos JSON locais

O ACF carrega os grupos de campos da pasta acf-json bem no início de cada requisição. A partir do WPML 5.2, o ACFML lê esses grupos de campos ao mesmo tempo. Portanto, quando você sincroniza as preferências de tradução, a sincronização também abrange os grupos de campos JSON. O WPML então usa as preferências nos arquivos JSON.

No arquivo JSON, adicione wpml_cf_preferences a cada campo, com os mesmos valores do PHP. Essa chave define a preferência de cada campo, independentemente da opção de tradução do grupo de campos. O exemplo usa Expert:

{
    "key": "group_event",
    "title": "Event",
    "acfml_field_group_mode": "advanced",
    "fields": [
        {
            "key": "field_event_title",
            "label": "Event Title",
            "name": "event_title",
            "type": "text",
            "wpml_cf_preferences": 2
        },
        {
            "key": "field_event_price",
            "label": "Price",
            "name": "event_price",
            "type": "number",
            "wpml_cf_preferences": 1
        }
    ]
}

Para enviar as preferências e os rótulos de grupos de campos JSON para o WPML:

1. Vá para ACF → Ferramentas.
2. Role até Translate ACF Local JSON and PHP-Registered Fields.
3. Em Sync Translation Preferences for Local Fields, selecione Sync once now ou Sync on every request (may affect performance).
4. Em Register Labels for Translation, selecione Register labels now.
5. Clique em Aplicar.

Para verificar o resultado, vá para WPML → Configurações e encontre os campos em Tradução de campos personalizados. Cada campo mostra a preferência do arquivo JSON. O ACFML também registra os rótulos dos grupos de campos, tipos de post, taxonomias e páginas de opções que existem apenas no código: na pasta acf-json ou registrados em PHP. Traduza-os como os rótulos de qualquer outro grupo de campos (veja Traduzir rótulos de campos do ACF abaixo).

Traduzir rótulos de campos do ACF

Os rótulos de campos do ACF são os nomes que identificam cada campo personalizado no editor do WordPress e no front-end (por exemplo, Número de telefone, Endereço). Eles são traduzidos separadamente dos valores dos campos, e ficam na WPML Tradução de Strings, não no trabalho de tradução do post.

Para enviar os rótulos de campos para tradução:

1. Abra WPML → Traduções → Painel.
2. Expanda a seção Grupo de campos do ACF.
3. Selecione o item Field Group Labels para o grupo de campos que você quer traduzir.
4. Escolha um método de tradução (PTC, seu tradutor ou Traduzir eu mesmo) e envie.

Os rótulos traduzidos aparecem no front-end automaticamente assim que a tradução é concluída.

Parar de traduzir os rótulos dos campos

Por padrão, o trabalho de tradução de um post não inclui os rótulos dos campos. Você os traduz apenas quando envia o item Field Group Labels a partir do Painel. Se você não o enviar, o ACF mostrará os rótulos originais. Para mostrar os rótulos originais mesmo quando existirem traduções, use o filtro acfml_should_translate_acf_entity e retorne false para os campos ou os grupos de campos que você quer ignorar. A referência de hooks e constantes do ACFML tem um exemplo.

Traduzir as opções de campos do ACF

Os campos de escolha (Select, Checkbox, Radio Button, Button Group) carregam seus próprios rótulos de opção (por exemplo, Small / Medium / Large). Eles também ficam junto com os rótulos dos campos, em vez de dentro da tradução do post. Envie-os da mesma forma:

1. Abra WPML → Traduções → Painel.
2. Expanda a seção ACF Field Group.
3. Selecione o grupo de campos cujos valores de escolha você quer traduzir.
4. Escolha um método de tradução e envie.

Traduzir as páginas de opções do ACF

As páginas de opções do ACF (telas de configurações globais como Contact details, Header settings, Footer links) são traduzidas como seu próprio tipo de objeto, separadamente dos posts:

1. Abra WPML → Traduções → Painel.
2. Expanda a seção ACF Options.
3. Selecione a página de opções que você quer traduzir.
4. Escolha um método de tradução e envie.

Os valores da página de opções de cada idioma aparecem automaticamente quando o ACF lê a opção no contexto daquele idioma.

A opção de tradução do grupo de campos na página de opções decide o que acontece com cada campo:

• Os campos que usam Traduzir vão para o item ACF Options que você envia a partir do Painel de tradução. Quando a tradução está concluída, o ACFML escreve os valores na página de opções daquele idioma. Os campos Repeater e Flexible Content recebem as mesmas linhas que o original.
• Os campos que usam Copiar recebem o valor do original em todos os idiomas. Quando você salva o original, o ACFML atualiza os outros idiomas.
• Os campos que usam Copiar uma vez começam como uma cópia do original. Depois disso, você os edita na página de opções de cada idioma.

Use Each language has its own content quando as opções diferirem por idioma. Por exemplo, uma página de opções lista três agentes de vendas em inglês e dois em espanhol. Para escolher a opção, edite o grupo de campos, como faria para qualquer outro grupo de campos.

Para alterar uma tradução concluída, vá para WPML → Traduções → Trabalhos de tradução e clique em Editar no trabalho ACF Options. Você também pode editar os valores traduzidos em WPML → Tradução de Strings. Quando você salva uma tradução lá, o ACFML a escreve na página de opções daquele idioma.

Quando você altera o idioma padrão do site, os valores existentes da página de opções permanecem no idioma em que você os escreveu. O ACF lê os mesmos valores de antes da alteração.

No código, get_field( 'my_field', 'option' ) retorna o valor do idioma atual. Depois de do_action( 'wpml_switch_language', 'fr' ), ele retorna o valor em francês. Isso também funciona para páginas de opções com um post_id personalizado.

Problemas comuns

• Os rótulos dos campos parecem não traduzidos. Eles ficam na Tradução de Strings, não na tradução do post. Envie o item Field Group Labels do grupo de campos a partir do Painel (veja Traduzir os rótulos dos campos do ACF acima).
• Os valores de escolha parecem não traduzidos. A mesma situação. Envie o grupo de campos a partir da seção ACF Field Group do Painel para que os valores das opções sejam incluídos.
• As linhas do Repeater ficam fora de sincronia. O grupo de campos provavelmente usa a opção Expert. Edite o post original, selecione Keep repeater and flexible sub-fields in the same order as the default language na caixa ACFML Synchronise translations e atualize o post. Ou mude o grupo de campos para Same content in every language, translated.
• A lógica condicional se comporta de forma inesperada. Quando o campo controlador está definido como Copiar ou Não traduzível, o comportamento condicional segue o valor do idioma de origem em todas as traduções. Defina o campo controlador como Traduzir se o seu valor dever ser diferente em cada idioma.
• Os campos locais (registrados em PHP) ignoram as preferências de tradução definidas no painel de administração. Defina a chave wpml_cf_preferences na própria definição do grupo de campos e sincronize a partir de ACF → Ferramentas. O procedimento está em Definir preferências para campos registrados em PHP ou JSON acima.

Hooks de desenvolvedor para casos extremos

Para controle programático (remover campos específicos da tradução, substituir a preferência padrão para um tipo de campo em todo o site, ocultar anotações dos tradutores ou excluir strings de grupos de campos dos trabalhos de tradução de posts), o ACFML tem dois filtros e quatro constantes. A referência completa com exemplos de código está na referência de hooks e constantes do ACFML.