ACFML – Campos personalizados multilíngues do ACF e ACF Pro no WordPress

Todos os tipos de campo do ACF são multilíngues

Se você cria sites com o ACF, o ACFML abrange todos os tipos de campo no catálogo do ACF e do ACF Pro:

• Os campos Texto e Wysiwyg são traduzidos por idioma.
• As linhas de Repetidor e Conteúdo flexível permanecem alinhadas entre os idiomas.
• Os campos Imagem, Arquivo e Galeria podem ser trocados para ativos localizados por idioma.
• Os campos Link, Relacionamento e Objeto de post permanecem conectados corretamente entre os idiomas.
• O Seletor de data, Seletor de cor, Mapa e os outros campos interativos se comportam corretamente por idioma.

Os tipos de post personalizados, as taxonomias e as páginas de opções que você registra pelo ACF também são traduzidos – incluindo seus rótulos. O site que você cria com o ACF é o site que se torna multilíngue com o ACFML, não um subconjunto.

Escolha o que é igual e o que é diferente por idioma

Os grupos de campos do ACF não têm um comportamento de tradução único para todos. A página Nossa equipe no seu site mostra os mesmos membros da equipe em todos os idiomas: traduza seus nomes e biografias, e mantenha a estrutura deles intacta. A página Eventos mostra eventos diferentes para públicos diferentes: mostre eventos totalmente diferentes por idioma. A página Especificações do produto mostra uma mistura: traduza a descrição, e mantenha o SKU e o preço iguais.

O ACFML lida com todos os três em uma base por grupo de campos: Mesmos campos em todos os idiomas, Campos diferentes em todos os idiomas e Modo especialista para configurações mistas. Escolha o modo que corresponde ao propósito de cada grupo de campos; o ACFML configura o comportamento de tradução automaticamente.

Controle de tradução por campo

Dentro de um grupo de campos, cada campo recebe sua própria preferência de tradução:

• Traduzir. O valor do campo é traduzido por idioma.
• Copiar. O valor do campo permanece sincronizado entre os idiomas; edite-o uma vez e ele se propaga.
• Copiar uma vez. O valor do campo preenche as novas traduções, e então cada versão de idioma pode ser editada independentemente.
• Não traduzir. O campo é ignorado inteiramente (por exemplo, um campo interno apenas para o painel de administração).

Padrões sensatos por tipo de campo vêm prontos para usar: os campos Texto e Wysiwyg têm como padrão Traduzir, e campos estruturados como Imagem, Link e Número têm como padrão Copiar. A referência completa de predefinições está em Como traduzir campos personalizados do ACF.

As linhas de Repetidor e Conteúdo flexível permanecem alinhadas entre os idiomas

Os campos Repetidor e Conteúdo flexível são onde as configurações multilíngues do ACF frequentemente quebram em outras ferramentas: as linhas perdem a sincronia, os layouts divergem e os tradutores veem conteúdos que não reconhecem. O ACFML mantém a estrutura das linhas alinhada entre os idiomas por padrão. Os tradutores veem as mesmas linhas na mesma ordem, com cada subcampo traduzível em seu lugar. Se você precisar de estruturas divergentes por idioma (por exemplo, uma lista de eventos diferente em cada idioma), a preferência Copiar uma vez permite isso.

Campos locais (registrados em PHP) recebem o mesmo comportamento de tradução

Muitos sites de produção registram campos do ACF em PHP em vez de na interface do ACF (para portabilidade, controle de versão ou configurações incluídas no tema). O ACFML 2.2.0 (fevereiro de 2026) traz suporte completo a campos locais. Você define a preferência de tradução de cada campo com a chave wpml_cf_preferences na definição do grupo de campos, sincroniza-a com o WPML em ACF > Ferramentas, e as telas do painel de administração refletem o que o grupo de campos declara. Os arquivos JSON locais do ACF carregam as preferências com eles quando você exporta e importa entre sites. O procedimento passo a passo está na página de instruções em Como definir preferências para campos registrados em PHP ou JSON.

Hooks de desenvolvedor para casos extremos

Para sites com lógica personalizada de tradução de campos (excluir campos específicos, substituir a preferência padrão para um tipo de campo globalmente, ocultar anotações dos tradutores), o ACFML expõe dois filtros (acfml_should_translate_acf_entity, acfml_field_group_mode_field_translation_preference) e quatro constantes (ACFML_EXCLUDE_FIELD_GROUP_STRINGS_IN_POST_JOBS, ACFML_HIDE_FIELD_ANNOTATIONS, ACFML_REPEATER_SYNC_DEFAULT, ACFML_SCAN_LOCAL_FIELDS). A referência completa com exemplos de código está em Referência de hooks e constantes do ACFML.

Criado e mantido junto com a equipe do ACF

O WPML e a equipe do ACF trabalham juntos na compatibilidade contínua – confirmada na página conjunta de compatibilidade do ACF. Quando o ACF ou o ACF Pro lança uma versão, o ACFML acompanha; quando o ACFML precisa de suporte do lado do ACF para um novo comportamento de tradução, a integração é construída em conjunto, em vez de usar engenharia reversa.