Интернационализация (i18n)

Как сайт документации Apothem объявляет свою группу локалей, выдаёт ссылки hreflang на альтернативные языки, обрабатывает рендеринг справа налево и честно показывает пробел в переводе.

Эта страница описывает, как сайт документации Apothem обрабатывает несколько языков: группу локалей, которую он объявляет, механизм hreflang, который он выдаёт, его готовность к письму справа налево и честное состояние перевода по локалям.

Сводка решений

Платформа: Next.js App Router + Fumadocs. Сайт собирается из site/. Группа локалей объявлена в site/lib/i18n.ts, а механизм ссылок на альтернативные языки находится в site/lib/hreflang.ts.
Группа локалей: объявлена. Группа Modern Dev из двенадцати локалей объявлена как канонический источник истины, с английским в качестве исходной локали.
Маршрутизация по локалям: ещё не включена. Включение маршрутов с префиксами локалей по всей группе при наличии контента только на английском создало бы одиннадцать маршрутов без контента, которые молча откатываются на английский источник. Это тот вид молчаливого дрейфа «только-английский», который запрещает дисциплина i18n, поэтому маршрутизация остаётся одноязычной, пока не появится проверенный переведённый контент.
Механизм hreflang: активен. Каждая страница выдаёт набор <link rel="alternate">, покрывающий каждую локаль с авторским контентом, плюс откат x-default. Локали, всё ещё ожидающие перевода, опускаются — никогда не указывают на английский откат — так что поисковым системам точно сообщается, что перевода не существует.
Готовность к письму справа налево: реализована. Общие таблицы стилей повсюду используют логические свойства CSS, поэтому арабские страницы рендерятся корректно под dir="rtl", как только появится арабский контент.
Политика машинного перевода: непроверенное не публикуется. Прозаический текст страниц с машинным переводом не публикуется. Перевод засевается машиной и пропускается через проверку человеком, прежде чем какая-либо локаль помечается как переведённая.

Группа локалей

Группа Modern Dev объявляет двенадцать локалей. Английский обслуживается в корне сайта; одиннадцать целевых локалей объявлены, чтобы стек был готов к интернационализации, а пробел в переводе был явным, а не молчаливым.

Код	Путь	Язык	Направление	Контент
`en`	`/`	Английский	LTR	Переведено (источник)
`zh-CN`	`/zh-cn/`	Упрощённый китайский	LTR	Ожидается
`es`	`/es/`	Испанский	LTR	Ожидается
`pt-BR`	`/pt-br/`	Бразильский португальский	LTR	Ожидается
`fr`	`/fr/`	Французский	LTR	Ожидается
`de`	`/de/`	Немецкий	LTR	Ожидается
`ja`	`/ja/`	Японский	LTR	Ожидается
`ko`	`/ko/`	Корейский	LTR	Ожидается
`ru`	`/ru/`	Русский	LTR	Ожидается
`id`	`/id/`	Индонезийский	LTR	Ожидается
`ar`	`/ar/`	Арабский	RTL	Ожидается
`hi`	`/hi/`	Хинди	LTR	Ожидается

Группа является единым источником истины; поправки к ней проходят через осознанное решение, а не через молчаливое редактирование.

Как работает `hreflang`

site/lib/hreflang.ts строит карту alternates.languages, которую Next.js рендерит в <head> каждой страницы. Её построение соблюдает одно правило: ссылка на альтернативный язык для локали выдаётся только тогда, когда у этой локали есть авторский контент. Поскольку английский — единственная переведённая локаль на сегодня, каждая страница выдаёт ровно две ссылки:

<link rel="alternate" hreflang="en" href="https://apothem.ahmedgad.com/..." />
<link rel="alternate" hreflang="x-default" href="https://apothem.ahmedgad.com/..." />

Ссылка canonical страницы всегда указывает на её собственный URL — она никогда не указывает между локалями. По мере появления контента локали и переключения её статуса на переведённый в site/lib/i18n.ts ссылка hreflang этой локали начинает выдаваться автоматически, а маршрутизация по локалям включается в том же наборе изменений.

Рендеринг справа налево

Арабский — локаль группы с письмом справа налево. Сайт готов к нему:

Только логические свойства CSS. Общие таблицы стилей и компоненты используют логические свойства (margin-inline-start, padding-inline-end, text-align: start, inset-inline-start), а не физические (margin-left, text-align: left). Логические свойства автоматически переворачиваются под dir="rtl", поэтому одна и та же таблица стилей корректно обслуживает оба направления.
Атрибут направления. Арабские страницы устанавливают dir="rtl" на элементе <html> вместе с lang="ar", как только появится арабский контент.
Двунаправленный контент. Строки со смешанным направлением — например, английская команда внутри арабского абзаца — оборачиваются в <bdi>, чтобы встроенный фрагмент слева направо рендерился корректно внутри потока справа налево.

Добавление перевода

Чтобы перевести сайт на локаль группы:

Создайте проверенные переведённые страницы для этой локали.
Переключите статус контента локали на переведённый в site/lib/i18n.ts.
Её ссылка hreflang начинает выдаваться, а её маршруты становятся достижимыми.

Сохраняйте английскую страницу в качестве источника истины, пока перевод локали не создан и не проверен. Никакой машинно-переведённый контент не публикуется без проверки.

Текущее состояние и путь к переведённому корпусу

Сегодня сайт готов к интернационализации, но контент только на английском. Инфраструктура — объявление группы, механизм hreflang, готовность к письму справа налево на логическом CSS — на месте; переведённого корпуса по локалям нет. Полностью переведённый корпус — это работа уровня функциональности: страницы каждой локали засеваются машиной, а затем проверяются человеком, и выпуск готов к продакшену по интернационализации только тогда, когда каждая локаль проходит свой порог проверки. До тех пор группа объявлена, пробел виден, и непроверенный перевод не публикуется.