Руководство по локализации

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

Модель локалей

Локали релиза: en, ru, zh-CN, es, pt-BR, de и ja. Канонический английский Markdown остаётся в исходнике, указанном в docs/DOCS_MANIFEST.json; документы, закреплённые политикой в корне репозитория, сохраняют свои установленные пути. Каждый неанглийский документ находится по адресу docs/LOCALE/SLUG.md и содержит:

---
slug: overview
source: docs/OVERVIEW.md
source_sha256: sha256:EXACT_ENGLISH_SOURCE_HASH
---

Slugs, порядок манифеста и принадлежность к навигации едины для всех локалей. Не создавайте второй манифест или renderer Docs для отдельной локали.

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

1. Сначала обновите и примите канонический английский документ.
2. Переведите каждое утверждение и заголовок, не меняя код или идентификаторы.
3. Обновите source_sha256 по точным байтам канонического источника.
4. Запустите python3 scripts/validate_localizations.py.
5. Соберите сайт и проверьте затронутые маршруты при ширине desktop, tablet и mobile.

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

Добавление локали

Добавьте локаль один раз в website/lib/locales.ts, предоставьте её полные метаданные landing/UI, добавьте по одному переведённому документу для каждого slug манифеста, добавьте локализованный README и расширьте детерминированные проверки маршрутов/браузера. При смене языка сохраняйте тот же публичный slug.

Добавление будущей локали, такой как fr или ko, должно быть ограниченным изменением содержимого. Оно не должно требовать другого приложения, манифеста или архитектуры Docs.

Технический текст

Сохраняйте следующее без изменений, если канонический английский источник их не меняет:

• fenced code blocks и shell-команды;
• inline code identifiers;
• API-пути, ключи конфигурации, переменные окружения, коды причин, ID профилей/провайдеров, имена пакетов и пути к файлам;
• названия продуктов и провайдеров, такие как ThreadCells, Codex, Claude Code, Git, Git worktree и tmux;
• назначения Markdown-ссылок и пути к медиа.

Естественно переводите пояснения вокруг этих значений. Избегайте буквальных калек, из-за которых руководства для разработчиков сложнее читать.

Файлы README

README.md — канонический английский. Каждый локализованный README следует той же структуре разделов, ссылается на те же свидетельства и начинается с компактного селектора семи языков. Выделяйте текущий язык жирным и используйте repository-relative ссылки для остальных шести.

Визуальная приёмка

Переводы не обязаны иметь одинаковые разрывы строк или высоту разделов. Они должны сохранять иерархию, читаемую типографику, работающие CTA, медиа, таблицы, блоки кода, поведение header/footer и отсутствие горизонтального переполнения. Уделите особое внимание расширению текста на немецком, переносам в русском, навигации на испанском и португальском, а также разбиению строк на китайском/японском.

Семантическая проверка свободно владеющим языком читателем, ориентированным на разработчиков, остаётся обязательной. Успешные проверки Markdown, hash, маршрутов и браузера доказывают структурную актуальность, но не доказывают качество перевода.