Markdoc
Переводите текст Markdoc и выбранные строковые атрибуты, сохраняя аннотации, переменные и код.
Аннотации Markdoc связывают текст документа с пользовательскими компонентами и переменными. Обработчик файлов markdoc переводит поддерживаемый текст и выбранные строковые атрибуты тегов, сохраняя аннотации, нужные вашему рендереру.
Выберите видимые свойства тегов #
В документе могут сочетаться видимые метаданные, фиксированный идентификатор макета и блок примечания:
---
title: Delivery options
description: Understand the available delivery methods.
layout: article
---
{% callout title="Delivery deadline" type="warning" %}
Confirm your address before checkout.
{% /callout %}Абзац и выбранные по умолчанию поля title и description в блоке метаданных — это текст. Атрибут title тега попадает в перевод, если его выбирает правило для свойств. type="warning" и layout: article — структурные идентификаторы. Не выбирайте их, если только компонент, который их использует, явно не ожидает переведённых значений.
Правила могут выбирать свойство по имени во всех тегах или только в указанных. Предпочитайте второй вариант, если разные теги используют один и тот же атрибут для разных целей. Числовые, логические и другие нестроковые атрибуты, а также атрибуты со значениями из переменных не считаются текстом для перевода.
Что остаётся защищённым #
Блоки кода и встроенный код не переводятся. Адреса ссылок сохраняются, а их текст может меняться. Встроенные аннотации и изображения защищены от изменений при переводе окружающего текста. Имена тегов и невыбранные атрибуты остаются в документе. Обработчик экранирует переведённые строковые атрибуты по правилам Markdoc для строк в кавычках, но не задаёт схему пользовательских тегов для вашего рендерера.
Поля title и description в блоке метаданных выбраны по умолчанию. Если список выбранных полей пуст, они останутся без изменений. При выборе отображения или последовательности в перевод включаются все вложенные скалярные значения. Указывайте точные пути, например seo.title, если соседние поля маршрутизации или ИД контента должны оставаться неизменными.
Сохраняйте соответствие исходника и перевода #
При сборке документа текстовые фрагменты заменяются в текущем исходнике. При этом можно повторно использовать формулировки из предыдущей сопоставленной пары исходника и перевода. Если защищённые встроенные структуры в этой паре нельзя надёжно сопоставить, повторное использование может не сработать. Сохраняйте версию исходника, которой соответствует принятый перевод, особенно после перемещения тегов или изменения ссылок.
Не рассчитывайте, что для документа .md с аннотациями Markdoc автоматически будет выбран этот обработчик. CLI определяет .md как Markdown. Выбирайте формат явно, если язык документа требует обработки по правилам Markdoc.
Настройте перевод Markdoc #
CLI определяет markdoc по .mdoc. Область видимости ключей недоступна. Настройки блока метаданных, выбора свойств тегов и структуры выходных файлов описаны в разделе Конфигурация CLI, а рабочий процесс для репозитория — в разделе GitHub.
Проверьте результат по схеме сайта #
Обработчик файлов не настраивает маршруты фреймворка, загрузку контента или преобразования Markdoc в приложении. Получив перевод, выполните его разбор и рендеринг с теми же схемами, что и для исходника. Вместе с переведёнными абзацами проверьте видимые атрибуты, адреса ссылок, переменные и выбранные поля блока метаданных.