Cómo traducir campos personalizados de ACF en WordPress: grupos de campos, repetidores y páginas de opciones

Antes de empezar

Instale y active estos plugins:

• Advanced Custom Fields o ACF Pro.
• WPML y WPML Traducción de cadenas.
• ACFML (el complemento que trata esta página).

Sus grupos de campos ya deberían estar configurados en ACF. Puede cambiar las preferencias de traducción por campo más adelante, por lo que el orden de las operaciones no importa. Configure los grupos de campos y luego vuelva a ACFML.

Elija un modo de traducción para cada grupo de campos

Los grupos de campos de ACF no se comportan todos de la misma manera en la traducción. ACFML ofrece tres modos por grupo de campos, que se configuran en ACF > Grupos de campos bajo la sección Configuración multilingüe:

Mismos campos en todos los idiomas

La configuración habitual para la mayoría de los sitios con ACF. Traduzca los valores de los campos a cada idioma sin que la estructura cambie. La página Nuestro equipo es el ejemplo clásico. Su equipo es el mismo en todos los idiomas, por lo que el nombre y la biografía de cada miembro del equipo se traducen por idioma mientras la estructura del campo permanece intacta. Introduzca el equipo en el idioma de origen y luego envíe la entrada para su traducción a través de WPML > Traducciones > Escritorio; los valores traducidos vuelven adjuntos a los mismos campos.

Diferentes campos en los distintos idiomas

Utilícelo cuando cada idioma muestre un contenido fundamentalmente diferente en el mismo grupo de campos. El caso clásico es el de una empresa que organiza eventos localizados. La página de Eventos en inglés muestra eventos para el público de habla inglesa, y la página en francés muestra eventos para el público de habla francesa. Configure el grupo de campos en Diferentes campos en los distintos idiomas, luego abra la entrada que quiera localizar > en el cuadro de Idiomas de la derecha, haga clic en el icono del signo más para el idioma de destino > se abrirá un borrador en blanco con los campos personalizados vacíos > rellene los valores específicos del idioma y publique.

Modo experto

Utilícelo cuando necesite una combinación: algunos campos se traducen por idioma, otros se mantienen igual y otros se copian una vez y luego divergen. Elija Modo experto en la configuración del grupo de campos y establezca la preferencia por campo. El ejemplo de Eventos con comportamiento mixto: el título y la descripción se establecen en Traducir; el precio, la fecha y la dirección se establecen en Copiar.

Preferencias de traducción para cada tipo de campo de ACF

Cada campo de un grupo de campos tiene una de estas cuatro preferencias de traducción:

• Traducir. El valor del campo se traduce por idioma.
• Copiar. El valor del campo se mantiene sincronizado en todos los idiomas; edítelo una vez y se propagará.
• Copiar una vez. El valor del campo sirve de base para la traducción, y luego cada versión de idioma se puede editar de forma independiente.
• No traducir. El campo se ignora en el proceso de traducción.

Al elegir Mismos campos en todos los idiomas o Diferentes campos en los distintos idiomas, cada campo recibe una preferencia predeterminada razonable según su tipo. Las siguientes tablas muestran esos valores predeterminados. Utilice el Modo experto para anularlos por campo, o use el filtro acfml_field_group_mode_field_translation_preference para anular el valor predeterminado de un tipo de campo en todo el sitio (consulte Hooks para desarrolladores en casos límite a continuación).

Repetidor y contenido flexible: Copiar o Copiar una vez

Para los campos Repetidor y Contenido flexible, puede elegir entre dos comportamientos a nivel de fila antes de que se apliquen las preferencias de los subcampos:

• Copiar. El mismo diseño y número de filas en todos los idiomas. Los traductores ven las mismas filas; los subcampos se traducen según sus propias preferencias.
• Copiar una vez. Cada idioma puede tener un diseño diferente y un número distinto de filas después de la copia inicial.

Elija Copiar cuando la estructura sea la misma en todos los idiomas (la mayoría de los casos). Elija Copiar una vez cuando las versiones de idioma diverjan estructuralmente (por ejemplo, una lista de eventos diferente por idioma).

Campos básicos

Campos de contenido

Campos de elección

Campos jQuery

Campos de diseño

Campos relacionales

Configurar preferencias para campos registrados en PHP o JSON

Los grupos de campos de ACF registrados en PHP (a través de acf_add_local_field_group()) o mediante la función Local JSON de ACF no adoptan las preferencias de traducción de la interfaz del panel de administración, porque este no las gestiona. Establezca las preferencias en el mismo lugar donde registre los campos.

Para cada campo en la definición del grupo de campos, añada una clave wpml_cf_preferences. El valor es un número entero que corresponde a una de las cuatro preferencias de traducción: 0 para No traducir (WPML ignora el campo), 1 para Copiar (el valor se mantiene sincronizado en todos los idiomas), 2 para Traducir (el valor pasa por la traducción) y 3 para Copiar una vez (el valor se copia a las nuevas traducciones, y luego cada idioma se puede editar de forma independiente).

Un ejemplo 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
] );

Después de definir los campos en el código, sincronice las preferencias en WPML para que el panel de administración las reconozca:

1. Vaya a ACF > Herramientas.
2. Desplácese hasta Traducir JSON local de ACF y campos registrados en PHP.
3. En Sincronizar preferencias de traducción para campos locales, elija Sincronizar una vez ahora y haga clic en Aplicar.

WPML lee las preferencias de sus definiciones de PHP y las almacena. La sincronización se ejecuta una vez cuando la activa, no en cada carga de la página.

Si utiliza la función Local JSON de ACF para compartir grupos de campos entre sitios, ACFML escribe las preferencias de traducción en los archivos JSON automáticamente. Exporte un archivo JSON desde un sitio, impórtelo en otro, y el sitio de destino adoptará las preferencias una vez que ACFML esté activo en ambos extremos.

Traducir las etiquetas de los campos de ACF

Las etiquetas de los campos de ACF son los nombres que identifican cada campo personalizado en el editor de WordPress y en el front-end (por ejemplo, Número de teléfono, Dirección). Se traducen por separado de los valores de los campos, y se encuentran en WPML Traducción de cadenas, no en el trabajo de traducción de la entrada.

Para enviar las etiquetas de los campos a traducir:

1. Abra WPML > Traducciones > Escritorio.
2. Expanda la sección Grupo de campos de ACF.
3. Seleccione el elemento Etiquetas del grupo de campos para el grupo de campos que quiera traducir.
4. Elija un método de traducción (PTC, su traductor o Traducir yo mismo) y envíelo.

Las etiquetas traducidas aparecen en el front-end automáticamente una vez que se completa la traducción.

Traducir las opciones de los campos de ACF

Los campos de elección (Seleccionar, Casilla de verificación, Botón de radio, Grupo de botones) llevan sus propias etiquetas de opción (por ejemplo, Pequeño / Mediano / Grande). Estas también se encuentran junto a las etiquetas de los campos en lugar de dentro de la traducción de la entrada. Envíelas de la misma manera:

1. Abra WPML > Traducciones > Escritorio.
2. Expanda la sección Grupo de campos de ACF.
3. Seleccione el grupo de campos cuyos valores de elección quiera traducir.
4. Elija un método de traducción y envíelo.

Traducir las páginas de opciones de ACF

Las páginas de opciones de ACF (pantallas de configuración global como Detalles de contacto, Configuración del encabezado, Enlaces del pie de página) se traducen como su propio tipo de objeto, por separado de las entradas:

1. Abra WPML > Traducciones > Escritorio.
2. Expanda la sección Opciones de ACF.
3. Seleccione la página de opciones que quiera traducir.
4. Elija un método de traducción y envíela.

Los valores de la página de opciones de cada idioma aparecen automáticamente cuando ACF lee la opción en el contexto de ese idioma.

Errores comunes

• Las etiquetas de los campos parecen no estar traducidas. Se encuentran en Traducción de cadenas, no en la traducción de la entrada. Envíe el elemento Etiquetas del grupo de campos del grupo de campos desde el Escritorio (consulte Traducir las etiquetas de los campos de ACF más arriba).
• Los valores de elección parecen no estar traducidos. Ocurre lo mismo. Envíe el grupo de campos desde la sección Grupo de campos de ACF del Escritorio para que se incluyan los valores de las opciones.
• Las filas del repetidor se desincronizan. Es probable que el campo esté configurado en Copiar una vez cuando Copiar mantendría las filas alineadas. Abra el grupo de campos > cambie el comportamiento del campo repetidor a Copiar.
• La lógica condicional se comporta de forma inesperada. Cuando el campo de control se establece en Copiar o No traducir, el comportamiento condicional sigue el valor del idioma de origen en todas las traducciones. Establezca el campo de control en Traducir si su valor debe ser diferente por idioma.
• Los campos locales (registrados en PHP) ignoran las preferencias de traducción establecidas en el panel de administración. Establezca la clave wpml_cf_preferences en la propia definición del grupo de campos y sincronice desde ACF > Herramientas. El procedimiento se encuentra en Configurar preferencias para campos registrados en PHP o JSON más arriba. ACFML 2.2.0 (febrero de 2026) añadió compatibilidad total con campos locales; las versiones anteriores tenían limitaciones al respecto.

Hooks para desarrolladores en casos límite

Para el control programático (excluir campos específicos de la traducción, anular la preferencia predeterminada para un tipo de campo en todo el sitio, ocultar anotaciones a los traductores o excluir cadenas de grupos de campos de los trabajos de traducción de entradas), ACFML expone dos filtros y cuatro constantes. La referencia completa con ejemplos de código se encuentra en la referencia de hooks y constantes de ACFML.