Cómo traducir campos personalizados de ACF en WordPress: grupos de campos, repetidores, 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 cubre esta página).

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

Elija una opción de traducción para cada grupo de campos

No todos los grupos de campos de ACF se comportan de la misma manera en la traducción. ACFML ofrece tres opciones de traducción para cada grupo de campos. Para elegir una:

1. Vaya a ACF → Grupos de campos y edite el grupo de campos.
2. En la sección Configuración multilingüe, en Seleccionar una opción de traducción para este grupo de campos, haga clic en Elegir en la opción que quiera.
3. Guarde el grupo de campos.

ACFML marca la opción que sugiere para su sitio como recomendada para este sitio. Para elegir otra opción más adelante, haga clic en Cambiar opción. Las versiones anteriores de ACFML llaman a las dos primeras opciones Mismos campos en todos los idiomas y Diferentes campos en los distintos idiomas.

El mismo contenido en todos los idiomas, traducido

La configuración típica para la mayoría de los sitios con ACF. Los visitantes de cada idioma ven las mismas páginas, en su propio idioma. El texto se traduce, y el diseño y la configuración se mantienen iguales. La página Nuestro equipo es el ejemplo habitual. 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, y la estructura de los campos se mantiene igual. Usted introduce el equipo en el idioma predeterminado y, a continuación, envía la entrada para su traducción desde WPML → Traducciones → Escritorio. Los valores traducidos vuelven a los mismos campos. Esta opción funciona con la traducción automática y con Traducir todo.

Cada idioma tiene su propio contenido

Utilice esta opción cuando cada idioma muestre un contenido diferente en el mismo grupo de campos. El ejemplo habitual es una empresa que organiza eventos locales. La página Eventos en inglés muestra eventos para un público inglés, y la página en francés muestra eventos para un público francés. Los campos comienzan como una copia del original. Después de eso, cada idioma mantiene sus propios valores. Usted edita cada idioma en el editor de WordPress: abra la entrada, haga clic en el icono del signo más para el idioma de destino en la caja Idioma, rellene los valores para ese idioma y publique. WPML no sincroniza las versiones de los idiomas posteriormente, y la traducción automática no se aplica.

Experto

Utilice esta opción cuando necesite una mezcla: algunos campos se traducen, otros se mantienen iguales y otros se copian una vez y luego cambian en cada idioma. Elija Experto y establezca la preferencia de traducción de cada campo manualmente. En el ejemplo de Eventos, el título y la descripción utilizan Traducir, y el precio, la fecha y la dirección utilizan Copiar. ACFML no recomienda esta opción para los nuevos grupos de campos. Un grupo de campos definido en PHP o JSON local puede no tener ninguna opción de traducción. En ese caso, utiliza Experto solo cuando el grupo de campos existe antes de que su sitio se actualice a WPML 5.2.

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

Cada campo que almacena un valor tiene una de estas cuatro preferencias de traducción:

• Traducir. Los visitantes ven el valor en su propio idioma. WPML lo rellena con la traducción. Usted lo edita en el editor de traducción.
• Copiar. Los visitantes de todos los idiomas ven exactamente lo que muestra el original. El campo está bloqueado en los demás idiomas.
• Copiar una vez. El valor comienza como una copia del original. Después de eso, usted lo edita en cada idioma manualmente. Si vacía el campo en una traducción, se mantiene vacío. WPML no vuelve a copiar el valor original en él.
• No traducir. Las traducciones comienzan sin este valor. Puede rellenarlo en cada idioma manualmente.

Cuando elige El mismo contenido en todos los idiomas, traducido o Cada idioma tiene su propio contenido, ACFML le da a cada campo la preferencia recomendada para su tipo de campo. Las siguientes tablas muestran estas preferencias recomendadas. Para establecer una preferencia diferente para un campo, utilice Experto. Para cambiar la preferencia recomendada de un tipo de campo en todo el sitio, utilice el filtro acfml_field_group_mode_field_translation_preference (consulte Hooks de desarrollador para casos extremos más abajo).

Los campos de pestaña, acordeón, mensaje y separador no almacenan un valor, por lo que no tienen preferencia de traducción. Un tipo de campo que no está en las tablas, por ejemplo, un tipo de campo de otro plugin, obtiene Copiar con ambas opciones de traducción.

Campos repetidores, de contenido flexible, de grupo y de clonación

Estos campos contienen otros campos. La preferencia recomendada del campo contenedor es Copiar o Copiar una vez. ACFML no ofrece Traducir para el propio campo contenedor. Cada subcampo tiene su propia preferencia de traducción.

Con El mismo contenido en todos los idiomas, traducido, las filas de los campos repetidores y de contenido flexible se mantienen en el mismo orden que en el idioma predeterminado. Con Experto, o cuando una entrada utiliza grupos de campos con diferentes opciones, el editor de la entrada muestra una caja ACFML Synchronise translations. Se muestra en la entrada original cuando la entrada tiene traducciones y un campo repetidor o de contenido flexible. Seleccione Keep repeater and flexible sub-fields in the same order as the default language para mantener las filas alineadas en todos los idiomas.

Campos básicos

Campos de contenido

Campos de elección

Campos jQuery

Campos de diseño

Campos relacionales

Para un campo de enlace, la traducción incluye el texto del enlace y la URL. Cuando la URL apunta a una página de su sitio y usted no la cambia, WPML muestra la página en el idioma del visitante.

Campos de URL y enlace

A partir de ACFML 5.0, los campos de URL y enlace utilizan la preferencia Traducir de forma predeterminada.

Relaciones bidireccionales

Desde ACF 6.2, los campos de relación, objeto de la entrada, taxonomía y usuario pueden ser bidireccionales. Cuando selecciona un destino en el campo, ACF añade su entrada al campo emparejado del destino. Por ejemplo, el libro Dune establece su campo Autor en Frank Herbert. A continuación, ACF añade Dune al campo Libros de Frank Herbert.

ACFML mantiene el par en cada idioma:

• Cuando WPML copia el campo a una traducción, ACFML apunta el campo al destino en el mismo idioma. Luego, ACFML añade la traducción al campo emparejado de ese destino. El Dune en español muestra el Frank Herbert en español, y el Frank Herbert en español enumera el Dune en español.
• Cuando el campo usa Copiar y cambia el destino en la entrada original, WPML actualiza la traducción. ACFML añade la traducción al nuevo destino en ese idioma y la elimina del antiguo destino.
• ACFML solo cambia los destinos en el idioma de la traducción. Las entradas en el idioma original mantienen su propio par.
• Cuando el destino aún no tiene traducción, la traducción apunta al destino original, y ACFML no cambia el destino original. Cuando traduce el destino más adelante, ACFML apunta el campo a la nueva traducción y añade la entrada a su campo emparejado. El campo enumera el destino una sola vez.
• Los usuarios no tienen traducciones, por lo que ACFML no añade traducciones al campo emparejado de un usuario. Ese campo mantiene la entrada original. En otro idioma, ACFML muestra la traducción de esa entrada, a menos que el campo use Copiar.

Esto funciona para las preferencias Copiar y Copiar una vez, que son las preferencias recomendadas para estos tipos de campos. También funciona cuando duplica una entrada con WPML.

Traducir bloques de ACF

De forma predeterminada, los bloques de ACF guardan los valores de sus campos dentro del bloque, en el contenido de la entrada, no como campos personalizados. ACFML envía estos valores para su traducción junto con el resto de la entrada, en el mismo trabajo de traducción.

• El bloque usa la opción de traducción y las preferencias de campo del grupo de campos cuya regla de ubicación es este bloque.
• ACFML envía solo los campos que usan Traducir. Los campos que usan Copiar, Copiar una vez o No traducir mantienen el valor del bloque original.
• Los campos de repetidor y contenido flexible dentro de un bloque también se traducen, incluso cuando están anidados. Cada subcampo usa su propia preferencia de traducción.
• Un bloque con "usePostMeta": true en la sección acf de su block.json guarda sus valores como campos personalizados de la entrada, no en el bloque. Estos valores se traducen como cualquier otro campo personalizado de la entrada, con la opción de traducción y las preferencias de campo del grupo de campos.
• Cuando cambia una preferencia de traducción en un grupo de campos que usa en bloques, WPML le pregunta si quiere actualizar las traducciones existentes. Si confirma, WPML marca las traducciones de estas entradas como pendientes de actualización. Envíelas a traducir de nuevo para aplicar el cambio. Un cambio a No traducir no las marca.

Campos declarados en block.json

Desde ACF 6.8.1, un bloque puede declarar sus campos en su archivo block.json, en acf.fields. ACF crea un grupo de campos para estos campos, y no puede editar este grupo de campos en el panel de administración. ACFML le asigna la opción Mismo contenido en cada idioma, traducido y la preferencia recomendada para cada tipo de campo, al igual que un grupo de campos registrado en PHP.

Para usar otra opción para todo el grupo, añada acfml_field_group_mode a la sección acf de block.json, o a acf_register_block_type(). Los valores aceptados son translation (Mismo contenido en cada idioma, traducido), localization (Cada idioma tiene su propio contenido) y advanced (Experto). ACFML ignora cualquier otro valor.

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

Para establecer la preferencia de un campo, añada wpml_cf_preferences a ese campo. ACFML mantiene esta preferencia con cada opción. Con Experto, solo los campos que declaran wpml_cf_preferences obtienen una preferencia.

Cuando block.json no nombra una opción, ACFML almacena la opción que le da al grupo la primera vez que lo ve, y la mantiene después de eso. En los sitios que usaban estos bloques con una versión anterior de ACFML, la opción almacenada es Experto.

Configurar preferencias para campos registrados en PHP o JSON

Los grupos de campos de ACF registrados en PHP (con acf_add_local_field_group()) o mediante la función Local JSON de ACF no toman las preferencias de traducción de las pantallas del panel de administración, porque el panel de administración no los gestiona. Configure las preferencias en el mismo lugar donde registra los campos.

Para configurar la opción de traducción del grupo de campos, añada la clave acfml_field_group_mode a la definición, con translation, localization o advanced (Experto). Cuando la definición no establece ninguna opción de traducción, ACFML asigna al grupo de campos la opción Mismo contenido en cada idioma, traducido la primera vez que ve el grupo. ACFML almacena esta opción y la mantiene después de eso. Los grupos de campos que existen antes de que su sitio se actualice a WPML 5.2 mantienen Experto.

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 se asigna a 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, 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 campos registrados en PHP y JSON local de ACF.
3. En Sincronizar preferencias de traducción para campos locales, seleccione Sincronizar una vez ahora y haga clic en Aplicar.

WPML lee las preferencias de sus definiciones de campos y las almacena. Sincronizar una vez ahora se ejecuta una vez. Si cambia las definiciones a menudo, seleccione Sincronizar en cada petición (puede afectar al rendimiento) en su lugar. Esta opción ejecuta la sincronización en cada petición del panel de administración.

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.

Los grupos de campos que ACF crea con el comando WP-CLI wp acf json import, o mediante su API Abilities para herramientas de IA, se almacenan en la base de datos. ACFML les asigna la opción Mismo contenido en cada idioma, traducido y la preferencia recomendada para cada tipo de campo. Cuando el JSON importado ya tiene una clave acfml_field_group_mode, ACFML utiliza esa opción en su lugar.

Grupos de campos en archivos JSON locales

ACF carga los grupos de campos de la carpeta acf-json muy pronto en cada petición. A partir de WPML 5.2, ACFML lee estos grupos de campos al mismo tiempo. Así que, cuando sincroniza las preferencias de traducción, la sincronización también cubre los grupos de campos JSON. Luego, WPML utiliza las preferencias de los archivos JSON.

En el archivo JSON, añada wpml_cf_preferences a cada campo, con los mismos valores que en PHP. Esta clave establece la preferencia de cada campo, sea cual sea la opción de traducción del grupo de campos. El ejemplo utiliza Experto:

{
    "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 las preferencias y las etiquetas de los grupos de campos JSON a WPML:

1. Vaya a ACF → Herramientas.
2. Desplácese hasta Traducir campos registrados en PHP y JSON local de ACF.
3. En Sincronizar preferencias de traducción para campos locales, seleccione Sincronizar una vez ahora o Sincronizar en cada petición (puede afectar al rendimiento).
4. En Registrar etiquetas para su traducción, seleccione Registrar etiquetas ahora.
5. Haga clic en Aplicar.

Para comprobar el resultado, vaya a WPML → Configuración y busque los campos en Traducción de campos personalizados. Cada campo muestra la preferencia del archivo JSON. ACFML también registra las etiquetas de los grupos de campos, tipos de contenido, taxonomías y páginas de opciones que existen solo en el código: en la carpeta acf-json o registrados en PHP. Tradúzcalos como las etiquetas de cualquier otro grupo de campos (consulte Traducir etiquetas de campos de ACF más abajo).

Traducir etiquetas de campos de ACF

Las etiquetas de campos de ACF son los nombres que identifican cada campo personalizado en el editor de WordPress y en el front-end (p. ej., Número de teléfono, Dirección). Se traducen por separado de los valores de los campos y residen 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. Despliegue 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.

Dejar de traducir las etiquetas de los campos

De forma predeterminada, el trabajo de traducción de una entrada no incluye las etiquetas de los campos. Solo las traduce cuando envía el elemento Field Group Labels (Etiquetas del grupo de campos) desde el Escritorio. Si no lo envía, ACF muestra las etiquetas originales. Para mostrar las etiquetas originales incluso cuando existen traducciones, utilice el filtro acfml_should_translate_acf_entity y devuelva false para los campos o los grupos de campos que quiera omitir. La referencia de hooks y constantes de ACFML incluye un ejemplo.

Traducir las opciones de los campos de ACF

Los campos de selección (Select, Checkbox, Radio Button, Button Group) tienen sus propias etiquetas de opciones (por ejemplo, Small / Medium / Large [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 ACF Field Group.
3. Seleccione el grupo de campos cuyos valores de opciones 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 Contact details, Header settings, Footer links) se traducen como su propio tipo de objeto, de forma separada a 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íelo.

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.

La opción de traducción del grupo de campos en la página de opciones decide qué ocurre con cada campo:

• Los campos que utilizan Translate (Traducir) van al elemento Opciones de ACF que envía desde el Escritorio de traducción. Cuando la traducción se ha completado, ACFML escribe los valores en la página de opciones de ese idioma. Los campos de repetidor y de contenido flexible obtienen las mismas filas que el original.
• Los campos que utilizan Copy (Copiar) obtienen el valor del original en todos los idiomas. Al guardar el original, ACFML actualiza los demás idiomas.
• Los campos que utilizan Copy once (Copiar una vez) comienzan como una copia del original. Después de eso, puede editarlos en la página de opciones de cada idioma.

Utilice Each language has its own content (Cada idioma tiene su propio contenido) cuando las opciones difieran según el idioma. Por ejemplo, una página de opciones enumera tres agentes de ventas en inglés y dos en español. Para elegir la opción, edite el grupo de campos, al igual que con cualquier otro grupo de campos.

Para cambiar una traducción finalizada, vaya a WPML → Traducciones → Trabajos de traducción y haga clic en Editar en el trabajo de Opciones de ACF. También puede editar los valores traducidos en WPML → Traducción de cadenas. Cuando guarda una traducción allí, ACFML la escribe en la página de opciones de ese idioma.

Cuando cambia el idioma predeterminado del sitio, los valores existentes de la página de opciones se mantienen en el idioma en el que los escribió. ACF lee los mismos valores que antes del cambio.

En el código, get_field( 'my_field', 'option' ) devuelve el valor del idioma actual. Después de do_action( 'wpml_switch_language', 'fr' ), devuelve el valor en francés. Esto también funciona para las páginas de opciones con un post_id personalizado.

Problemas 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 Field Group Labels (Etiquetas del grupo de campos) del grupo de campos desde el Escritorio (consulte Traducir las etiquetas de los campos más arriba).
• Los valores de las opciones parecen no estar traducidos. Mismo caso. Envíe el grupo de campos desde la sección ACF Field Group del Escritorio para que se incluyan los valores de las opciones.
• Las filas del repetidor se desincronizan. Es probable que el grupo de campos utilice Expert (Experto). Edite la entrada original, seleccione Keep repeater and flexible sub-fields in the same order as the default language (Mantener los subcampos flexibles y del repetidor en el mismo orden que el idioma predeterminado) en la caja ACFML Synchronise translations (Sincronizar traducciones de ACFML) y actualice la entrada. O cambie el grupo de campos a Same content in every language, translated (El mismo contenido en todos los idiomas, traducido).
• La lógica condicional se comporta de forma inesperada. Cuando el campo de control está configurado como Copy (Copiar) o Don’t translate (No traducir), el comportamiento condicional sigue el valor del idioma de origen en todas las traducciones. Configure el campo de control como Translate (Traducir) si su valor debe diferir según el idioma.
• Los campos locales (registrados en PHP) ignoran las preferencias de traducción configuradas en el panel de administración. Configure 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.

Hooks para desarrolladores en casos especiales

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 las cadenas de los grupos de campos de los trabajos de traducción de entradas), ACFML cuenta con dos filtros y cuatro constantes. La referencia completa con ejemplos de código se encuentra en Referencia de hooks y constantes de ACFML.