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 тоже пропускает такой файл:
{
"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 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 эти варианты равнозначны.
- Ссылки.
&,<,>,",'и ссылки на символы, например©, декодируются перед переводом. Сущность, объявленная в DOCTYPE, например&brand;или&product-name;, защищается как плейсхолдер и записывается обратно без изменений. - Значения, не относящиеся к обычному тексту. Текст, состоящий только из цифр, URL, даты в формате ISO или 22-символьного идентификатора из букв и цифр, не переводится, а копируется в каждый целевой файл.
Имена и пути элементов считываются точно так, как записаны, с учётом регистра и префиксов пространств имён.
Перевод атрибутов #
Значения атрибутов переводятся, только если эти атрибуты указаны в translateComponentProps. Строка задаёт атрибут для всех элементов, а объект с component — только для указанных элементов:
{
"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 записываются как ссылки на символы: например, é для é. Так целевой файл остаётся читаемым в этой кодировке. Файл считывается как 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.