Локализация
Документация следует тем же локалям, что и LadVen OS: ru, en, de, zh, es, fr, kk, ky.
Правила
- новая страница добавляется во все локали в одном изменении;
- структура разделов и адреса страниц остаются одинаковыми;
- термины интерфейса сверяются с переводами LadVen OS;
- русская версия может быть исходной, но остальные языки не должны молча отставать;
- непроверенный перевод помечается как черновик в тексте страницы.
- языковые протечки проверяются автоматически через
npm run check:locale-leaks; новые страницы не должны обходить этот guard. - локализованные SVG-ассеты должны добавляться во все языки сразу; это проверяет
npm run check:localized-assets.
Что переводим вместе со страницей
Для каждой статьи переводится не только основной текст, но и весь пользовательский контекст вокруг него:
- заголовок,
description, подписи таблиц и callout-блоки; - названия действий и состояний, если они видны пользователю в интерфейсе;
- хорошие практики, антипримеры и управленческие проверки;
- alt-тексты и подписи к скриншотам, когда они добавлены в Markdown;
- ссылки на соседние статьи, если текст ссылки пользовательский.
Не переводятся технические идентификаторы: пути страниц, id скриншотов, имена файлов, route-примеры, значения в кодовых блоках и системные ключи frontmatter. Название продукта всегда пишется как LadVen OS.
Автоматическая защита от языковых протечек
npm run check включает отдельный guard check:locale-leaks. Он проверяет Markdown-страницы и пользовательские message-значения в JSON-переводах, но не трогает служебные ключи и description, где Docusaurus хранит исходные русские подписи.
Сейчас guard закрывает три практических риска:
- кириллица в
en,de,es,fr,zh; - казахские буквы и типовые казахские формулировки в
ky; - кыргызские формулировки в
kk.
Если появляется новое устойчивое смешение языков, его нужно добавлять в scripts/check-locale-leaks.mjs, а не полагаться только на ручную вычитку.
Для схем и других SVG действует отдельное правило паритета: если файл появился в static/img/<locale>/..., то одноименный SVG должен существовать во всех локалях документации. Это проверяет check:localized-assets. Сами PNG-скриншоты живут по screenshot-manifest.json, потому что у них возможны состояния ready, planned и blocked.
Термины модуля задач
Переводы должны звучать естественно для языка, но сохранять одинаковую управленческую модель: задача фиксирует результат, ответственного, срок, контекст, материалы, чек-лист, обсуждение и приемку.
| RU | EN | DE | ES | FR | ZH | KK | KY |
|---|---|---|---|---|---|---|---|
| Задача | Task | Aufgabe | Tarea | Tache | 任务 | Тапсырма | Тапшырма |
| Постановщик | Creator | Ersteller | Creador | Createur | 创建人 | Қоюшы | Тапшырма берген |
| Ответственный | Assignee | Verantwortliche/r | Responsable | Responsable | 负责人 | Жауапты | Жооптуу |
| Соисполнители | Co-executors | Mitausfuhrende | Coejecutores | Co-executants | 协作执行人 | Бірлескен орындаушылар | Биргелешкен аткаруучулар |
| Наблюдатели | Observers | Beobachter | Observadores | Observateurs | 观察者 | Бақылаушылар | Байкоочулар |
| Чек-лист | Checklist | Checkliste | Lista de verificacion | Liste de controle | 检查清单 | Чек-лист | Чек-лист |
| Карточка задачи | Task card | Aufgabenkarte | Tarjeta de tarea | Fiche de tache | 任务卡片 | Тапсырма карточкасы | Тапшырма карточкасы |
| Task Drawer | Task drawer | Aufgabenbereich / Task Drawer | Panel de tarea / Task Drawer | Panneau de tache / Task Drawer | 任务抽屉 / Task Drawer | Тапсырма панелі / Task Drawer | Тапшырма панели / Task Drawer |
| Приемка | Acceptance | Abnahme | Aceptacion | Validation | 验收 | Қабылдау | Кабыл алуу |
| Просрочка | Overdue | Uberfallig | Vencida | En retard | 逾期 | Мерзімі өткен | Мөөнөтү өткөн |
| Регулярная задача | Recurring task | Wiederkehrende Aufgabe | Tarea recurrente | Tache recurrente | 周期任务 | Қайталанатын тапсырма | Кайталануучу тапшырма |
| Защитная проверка | Guard check | Schutzprufung | Verificacion de proteccion | Controle de protection | 保护性检查 | Қорғаныс тексеруі | Коргоочу текшерүү |
Если в UI LadVen OS для конкретного языка используется другое слово, приоритет у UI. В таком случае нужно обновить таблицу и соответствующие статьи одним изменением.
Скриншоты и языки
Скриншоты постепенно должны появиться для всех локалей, но русские PNG не публикуются на страницах других языков. Если интерфейс на другом языке еще не снят, в переводе лучше временно оставить текст, SVG-схему или запись в плане скриншотов, чем показывать пользователю русскоязычный UI.
При этом:
- id скриншота должен быть одинаковым во всех локалях;
- путь к изображению должен оставаться стабильным и проходить проверку manifest parity;
- подпись под скриншотом переводится вместе со страницей;
- в
docs/admin/screenshots.mdфиксируется, какие языковые версии уже сняты, а какие остаются backlog; - для пользовательских сценариев сначала снимаем desktop light, затем desktop dark, затем mobile.
check:locale-leaks блокирует ссылки /img/ru/ и static/img/ru/ внутри i18n. Это намеренное правило: локализованная статья не должна показывать скриншот на другом языке.
check:image-locale-refs дополняет это правило шире: опубликованная Markdown-картинка на странице языка должна ссылаться на ассет этого же языка. Для русской документации разрешены /img/ru/..., для английской - /img/en/..., для немецкой - /img/de/... и так далее. Если нужен нейтральный общий ассет, его лучше хранить вне локализованных папок или явно добавить в правила проверки отдельным изменением.
Для задач минимальный набор первой волны: создание задачи, карточка задачи, чек-лист, файлы, комментарии, список задач, закрытие задачи и автоматизация. Остальные состояния снимаются второй волной: ошибки прав, частичный bulk-результат, мобильные фильтры, Kanban, расписание, guard editor и история запусков.
Критерий готовности перевода
Страница считается готовой к первой волне перевода, если она:
- объясняет пользовательский или управленческий сценарий, а не внутреннюю реализацию;
- описывает все видимые блоки окна или явно фиксирует backlog;
- содержит порядок действий, хорошие практики и проверку результата;
- учитывает ошибки, ограничения или права доступа там, где они влияют на работу;
- имеет хотя бы базовый скриншот или запись в плане скриншотов;
- не содержит ссылок на несуществующие страницы.
URL языков
Первая версия использует пути: /, /en/, /de/, /zh/, /es/, /fr/, /kk/, /ky/.
Поддомены можно добавить позже на уровне CDN, сохранив одну статическую сборку.