XML

Перевод текста любого XML-документа прямо в файле с побайтовым сохранением объявления, комментариев, атрибутов и форматирования.

Обработчик файлов xml переводит текст XML-документа, для которого нет отдельного формата: например, экспортированного контента, файла справки или ресурсов в собственном формате. Каждый перевод записывается в копию исходного файла, поэтому объявление, DOCTYPE, комментарии, инструкции обработки, атрибуты, пространства имён и пробельные символы остаются без изменений. Меняются только переведённый текст и указанные вами атрибуты.

Ресурсы Android, XLIFF и словари множественных форм Apple — тоже XML, но для них есть отдельные форматы: Android, XLIFF и Apple stringsdict. Используйте их для таких файлов: они учитывают ключи, множественные формы и состояние каждого перевода.

Настройка перевода XML #

Файл переводится как XML общего назначения, только если в соответствующей записи files задано "format": "xml". Само по себе расширение .xml не определяет формат, потому что оно используется и для strings.xml в Android. CLI пропускает файл .xml, если в его записи не указан формат, и выводит сообщение. GitHub App тоже пропускает такой файл:

json
{
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "files": [{ "pattern": "content/en/*.xml", "format": "xml" }]
}

Так для content/en/guide.xml создаются content/de/guide.xml и content/fr/guide.xml. Для путей к целевым файлам действуют те же правила, что и для JSON. Они описаны в разделе пути вывода, а targetPath позволяет задать другое расположение. Файл относится к первой записи, шаблон которой ему соответствует. Поэтому выделите ресурсы Android в отдельную запись с "format": "android", а для записи xml задайте шаблон, который их не охватывает. Одна и та же конфигурация работает в CLI и GitHub App.

Что переводится #

Каждый элемент с текстом — одна единица перевода. У элемента, который содержит только другие элементы, комментарии и пробельные символы, своей единицы перевода нет. Вместо него считываются дочерние элементы:

xml
<?xml version="1.0" encoding="UTF-8"?>
<help>
  <!-- shown on the settings page -->
  <topic id="sync">
    <title>Sync your files</title>
    <p>Click <b>Sync</b> to upload your <a href="/files">files</a> now.</p>
  </topic>
</help>

Здесь title — одна единица перевода, а p — другая. Комментарий, id и href не отправляются на перевод.

  • Встроенные элементы. Текст с элементами внутри, как p выше, образует одну единицу перевода на всё предложение. Встроенные элементы передаются модели как плейсхолдеры: их можно перемещать, но нельзя менять. Благодаря этому Sync и files могут занять в переводе те места, которых требует целевой язык. Комментарии и инструкции обработки внутри такого текста сохраняются так же.
  • Пробельные символы. Текст только из пробельных символов, например отступы между элементами, никогда не отправляется на перевод. Пробельные символы вокруг текста сохраняются в файле, а внутри текста — отправляются без изменений. Пробельные символы, которые перевод добавляет по краям текста, удаляются.
  • CDATA. Текст из одной секции CDATA переводится и записывается обратно как секция CDATA. Секция CDATA рядом с другим текстом становится его частью и записывается обратно с экранированием. Для XML эти варианты равнозначны.
  • Ссылки. &amp;, &lt;, &gt;, &quot;, &apos; и ссылки на символы, например &#169;, декодируются перед переводом. Сущность, объявленная в DOCTYPE, например &brand; или &product-name;, защищается как плейсхолдер и записывается обратно без изменений.
  • Значения, не относящиеся к обычному тексту. Текст, состоящий только из цифр, URL, даты в формате ISO или 22-символьного идентификатора из букв и цифр, не переводится, а копируется в каждый целевой файл.

Имена и пути элементов считываются точно так, как записаны, с учётом регистра и префиксов пространств имён.

Перевод атрибутов #

Значения атрибутов переводятся, только если эти атрибуты указаны в translateComponentProps. Строка задаёт атрибут для всех элементов, а объект с component — только для указанных элементов:

json
{
  "pattern": "content/en/*.xml",
  "format": "xml",
  "translateComponentProps": ["title", { "component": "item", "props": ["label"] }]
}

Так переводится каждый атрибут title и атрибут label у элементов <item>. Имена должны совпадать в точности, поэтому x:title и Title — другие атрибуты. Пустое значение пропускается. Идентификаторы, ссылки, xml:lang и объявления пространств имён переводятся, только если вы их указали. Если указать что-то из них по ошибке, изменится то, как читается файл.

Запись переводов #

В переведённом тексте экранируются &, < и >. В переведённом атрибуте экранируются &, < и символ кавычки, которым ограничено его значение. Символы табуляции и переносы строк записываются как ссылки на символы, чтобы XML сохранял их. Последовательность ]]> в переведённой секции CDATA разбивается между двумя секциями. Переносы строк в переводе записываются в том же формате, что и в исходном файле. Управляющие символы, недопустимые в XML, удаляются из перевода.

Если в объявлении указана кодировка, отличная от UTF-8, например encoding="ISO-8859-1", символы перевода вне ASCII записываются как ссылки на символы: например, &#xE9; для é. Так целевой файл остаётся читаемым в этой кодировке. Файл считывается как UTF-8. Поэтому, если в нём объявлена другая кодировка и буквы с диакритикой записаны напрямую в виде байтов, а не ссылок на символы, возникает ошибка с указанием позиции первой такой буквы. Для этого файла ничего не записывается. Сохраните его в UTF-8 или запишите эти символы как ссылки.

Обработчик не меняет xml:lang и другие атрибуты, указывающие язык документа. Обновляйте такой атрибут при сборке или укажите его в translateComponentProps, если он содержит текст.

Ключи и повторное использование #

Ключ каждой единицы перевода — путь к её элементу, записанный в стиле XPath: /help/topic/title, /list/item[2] или /menu/item[1]/@label для атрибута. Позиция указывается, только если у элемента есть соседние элементы с тем же именем. Эти ключи определяют единицы перевода в задании и в Studio.

Единица сохраняет текущий перевод, пока её текст и путь элемента (без учёта позиций) не изменились с последнего push, а встроенные элементы исходного текста сохранены в переводе с той же вложенностью. При этом элементы могут идти в другом порядке — этого часто требует порядок слов в целевом языке. Переведённый атрибут встроенного элемента перемещается вместе с ним. При вставке элемента переводится только новый элемент. Элементы после него сохраняют свои переводы, даже если их позиции изменились. Если встроенные элементы в переводе больше не соответствуют исходным — например, в переводе удалили один из них или переместили его внутрь другого, — единица переводится заново.

Параметры, которые не применяются к XML #

В XML нет правил для ключей. CLI и GitHub App отклоняют запись xml, в которой заданы lockedKeys, preservedKeys, ignoredKeys, keyColumn, injectLocale или translateFrontmatterFields. Иначе файл переводился бы так, будто параметр не задан. Параметр lockedPatterns тоже отклоняется, как и для любого формата, кроме Java properties.

lingo push --key пропускает файлы xml, выводит сообщение и отправляет остальные выбранные файлы.

Некорректный XML #

Если структура XML в файле некорректна, обработка завершается ошибкой с указанием строки и столбца первой проблемы: например, незакрытого или несовпадающего тега, неэкранированного &, двух корневых элементов или текста вне корневого элемента. Если в конце файла остаётся несколько незакрытых тегов, в сообщении об ошибке вместо этого перечисляются они. Глубина вложенности элементов больше 256 тоже вызывает ошибку. Для такого файла ничего не записывается, а существующий целевой файл остаётся без изменений. Некорректный целевой XML вызывает такую же ошибку с указанием его локали. Исправьте XML, затем повторите push.