Markdown

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

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

Текст и защищённая структура #

Например, текст ссылки может измениться, а её адрес и имя функции — остаться прежними:

markdown
---
title: Delivery options
description: Choose how your order arrives.
slug: delivery
---

## Choose delivery

Read the [delivery policy](/policies/delivery) before calling `confirmOrder()`.

Заголовок, текст абзаца и текст ссылки — это переводимый текст. Адрес ссылки и встроенный код — защищённая структура. В стандартном профиле документа блоки кода с разделителями и необработанный HTML не извлекаются для перевода. Используйте HTML, если исходный документ написан на HTML, или Markdoc, если собственные теги Markdoc — часть языка документа.

Выбор метаданных #

По умолчанию обработчик файлов выбирает title и description. Остальные поля не меняются, если не выбрать их явно. Пустой список translateFrontmatterFields отключает перевод метаданных. Выбирайте поля с учётом их назначения: заголовок для читателей можно перевести, а слаг, идентификатор компонента или ключ маршрутизации может потребоваться оставить без изменений.

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

Для повторного использования нужна согласованная структура документов #

Обработчик сопоставляет фрагменты текста с предыдущим исходником и соответствующим переводом, а затем вставляет изменённые переводы в структуру текущего исходника. Готовые формулировки можно использовать повторно, только если понятно, каким фрагментам они соответствуют. Если защищённые встроенные структуры в предыдущем исходнике и переводе различаются, повторное использование может завершиться ошибкой из-за несовпадения структур.

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

Как настроить и отобразить документ #

CLI определяет md по .md. Настройте выбор файлов, поля метаданных и пути вывода в разделе Конфигурация CLI или используйте GitHub для управляемого перевода репозитория. Для Markdown область видимости ключей CLI недоступна.

Отобразите результат с помощью обработчика Markdown вашего сайта. Проверьте переведённые метаданные, ссылки, фрагментные идентификаторы заголовков и примеры кода в комплексе. Сохранение /policies/delivery не создаёт эту страницу на другом языке. Руководство по статическому контенту объясняет, как связать пути вывода с загрузчиком сайта и маршрутами локалей.