Файлы конфигурации языка

Amir

Обновлено

22 февраля, 2023

WPML может читать конфигурационный файл, в котором указывается, что нужно перевести в темах и плагинах. Файл называется wpml-config.xml и помещается в корневую папку плагина или темы.

Содержание

1. Назначение файла конфигурации языка
2. Автоматическая генерация файла wpml-config.xml
3. Структура и синтаксис
   • Шорткоды и содержимое конструктора страниц
   • Пользовательские поля
   • Пользовательские термины
   • Пользовательские типы
   • Пользовательские таксономии
   • Блоки Gutenberg
   • Админ тексты / wp_options
   • Конфигурация переключателя языков
4. Использование файла конфигурации языка WPML с дочерними темами

Назначение

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

Перейдите на страницу WPML → Настройки.

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

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

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

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

Автоматическая генерация файла wpml-config.xml

Если Вы не знакомы с созданием XML-файлов, наша команда создала плагин Multilingual Tools, который облегчает эту задачу. Хотя изначально он задумывался как инструмент для помощи авторам тем и плагинов в создании многоязычных продуктов, его можно легко использовать для создания собственного файла wpml-config.xml .

Чтобы узнать больше о генерации файла wpml-config.xml, посетите страницу плагина Multilingual Tools. В частности, посмотрите раздел Как генерировать файлы языковой конфигурации с помощью Multilingual Tools?

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

Обратите внимание, что этот плагин не предназначен для использования на рабочих сайтах.

Чтобы ознакомиться с этим руководством и создать языковые конфигурационные файлы для ваших тем и плагинов, Вы можете начать с этого примера — wpml-config.zip.

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

Структура и синтаксис

Содержимое файла wpml-config.xml должно быть завернуто в эти теги

<wpml-config>

и

</wpml-config>

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

1. Содержание конструктора страниц
2. Пользовательские поля
3. Пользовательские термины
4. Пользовательские типы
5. Пользовательские таксономии
6. Блоки Gutenberg
7. Админ тексты / wp_options
8. Конфигурация переключателя языков

1. Шорткоды и содержимое конструктора страниц

WPML позволяет использовать файл wpml-config.xml для определения шорткодов, которые необходимо добавить при переводе контента.

В примерах ниже мы покажем, как регистрировать шорткоды конструктора страниц. Вы можете использовать одну и ту же структуру кода для регистрации всех типов шорткодов для перевода.

1.1 Перевод строк

Рассмотрим пример, когда на страницу с помощью Visual Composer добавлен текстовый разделитель. Этот разделитель имеет заголовок, а его шорткод выглядит следующим образом:

[vc_text_separator title="Separator Title"]

Для того чтобы перевести заголовок этого текстового разделителя, нам нужно добавить несколько строк в наш файл wpml-config.xml. Таким образом, WPML будет «знать», что заголовок этого разделителя нуждается в переводе. Это следует той же логике, которая используется для пользовательских типов постов, пользовательских полей и др.

Следующий код является примером того, что нам нужно добавить в файл wpml-config.xml в данном случае.

Давайте рассмотрим структуру приведенного выше примера:

• Начните с тега shortcodes. Все шорткоды на Вашем сайте, которые необходимо перевести, должны быть помещены в этот тег.
• Затем используйте тег shortcode, чтобы обернуть все теги, принадлежащие одному-единственному шорткоду.
• Тег tag используется для определения имени шорткода. В данном случае это vc_text_separator. Вы можете добавить пользовательские метки опций для отображения как в редакторе расширенного перевода, так и в редакторе классического перевода. Эти метки также включаются при экспорте в файлы XLIFF. См. приведенный ниже пример о метках тегов и атрибутов.
• Шорткоды могут иметь один или несколько атрибутов, поэтому мы заключаем их в тег attributes (множественное число) и используем тег attribute (единственное число) для определения названия каждого атрибута.

Конструкторы страниц включают (иногда) элементы дизайна, которые имеют атрибуты ссылок.

Вы можете сделать так, чтобы внутренние ссылки автоматически указывали на переведенную версию записи, используя в файле wpml-config.xml новую опцию ссылки шорткода: type=”link”.

С ним можно использовать атрибут encoding. Он обрабатывает специальную кодировку, которую используют различные конструкторы страниц. Атрибут кодировки обычно зависит от используемого конструктора страниц. Он принимает следующие значения:

• base64 — Visual Composer необработанный шорткод HTML. HTML хранится в виде строки base64 в шорткоде.
• vc_link — Специальное форматирование ссылок для Visual Composer.
• av_link — Специальное форматирование ссылок для Enfold.
• allow_html_tags — Обычно HTML-теги удаляются из атрибутов шорткода. Установите кодировку в allow_html_tags, если атрибут шорткода должен разрешать HTML-теги. Это следует использовать с осторожностью, так как разрешение HTML-тегов в некоторых ситуациях может испортить форматирование и стать проблемой безопасности.

Если Вы собираетесь использовать шорткоды с кодировкой url, обязательно прочитайте страницу о переводе шорткодов с кодировкой url.

Добавление меток к тегам и атрибутам позволяет отображать пользовательские метки в редакторе расширенного перевода или редакторе классического перевода. Это может помочь переводчику лучше понять контекст строки.

1.2 Перевод медиа

Вы можете использовать WPML Media Translation для перевода изображений в содержимом конструктора страниц. Это делается путем преобразования ID изображений и URL-адресов изображений. Необходимо указать конструктору страниц, использующему шорткоды, как выполнять это преобразование. Следующий код является примером того, что нам нужно добавить в файл wpml-config.xml в данном случае.

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

• ignore-content — Может использоваться внутри элемента тега. Это значение является необязательным и может быть равно 0 или 1. Вы можете использовать этот атрибут для достижения обратной совместимости для новых медиа-шорткодов. Если значение установлено в 1 , содержимое шорткода не будет обрабатываться.
• type — Может использоваться внутри элемента тега. Вы также можете использовать содержимое шорткода, содержащее URL медиафайла в качестве необязательного значения в media-url.
• type — может также использоваться внутри элемента атрибута. В этом случае он может иметь одно из следующих необязательных значений:
  • media-ids — разделенный запятыми список ID медиа.
  • media-url — URL медиафайла
  • link — указывает на другую страницу сайта, и WPML автоматически преобразует его в URL-адрес перевода страницы

1.3 Перевод виджетов конструктора страниц

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

1.4 Автоматическое преобразование ID шорткодов

Начиная с версии WPML 4.5.9, Вы можете объявлять ID записей или значений таксономии, расположенные в атрибутах шорткодов. Затем эти ID могут быть автоматически преобразованы на Вашем сайте.

Например, при рассмотрении следующего шорткода:

[foo_product_list product_ids="12,34,56"]

Мы можем объявить, что атрибут product_ids содержит ID записей с помощью следующей конфигурации:

<shortcode>
    <tag ignore-content="1">foo_product_list</tag>
    <attributes>
        <attribute type="post-ids" sub-type="product">product</attribute>
    </attributes>
</shortcode>

На сайте шорткод будет автоматически преобразован в:

[foo_product_list product_ids="13,35,57"]

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

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

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

2. Пользовательские поля

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

Этот блок должен быть вложен в тег <wpml-config>.

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

• перевести: позволяет пользователю перевести значение пользовательского поля. Эти поля отображаются в редакторе переводов и могут быть отправлены в любую из профессиональных служб перевода.
• копировать: это действие копирует значение пользовательского поля языка по умолчанию во вторичные языки. Это означает, что обновление значения пользовательского поля на языке по умолчанию всегда будет копироваться на вторичный язык. Пользовательские поля, установленные для копирования, не отображаются в редакторе переводов.
• копировать раз: Значение пользовательского поля копируется на вторичный язык в процессе первоначального перевода. Пользовательские поля, использующие действие копировать раз, не будут отображаться в редакторе переводов. Однако пользователь может изменить значение пользовательского поля вторичного языка, чтобы оно отличалось от языка по умолчанию, используя экран редактирования записи. Предпочтительно установить для пользовательских полей, которые содержат такие параметры, как цвет фона, цвет шрифта, размер шрифта и другие, значение «копировать раз «. Это позволяет пользователю иметь настройки для переведенного контента, отличные от настроек, установленных для записей и страниц на языке по умолчанию. Например, пользователь хочет установить цвет фона одного и того же элемента желтым на языке по умолчанию и синим на дополнительном языке. Обратите внимание, что при редактировании поля, установленного как копировать раз не будет помечено как требующее обновления. Это связано с тем, что поле не будет скопировано в существующий перевод, оно копируется только при создании перевода.
• игнорировать: это действие исключает копирование пользовательского поля во вторичный язык.

Вы можете добавить атрибуты к тегам <custom-field>. Эти атрибуты настраивают тексты инструкций в редакторе расширенного перевода или редакторе классического перевода.

• style может быть line, textarea или visual, для отображения одной строки, текстовой области или WYSIWYG соответственно.
• label отображается рядом с полем.
• group указывает, принадлежит ли пользовательское поле к группе и какой должна быть метка группы. Когда поле находится в группе:

* поле удаляется из раздела пользовательских полей

* поле добавляется в раздел связанной группы

Вы также можете добавить необязательные атрибуты encode, чтобы изменить кодировку по сравнению со значением по умолчанию(без кодировки). Атрибут Encoding принимает следующие значения:

• json
• base64
• urlencode

Атрибут позволяет использовать несколько кодировок. В этом случае значения необходимо разделять запятой, например, encoding="json,base64".

При использовании этого содержимого wpml-config.xml эти пользовательские поля отображаются в редакторе расширенного перевода или редакторе классического перевода, как показано на следующем изображении.

2.1 Перевод вложенных ключей в пользовательских полях

WPML по умолчанию переводит все вложенные ключи в пользовательских полях. Можно обойти такое поведение, указав, какие подключи должны быть переведены.

Можно использовать wildcards так же, как они используются для админ текстов:

• Сопоставьте все подполя, начинающиеся с title-, используя код:
  <key name="title-*" />
• Соответствует всем подполям и обычно используется для сопоставления индекса массива с использованием кода:
  <key name="*" />
• Чтобы получить [{"title":"First title"},{"title":"Second title"}], используйте код

3. Пользовательские термины

Необходимо указать название пользовательского термина, а также действие, которое должен выполнить WPML: перевести, копировать, копировать раз, игнорировать.

Этот блок должен быть вложен в тег <wpml-config>.

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

• перевести: позволяет пользователю перевести значение пользовательского термина. Эти термины отображаются в редакторе переводов и могут быть отправлены в любую из профессиональных служб перевода.
• копировать: это действие копирует значение пользовательского термина языка по умолчанию во вторичные языки. Это означает, что обновление значения пользовательского термина на языке по умолчанию всегда будет копироваться на вторичный язык. Пользовательские термины, установленные для копирования, не отображаются в редакторе переводов.
• копировать раз: Значение пользовательского термина копируется на вторичный язык в процессе первоначального перевода. Пользовательские термины, использующие действие копировать раз, не будут отображаться в редакторе переводов. Однако пользователь может изменить значение пользовательского термина вторичного языка, чтобы оно отличалось от языка по умолчанию, используя экран редактирования записи.
• игнорировать: это действие исключает копирование пользовательского термина во вторичный язык.

4. Пользовательские типы

Пользовательские типы постов, которые WPML должен перевести.

Вы можете добавить атрибут «display-as-translated» к тегу, чтобы показывать типы постов на определенном языке, если перевода не существует.

Вы можете добавить атрибут «automatic» к тегу, чтобы исключить тип поста из автоматического перевода при использовании режима «Полный перевод«. Обратите внимание, если Вы используете этот атрибут, весь Ваш файл конфигурации языка будет работать только для WPML версии 4.5.0 и выше.

5. Пользовательские таксономии

Пользовательские таксономии, которые может использовать Ваш плагин и которые уже зарегистрированы в WP.

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

Вы можете добавить атрибут «display-as-translated» к тегу, чтобы показывать таксономии на языке по умолчанию, если не существует перевода.

6. Блоки Gutenberg

В редакторе Gutenberg Вы создаете контент с помощью блоков.

Вы можете указать, какие части Вашего блока Gutenberg должны быть переведены, добавив настройки в wpml-config.xml.

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

6.1 Регистрация блоков Gutenberg как переводимо

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

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

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

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

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

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

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

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

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

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

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

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

Мы можем задать определение блока с помощью wildcard:

Это позволит нам перевести «Заголовок» и «Содержание», поскольку это единственные атрибуты, начинающиеся с myp.

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

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

Это позволит нам перевести «Заголовок» и «Содержание», поскольку это единственные атрибуты, не начинающиеся с _.

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

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

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

6.3 Блок Namespace

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

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

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

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

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

<!-- 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 записи атрибут блока ids и значение атрибута HTML-тега foo_form_post_ids, как показано ниже:

<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, как показано ниже:

<!-- 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. Если не определено, конкретный тип будет угадан.

7. Админ тексты / wp_options

Строки, являющиеся частью опций, которые плагины или темы сохраняют в таблице wp_options.

Когда темы и плагины используют get_option, они считывают значения из таблицы wp_options. WPML может фильтровать эти вызовы и обеспечивать перевод значений этих опций.

Это работает, если запись wp_option является простой строкой, а также если это сериализованный массив.

Чтобы перевести одну опцию, добавьте key запись в разделе admin-texts. Чтобы перевести сериализованный массив, добавьте несколько ключей под key, как это показано в примере my_plugin_options ниже.

Можно использовать wildcard * во вложенных ключах, как в следующем случае.

Она равна этому коду:

Обратите внимание, что wildcard * НЕ работает в родительских ключах:

8. Конфигурация переключателя языков

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

Чтобы увидеть новые изменения, обязательно нажмите кнопку Восстановить по умолчанию в нижней части страницы WPML → Языки.

 

---

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

Использование файла конфигурации языка WPML с дочерними темами

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

Рассмотрим пример, когда в файле языковой конфигурации родительской темы пользовательский тип поста «Property» устанавливается как переводимый.

Если Вы используете дочернюю тему и хотите установить пользовательский тип поста «Property» непереводимым, перейдите на страницу WPML → Настройки и перейдите на вкладку Пользовательская конфигурация XML. Используйте редактор, чтобы установить пользовательский тип поста «Property» как непереводимый. Просто установите значение атрибута translate на 0 вместо 1.

Настройки на вкладке Пользовательская конфигурация XML имеют приоритет над настройками в файле конфигурации языка в родительской теме.