Skip to content

Localization RU

Pavel Erokhin edited this page Nov 20, 2026 · 2 revisions

English version

ctxray говорит по-английски и по-русски: все сообщения, справка, отчёты и установщики. Язык системы он выбирает сам, а вы можете переопределить его для одного запуска или для всего проекта. Вторая половина страницы — для тех, кто хочет добавить язык.

Как ctxray выбирает язык

ctxray перебирает источники по порядку, и побеждает первый, который называет язык:

# Источник Пример
1 --lang ctxray inspect --lang ru
2 CTXRAY_LANG CTXRAY_LANG=ru ctxray test
3 lang в конфиге defineConfig({ lang: "ru" })
4 LC_ALL LC_ALL=ru_RU.UTF-8
5 LC_MESSAGES LC_MESSAGES=ru_RU.UTF-8
6 LANG LANG=en_US.UTF-8
7 локаль системы, как её видит среда JavaScript то, что выставлено в macOS или Windows
8 английский если выше язык не назван нигде

Что значит «называет язык», решают несколько деталей:

  • ctxray смотрит только на код языка: ru_RU.UTF-8, ru-RU и RU означают ru.
  • C, POSIX, пустое значение и auto ничего не называют, и ctxray идёт к следующему источнику. Поэтому lang: "auto" в конфиге возвращает выбор системе.
  • Язык, на котором ctxray не говорит, превращается в английский, а не в следующий источник. --lang de на машине с LANG=ru_RU.UTF-8 даст английский: вы просили немецкий, а не русский. Если неподдерживаемый язык пришёл из --lang, CTXRAY_LANG или конфига, ctxray предупредит, что такой язык пока не поддерживается.
  • lang из конфига действует на команды, которые читают конфиг. init и mcp его не читают, поэтому слушают флаг, окружение и систему.

ИИ-харнессы, которые запускает ctxray, всегда получают LANG=en_US.UTF-8, на каком бы языке ни говорил сам ctxray. Так capture не зависит от машины, на которой идёт.

Отчёты

HTML-отчёт может нести несколько языков сразу и переключаться между ними. Они задаются через --report-lang, CTXRAY_REPORT_LANG или report.langs, по умолчанию — язык CLI. Первый из них задаёт ещё и язык текстов в report.json, JUnit, Allure и Markdown. Подробности — на странице Reporters and Reports.

Установщики и npm-пакет

Установочные скрипты тоже говорят на вашем языке и выбирают его чуть проще:

  • install.sh смотрит на CTXRAY_LANG, затем на LC_ALL, LC_MESSAGES, LANG, пропуская C, POSIX и auto.
  • install.ps1 смотрит на CTXRAY_LANG, затем на язык интерфейса Windows.
  • npm-пакет @mairwunnx/ctxray следует порядку самого ctxray, только без флага и конфига: CTXRAY_LANG, переменные POSIX, затем локаль системы.

Как добавить язык

Язык — это один каталог: файл TypeScript со всеми сообщениями, которые показывает ctxray. Проверка типов и один тест следят, чтобы ничего не потерялось. Ниже путь для языка с кодом xx.

1. Напишите каталог

Источник истины — английский: packages/ctxray/src/shared/i18n/locales/en/index.ts. Создайте рядом папку и каталог с теми же ключами:

// packages/ctxray/src/shared/i18n/locales/xx/index.ts
import type { Catalog } from "#shared/i18n/catalog-type.ts";

export const xx: Catalog = {
  "count.tests": { one: "{count} …", other: "{count} …" },
  "status.passed": "…",
  // все ключи английского каталога
};

Тип Catalog выводится из английского каталога. Обязателен каждый ключ, и сообщение сохраняет свой вид: строка остаётся строкой, множественное число — множественным числом. Пропущенный ключ валит bun run check. Быстрее всего начать с копии ru/index.ts и переводить строку за строкой.

Ключи плоские и сгруппированы по областям: command.* и option.* для справки, inspect.*, test.*, report.*, html.* для HTML-отчёта, doctor.*, lint.* и так далее. На каталоги не распространяется ограничение в 200 строк на файл.

2. Подстановки

В сообщении есть подстановки {name}, и в переводе должен быть тот же их набор, что в английском, в любом порядке:

"doctor.git": "git {version}",

ctxray сам форматирует значения под язык: числа — через Intl.NumberFormat (12,345 по-английски, 12 345 по-русски), списки — через Intl.ListFormat (“Cursor CLI and Cursor”, «Cursor CLI и Cursor»). Так что вручную форматировать числа и склеивать списки не нужно.

3. Множественное число

Сообщение, которое зависит от числа, — это объект с шаблоном на каждую категорию множественного числа вашего языка, и other есть всегда. ctxray выбирает форму через new Intl.PluralRules(lang) по параметру count:

// английский: one и other
"count.rules": { one: "{count} rule", other: "{count} rules" },
// русский: one, few, many и other
"count.rules": { one: "{count} правило", few: "{count} правила", many: "{count} правил", other: "{count} правила" },

Используйте ровно те категории, которые Intl.PluralRules сообщает для вашего языка, не больше и не меньше. Проверить их можно в Bun:

bun -e 'console.log(new Intl.PluralRules("xx").resolvedOptions().pluralCategories)'

4. Зарегистрируйте каталог

Добавьте каталог в CATALOGS в packages/ctxray/src/shared/i18n/locales/index.ts:

import { en } from "./en/index.ts";
import { ru } from "./ru/index.ts";
import { xx } from "./xx/index.ts";

export const CATALOGS: Readonly<Record<string, Catalog>> = { en, ru, xx };

Больше в коде ничего не нужно. --lang покажет новый язык в справке, --report-lang all добавит его в HTML-отчёт, а npm-пакет заговорит на нём.

5. Запустите проверки

bun run check
bun test packages/ctxray/src/shared/i18n

catalogs.test.ts проходит по каждому языку в CATALOGS, так что ваш он проверит без правок. Он проверяет три вещи, которые не видит проверка типов:

  1. в каталоге ровно английские ключи
  2. у каждого множественного числа ровно те категории, что Intl.PluralRules сообщает для языка
  3. каждое сообщение использует те же подстановки, что английское

Запустите несколько команд с CTXRAY_DEBUG=1 ctxray --lang xx …. С этой переменной каждое сообщение, которого нет в вашем каталоге, сообщит об этом по-английски.

6. Обновите места вне каталога

Несколько строк берутся не из каталога:

  • Схема конфига. Описание lang в packages/ctxray/src/shared/contract/config.ts перечисляет языки вручную: «CLI language: auto, en, or ru». Добавьте свой — редакторы показывают это описание в подсказках.
  • packaging/install.sh. Его say и fail принимают по сообщению на язык, сначала английское, потом русское, и выбирают по началу кода языка. Добавьте свой текст в каждый вызов и ветку в say.
  • packaging/install.ps1. Say($en, $ru) устроена так же: добавьте параметр, ветку и свой текст в каждый вызов.
  • npm-лаунчер. Его сообщения лежат в каталоге под npm.*, так что шаг 1 их уже покрыл.

Описания MCP-инструментов и скиллы Claude Code Plugin намеренно остаются на английском: их читает модель, а не человек. Как открыть pull request, рассказано на странице Contributing.

Clone this wiki locally