Как переводить произвольные поля ACF в WordPress — группы полей, повторители, страницы параметров

Перед началом работы

Установите и активируйте эти плагины:

• Advanced Custom Fields или ACF Pro.
• WPML и WPML Перевод строк.
• ACFML (дополнение, о котором идет речь на этой странице).

Ваши группы полей уже должны быть настроены в ACF. Вы можете изменить параметры перевода для каждого поля постфактум, поэтому порядок действий не имеет значения. Настройте группы полей, а затем вернитесь к ACFML.

Выбор варианта перевода для каждой группы полей

Не все группы полей ACF ведут себя одинаково при переводе. ACFML предлагает три варианта перевода для каждой группы полей. Чтобы выбрать один из них:

1. Перейдите в ACF → Группы полей и отредактируйте группу полей.
2. В разделе Multilingual Setup под Select a translation option for this field group нажмите Choose на нужном варианте.
3. Сохраните группу полей.

ACFML отмечает вариант, который он предлагает для Вашего сайта, как recommended for this site. Чтобы выбрать другой вариант позже, нажмите Change option. В старых версиях ACFML первые два варианта называются Same fields across languages и Different fields across languages.

Одинаковый контент на каждом языке, переводится

Типичная настройка для большинства сайтов с ACF. Посетители на всех языках видят одни и те же страницы на своем языке. Текст переводится, а макет и настройки остаются прежними. Обычный пример — страница Наша команда. Ваша команда одинакова на всех языках, поэтому имя и биография каждого участника переводятся, а структура полей остается прежней. Вы вводите информацию о команде на языке по умолчанию, а затем отправляете запись на перевод из WPML → Переводы → Панель управления. Переведенные значения возвращаются в те же поля. Этот вариант работает с автоматическим переводом и режимом Переводить все.

У каждого языка свой собственный контент

Используйте этот вариант, когда на каждом языке отображается разный контент в одной и той же группе полей. Обычный пример — компания, которая проводит местные мероприятия. На английской странице Мероприятия отображаются события для англоязычной аудитории, а на французской — для франкоязычной. Поля изначально создаются как копия оригинала. После этого каждый язык сохраняет свои собственные значения. Вы редактируете каждый язык в редакторе WordPress: откройте запись, нажмите на значок плюса для языка перевода в блоке Язык, заполните значения для этого языка и опубликуйте. WPML больше не синхронизирует языковые версии, и автоматический перевод не применяется.

Expert

Используйте этот вариант, когда Вам нужна комбинация: некоторые поля переводятся, некоторые остаются неизменными, а некоторые копируются один раз, а затем изменяются в каждом языке. Выберите Expert и задайте параметры перевода для каждого поля вручную. В примере с Мероприятиями для заголовка и описания используется Перевести, а для цены, даты и адреса — Копировать. ACFML не рекомендует этот вариант для новых групп полей. Группа полей, определенная в PHP или Local JSON, может не иметь варианта перевода. В таком случае она использует Expert, только если группа полей существовала до обновления Вашего сайта до WPML 5.2.

Параметры перевода для каждого типа полей ACF

Каждое поле, в котором хранится значение, имеет один из четырех параметров перевода:

• Перевести. Посетители видят значение на своем языке. WPML заполняет его переводом. Вы редактируете его в редакторе переводов.
• Копировать. Посетители на всех языках видят в точности то же, что и в оригинале. Поле заблокировано для других языков.
• Копировать один раз. Значение изначально создается как копия оригинала. После этого Вы редактируете его в каждом языке вручную. Если Вы очистите поле в переводе, оно останется пустым. WPML не будет снова копировать в него исходное значение.
• Не переводить. Переводы создаются без этого значения. Вы можете заполнить его в каждом языке вручную.

Когда Вы выбираете Same content in every language, translated или Each language has its own content, ACFML задает каждому полю рекомендуемый параметр для его типа. В таблицах ниже показаны эти рекомендуемые параметры. Чтобы задать другой параметр для одного поля, используйте Expert. Чтобы изменить рекомендуемый параметр типа поля для всего сайта, используйте фильтр acfml_field_group_mode_field_translation_preference (см. раздел Хуки разработчика для нестандартных ситуаций ниже).

Поля Вкладка (Tab), Аккордеон (Accordion), Сообщение (Message) и Разделитель (Separator) не хранят значение, поэтому для них нет параметров перевода. Тип поля, которого нет в таблицах, например тип поля из другого плагина, получает параметр Копировать при обоих вариантах перевода.

Поля повторителя, гибкого содержания, группы и клона

Эти поля содержат другие поля. Рекомендуемый параметр для поля-контейнера — Копировать или Копировать один раз. ACFML не предлагает вариант Перевести для самого поля-контейнера. Каждое подполе имеет свой собственный параметр перевода.

При выборе Same content in every language, translated строки полей повторителя и гибкого содержания остаются в том же порядке, что и на языке по умолчанию. При выборе Expert или когда в записи используются группы полей с разными вариантами, в редакторе записей отображается блок ACFML Synchronise translations. Он отображается в оригинальной записи, когда у записи есть переводы и поле повторителя или гибкого содержания. Выберите Keep repeater and flexible sub-fields in the same order as the default language, чтобы сохранить выравнивание строк на всех языках.

Базовые поля

Поля контента

Поля выбора

Поля jQuery

Поля макета

Реляционные поля

Для поля «Ссылка» перевод охватывает текст ссылки и URL-адрес. Если URL-адрес указывает на страницу Вашего сайта и Вы его не изменяете, WPML показывает страницу на языке посетителя.

Поля URL и ссылки

Начиная с ACFML 5.0, поля URL и ссылки по умолчанию используют настройку Перевести.

Двунаправленные связи

Начиная с ACF 6.2, поля «Связь», «Объект записи», «Таксономия» и «Пользователь» могут быть двунаправленными. Когда Вы выбираете цель в поле, ACF добавляет Вашу запись в парное поле цели. Например, для книги Дюна в поле Автор указан Фрэнк Герберт. Затем ACF добавляет Дюну в поле Книги Фрэнка Герберта.

ACFML сохраняет пару в каждом языке:

• Когда WPML копирует поле в перевод, ACFML указывает поле на целевой объект в том же языке. Затем ACFML добавляет перевод в парное поле этого целевого объекта. Испанская Dune показывает испанского Frank Herbert, а испанский Frank Herbert выводит испанскую Dune.
• Когда для поля используется параметр Копировать и Вы меняете целевой объект в оригинальной записи, WPML обновляет перевод. ACFML добавляет перевод к новому целевому объекту в этом языке и удаляет его из старого.
• ACFML изменяет целевые объекты только в языке перевода. Записи на языке оригинала сохраняют свою собственную пару.
• Если у целевого объекта еще нет перевода, перевод указывает на оригинальный целевой объект, и ACFML не изменяет оригинальный целевой объект. Когда Вы переведете целевой объект позже, ACFML укажет поле на новый перевод и добавит запись в его парное поле. Поле выводит целевой объект один раз.
• У пользователей нет переводов, поэтому ACFML не добавляет переводы в парное поле пользователя. Это поле сохраняет оригинальную запись. На другом языке ACFML показывает перевод этой записи, если только для поля не используется параметр Копировать.

Это работает для параметров Копировать и Копировать один раз, которые являются рекомендуемыми для этих типов полей. Это также работает, когда Вы дублируете запись с помощью WPML.

Перевод блоков ACF

По умолчанию блоки ACF сохраняют значения своих полей внутри блока, в контенте записи, а не как произвольные поля. ACFML отправляет эти значения на перевод вместе с остальной частью записи в одном задании на перевод.

• Блок использует опцию перевода и параметры полей той группы полей, правилом расположения которой является этот блок.
• ACFML отправляет только те поля, которые используют параметр Перевести. Поля, использующие параметры Копировать, Копировать один раз или Не переводить, сохраняют значение из оригинального блока.
• Поля Repeater и Flexible Content внутри блока также переводятся, в том числе когда они вложены. Каждое подполе использует свой собственный параметр перевода.
• Блок с "usePostMeta": true в разделе acf своего файла block.json сохраняет свои значения как произвольные поля записи, а не в блоке. Эти значения переводятся как любое другое произвольное поле записи, с учетом опции перевода и параметров полей группы полей.
• Когда Вы изменяете параметр перевода в группе полей, которую используете для блоков, WPML спрашивает, хотите ли Вы обновить существующие переводы. Если Вы подтверждаете, WPML отмечает переводы этих записей как нуждающиеся в обновлении. Отправьте их на перевод снова, чтобы применить изменение. Изменение на Не переводить не отмечает их.

Поля, объявленные в block.json

Начиная с версии ACF 6.8.1, блок может объявлять свои поля в файле block.json, в acf.fields. ACF создает группу полей для этих полей, и Вы не можете редактировать эту группу полей в админ-панели. ACFML назначает ей опцию Одинаковый контент на всех языках, переводится и рекомендуемый параметр для каждого типа поля, как и для группы полей, зарегистрированной в PHP.

Чтобы использовать другую опцию для всей группы, добавьте acfml_field_group_mode в раздел acf файла block.json или в acf_register_block_type(). Допустимые значения: translation (Одинаковый контент на всех языках, переводится), localization (У каждого языка свой контент) и advanced (Эксперт). ACFML игнорирует любые другие значения.

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

Чтобы задать параметр для одного поля, добавьте wpml_cf_preferences к этому полю. ACFML сохраняет этот параметр при любой опции. С опцией Эксперт параметр получают только те поля, в которых объявлено wpml_cf_preferences.

Если block.json не указывает опцию, ACFML сохраняет ту опцию, которую он назначает группе при первом обнаружении, и в дальнейшем использует ее. На сайтах, которые использовали эти блоки с более старой версией ACFML, сохраненной опцией является Эксперт.

Настройка параметров для полей, зарегистрированных в PHP или JSON

Группы полей ACF, зарегистрированные в PHP (с помощью acf_add_local_field_group()) или через функцию Local JSON в ACF, не получают параметры перевода из экранов админ-панели, поскольку админ-панель ими не управляет. Задайте параметры там же, где Вы регистрируете поля.

Чтобы задать параметр перевода для группы полей, добавьте ключ acfml_field_group_mode в определение со значением translation, localization или advanced (Expert). Если в определении не задан параметр перевода, ACFML назначает группе полей параметр Одинаковый контент на всех языках, переведенный при первом обнаружении группы. ACFML сохраняет этот параметр и применяет его в дальнейшем. Группы полей, существовавшие до обновления Вашего сайта до WPML 5.2, сохраняют параметр Expert.

Для каждого поля в определении группы полей добавьте ключ wpml_cf_preferences. Значение представляет собой целое число, которое соответствует четырем параметрам перевода: 0 для Не переводить (WPML игнорирует поле), 1 для Копировать (значение синхронизируется между языками), 2 для Перевести (значение переводится) и 3 для Копировать один раз (значение копируется в новые переводы, после чего каждый язык можно редактировать независимо).

Минимальный пример:

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

После определения полей в коде синхронизируйте параметры с WPML, чтобы админ-панель распознала их:

1. Перейдите в ACF → Инструменты.
2. Прокрутите до Перевод полей ACF Local JSON и зарегистрированных в PHP.
3. В разделе Синхронизация параметров перевода для локальных полей выберите Синхронизировать один раз сейчас и нажмите Применить.

WPML считывает параметры из определений Ваших полей и сохраняет их. Опция Синхронизировать один раз сейчас выполняется однократно. Если Вы часто меняете определения, выберите вместо этого Синхронизировать при каждом запросе (может повлиять на производительность). Эта опция запускает синхронизацию при каждом запросе к админ-панели.

Если Вы используете функцию Local JSON в ACF для обмена группами полей между сайтами, ACFML автоматически записывает параметры перевода в файлы JSON. Экспортируйте файл JSON с одного сайта, импортируйте его на другой, и целевой сайт подхватит параметры, как только ACFML будет активен на обеих сторонах.

Группы полей, которые ACF создает с помощью команды WP-CLI wp acf json import или через свой Abilities API для инструментов ИИ, сохраняются в базе данных. ACFML назначает им параметр Одинаковый контент на всех языках, переведенный и рекомендуемый параметр для каждого типа поля. Если в импортированном JSON уже есть ключ acfml_field_group_mode, ACFML использует этот параметр вместо него.

Группы полей в локальных файлах JSON

ACF загружает группы полей из папки acf-json на очень раннем этапе каждого запроса. Начиная с WPML 5.2, ACFML считывает эти группы полей в то же самое время. Поэтому при синхронизации параметров перевода синхронизация охватывает и группы полей JSON. Затем WPML использует параметры из файлов JSON.

В файле JSON добавьте wpml_cf_preferences к каждому полю с теми же значениями, что и в PHP. Этот ключ задает параметр для каждого поля, независимо от параметра перевода группы полей. В примере используется Expert:

{
    "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
        }
    ]
}

Чтобы отправить параметры и метки групп полей JSON в WPML:

1. Перейдите в ACF → Инструменты.
2. Прокрутите до Перевод полей ACF Local JSON и зарегистрированных в PHP.
3. В разделе Синхронизация параметров перевода для локальных полей выберите Синхронизировать один раз сейчас или Синхронизировать при каждом запросе (может повлиять на производительность).
4. В разделе Регистрация меток для перевода выберите Зарегистрировать метки сейчас.
5. Нажмите Применить.

Чтобы проверить результат, перейдите в WPML → Настройки и найдите поля в разделе Перевод пользовательских полей. Каждое поле показывает параметр из файла JSON. ACFML также регистрирует метки групп полей, типов записей, таксономий и страниц параметров, которые существуют только в коде: в папке acf-json или зарегистрированные в PHP. Переводите их как метки любой другой группы полей (см. Перевод меток полей ACF ниже).

Перевод меток полей ACF

Метки полей ACF — это названия, которые идентифицируют каждое произвольное поле в редакторе WordPress и на фронтенде (например, Номер телефона, Адрес). Они переводятся отдельно от значений полей и находятся в WPML Перевод строк, а не в задании на перевод записи.

Чтобы отправить метки полей на перевод:

1. Откройте WPML → Переводы → Панель управления.
2. Разверните раздел Группа полей ACF.
3. Выберите элемент Метки группы полей для группы полей, которую Вы хотите перевести.
4. Выберите метод перевода (PTC, Ваш переводчик или Переводить самому) и отправьте.

Переведенные метки автоматически появляются на фронтенде, как только перевод завершается.

Остановка перевода меток полей

По умолчанию задание на перевод записи не включает метки полей. Вы переводите их только тогда, когда отправляете элемент Field Group Labels из панели управления. Если Вы его не отправите, ACF покажет оригинальные метки. Чтобы показывать оригинальные метки даже при наличии переводов, используйте фильтр acfml_should_translate_acf_entity и возвращайте false для полей или групп полей, которые Вы хотите пропустить. В справочнике хуков и констант ACFML есть пример.

Перевод вариантов выбора полей ACF

Поля выбора (Select, Checkbox, Radio Button, Button Group) содержат собственные метки вариантов (например, Small / Medium / Large). Они также находятся вместе с метками полей, а не внутри перевода записи. Отправьте их таким же образом:

1. Откройте WPML → Переводы → Панель управления.
2. Разверните раздел ACF Field Group.
3. Выберите группу полей, значения выбора которой Вы хотите перевести.
4. Выберите метод перевода и отправьте.

Перевод страниц параметров ACF

Страницы параметров ACF (экраны глобальных настроек, такие как Контактные данные, Настройки шапки, Ссылки в футере) переводятся как собственный тип объекта, отдельно от записей:

1. Откройте WPML → Переводы → Панель управления.
2. Разверните раздел ACF Options.
3. Выберите страницу параметров, которую Вы хотите перевести.
4. Выберите метод перевода и отправьте.

Значения страницы параметров для каждого языка появляются автоматически, когда ACF считывает параметр в контексте этого языка.

Параметр перевода группы полей на странице параметров определяет, что произойдет с каждым полем:

• Поля, использующие Перевести, попадают в элемент ACF Options, который Вы отправляете из панели управления переводами. Когда перевод завершен, ACFML записывает значения на страницу параметров этого языка. Поля повторителя и гибкого контента получают те же строки, что и оригинал.
• Поля, использующие Копировать, получают значение оригинала на всех языках. Когда Вы сохраняете оригинал, ACFML обновляет остальные языки.
• Поля, использующие Копировать один раз, изначально создаются как копия оригинала. После этого Вы редактируете их на странице параметров каждого языка.

Используйте Each language has its own content, если параметры отличаются в зависимости от языка. Например, на странице параметров указаны три торговых агента на английском языке и два на испанском. Чтобы выбрать этот параметр, отредактируйте группу полей, как и любую другую группу полей.

Чтобы изменить готовый перевод, перейдите в WPML → Переводы → Задания на перевод и нажмите Изменить для задания ACF Options. Вы также можете редактировать переведенные значения в WPML → Перевод строк. Когда Вы сохраняете там перевод, ACFML записывает его на страницу параметров этого языка.

При изменении языка сайта по умолчанию существующие значения страницы параметров остаются на том языке, на котором Вы их написали. ACF считывает те же значения, что и до изменения.

В коде get_field( 'my_field', 'option' ) возвращает значение для текущего языка. После do_action( 'wpml_switch_language', 'fr' ) функция возвращает значение для французского языка. Это также работает для страниц параметров с пользовательским post_id.

Распространенные проблемы

• Метки полей выглядят непереведенными. Они находятся в Переводе строк, а не в переводе записи. Отправьте элемент Field Group Labels для группы полей из панели управления (см. Перевод меток полей ACF выше).
• Значения выбора выглядят непереведенными. Та же ситуация. Отправьте группу полей из раздела ACF Field Group в панели управления, чтобы значения параметров были включены.
• Строки повторителя рассинхронизируются. Вероятно, в группе полей используется режим Expert. Отредактируйте оригинальную запись, выберите Keep repeater and flexible sub-fields in the same order as the default language в блоке ACFML Synchronise translations и обновите запись. Либо переключите группу полей на Same content in every language, translated.
• Условная логика ведет себя неожиданно. Если для управляющего поля установлено значение Копировать или Не переводить, условное поведение следует за значением исходного языка во всех переводах. Установите для управляющего поля значение Перевести, если его значение должно отличаться в зависимости от языка.
• Локальные поля (зарегистрированные в PHP) игнорируют параметры перевода, заданные в админ-панели. Установите ключ wpml_cf_preferences в самом определении группы полей и синхронизируйте из ACF → Инструменты. Процедура описана в разделе Настройка параметров для полей, зарегистрированных в PHP или JSON выше.

Хуки разработчика для нестандартных случаев

Для программного управления (исключение определенных полей из перевода, переопределение параметров по умолчанию для типа поля на всем сайте, скрытие аннотаций от переводчиков или исключение строк группы полей из заданий на перевод записей) в ACFML есть два фильтра и четыре константы. Полный справочник с примерами кода находится в справочнике хуков и констант ACFML.