---
metadata:
  - name: generator
    content: Diplodoc Platform v5.56.0
alternate:
  - https://diplodoc.com/docs/ru/guides/multilingual-projects.md
  - href: ru/guides/multilingual-projects.md
    type: text/markdown
    title: Markdown version
  - href: ../llms.txt
    type: text/markdown
    title: llms.txt
updatedAt: '2026-08-25T13:03:26.000Z'
---
> **Documentation Index:** Fetch the complete configuration index at https://diplodoc.com/docs/ru/llms.txt

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

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

## Структура проекта {#project-structure}

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

```
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  # Конфигурационный файл, задает параметры сборки и отображения для вашего проекта
```
### Языковая папка {#language-folder}

**Языковая папка** содержит полный набор файлов своей версии: [оглавление](#toc), [инклюды](#includes), страницы контента, [пресеты переменных](#presets) и [изображения](#images). Файлы внутри папки ссылаются друг на друга.

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

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

### Файлы проекта {#project-files}

#### .yfm {#yfm}

[Конфигурационный файл](https://diplodoc.com/docs/ru/settings.md) в корне проекта. Помимо общих параметров, в нем указывается список языков — в основном блоке параметров и в секции `docs-viewer`:

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

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

{% note info %}

Коды локалей в `langs` должны совпадать с именами языковых папок.

{% endnote %}

<!-- source: ru/_includes/supported-languages.md -->
{% cut "Полный список поддерживаемых языков" %}

#|
|| **Код языка (ISO 639-1)** | **Язык** ||
|| `am` | Амхарский  ||
|| `ar` | Арабский   ||
|| `az` | Азербайджанский ||
|| `be` | Белорусский ||
|| `bg` | Болгарский ||
|| `el` | Греческий  ||
|| `en` | Английский ||
|| `es` | Испанский  ||
|| `et` | Эстонский  ||
|| `fi` | Финский    ||
|| `fr` | Французский ||
|| `he` | Иврит      ||
|| `hu` | Венгерский ||
|| `hy` | Армянский  ||
|| `ka` | Грузинский ||
|| `kk` | Казахский  ||
|| `km` | Кхмер      ||
|| `ky` | Киргизский ||
|| `lt` | Литовский  ||
|| `lv` | Латышский / Латвийский ||
|| `ne` | Непальский ||
|| `no` | Норвежский ||
|| `pl` | Польский   ||
|| `pt` | Португальский  ||
|| `ro` | Румынский / Молдавский ||
|| `ru` | Русский    ||
|| `sr` | Сербский   ||
|| `tg` | Таджикский ||
|| `tr` | Турецкий   ||
|| `uk` | Украинский ||
|| `ur` | Урду       ||
|| `uz` | Узбекский  ||
|| `vi` | Вьетнамский ||
|| `zh` | Китайский  ||
|#

{% endcut %}
<!-- endsource: ru/_includes/supported-languages.md -->

{% note warning %}

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

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

{% endnote %}

#### toc.yaml {#toc}

[Оглавление](https://diplodoc.com/docs/ru/project/toc.md) языковой версии. В каждой папке — свой `toc.yaml`.

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

[Расширенная навигация](https://diplodoc.com/docs/ru/project/navigation.md) настраивается отдельно для каждой локализованной версии.

#### Папки с инклюдами {#includes}

[Инклюды](https://diplodoc.com/docs/ru/syntax/includes.md) хранятся в языковых папках и [переводятся](#translation) так же, как страницы с контентом.

#### Папки с изображениями {#images}

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

## Создание многоязычного проекта {#create-project}

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

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

Читайте подробнее: [Создание проекта](https://diplodoc.com/docs/ru/tools/docs/init.md)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

После [сборки](https://diplodoc.com/docs/ru/tools/docs/build.md) проверьте, что страницы отображаются корректно.

## Перевод контента {#translation}

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

Читайте подробнее: [Локализация](https://diplodoc.com/docs/ru/tools/docs/translate.md).

## Пресеты переменных {#presets}

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

Пример:

- в папке `ru`:

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

- в папке `en`:

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

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

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

Читайте подробнее: [Пресеты переменных](https://diplodoc.com/docs/ru/project/presets.md).

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

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

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

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

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

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

- [Единый источник](https://diplodoc.com/docs/ru/guides/single-source/index.md)
- [Профилирование](https://diplodoc.com/docs/ru/guides/single-source/profiling.md)

## Переключение между языками {#switch-languages}

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

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

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

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

## Локализация логотипа {#language-logo}

Вы можете настроить отдельный логотип для каждого языка. Для этого в [секции docs-viewer](https://diplodoc.com/docs/ru/settings.md#docs-viewer) файла `.yfm` вместо одного значения укажите коды языков и ключ `default`:

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

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

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

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

## Ссылки на другие языковые версии {#language-version-link}

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

При необходимости вы можете вручную указать ссылки с помощью параметра `alternate` в [метаданных](https://diplodoc.com/docs/ru/project/meta.md).