Чтобы перевести HTML через DeepL API, передайте фрагмент в text, включите tag_handling: "html" и явно задайте tag_handling_version: "v2". До отправки отметьте непереводимые обозначения, а после получения ответа проверьте ссылки и защищённый текст. Такой режим описан в официальной инструкции DeepL по HTML.
Инструкция для разработчика интеграции и редактора, которому нужно локализовать описание услуги, справочную статью или карточку в CMS. Исходный материал уже существует в HTML. Переводить приложение целиком, переносить шаблонный движок или автоматически публиковать результат этот порядок не предлагает.
Документация сверена 3 ноября 2026 года. Запрос ниже — пример по документации, без выполненного обращения к DeepL. Локально проверены подготовка JSON, извлечение HTML из учебного ответа и сравнение структурных признаков. Качество машинного перевода и поведение конкретной CMS здесь не измерялись.
Содержание
- Что подготовить до перевода
- Шаг 1. Выделите цельный HTML-фрагмент
- Шаг 2. Отметьте то, что должно остаться без перевода
- Шаг 3. Соберите JSON без ручного экранирования
- Шаг 4. Отправьте запрос из серверной среды
- Шаг 5. Извлеките HTML и сравните важные элементы
- Шаг 6. Перенесите перевод в черновик CMS
- Типичные ошибки при переводе HTML
- Частые вопросы
Что подготовить до перевода
Понадобятся доступ к DeepL API, серверная среда с Python 3 и curl, исходный HTML-фрагмент и отдельный черновик в CMS. У API Free и API Pro разные адреса: соответственно https://api-free.deepl.com и https://api.deepl.com. Ключ берут в разделе API Keys и передают в заголовке авторизации; помещать его в клиентский JavaScript нельзя. Это требования документации доступа DeepL.
Начните с одного блока, который редактор может прочитать целиком. Сохраните исходник, его версию и место в CMS: например, поле body страницы услуги. Работайте с копией. Для облачной обработки используйте материал, передачу которого компания разрешила; служебные данные и секреты в пример не добавляйте.
Заранее разделите содержимое:
| Часть страницы | Действие в этой инструкции | Результат этапа |
|---|---|---|
| Абзацы, заголовки, подписи ссылок | Перевести вместе с HTML-контекстом | Читатель получает связный текст |
| Точное обозначение тарифа или команды | Пометить как непереводимое | Обозначение можно сравнить с исходником |
| Адреса ссылок и изображений | Сохранить для первого перевода; локальные маршруты менять отдельно | Случайный перевод не определяет навигацию |
alt, title, метаданные страницы |
Вынести в отдельный список локализации | Не забыты тексты вне видимых абзацев |
| Шаблонные переменные и исполняемый код | Исключить из первого прогона | Учебный маршрут остаётся обычным HTML |
Это предлагаемый порядок работы с CMS, а не перечень гарантий DeepL. Если экспорт содержит React-компоненты, шаблоны или XML, сначала определите реальный формат. Для XML у DeepL отдельный режим и правила обработки структуры.
Шаг 1. Выделите цельный HTML-фрагмент
Сохраните в source.html этот учебный англоязычный фрагмент:
<section id="service">
<h2>Priority support</h2>
<p>Activate <strong>priority support</strong> for your team.</p>
<p>Plan: <span translate="no">TEAM-PRO</span>.</p>
<p><a href="/support/contact">Contact support</a></p>
</section>В нём есть заголовок, выделение, точное название тарифа и ссылка. TEAM-PRO — вымышленное обозначение для демонстрации. Адрес /support/contact — учебный относительный маршрут: перед реальной работой укажите существующий адрес своего сайта.
Сохраняйте связную фразу вместе с выделением. В этом примере не нужно отдельно переводить Activate, priority support и for your team: редактору легче оценить готовое предложение. Вместе с тем не отправляйте весь HTML сайта с меню и скриптами ради одного описания. Граница задачи — содержимое выбранного поля.
Результат: один небольшой файл с понятным назначением каждого элемента. Откройте его в редакторе кода и убедитесь, что это HTML, а не строка, в которой угловые скобки уже заменены на < и >.
Шаг 2. Отметьте то, что должно остаться без перевода
Атрибут translate="no" сообщает, что содержимое элемента нужно оставить исходным. Его смысл определён в стандарте HTML. DeepL документирует поддержку этого атрибута и класса notranslate для HTML. В нашем файле защита относится к TEAM-PRO, а окружающая фраза остаётся доступной для перевода.
Не ставьте запрет на весь абзац, если в нём нужно перевести обычные слова. И не рассчитывайте, что сам вид строки, заглавные буквы или дефисы убедят переводчик сохранить обозначение. Запишите точное ожидаемое значение и сравните его после ответа.
Защита от перевода не скрывает данные от облачного сервиса. Если отправлять строку нельзя, её нужно исключить из запроса, а не только обернуть в span. Термины, которым нужен согласованный перевод, требуют другого решения: им посвящён FAQ о глоссарии DeepL.
Результат: отмечены только неизменяемые фрагменты. Проверка названия тарифа после перевода остаётся обязательной частью этого маршрута.
Шаг 3. Соберите JSON без ручного экранирования
Для Linux/macOS или серверной оболочки с Python 3 выполните в папке с source.html:
import json
from pathlib import Path
source = Path("source.html").read_text(encoding="utf-8")
request = {
"text": [source],
"source_lang": "EN",
"target_lang": "RU",
"tag_handling": "html",
"tag_handling_version": "v2"
}
Path("request.json").write_text(
json.dumps(request, ensure_ascii=False), encoding="utf-8"
)Код читает HTML как строку и поручает библиотеке JSON корректно записать кавычки и переносы. Он не переводит содержимое. EN и RU — языки именно этого примера; для другого исходника задайте соответствующую пару.
Параметры text, source_lang, target_lang и обработки тегов перечислены в справочнике Translate text. Версию обработки задаём явно, чтобы результат запроса не зависел от предположения о настройке по умолчанию для учётной записи. Число v2 здесь относится к алгоритму тегов, а не к версии сайта или CMS.
Результат: request.json, который открывается как JSON, а его первый элемент text совпадает с исходным файлом. Этот этап можно выполнить без ключа и без сетевого запроса.
Шаг 4. Отправьте запрос из серверной среды
Следующий пример рассчитан на DeepL API Pro. До запуска безопасно задайте в серверной среде переменную DEEPL_AUTH_KEY; не записывайте ключ в публичный репозиторий. Для API Free замените домен на api-free.deepl.com.
curl --fail-with-body --silent --show-error \
--request POST 'https://api.deepl.com/v2/translate' \
--header "Authorization: DeepL-Auth-Key $DEEPL_AUTH_KEY" \
--header 'Content-Type: application/json' \
--data-binary @request.json \
--output response.jsonЭто документированный способ запроса с подготовленным телом; команда в рамках статьи не отправлялась. Сам вызов может расходовать лимит вашей подписки. Используется curl с поддержкой --fail-with-body: при ошибке HTTP он возвращает ненулевой код, сохраняя тело ответа. Поведение ключа описано в официальной справке curl.
Продолжайте только после успешного завершения команды. Если запрос завершился ошибкой, не воспринимайте существующий response.json как перевод: в нём может оказаться сообщение сервера либо результат прежней попытки. Сначала разберите ошибку, затем выполните новый запрос осознанно.
Результат: успешный JSON-ответ с массивом translations. Успех HTTP ещё не означает, что полученный текст можно публиковать.
Шаг 5. Извлеките HTML и сравните важные элементы
Для одиночного фрагмента из примера сохраните перевод так:
import json
from pathlib import Path
response = json.loads(Path("response.json").read_text(encoding="utf-8"))
translations = response.get("translations")
if not isinstance(translations, list) or len(translations) != 1:
raise ValueError("Expected one translation")
text = translations[0].get("text")
if not isinstance(text, str) or not text.strip():
raise ValueError("Missing translated HTML")
Path("translated.html").write_text(text, encoding="utf-8")В HTML-поле CMS передают значение translations[0].text, а не весь JSON и не строку с внешними JSON-кавычками. Соответствие массива переводов входному массиву описано в справочнике DeepL. Если позже расширите запрос на несколько блоков, сохраняйте связь с исходными полями; этот короткий извлекатель намеренно принимает только один результат.
Сравните source.html и translated.html по конкретным признакам:
- обозначение внутри защищённого
spanосталосьTEAM-PRO; - ссылка ведёт на прежний
/support/contact; - заголовок и абзацы сохранили свои роли;
- выделение относится к нужным словам переведённой фразы;
- русский текст передаёт исходный смысл без добавленных условий.
Не требуйте побайтового совпадения HTML: слова и их порядок меняются при переводе. При этом изменение нужного адреса, пропажа защищённого обозначения или потеря заголовка — повод остановить перенос и выяснить причину.
Локальная проверка этой статьи выполнена на исходном фрагменте и вручную составленном учебном русском ответе, а не на результате DeepL. Подготовка JSON и извлечение текста сохранили данные; сравнение обнаружило намеренно изменённую ссылку и название тарифа. Это проверяет работу вспомогательного маршрута, но ничего не доказывает о качестве или надёжности облачного перевода.
Результат: отдельный HTML-файл и разобранные различия. При любой ошибке вспомогательного скрипта не используйте прежний translated.html как результат текущего запуска.
Шаг 6. Перенесите перевод в черновик CMS
Откройте исходное поле в режиме HTML и вставьте перевод в отдельную языковую копию. Используйте штатный предварительный просмотр вашей CMS. Проверьте заголовок, выделение и переход по ссылке уже на странице: редактор может преобразовать вставленную разметку.
Адрес ссылки оставался исходным намеренно. Если у русской версии есть другой маршрут, замените его по таблице соответствий сайта и проверьте переход. Перевод подписи ссылки и выбор её адреса — отдельные действия.
Затем обработайте тексты за пределами фрагмента: название страницы, описание для поиска, подписи изображений и элементы интерфейса. Не делайте вывод об их готовности по переведённому абзацу. Атрибуты, допускающие перевод, отдельно описаны в стандарте HTML; фактическое поведение выбранного API и интеграции проверяйте на своих полях.
Результат: языковой черновик с работающей навигацией и полным набором видимых текстов. Публикуйте его после редакторской проверки смысла и просмотра страницы. Такая проверка в CMS в рамках этой статьи не выполнялась.
Типичные ошибки при переводе HTML
| Симптом | Что проверить | Что сделать |
|---|---|---|
| На странице видны скобки тегов | Не вставлен ли экранированный текст в визуальный редактор | Использовать нужный HTML-режим и правильный уровень экранирования |
| Название тарифа перевелось | Есть ли узкая защита в исходнике | Добавить translate="no" и повторно сравнить точную строку |
| Ссылка подписана по-русски, но открывает старую языковую страницу | Есть ли локальный маршрут для неё | Применить подтверждённое соответствие адресов |
| Перевод есть, но часть страницы осталась на исходном языке | Попали ли в задачу метаданные и атрибуты | Перевести недостающие поля отдельно |
| Страница выглядит иначе после вставки | Не преобразовала ли HTML сама CMS | Сравнить файл перевода с сохранённым полем и предпросмотром |
| Ошибка скрипта, а файл результата существует | Не остался ли файл от прежнего запуска | Прекратить перенос; получить успешный результат текущей попытки |
Это диагностические направления, а не результаты испытаний всех CMS. Если задача касается субтитров, понадобится другой маршрут: перевод SRT с сохранением таймкодов проверяет временную структуру видео.
Частые вопросы
Можно ли просто попросить чат-бота перевести HTML?
Можно подготовить черновик таким способом, но наличие просьбы «сохрани теги» не проверяет результат. Для описанного маршрута выбран API с документированным HTML-режимом и явным отделением перевода от переноса в CMS. Сравнения качества чат-бота и DeepL здесь нет.
Нужно ли превращать HTML в XML?
Для обычного HTML в этой инструкции используется tag_handling: "html". XML — другой формат с отдельными правилами. В частности, DeepL документирует строгий разбор XML в алгоритме v2; переносить это правило на HTML нельзя.
Сохраняет ли непереводимый span конфиденциальность?
Нет. Он задаёт поведение перевода. Сам фрагмент всё равно входит в отправляемое тело запроса; запрещённые для передачи данные следует исключать до отправки.
Как AI студия Владимира Ломтева помогает связать перевод с CMS
AI студия Владимира Ломтева занимается подготовкой данных, интеграциями и автоматизацией рабочих процессов. Для задачи локализации это может включать выделение переводимых полей из экспорта, интеграцию этапа обработки с бизнес-системой и тестирование возврата результата в черновики. Поддержку конкретной CMS и переводчика нужно определить по устройству проекта.
Первый шаг — выбрать одно поле одной страницы, описать текущий ручной процесс, источники, ограничения передачи данных и критерий готовности: корректный текст, нужные ссылки и сохранённые обозначения. Обсудить задачу.
Итог: сохраните управляемый путь от HTML до страницы
Начните с небольшого фрагмента, явно включите HTML-режим и защитите точные обозначения. Полученный текст извлеките из JSON, сравните важные элементы и перенесите в языковой черновик CMS. Готовый результат — страница, которую редактор прочитал и проверил вместе с навигацией; успешный запрос остаётся только одним этапом этого пути.
