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 aborda).

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, em seguida, volte para o ACFML.

Escolha um modo de tradução para cada grupo de campos

Nem todos os grupos de campos do ACF se comportam da mesma maneira durante a tradução. O ACFML oferece três modos por grupo de campos, definidos em ACF → Grupos de campos, na seção Configuração multilíngue:

Mesmos campos em todos os idiomas

A configuração típica para a maioria dos sites com ACF. Traduza os valores dos campos para cada idioma enquanto a estrutura permanece a mesma. A página Nossa equipe é o exemplo clássico. Sua equipe é a mesma em todos os idiomas, portanto, o nome e a biografia de cada membro da equipe são traduzidos por idioma enquanto a estrutura do campo permanece intacta. Você insere a equipe no idioma de origem e, em seguida, envia o post para tradução em WPML → Traduções → Painel; os valores traduzidos voltam vinculados aos mesmos campos.

Campos diferentes em todos os idiomas

Use quando cada idioma mostrar um conteúdo fundamentalmente diferente no mesmo grupo de campos. O caso clássico é uma empresa que realiza eventos localizados. A página Eventos em inglês mostra eventos para o público inglês, a página em francês mostra eventos para o público francês. Defina o grupo de campos como Campos diferentes em todos os idiomas e, em seguida, abra o post que você quer localizar → na caixa Idiomas à direita, clique no ícone de adição para o idioma de destino → um rascunho em branco será aberto com campos personalizados vazios → preencha os valores específicos do idioma e publique.

Modo especialista

Use quando você precisar de uma mistura: alguns campos são traduzidos por idioma, outros permanecem os mesmos, outros são copiados uma vez e depois divergem. Escolha Modo especialista na configuração do grupo de campos e defina a preferência por campo. O exemplo de Eventos com comportamento misto: título e descrição definidos como Traduzir; preço, data e endereço definidos como Copiar.

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

Cada campo em um grupo de campos tem uma das quatro preferências de tradução:

• Traduzir. O valor do campo é traduzido por idioma.
• Copiar. O valor do campo permanece sincronizado em todos os idiomas; edite-o uma vez e ele se propagará.
• Copiar uma vez. O valor do campo serve como base para a tradução e, em seguida, a versão de cada idioma pode ser editada de forma independente.
• Não traduzir. O campo é ignorado pela etapa de tradução.

Ao escolher Mesmos campos em todos os idiomas ou Campos diferentes em todos os idiomas, cada campo recebe uma preferência padrão adequada com base no seu tipo de campo. As tabelas abaixo mostram esses padrões. Use o Modo especialista para substituí-los por campo ou use o filtro acfml_field_group_mode_field_translation_preference para substituir o padrão de um tipo de campo em todo o site (consulte Hooks de desenvolvedor para casos extremos abaixo).

Repetidor e conteúdo flexível – Copiar ou copiar uma vez

Para campos de repetidor e conteúdo flexível, você escolhe entre dois comportamentos no nível da linha antes que as preferências de subcampos entrem em ação:

• Copiar. Mesmo layout e número de linhas em todos os idiomas. Os tradutores veem as mesmas linhas; os subcampos são traduzidos de acordo com suas próprias preferências.
• Copiar uma vez. Cada idioma pode ter um layout diferente e um número diferente de linhas após a cópia inicial.

Escolha Copiar quando a estrutura for a mesma em todos os idiomas (na maioria dos casos). Escolha Copiar uma vez quando as versões em cada idioma divergirem estruturalmente (por exemplo, uma lista de eventos diferente por idioma).

Campos básicos

Campos de conteúdo

Campos de escolha

Campos jQuery

Campos de layout

Campos relacionais

Como definir preferências para campos registrados em PHP ou JSON

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

Para cada campo na definição do grupo de campos, adicione uma chave wpml_cf_preferences. O valor é um número inteiro que corresponde às quatro preferências de tradução: 0 para Não traduzir (o WPML ignora o campo), 1 para Copiar (o valor permanece sincronizado em todos 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é Traduzir campos ACF registrados em PHP e JSON local.
3. Em Sincronizar preferências de tradução para campos locais, escolha Sincronizar uma vez agora e clique em Aplicar.

O WPML lê as preferências das suas definições em PHP e as armazena. A sincronização é executada uma vez quando você a aciona, não a cada carregamento de página.

Se você usar o recurso Local JSON 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 assumirá as preferências assim que o ACFML estiver ativo em ambos os lados.

Como 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 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 Rótulos do grupo de campos 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 for concluída.

Como traduzir escolhas de campos do ACF

Os campos de escolha (Seleção, Caixa de seleção, Botão de rádio, Grupo de botões) carregam seus próprios rótulos de opções (por exemplo, Pequeno / Médio / Grande). Eles também ficam junto com os rótulos dos campos, em vez de dentro da tradução do post. Envie-os da mesma maneira:

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

Como traduzir páginas de opções do ACF

As páginas de opções do ACF (telas de configurações globais, como Detalhes de contato, Configurações de cabeçalho, Links de rodapé) são traduzidas como seu próprio tipo de objeto, separadamente dos posts:

1. Abra WPML → Traduções → Painel.
2. Expanda a seção Opções do ACF.
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.

Armadilhas comuns

• Os rótulos dos campos aparecem sem tradução. Eles ficam na Tradução de Strings, não na tradução do post. Envie o item Rótulos do grupo de campos do grupo de campos a partir do Painel (consulte Como traduzir rótulos de campos do ACF acima).
• Os valores de escolha aparecem sem tradução. Mesma situação. Envie o grupo de campos a partir da seção Grupo de campos do ACF do Painel para que os valores das opções sejam incluídos.
• As linhas do repetidor ficam fora de sincronia. O campo provavelmente está definido como Copiar uma vez, quando Copiar manteria as linhas alinhadas. Abra o grupo de campos → mude o comportamento do campo de repetidor para Copiar.
• A lógica condicional se comporta de forma inesperada. Quando o campo de controle está definido como Copiar ou Não traduzir, o comportamento condicional segue o valor do idioma de origem em todas as traduções. Defina o campo de controle como Traduzir se o valor dele precisar ser diferente por 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 Como definir preferências para campos registrados em PHP ou JSON acima. O ACFML 2.2.0 (fevereiro de 2026) adicionou suporte completo a campos locais; as versões mais antigas tinham limitações nesse aspecto.

Hooks de desenvolvedor para casos extremos

Para controle programático (optar por não traduzir campos específicos, 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 de trabalhos de tradução de posts), o ACFML expõe dois filtros e quatro constantes. A referência completa com exemplos de código está em Referência de hooks e constantes do ACFML.