Локализация под вашу команду

Ваша команда работает по-русски, по-немецки, по-французски — на любом языке, кроме английского. DWE поставляется с английской базой для собственного интерфейса, но каждую написанную вами пользовательскую команду (dwe db.seed, dwe build.docker, …) и каждый заголовок секции в сгенерированной документации можно перевести на уровне проекта, рядом с английским оригиналом.

Это руководство рассказывает, где хранятся переводы, что переводится, а что остаётся английским, разбирает рабочий пример и показывает, как переключать локаль без правки файлов. Полный справочник ключей — в i18n reference.

Разделы

• Разрешение локали
• Раскладка файлов
• Что переводится
• Что НЕ переводится
• Рабочий пример
• Валидация
• Переключение per-invocation

Разрешение локали

DWE выбирает активную локаль из пяти источников, по убыванию приоритета:

1. Флаг --lang у любой подкоманды dwe docs (show, list, search, export, generate, llms-txt). Действует на один вызов, никогда не сохраняется.
2. Переменная окружения DWE_LANGUAGE. Перекрывает поле language из userconfig для одного шелла или одной команды.
3. Поле language в userconfig (~/.config/dwe/config или .dwe/config). Задайте его один раз для каждого разработчика, чтобы зафиксировать предпочтительную локаль.
4. Системная $LANG — разбирается в 2-буквенный код (ru_RU.UTF-8 → ru). C и POSIX игнорируются, и цепочка продолжается дальше.
5. По умолчанию: en.

Коды вида ru-RU, ru_RU или ru_RU.UTF-8 на каждом уровне нормализуются до ru. Пустые значения пропускаются.

На практике большинство разработчиков один раз прописывают language: ru (или любой нужный код) в userconfig и больше об этом не думают. DWE_LANGUAGE и --lang — это запасные варианты для разовых переопределений.

Раскладка файлов

Переводы — это YAML-файлы уровня проекта в каталоге workspace/i18n/. Глобального или пользовательского каталога переводов нет — каждый проект поставляет свои.

workspace/
  i18n/
    ru.yml
    de.yml
    fr.yml

Имя файла — 2-буквенный код языка. Отсутствующий каталог workspace/i18n/ молча трактуется как «только английский» — ни ошибки, ни предупреждения.

Файлы переводов используют строгий YAML-декод: неизвестный ключ (например, descripton: вместо description:) не загрузится, и dwe validate выдаст понятную ошибку. Опечатки не проскальзывают молча.

Что переводится

YAML-хранилище переводов содержит три группы строк:

Семейство ключей	Что покрывает
commands.<id>.description	однострочное описание, показываемое в dwe commands list и dwe <id> --help
commands.<id>.confirmation_text	запрос перед запуском деструктивной команды (при confirmation: true)
commands.<id>.messages.success / .error	строки, печатаемые при успехе/провале, когда у команды задан messages:
commands.<id>.params.<name>.description	текст справки для каждого объявленного параметра
commands.<id>.params.<name>.options.<value>	подписи отдельных значений для enum-параметров (например, prod: "Production")
groups.<id>.title / .description	заголовок группы команд и её описание в TUI-браузере
ui.docs.section.* / ui.docs.property.*	заголовки секций и подписи свойств, выдаваемые dwe docs generate и таблицами свойств в dwe commands <id>

ID команды в commands.<id> — та же точечная форма, что вы набираете в шелле: workspace/commands/db/seed.yml → commands.db.seed. ID групп следуют той же конвенции на основе путей.

Все поля необязательны. Опустите любой ключ — и DWE возьмёт английское значение из YAML-источника команды (или встроенную английскую базу для ui.*). Частичные переводы — это нормально: переведённые и непереведённые строки сосуществуют в одном выводе без предупреждений.

Что НЕ переводится

За пределами YAML-хранилища остаётся:

• Собственные Cobra-команды DWE. dwe deploy --help, dwe run --help, dwe docs --help и любая другая встроенная команда остаются английскими независимо от локали. Хранилище переводов покрывает только пользовательские команды проекта.
• Сообщения об ошибках во время выполнения и логи. Они машиночитаемы и всегда на английском, чтобы их можно было грепать и вставлять в баг-трекеры без сюрпризов.
• Длинная справочная документация в docs/reference/ и docs/internals/. Она переводится через отдельное markdown-пространство имён по адресам docs/i18n/<lang>/reference/... и docs/i18n/<lang>/internals/.... Другой загрузчик, другой валидатор, другой формат файлов — эти два пространства имён не сливаются. См. i18n reference — long-form documentation translations.

Разделение этих областей позволяет каждой развиваться независимо: можно выкатить команде русские переводы для ваших команд dwe db.seed, не дожидаясь полного перевода справочника.

Рабочий пример

Английский источник — канонический YAML команды:

workspace/commands/db/seed.yml

- id: db.seed
  description: "Seed the database with fixture data"
  confirmation: true
  confirmation_text: "Wipe and re-seed the database?"
  messages:
    success: "Database seeded"
    error: "Seeding failed"
  params:
    - name: env
      description: "Target environment"
      options:
        - dev
        - staging
  type: service_exec
  service: db
  cmd: "/usr/local/bin/seed --env ${env}"

Русский перевод — та же форма под commands.db.seed:

workspace/i18n/ru.yml

ui:
  docs.section.parameters: "Параметры"
  docs.section.command: "Команда"
  docs.property.workdir: "Рабочая директория"

commands:
  db.seed:
    description: "Заполнить базу тестовыми данными"
    confirmation_text: "Очистить и заново заполнить базу?"
    messages:
      success: "База заполнена"
      error: "Не удалось заполнить базу"
    params:
      env:
        description: "Целевое окружение"
        options:
          dev: "Разработка"
          staging: "Стейджинг"

groups:
  db:
    title: "База данных"
    description: "Команды управления базой данных"

Три вещи, на которые стоит обратить внимание:

• YAML-источник команды остаётся на 100% английским. Авторы и переводчики работают с разными файлами и никогда не пересекаются.
• confirmation_text переводится, но сам флаг confirmation: true остаётся в источнике — переводы несут строки, а не поведение.
• Блок ui: необязателен. Если его пропустить, сгенерированная документация использует английские заголовки секций — частичное покрытие допустимо.

После сохранения ru.yml запустите:

DWE_LANGUAGE=ru dwe commands list   # → "Заполнить базу тестовыми данными"
DWE_LANGUAGE=ru dwe db.seed --help  # → переведённое описание + params

Валидация

dwe validate проверяет каждый файл в workspace/i18n/. Три класса находок:

Находка	Severity	Что означает
ошибка парсинга	error	строгий декод поймал неизвестное поле или ошибку синтаксиса YAML — исправьте файл
осиротевшая запись	warning	commands.<id> ссылается на команду, которой больше нет в workspace/commands/ — переименуйте или удалите запись
неизвестный UI-ключ	warning	ключ ui.*, которого нет в каноническом списке разрешённых — заведите issue, если нужен новый

Предупреждения по умолчанию носят справочный характер. Чтобы они блокировали CI:

dwe validate --strict

Чтобы ограничиться только доменом i18n:

dwe validate translations

Валидация выполняется рано (на этапе preflight), так что битый файл переводов не всплывёт где-то в середине деплоя.

Переключение per-invocation

Для быстрого переключения локали без правки конфига:

# Одна команда по-русски
DWE_LANGUAGE=ru dwe commands list

# Целая сессия шелла по-немецки
export DWE_LANGUAGE=de
dwe commands list      # немецкий
dwe db.seed --help     # немецкий

# Явный --lang на docs-подкоманде всегда побеждает
DWE_LANGUAGE=de dwe docs show config/services/fields --lang ru
# → рендерит русский перевод независимо от DWE_LANGUAGE

DWE_LANGUAGE стоит выше поля language из userconfig и ниже флага --lang. Такой порядок позволяет разработчику зафиксировать значение по умолчанию в userconfig, переопределить его для одного терминала через переменную окружения и всё равно получить явный --lang ru для разового обращения к документации.

См. также

• i18n reference — каждый ключ в YAML-хранилище, правила валидации, переводы длинной markdown-документации
• userconfig reference — задать language: для каждого разработчика
• author-project-commands — написать английский источник команды, на который указывают переводы
• brand-your-project — кастомизация шапки дашборда (отдельно от перевода текста)