HTML
Переводите текст и атрибуты HTML, сохраняя остальной исходный код без изменений и задавая язык документа по целевой локали.
В HTML читаемый текст встроен в структуру, которая также содержит ссылки, задаёт поведение и хранит данные для специальных возможностей. Обработчик html выбирает поддерживаемые текстовые фрагменты и описательные атрибуты, затем вставляет их переводы в исходный код для одной целевой локали. Он не делит многоязычную страницу на отдельные области по локалям.
Сохраняйте структуру исходного документа #
Документы сохраняют исходный doctype и явно заданные элементы. Фрагменты остаются фрагментами: при переводе не добавляются обёртки <html>, <head> или <body>. Комментарии, незатронутые атрибуты, тип кавычек и пробельные символы вне переведённых участков остаются такими же, как в исходном коде.
У явно заданного элемента <html> значение lang заменяется целевой локалью. Если атрибута lang нет, он добавляется. Например, для французского языка <html lang="en"> становится <html lang="fr">. Если во фрагменте нет явно заданного элемента <html>, он не добавляется только ради указания языка.
Например, этот фрагмент содержит видимый текст и текст для специальных возможностей:
<section>
<h2>Delivery options</h2>
<p>Read the <a href="/delivery">delivery policy</a>.</p>
<img src="/truck.svg" alt="Delivery truck" />
<input placeholder="Enter your address" aria-label="Delivery address" />
</section>Обработчик поддерживает перевод заголовка, абзаца, текста ссылки, альтернативного текста изображения, подсказки в поле ввода и метки ARIA. Адрес ссылки и источник изображения остаются структурными свойствами. Перевод этого фрагмента не создаёт локализованные ссылки и не заменяет файлы изображений.
Выбор атрибутов и областей #
По умолчанию поддерживаются атрибуты alt и title у изображений, placeholder и title у полей ввода и многострочных текстовых полей, отдельные атрибуты title, атрибут content метатегов и атрибуты меток ARIA. Внимательно проверяйте метаданные: выбор атрибута по имени не означает, что все его значения — обычный текст. Правила для свойств компонентов позволяют добавить атрибуты для элементов с заданными именами.
Содержимое элементов script, style, pre, code, math, template, noscript и textarea не входит в обычное извлечение текста. При этом у пропущенного элемента может быть поддерживаемый описательный атрибут. В SVG для перевода отдельно выбирается поддерживаемое содержимое title, desc и text, а не произвольные данные рисунка.
На время перевода внутристрочная разметка и токены {{...}} защищаются плейсхолдерами. При сборке результата они возвращаются в переведённые участки. Проверьте структуру элементов в результате и отобразите его, подставив в переменные типичные для приложения значения.
Повторное использование и сохранение исходного кода #
Для повторного использования структура текста и плейсхолдеров в предыдущем исходном тексте и его переводе должна совпадать. Обработчик проверяет это соответствие и может отклонить неоднозначную пару. Храните принятый перевод вместе с соответствующей версией исходного текста, а не сравнивайте отображённые страницы, не связанные друг с другом.
Меняются только переведённые участки и атрибут языка явно заданного элемента <html>. Остальной исходный код копируется в результат без изменений. Обработчик не очищает недоверенный HTML от потенциально опасного содержимого. Продолжайте использовать собственные проверки безопасности и отображения в приложении.
Если из-за неправильной вложенности парсер объединяет текст из несвязанных участков разметки, обработчик отклоняет документ, а не записывает неоднозначный перевод. Исправьте вложенность и повторите попытку. Если теги HTML опущены по правилам, добавлять структурные элементы документа не нужно.
Настройте HTML-файлы в CLI или GitHub App #
CLI и GitHub App определяют html по .html и .htm. Выберите исходные файлы в .lingo/config.json так, чтобы создаваемые переводы не попадали под шаблоны исходных файлов:
{
"sourceLocale": "en",
"targetLocales": ["fr"],
"files": [
{ "pattern": "pages/en/**/*.html", "format": "html" },
{ "pattern": "pages/en/**/*.htm", "format": "html" }
]
}Для этих расширений явно задавать format необязательно. Свяжите проект с организацией и движком локализации с помощью настройки CLI или укажите движок для GitHub App. Для каждой целевой локали создаётся отдельный файл, например pages/fr/index.html. HTML не поддерживает перевод отдельных ключей.
После получения результата отобразите документ или фрагмент там, где он будет использоваться. Сравните ссылки и нетекстовые атрибуты, проверьте текст для специальных возможностей вместе с видимым текстом. Если HTML поступает из CMS, следуйте инструкциям её коннектора по выбору полей и обратной записи. Коннекторы могут принимать разные входные данные, даже если внутри они используют обработку HTML.