Repository navigation
Localization
ctxray speaks English and Russian: every message, the help, the reports, and the installers. It picks the language of your system on its own, and you can override it per run or per project. The second half of this page is for contributors who want to add a language.
ctxray walks these sources in order, and the first one that names a language wins:
| # | Source | Example |
|---|---|---|
| 1 | --lang |
ctxray inspect --lang ru |
| 2 | CTXRAY_LANG |
CTXRAY_LANG=ru ctxray test |
| 3 |
lang in the config |
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 | the system locale, as the JavaScript runtime reports it | what macOS or Windows is set to |
| 8 | English | when nothing above names a language |
A few details decide what “names a language” means:
- ctxray reads only the language part:
ru_RU.UTF-8,ru-RU, andRUall meanru. -
C,POSIX, an empty value, andautoname nothing, so ctxray goes on to the next source. That makeslang: "auto"in a config hand the choice back to your system. - A language ctxray doesn't speak falls back to English, not to the next source.
--lang deon a machine withLANG=ru_RU.UTF-8gives English, because you asked for German and Russian wasn't it. When the unsupported language came from--lang,CTXRAY_LANG, or the config, ctxray warns that the language isn't supported yet. - The config's
langapplies to the commands that read a config.initandmcpdon't, so they follow the flag, the environment, and the system.
Harnesses that ctxray launches always get LANG=en_US.UTF-8, whatever language ctxray itself speaks. A capture then doesn't change with the machine it runs on.
The HTML report can carry several languages at once and switch between them. You pick them with --report-lang, CTXRAY_REPORT_LANG, or report.langs, and the CLI language is the default. The first one also sets the language of the texts in report.json, JUnit, Allure, and Markdown. Reporters and Reports has the details.
The install scripts speak your language too, and they choose it a little more simply:
-
install.shreadsCTXRAY_LANG, thenLC_ALL,LC_MESSAGES,LANG, skippingC,POSIX, andauto. -
install.ps1readsCTXRAY_LANG, then the Windows UI culture. - The
@mairwunnx/ctxraynpm package uses ctxray's own order without the flag and the config:CTXRAY_LANG, the POSIX variables, then the system locale.
A language is one catalog: a TypeScript file with every message ctxray shows. The type checker and one test make sure nothing is missing. Here's the path for a language with the code xx.
English is the source of truth: packages/ctxray/src/shared/i18n/locales/en/index.ts. Create a folder next to it and a catalog that holds the same keys:
// 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": "…",
// every key of the English catalog
};Catalog is derived from the English catalog. Every key is required, and a message must keep its kind: a plain string stays a string, a plural stays a plural. A missing key fails bun run check. Copying ru/index.ts and translating it line by line is the quickest start.
The keys are flat and grouped by area: command.* and option.* for the help, inspect.*, test.*, report.*, html.* for the HTML report, doctor.*, lint.*, and so on. Catalogs are exempt from the 200-line file limit.
A message holds {name} placeholders, and your translation must use the same set as the English one, in any order:
"doctor.git": "git {version}",ctxray formats the values for the language: numbers through Intl.NumberFormat (12,345 in English, 12 345 in Russian) and lists through Intl.ListFormat (“Cursor CLI and Cursor”, «Cursor CLI и Cursor»). So you never format a number or join a list by hand.
A message that depends on a number is an object with one template per plural category of your language, and other is always there. ctxray picks the form with new Intl.PluralRules(lang) from the count parameter:
// English: one and other
"count.rules": { one: "{count} rule", other: "{count} rules" },
// Russian: one, few, many, and other
"count.rules": { one: "{count} правило", few: "{count} правила", many: "{count} правил", other: "{count} правила" },Use exactly the categories Intl.PluralRules reports for your language, no more and no fewer. Check them in Bun:
bun -e 'console.log(new Intl.PluralRules("xx").resolvedOptions().pluralCategories)'Add the catalog to CATALOGS in 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 };That's all the code needs. --lang lists the new language in its help, --report-lang all puts it into HTML reports, and the npm package speaks it.
bun run check
bun test packages/ctxray/src/shared/i18ncatalogs.test.ts runs for every language in CATALOGS, so it covers yours with no edits. It checks three things the type checker can't:
- the catalog holds exactly the English keys
- every plural has exactly the categories
Intl.PluralRulesreports for the language - every message uses the same placeholders as English
Run a few commands with CTXRAY_DEBUG=1 ctxray --lang xx …. With it, every message missing from your catalog says so in English.
A few strings don't come from the catalog:
-
The config schema. The description of
langinpackages/ctxray/src/shared/contract/config.tslists the languages by hand: “CLI language:auto,en, orru”. Add yours, because editors show it in completion. -
packaging/install.sh. Itssayandfailtake one message per language, English then Russian, and pick by the language prefix. Add your text to every call and a branch tosay. -
packaging/install.ps1.Say($en, $ru)works the same way: add a parameter, a branch, and your text to every call. -
The npm launcher. Its messages are in the catalog under
npm.*, so step 1 already covered them.
MCP tool descriptions and the skills of the Claude Code Plugin stay in English on purpose: a model reads them, not a person. Contributing explains how to open the pull request.
Start
Use
Teams
Develop
По-русски
- Начало работы · Понятия · Loadout Stack · Режимы захвата
- Тесты · Конфигурация · Политики · Харнессы · Команды · Отчёты · Плагин Claude Code
- CI · Enterprise
- Архитектура · Локализация · Участие