Многоязычность (i18n)

Продукты и документация экосистемы обслуживаются на нескольких языках. Эта страница объясняет языковую политику и её техническую реализацию.

Языковая политика

Уровень	Языки
Обязательно	Монгол (mn) · English (en)
Для основных продуктов	+ 中文 (zh) · Русский (ru)
Для документации уровня экосистемы	Монгольский + шесть официальных языков ООН

Монгольский — исходный язык: оригинальный текст пишется по-монгольски и переводится наружу.

Шесть официальных языков ООН — это: العربية (ar) · 中文 (zh) · English (en) · Français (fr) · Русский (ru) · Español (es). Этот сайт (документация уровня экосистемы) выходит на монгольском плюс эти шесть — всего на семи языках.

Почему именно эти языки?

Читатели документации уровня экосистемы — не только внутренние разработчики: среди них международные партнёры, донорские организации, органы стандартизации и зарубежные интеграторы. Шесть языков ООН дают наибольший глобальный охват и являются нейтральным выбором, который не даёт преимущества ни одной стране.

Глубокая техническая документация конкретной платформы (схемы endpoint'ов, справочник SDK) под эту политику не подпадает — она остаётся MN + EN внутри своего репозитория.

i18n в продуктах

Приложения определяют язык пользователя в таком порядке:

1. Настройка пользователя (сохранённая в профиле),
2. Accept-Language браузера,
3. Язык по умолчанию (mn).

ИИ-помощник отвечает на языке пользователя — на том, на котором пришёл вопрос.

Два слоя словаря

Словарь находится в двух местах, и понимать границу между ними важно:

Словарь	Где	Размер
Общий — вход, меню, админка, eID	@gerege/ui-core	846 ключей × 7 языков
Платформенный — терминология конкретной предметной области	lib/<platform>I18n.ts	У каждой платформы свой, обычно 2–4 языка

Правило: общий словарь знает только общую поверхность. Лексика выписок и IBAN в кошельке, каталог API портала разработчика, терминология бизнес-процессов Ring — всё это лежит в собственном словаре приложения.

Причина — стоимость: если поместить 1,104 термина Ring в общий словарь, их понесут и kiosk, и POS, и кошелёк, причём с каждым добавленным языком эта стоимость вырастает семикратно.

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

Язык интерфейса ≠ язык содержимого

Расширение словаря с четырёх языков до семи сломало каждое место, где было написано Record<Lang, …>: маркетинговый текст landing-страницы, описания в каталоге API — их пишет человек, и они не масштабируются так, как интерфейс. В таких местах набор языков объявляется явно, например как LANDING_LANGS.

i18n в документации

Сайт документации каждого репозитория использует MkDocs Material + mkdocs-static-i18n.

Суффиксная схема

Перевод оформляется добавлением кода языка к имени файла:

docs/
├── index.md        ← Монгол (по умолчанию)
├── index.ar.md     ← العربية
├── index.zh.md     ← 中文
├── index.en.md     ← English
├── index.fr.md     ← Français
├── index.ru.md     ← Русский
└── index.es.md     ← Español

Конфигурация:

plugins:
  - i18n:
      docs_structure: suffix
      fallback_to_default: true
      reconfigure_material: true
      reconfigure_search: true
      languages:
        - locale: mn
          default: true
          name: Монгол
          build: true
        - locale: en
          name: English
          build: true
        - locale: ar
          name: العربية
          build: true
        # … zh · fr · ru · es аналогично

Язык по умолчанию собирается в корне сайта (/), остальные — по подпутям (/en/, /ar/, /zh/, /fr/, /ru/, /es/).

Fallback

fallback_to_default: true — непереведённая страница показывает содержимое на языке по умолчанию. Поэтому даже при неполном переводе сайт остаётся целым, и 404 не появляется.

Это практичное решение: документация постоянно растёт, а перевод отстаёт. Ждать, пока будут переведены сразу все страницы, равносильно тому, чтобы не публиковать документацию вовсе.

Перевод навигации

Названия пунктов меню лежат не в содержимом страниц, а в mkdocs.yml, поэтому переводятся отдельно для каждой локали:

        - locale: en
          nav_translations:
            Архитектур: Architecture
            Платформууд: Platforms
        - locale: ar
          nav_translations:
            Архитектур: البنية المعمارية
            Платформууд: المنصّات

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

Письмо справа налево (RTL)

العربية читается справа налево. Material распознаёт локаль ar, проставляет <html dir="rtl"> и сам разворачивает меню, заголовки и порядок в таблицах — отдельно указывать direction не нужно.

При этом блоки кода и ASCII-диаграммы и в RTL остаются слева направо. Так и должно быть: техническая запись (URL, команды, YAML) при смене направления теряет смысл.

Якоря для кириллических заголовков

Стандартный slugify выбрасывает кириллицу

Штатный slugify расширения toc в Python-Markdown удаляет не-ASCII символы. Из-за этого заголовок ## Танилт получает пустой id, и внутристраничная ссылка (#танилт) перестаёт работать.

Решение — slugify, сохраняющий unicode:

markdown_extensions:
  - toc:
      permalink: true
      slugify: !!python/object/apply:pymdownx.slugs.slugify {kwds: {case: lower}}

Этот сайт настроен так же.

Порядок перевода

При добавлении новой документации:

1. Напишите исходный текст по-монгольски — источник всегда монгольский.
2. Стабилизируйте монгольскую версию строгой сборкой (проверяются ссылки и якоря).
3. Затем переведите сразу на шесть языков. Перевод страницы по частям разводит языки между собой.

Доводите одну страницу до конца на всех языках

Работать лучше постранично, а не по языкам: когда один документ переводится на шесть языков одновременно, терминология, структура и строки таблиц остаются одинаковыми. При обратном подходе — «сначала все страницы по-английски» — языки, переведённые позже, будут догонять уже изменившийся исходный текст.

Что переводится, а что нет

Переводится	Остаётся как есть
Основной текст, заголовки, значения в таблицах	Доменные имена (sso.gerege.mn)
Пояснения, предупреждения, советы	Имена репозиториев (template-gerege-mn)
Поясняющие подписи внутри диаграмм	Код, YAML, команды, пути endpoint'ов
Заголовки таблиц	Названия продуктов (eID Mongolia, G-Sign)
Текст на бейджах статуса	Названия стандартов (OIDC, PKCE, RFC 3161)

Имена файлов и структура каталогов не переводятся никогда — это platforms/sso.ru.md, а не платформы/sso.md. Благодаря этому путь в URL при переключении языка не меняется, и глубокие ссылки продолжают работать.

Состояние этого сайта

Все страницы документации уровня экосистемы готовы на семи языках:

Локаль	Язык	Путь	Состояние
mn	Монгол (по умолчанию)	/	✅ полностью
ar	العربية	/ar/	✅ полностью
zh	中文	/zh/	✅ полностью
en	English	/en/	✅ полностью
fr	Français	/fr/	✅ полностью
ru	Русский	/ru/	✅ полностью
es	Español	/es/	✅ полностью

fallback_to_default остаётся включённым: когда добавляется новая страница, а перевод отстаёт, эта страница покажет монгольский оригинал, и сайт останется целым.

Если вы заметили ошибку или неудачную формулировку, пришлите PR в репозиторий — подробности на странице Платформа этой документации.