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 do catálogo do ACF e do ACF Pro:

• Os campos de texto e Wysiwyg são traduzidos por idioma.
• As linhas do Repeater e do Flexible Content permanecem alinhadas entre os idiomas.
• Os campos de imagem, arquivo e galeria podem ser trocados por recursos localizados por idioma.
• Os campos de link, relacionamento e objeto de post permanecem conectados corretamente entre os idiomas.
• Os campos de seletor de data, seletor de cores, mapa e 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 os casos. A página Nossa equipe no seu site mostra os mesmos membros da equipe em todos os idiomas: traduza seus nomes e biografias, mantenha a estrutura 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, mantenha o SKU e o preço iguais.

O ACFML lida com os três casos com base em cada 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, em seguida, cada versão de idioma pode ser editada independentemente.
• Não traduzir. O campo é totalmente ignorado (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 de texto e Wysiwyg têm como padrão Traduzir, enquanto campos estruturados como imagem, link e número têm como padrão Copiar. A referência completa das predefinições está em Como traduzir campos personalizados do ACF.

As linhas do Repeater e do Flexible Content permanecem alinhadas entre os idiomas

Os campos Repeater e Flexible Content são onde as configurações multilíngues do ACF costumam falhar em outras ferramentas: as linhas perdem a sincronia, os layouts divergem e os tradutores veem um conteúdo 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.

Os campos locais (registrados em PHP) têm o mesmo comportamento de tradução

Muitos sites de produção registram os campos do ACF em PHP em vez de usar a interface do painel de administração 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 com o WPML em ACF > Ferramentas, e as telas 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 de tradução de campos personalizada (excluir campos específicos, substituir a preferência padrão de 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á na 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 em estreita colaboração na compatibilidade contínua – confirmada na página de compatibilidade do ACF conjunta. 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.