11. Локализация

AstraCode полностью поддерживает русский и английский языки в TUI. Локализация пронизывает: описания slash-команд, всплывающие меню, оверлеи (/diff, /review, /help), предупреждения при загрузке скиллов, ошибки /keymap, сообщения «Conversation interrupted» / «Failed to apply patch» / «Heads up» при /compact и т.д.

1. Тип TuiLocale

В astracode-rs/tui/src/locale.rs:

pub enum TuiLocale {
    En,
    Ru,
}

Локаль пронизывает большинство call-chain'ов в TUI — функции принимают locale: TuiLocale и выбирают строки соответственно.

2. Установка локали

При первом запуске

Автодетект из переменных окружения (locale.rs): - ASTRACODE_LOCALE (явное значение) - POSIX-локаль в порядке LC_ALL → LC_MESSAGES → LANG (если значение содержит ru, RU, russian → TuiLocale::Ru) - Иначе → TuiLocale::En

Через команду

/locale ru
/locale en

⚠️ Важно: /locale доступна только до первого сообщения в новой сессии. После того как агент уже что-то делал, локаль фиксируется. Чтобы сменить — /new, потом /locale.

После /new или /clear смена локали снова доступна до первого сообщения в новой сессии. За это правило отвечает session_lifecycle.rs:locale_change_allowed.

Через config

[tui]
locale = "ru"

Применяется при следующем запуске.

Через CLI

astracode --locale ru
ASTRACODE_LOCALE=ru astracode

3. Приоритет источников

1. CLI флаг (--locale)
2. ASTRACODE_LOCALE env
3. [tui].locale в config.toml
4. Автодетект из POSIX-локали (LC_ALL → LC_MESSAGES → LANG)
5. Дефолт: en

4. Что локализовано

Slash-команды

В slash_command.rs каждая команда имеет EN- и RU-описания:

SlashCommand::Compact => match locale {
    TuiLocale::En => "summarize conversation to prevent hitting the context limit",
    TuiLocale::Ru => "сжать разговор, чтобы не упереться в лимит контекста",
},

Всплывающие меню

Все всплывающие окна (auto-complete, file picker, model picker, theme picker) показывают локализованные строки.

Оверлеи (/diff, /review, /help)

Pager-оверлеи имеют локализованные подсказки внизу: - EN: ↑↓ to scroll • PgUp/PgDn to page • g/G to jump • q to close - RU: ↑↓ прокрутить • PgUp/PgDn листать • g/G к началу/концу • q закрыть

Сделано в pager_overlay.rs:render_hints.

Help (/help)

Весь контент модуля help_text.rs имеет EN/RU варианты: - Обзорная страница - Per-command детали (USAGE / DETAILS / NOTES) - Заголовки страниц - Сообщения «команда не найдена»

Предупреждения при загрузке скиллов

Когда SKILL.md не парсится, вместо Skipped loading 1 skill(s) due to invalid SKILL.md files: invalid YAML: ... показывается:

Пропущена загрузка 1 скилла из-за некорректных файлов SKILL.md: некорректный YAML: ...

Реализация — app/startup_prompts.rs:emit_skill_load_warnings() + localize_skill_error_message().

Ошибки /keymap

Конфликты привязок локализуются через keymap_setup.rs:localize_keymap_conflict_error():

EN:

Ambiguous `tui.keymap.composer.submit` bindings: `submit` and `newline` use the same key. Set unique keys in `~/.astracode/config.toml` and retry. See the AstraCode keymap documentation for supported actions and examples.

RU:

Конфликт привязок `tui.keymap.composer.submit`: `submit` и `newline` используют одну и ту же клавишу. Задайте уникальные клавиши в `~/.astracode/config.toml` и повторите. См. документацию по сочетаниям клавиш AstraCode для поддерживаемых действий и примеров.

Идентификаторы (backtick-quoted ключи) сохраняются как есть — переводится только обрамляющий текст.

Ошибка применения патча

Failed to apply patch → Не удалось применить патч. Реализовано в history_cell.rs:new_patch_apply_failure_for_locale().

Предупреждение при сжатии

EN: ⚠ Heads up: Long threads and multiple compactions can degrade the model's responses… RU: ⚠ Внимание: длинные ветки и многократные сжатия могут ухудшить ответы модели…

Сообщение о прерывании

EN: ■ Conversation interrupted - tell the model what to do differently. RU: ■ Разговор прерван — скажите модели, что делать иначе.

Скиллы

См. 05-skills.md. Описания скиллов локализованы через short_description_ru / short-description-ru в frontmatter или interface.short_description_ru в agents/astracode.yaml.

5. Что НЕ локализовано

• Содержимое ответов модели — это контролирует пользователь (через инструкции системному промпту).
• Имена slash-команд — /cd, /help остаются английскими (это identifiers).
• Названия моделей и провайдеров — gpt-5, claude-sonnet-4-6.
• Имена tool'ов — local_shell, edit_file (видны в audit log).
• Файлы конфигурации — TOML, JSON-схемы.
• Логи — для удобства парсинга остаются на английском.

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

Сейчас поддерживаются только EN и RU. Чтобы добавить, например, ES:

1. Добавить вариант в TuiLocale: rust pub enum TuiLocale { En, Ru, Es }
2. Расширить все match locale { ... } блоки (их много — slash_command.rs, help_text.rs, pager_overlay.rs, keymap_setup.rs, app/event_dispatch.rs, chatwidget.rs, etc.).
3. Перевести скиллы — добавить short_description_es или сделать generic-поле short_descriptions: BTreeMap<String, String>.
4. Добавить в [tui].locale парсинг "es".
5. Обновить snapshot-тесты (есть .snap-файлы со строками TUI).

Будьте готовы к большому объёму работы — локализация прошла по сотням мест в коде.

7. Тестирование локализации

Snapshot-тесты используют insta:

cd astracode-rs
cargo insta test --workspace
cargo insta review   # просмотр изменений снапшотов

Снапшоты лежат в tui/src/**/snapshots/*.snap.

При смене локали в коде обновлять снапшоты:

cargo insta accept --workspace

8. Файлы кода

• Тип TuiLocale: astracode-rs/tui/src/locale.rs
• Slash-команды: astracode-rs/tui/src/slash_command.rs
• Help: astracode-rs/tui/src/help_text.rs
• Pager hints: astracode-rs/tui/src/pager_overlay.rs
• Skills loading errors: astracode-rs/tui/src/app/startup_prompts.rs
• Keymap errors: astracode-rs/tui/src/keymap_setup.rs
• Patch failure: astracode-rs/tui/src/history_cell.rs
• Compact warning: astracode-rs/tui/src/chatwidget.rs (localize_warning_ru)
• Skill description helper: astracode-rs/tui/src/skills_helpers.rs
• Session lifecycle (/locale после /new//clear): astracode-rs/tui/src/app/session_lifecycle.rs