Многоязычные проекты

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

Структура проекта

Пример структуры многоязычного проекта:

document-name  # Каталог проекта
├── ru  # Языковая папка
│   ├── toc.yaml  # Оглавление
│   ├── presets.yaml  # Пресеты переменных
│   ├── index.yaml  # Разводящая страница
│   ├── _includes/  # Папка с инклюдами
│   ├── _images/  # Папка с изображениями
│   ├── content-folder/
│       └── file.md  # Файлы и папки с контентом
├── en  # Языковая папка
│   ├── toc.yaml  # Оглавление
│   ├── presets.yaml  # Пресеты переменных
│   ├── index.yaml  # Разводящая страница
│   ├── _includes/  # Папка с инклюдами
│   ├── _images/  # Папка с изображениями
│   ├── content-folder/
│       └── file.md  # Файлы и папки с контентом
├── es  # Языковая папка
│   ├── toc.yaml  # Оглавление
│   ├── presets.yaml  # Пресеты переменных
│   ├── index.yaml  # Разводящая страница
│   ├── _includes/  # Папка с инклюдами
│   ├── _images/  # Папка с изображениями
│   ├── content-folder/
│       └── file.md  # Файлы и папки с контентом  
├── .yfm  # Конфигурационный файл, задает параметры сборки и отображения для вашего проекта

Языковая папка

Языковая папка содержит полный набор файлов своей версии: оглавление, инклюды, страницы контента, пресеты переменных и изображения. Файлы внутри папки ссылаются друг на друга.

Имя папки — код языка (ru, en, es), те же значения вы указываете в конфигурации.

Пути к страницам могут совпадать в разных языковых папках. Например: ru/guides/start.md для русской версии и en/guides/start.md для английской. Хотя это необязательное условие, оно помогает платформе Diplodoc корректно связывать языковые версии.

Файлы проекта

.yfm

Конфигурационный файл в корне проекта. Помимо общих параметров, в нем указывается список языков — в основном блоке параметров и в секции docs-viewer:

langs: ['ru', 'en']  # Массив языков, которые участвуют в сборке.

docs-viewer:
  project-name: my-project
  langs: ['ru', 'en']  # Массив языков, которые отображаются в интерфейсе документации. Язык по умолчанию при открытии страницы — первый элемент в массиве.

toc.yaml

Оглавление языковой версии. В каждой папке — свой toc.yaml.

Содержимое файлов для разных локалей может различаться. Например, если русскоязычная страница не переведена на английский, то ее нет ни в папке en, ни в оглавлении английской версии.

Расширенная навигация настраивается отдельно для каждой локализованной версии.

Папки с инклюдами

Инклюды хранятся в языковых папках и переводятся так же, как страницы с контентом.

Папки с изображениями

Изображения можно хранить как в общей корневой папке, так и в отдельных языковых — если для каждого языка нужны свои версии.

Создание многоязычного проекта

Способ 1: с помощью команды

Выполните команду yfm init: в интерактивном или ручном режиме. В ручном режиме вы можете указать языки через параметр --langs.

Читайте подробнее: Создание проекта

Способ 2: вручную

Этот способ подходит, если проект уже существует и вы хотите добавить в него языковые папки.

Шаг 1. Создайте языковые папки

В корне проекта создайте папки для всех языков, на которые переведена документация. Для названий используйте их коды. Например: ru, en, es.

Шаг 2. Настройте языки в .yfm

Откройте файл .yfm и укажите список языков в параметре langs: в корневом блоке и в секции docs-viewer. Язык, который должен открываться по умолчанию, поставьте первым в docs-viewer.langs.

Шаг 3. Добавьте оглавление

В каждой языковой папке создайте файл toc.yaml.

Шаг 4. Настройте пресеты переменных

Если в контенте есть переменные, значения которых зависят от языка, укажите их в файлах presets.yaml.

По умолчанию в сборку попадают значения из блока default.

Шаг 5. Добавьте контент

Добавьте страницы, инклюды, изображения и другой необходимый контент. См. также: Перевод контента.

Шаг 6. Соберите проект

После сборки проверьте, что страницы отображаются корректно.

Перевод контента

Для перевода документации на другие языки используется команда yfm translate, которая обеспечивает автоматические переводы, AI-перевод или обмен *.xliff файлами с CAT-системами.

Читайте подробнее: Локализация.

Пресеты переменных

Файл presets.yaml содержит значения переменных. Общий файл располагается в корневой директории проекта. Если для разных локалей нужны свои значения переменных, создайте отдельные пресеты в языковых папках.

Пример:

• в папке ru:

  default:
    locale: ru
    service-url: https://example.ru
  

• в папке en:

  default:
    locale: en
    service-url: https://example.com
  

При сборке система заменит {{ service-url }} на https://example.ru для русской версии и https://example.com для английской.

Убедитесь, что имена переменных одинаковы во всех языковых папках. Например, если в папке ru вы используете переменную locale, в папке en тоже должна быть locale, а не region.

Читайте подробнее: Пресеты переменных.

Профилирование в многоязычных проектах

Внутри одной языковой версии вы можете разделить контент для разных платформ, стран или аудиторий.

Например, пользователи мобильной и веб-версии увидят разный текст, если вы разметите его с помощью условных операторов if:

{% if platform == 'mobile' %}Установите приложение.{% endif %}

{% if platform == 'web' %}Откройте сайт.{% endif %}

Читайте подробнее:

• Единый источник
• Профилирование

Переключение между языками

В интерфейсе документации пользователь может переключаться между локализованными версиями. Доступны только те, для которых есть перевод текущей статьи.

При выборе другого языка страница перезагружается: обновляется содержимое, оглавление и интерфейс.

Один и тот же материал в разных версиях находится по адресам, которые различаются кодами локалей:

https://diplodoc.com/docs/ru/
https://diplodoc.com/docs/en/

Локализация логотипа

Вы можете настроить отдельный логотип для каждого языка. Для этого в секции docs-viewer файла .yfm вместо одного значения укажите коды языков и ключ default:

docs-viewer:
  logo-options:
    src:
      ru: logo-ru
      en: logo-en
      default: logo

В этом примере:

• Если ссылка содержит код папки ru или en, система показывает соответствующий логотип: logo-ru или logo-en.

• Если ссылка не содержит код языковой папки, система показывает логотип logo.

Ссылки на другие языковые версии

Система сборки автоматически добавляет в метаданные ссылки на локализованные версии страницы. Благодаря этому поисковые системы могут показывать пользователю ту версию документации, которая соответствует его региональным настройкам.

При необходимости вы можете вручную указать ссылки с помощью параметра alternate в метаданных.