0.4.11
Поиск по документации… ⌘K
11 · Техническая документация

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

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

1. Тип TuiLocale

В astracode-rs/config/src/types.rs (реэкспортируется в astracode-rs/tui/src/locale.rs):

rust
pub enum TuiLocale {
    En,
    Ru,
}

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

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

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

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

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

text
/locale ru
/locale en

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

Через config

toml
[tui]
locale = "ru"

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

Через CLI

bash
astracode --locale ru
ASTRACODE_LOCALE=ru astracode

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

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

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

Slash-команды

Реестр команд в крейте astracode-slash-commands хранит EN- и RU-описания для каждой команды (commands.rs, LocalizedText). TUI реэкспортит id как SlashCommand (tui/src/slash_command.rs):

rust
SlashCommandSpec {
    id: SlashCommandId::Compact,
    description: LocalizedText {
        en: "summarize conversation to prevent hitting the context limit",
        ru: "сжать разговор, чтобы не упереться в лимит контекста",
    },
    ...
}

Все popup'ы (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) - Заголовки страниц - Сообщения «команда не найдена»

Warning'и при загрузке скиллов

Когда 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:

text
Ambiguous `tui.keymap.composer.submit` bindings: 'enter' is used by both `submit` and `newline`.
Set unique keys in `~/.astracode/config.toml` and retry.

RU:

text
Конфликт привязок `tui.keymap.composer.submit`: 'enter' использован и для `submit`, и для `newline`.
Задайте уникальные клавиши в `~/.astracode/config.toml` и попробуйте снова.

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

Patch failure

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

Compact warning

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

Interrupted message

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:

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

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

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

bash
cargo insta accept --workspace

8. Файлы кода

  • Тип TuiLocale: astracode-rs/tui/src/locale.rs
  • Определение TuiLocale: astracode-rs/config/src/types.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
ESC