Перевод

Как языковые версии отражают друг друга, что показывает сайт без перевода и как сохранить каждый язык полным

Зеркальные пути

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

en/docs/2_editor/4_craft/3_difficulty-curve.md
ru/docs/2_editor/4_craft/3_difficulty-curve.md

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

Что не меняется:

• имя файла и все имена папок, вместе с префиксами
• date и tags во frontmatter (title переводится)
• вики-ссылки [[wiki-links]]: их цели - имена файлов, одинаковые во всех языках
• внешние ссылки, имена изображений, блоки кода и код в строке: файлы, поля, клавиши, значения, команды
• структура: те же заголовки в том же порядке, те же списки, таблицы и выноски

Заголовки выносок переводятся на язык страницы. Подробнее - Руководство по стилю

Английский - запасной язык

Когда страницы нет на каком-то языке, сайт показывает английскую страницу с пометкой. Наоборот это не работает: страница, которая есть только в ru/, даёт англоязычному читателю 404

Каждый язык несёт каждый факт

Английский главный только для адресов, но не для содержания. Факт может появиться сначала на любом языке, и потом он переносится во все остальные. После правки каждая версия содержит всё, что знают все версии

• Добавлять, никогда не удалять. Недостающая информация дописывается в каждый язык, где её нет
• Противоречия не решаются угадыванием. Две версии дают разные числа или противоположные утверждения? Проверьте источник (игру, SDK) и поднимите вопрос в pull request
• Ничего не удаляется без вопроса, даже текст, который выглядит устаревшим

Разница в формулировках - не проблема. Разница в том, что узнаёт читатель, - проблема

Сравнение версий

В репозитории есть скилл для Claude Code, compare-translations (в .claude/skills/). Он выполняет это сравнение. Без него пройдите те же два прохода вручную

Структурный проход сравнивает версии поэлементно: frontmatter, H1, первый абзац, заголовки, число абзацев, пункты списков, строки таблиц и выноски, цели ссылок, изображения, код

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

Новый язык

Новый язык добавляется целиком в этом репозитории, код сайта не меняется:

1. Скопируйте frontend/en.yaml в frontend/<код>.yaml, например frontend/de.yaml, и переведите значения. Это строки самого сайта: меню, кнопки, поиск, баннер cookie. Ключи и каждое {имя} оставьте как есть
2. Создайте папку <код>/ рядом с en/ и ru/ и переводите в неё страницы. Страница без перевода показывается на английском с пометкой

Ключ с формами one / few / many / other зависит от числа. Дайте ему все формы, которые нужны вашему языку, сборка назовёт недостающие. Непереведённый ключ показывается на английском. Сборка перечисляет такие ключи как предупреждения

Перед большим переводом откройте issue в bullet-hero/docs, чтобы двое не переводили одно и то же