localization.md

Локализация документации

Язык: English · Русский

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

Структура репозитория

Английская документация остаётся по текущим каноническим путям:

README.md
CONTRIBUTING.md
SECURITY.md
docs/
  README.md
  getting-started.md
  ...

Локализованные корневые документы получают языковой суффикс, а дерево документации повторяет английскую структуру внутри docs/<locale>/:

README.ru.md
CONTRIBUTING.ru.md
SECURITY.ru.md

docs/
  localization.md
  ru/
    README.md
    getting-started.md
    connections.md
    providers/
      vastai.md
      intelion.md
    releases/
      v0.2.3.md
      v0.2.2.md
      v0.2.1.md
      v0.2.0.md
    ...

Для новых переводов используется locale-тег в стиле BCP 47: строчный код языка для общего перевода (ru, de, fr) и суффикс региона/письменности только тогда, когда различие действительно важно (pt-BR, zh-CN). Отдельное зеркало en/ не создаётся: существующие английские пути остаются каноническим источником и сохраняют стабильные публичные ссылки.

Канонический источник и статус перевода

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

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

Если английский текст и перевод расходятся, каноническими считаются английский документ и фактическое публичное поведение продукта; после этого перевод нужно привести в соответствие.

Правила перевода

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

• CLI-команды, имена опций, переменные окружения, имена пакетов, ID, поля JSON, коды ошибок и пути файловой системы;
• блоки кода и машинно-читаемые примеры, кроме поясняющих комментариев или текстовых строк, которые не являются частью контракта;
• текущие подписи TUI, которые пользователь должен найти на экране, пока само приложение не локализовано;
• имена провайдеров/продуктов и протокольные термины, если перевод сделает интерфейс неоднозначным.

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

Исторические материалы остаются историческими. Переводится именно утверждение, сделанное для конкретного релиза; старые release notes и аудиты нельзя незаметно переписывать в описание текущего состояния.

Ссылки между языками

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

Внутри локализованного дерева следует ссылаться на документ той же локали, если его перевод существует. Внешние URL остаются без изменений. Если отдельная специализированная/package-страница существует только на английском, ссылка на неё допустима, но для обычного пользователя основным маршрутом должно оставаться ближайшее локализованное руководство.

README пакетов и плагинов

README пакетов и плагинов — компактные поверхности npm/GitHub и остаются каноническими английскими файлами. Они могут напрямую вести на локализованную документацию проекта, провайдера или SDK.

Не следует добавлять отдельные локализованные README в публикуемые package-директории только ради зеркального соответствия каждому файлу репозитория. Это может изменить содержимое npm-архивов и создаёт ещё одну текстовую поверхность, которую придётся синхронизировать. Локализованные пользовательские, provider- и SDK-руководства должны жить в docs/<locale>/, если отдельное требование релиза не говорит, что перевод должен поставляться внутри самого пакета.

Как добавить новый язык

Чтобы добавить новую локаль:

1. Добавьте локализованные корневые документы, где они нужны: README.<locale>.md, CONTRIBUTING.<locale>.md и SECURITY.<locale>.md.
2. Создайте docs/<locale>/README.md и повторите актуальную структуру английского docs/ для страниц, входящих в эту локаль.
3. Добавьте язык в переключатель в корневом README и docs/README.md.
4. Не меняйте точные product/API-токены и переводите буквальные UI-подписи только после появления реальной локализации интерфейса.
5. Внутри перевода предпочитайте ссылки на документы той же локали.
6. Запустите проверку Markdown-ссылок/якорей и отдельно проверьте корректность shell-примеров на документируемой платформе.
7. Перед объявлением локали полной попросите свободно владеющего языком ревьюера сверить с английским оригиналом утверждения о безопасности, совместимости, провайдерах и автоматизации.

Русский (ru) — первая полная локаль, поддерживаемая по этой схеме.