WPML

Как сделать пользовательские блоки Gutenberg переводимыми

Обновлено: 5 июня 2025 года

Узнайте, как указать, какие из разработанных Вами пользовательских блоков Gutenberg должны быть переводимыми. Это можно сделать, настроив файл wpml-config.xml с помощью тестового плагина Multilingual Tools.

Это руководство предназначено для разработчиков, которые создают свои собственные пользовательские блоки для Gutenberg. Если Вы не являетесь разработчиком плагинов, узнайте, как переводить контент, созданный в редакторе Gutenberg.

С чего начать

Для начала установите и активируйте:

  1. Базовый плагин WPML
  2. WPML Перевод строк
  3. Multilingual Tools

Плагин Multilingual Tools не следует использовать на действующих или рабочих сайтах. Используйте его только для тестирования.

Генерация и тестирование XML-кода для регистрации блоков Gutenberg для перевода

1. Создайте новую запись или страницу и добавьте блоки Gutenberg, которые Вы хотите зарегистрировать. Обязательно добавьте тестовый контент в каждое поле, которое Вы хотите сделать переводимым, а затем опубликуйте.

Прокрутите вниз до раздела WPML: Gutenberg Blocks и скопируйте сгенерированный XML-код.

Копирование предварительно сгенерированного XML-кода для проверки
Копирование предварительно сгенерированного XML-кода для проверки

Важно: автоматически сгенерированный XML-код не следует использовать в исходном виде. Вы должны протестировать и отредактировать его, прежде чем предоставлять пользователям. См. следующий шаг.

2. Перейдите в WPML → Настройки и вставьте сгенерированный XML-код на вкладке Пользовательская конфигурация XML.

Обязательно тщательно проверьте автоматически сгенерированный код. Возможно, Вам потребуется удалить некоторые поля, не предназначенные для перевода, например поля конфигурации с определенными значениями.

Нажмите Сохранить, когда будете готовы.

3. Вернитесь на опубликованную страницу и внесите небольшие изменения, например, отредактируйте текст кнопки или заголовок.

Нажмите значок плюса в разделе Язык, чтобы открыть Расширенный редактор переводов. Поля из блоков Gutenberg появятся в редакторе и будут доступны для перевода.

Проверка переводимых блоков Gutenberg в Расширенном редакторе переводов WPML
Проверка переводимых блоков Gutenberg в Расширенном редакторе переводов WPML

После регистрации блоков Gutenberg, которые Вы хотите сделать переводимыми, Вы можете создать свой файл языковой конфигурации. Если он у Вас уже есть, просто отредактируйте его, добавив окончательный XML-код.

Примеры регистрации блоков Gutenberg как переводимых

Перевод изображений

Допустим, у Вас есть изображение, которое отображается с помощью следующего кода:

Пример изображения, которое нужно перевести
<!-- wp:image {"id":3} -->
<figure class="wp-block-image"><img src="http://example.com/wp-content/uploads/2018/07/figure-2.png" alt="Image alt text" class="wp-image-3"/><figcaption>Image Caption</figcaption></figure>
<!-- /wp:image -->

Вы хотите перевести значения атрибутов figcaptionи altэтого изображения.

Для этого Вам нужно вставить следующий код в файл wpml-config.xml:

Пример настроек для перевода блока Gutenberg
<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="core/image" translate="1">
        <xpath>//figure/figcaption</xpath>
        <xpath>//figure/img/@alt</xpath>
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

Обратите внимание, что атрибут type имеет значение core/image, а не wp:image, поскольку это значение возвращается API блоков.

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

Перевод ссылок в блоках Gutenberg
<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="core/some-block" translate="1">
        <xpath type="link">//a/@href</xpath>
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

Перевод атрибутов блока

Вот один из примеров формата для определения блока редактора:

Формат для определения блока редактора
<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="my-plugin/my-block" translate="1">
        <xpath label="My Block">//p</xpath>
        <key name="title" />
        <key name="foo">
            <key name="bar1" />
            <key name="bar2" />
        </key>
        <key name="/^[^_]\S+$/" search-method="regex" />
        <key name="something" search-method="wildcards" />
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

Вы можете использовать элемент key так же, как он используется в конфигурации Тексты администратора / wp_options. Это также означает, что Вы можете вкладывать элементы key в родительские элементы key.

Вы можете использовать атрибут label для добавления необязательных пользовательских меток, которые отображаются в Расширенном редакторе переводов рядом с элементами блока. Если атрибут label является частью тега gutenberg-block, он будет использоваться в качестве резервной метки для элементов блока, для которых не определена конкретная метка.

Пример резервной метки
<wpml-config>
    <gutenberg-blocks>
        <gutenberg-block type="my-plugin/mybutton" translate="1" label="My fallback block label">
            <xpath>//span</xpath>
            <xpath>//a@href</xpath>
        </gutenberg-block>
    </gutenberg-blocks>
</wpml-config>

Атрибут search-method может иметь одно из двух значений:

  • wildcards (по умолчанию)
  • regex.

Вы можете использовать подстановочные знаки (wildcards) так же, как и для текстов администратора. Это означает, что в атрибуте name можно использовать звездочку (*). Вот пример одного блока:

Пример блока
<!-- wp:my-plugin/my-block
    {
        "myp": {
            "mypTitle":"The title",
            "mypContent":"The Content",
            "_mypSystem:"Meta attribute to not translate"
        }
    }
/-->

Вы можете задать определение блока с помощью подстановочного знака:

Определение блока с помощью подстановочного знака
<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="my-plugin/my-block" translate="1">
      <key name="myp">
          <key name="myp*" />
      </key>
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

Это позволит Вам перевести «The title» и «The content», поскольку это единственные атрибуты, начинающиеся с myp.

Значение regex позволяет использовать регулярное выражение в атрибуте name. Это может быть крайне полезно для сложных конфигураций. Вот пример одного блока:

Сложная конфигурация — пример
<!-- wp:my-plugin/my-block
    {
        "data": {
            "title":"The title",
            "_title":"e980759463943209f6f1ae09a239e353",
            "content":"The Content",
            "_content":"1502a7b825dfe7b789c63830609f1701"
        }
    }
/-->

Вы можете задать определение блока с помощью регулярного выражения:

Определение блока с помощью регулярного выражения
<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="my-plugin/my-block" translate="1">
        <key name="data">
            <key name="/^[^_]\S+$/" search-method="regex" />
        </key>
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

Это позволит Вам перевести «The title» и «The content», поскольку это единственные атрибуты, не начинающиеся с подчеркивания (_).

Некоторые плагины блоков сохраняют данные в виде JSON-строки в URL-кодировке внутри атрибута блока. Атрибут encoding позволяет декодировать строку и зарегистрировать ее подключи для перевода.

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

Пример блока LazyBlocks с JSON-строкой в URL-кодировке
<!-- wp:lazyblock/testwpml {"name":"%5B%7B%22firstname%22:%22Shekhare%22,%22lastname%22:%22Bhandari%22%7D,%7B%22firstname%22:%22Compatibility%22,%22lastname%22:%22Escalation%22%7D%5D","blockId":"Z169b0O","blockUniqueClass":"lazyblock-testwpml-Z169b0O"} /-->

Вы можете зарегистрировать подключи firstname и lastname с помощью следующей конфигурации XML:

Пример регистрации JSON-строк в URL-кодировке внутри атрибута блока
<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="lazyblock/team" translate="1">
      <key name="name" encoding="json">
        <key name="*">
          <key name="firstname" />
          <key name="lastname" />
        </key>
      </key>
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

Чтобы WPML мог автоматически переводить URL-адреса, Вы можете объявить атрибуты блоков Gutenberg как ссылки.

Вот пример пользовательского блока Gutenberg с интерактивной ссылкой:

<!-- wp:foo/link {"label":"Click here!","url":"https://example.com/some-page/"} /-->

Чтобы сделать атрибуты label и url переводимыми, добавьте следующее в Ваш файл wpml-config.xml:

<gutenberg-block type="foo/link" translate="1">
	<key name="label" />
	<key name="url" type="link" />
</gutenberg-block>

В этой конфигурации указание type="link" для атрибута url позволяет WPML автоматически переводить URL-адрес.

Пространство имен блока

Вы можете иметь глобальную конфигурацию для пространства имен блока.

Имя блока больше не является обязательной частью определения.

Если конфигурация блока одинакова для всех блоков в пространстве имен, Вы можете записать ее следующим образом:

Блоки в пространстве имен
<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="my-plugin" translate="1">
        <key name="data">
            <key name="/^[^_]\S+$/" search-method="regex" />
        </key>
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

Автоматическое преобразование ID в блоках

Преобразование ID универсально и пытается адаптироваться к большинству возможных форматов ID (одиночный ID, список ID, сериализованный массив, массив в кодировке JSON).

Рассмотрим следующий блок:

Автоматическое преобразование ID в блоках — пример блока
<!-- wp:foo/form {"ids":[27,28]} -->
<div class="wp-block-foo-form-wrap">
  <form class="foo-form" action="" method="post">
    <input type="hidden" name="foo_form_post_ids" value="27,28" />
    <input type="submit" />
  </form>
</div>
<!-- /wp:foo/form -->

Вы можете объявить в качестве ID записей ID атрибутов блока и значение атрибута HTML-тега foo_form_post_ids, как показано ниже:

ID атрибутов блока и значение атрибута HTML-тега
<gutenberg-block type="foo/form" translate="0">
  <key name="ids">
      <key name="*" type="post-ids" sub-type="post" />
  </key>
  <xpath type="post-ids" sub-type="post">//*[@name="foo_form_post_ids"]/@value</xpath>
</gutenberg-block>

Блок будет преобразован с наивысшим приоритетом в фильтре render_block_data, как показано ниже:

Блок, преобразованный фильтром render_block_data
<!-- wp:foo/form {"ids":[42,43]} -->
<div class="wp-block-foo-form-wrap">
    <form class="foo-form" action="" method="post">
        <input type="hidden" name="foo_form_post_ids" value="42,43" />
        <input type="submit" />
    </form>
</div>
<!-- /wp:foo/form -→

Вы можете использовать следующие атрибуты конфигурации:

  • type — может быть post-ids или taxonomy-ids
  • sub-type (необязательно) — может быть конкретной сущностью для type, если она уже известна. Например, product для произвольного типа записи Product. Если не определено, конкретная сущность будет определена автоматически.

Дополнительные ресурсы

Чтобы узнать больше о файле wpml-config.xml, ознакомьтесь с руководством Файлы языковой конфигурации.

Для настройки других элементов с помощью файла wpml-config.xml ознакомьтесь с нашими дополнительными руководствами:

Автор: Amir · Последнее обновление: 5 июня 2025