Languages

itda speaks twelve languages where a person reads it: the lines itda setup and its friends print, the landing page and the README. English is the source. Korean was edited by hand and is kept as it is. The other ten are translated from English with the glossary below.

What is translated, and what is not

What a person reads. Everything an agent acts on stays English, on purpose, so that a definition, an error or a tool behaves the same in every conversation. Translated:

• the lines the CLI prints during itda setup, itda login, itda refresh, itda fsck and the first bare itda, all through apps/cli/src/text.rs;
• what itda describe <site> and itda ls --json say a person can do with a site (user_guide) and the example prompts (natural_prompts), from one table of phrases in crates/prep/src/guide.rs; itda_sites gives them to agents in English;
• the action descriptions itda setup and itda draft write, from one table of phrases in crates/prep/src/label.rs (List what {title} shows, Search on {title}). The language is the one the person set, else the page’s own <html lang>, else English. The site’s own words (titles, field and operation names) stay as the site wrote them, and so does the kind of record (news articles) outside Korean. Agents read every one of these languages, so a description in Japanese works as well as one in English; what an agent acts on (tool names, error codes, remedies) stays English;
• the landing page and its title and description;
• the README.

Not translated:

• MCP tool descriptions, error codes and their remedy lines, the keys of the JSON envelope. Agents read them.
• Site definitions apart from the drafted desc: the ready-made ones and the reviewed ones in examples/ are English originals, and nothing translates a definition once it is written.
• The handbook under docs/ (this file included). docs/SPEC.md alone is 41 KB and changes with every minor release; a translation would be wrong within weeks. The README carries what a newcomer needs in every language.
• og:title and og:description on the landing page. Crawlers do not run scripts, so they see English.

How the language is chosen

The CLI reads ITDA_LANG, then the system LANG, and takes the first language it supports. The tag may be BCP 47 (ja, zh-TW, pt-BR) or a POSIX locale (ja_JP.UTF-8, zh_TW.Big5, C). Encoding and modifier are dropped, _ reads as -, case does not matter. Then:

ITDA_LANG=ja itda speaks Japanese whatever the system says. A key that a language file lacks falls back to English.

The landing page picks ?lang= from the address, then the last choice on that device (localStorage), then the first entry of navigator.languages that maps to a language above, with the same rules. The picker in the header changes it and remembers it. <html lang>, the title and the description change with it.

Glossary

Each language uses these words for these things, in the CLI, on the landing page and in the README alike. A translation that needs another word for one of them changes this table in the same pull request.

Product and command names stay as they are: itda, Claude Desktop, Claude Code, Cursor, VS Code, Codex, GitHub, MCP, and every itda ... command, flag, exit code, verdict (ok, signed_out, site_changed, blocked, unreachable) and error code.

Rules for a translation

• A {field} in a CLI string is filled in by the code. Every translation keeps the same set of fields as English, in whatever order its grammar wants. A test checks that.
• A landing string keeps every HTML tag and attribute, every <code> and link exactly. Only the words change.
• Numbers, commands, code blocks, file names, addresses and the console transcript’s prompt line are not translated.
• The example hosts (the-site-you-use.example, intranet.example) stay exactly as they are in every language. They are reserved example domains inside commands people copy, not prose. The transcript’s output lines are what the binary prints in that language: they come from the CLI strings.
• The README keeps the English section order, the same headings count, the same links and the same images. Its first lines carry the same language line as every other README, with its own language in bold.
• Plain words, in the voice of the English text. No slogans.

Add a language

1. Copy apps/cli/text/en.json to apps/cli/text/<tag>.json and translate the values. Add the tag to LANGUAGES in crates/types/src/lang.rs, to SUPPORTED in apps/cli/src/text.rs and the file to the include_str! list next to it, and to LANGS in apps/cli/tests/i18n.rs. Add a column to TEMPLATES in crates/prep/src/label.rs and in crates/prep/src/guide.rs. cargo test -p itda-cli and cargo test -p itda-prep check the keys and fields.
2. Copy site/i18n/ko.js to site/i18n/<tag>.js, change the tag in window.ITDA_I18N["<tag>"] and translate the values. Add the tag and its name in its own language to the <select data-lang-switch> in site/index.html and to LANGS in site/main.js. Drop flow.src unless the diagram was redrawn in that language (python3 assets/src/flow.py).
3. Translate README.md to README.<tag>.md and add the language to the language line of every README.
4. Add the row to the tables above and a line to CHANGELOG.md.

Checks

• cargo test -p itda-cli text:: : every language has every key of en.json and no other; every key has the same {fields} in every language; locale tags resolve as the table says; the strings and the description phrases cover the same languages.
• cargo test -p itda-prep label:: and guide:: : every description, guide and prompt phrase exists in every language, with the same {fields} as English.
• cargo test -p itda-cli --test i18n : every site/i18n/<tag>.js has the keys of index.html and the same HTML tags and links per key, and links to a heading its README has; every README has the headings, code blocks and links of README.md and the same language line; the picker lists every language.
• A pull request that changes README.md, site/index.html or apps/cli/text/en.json changes the eleven other languages in the same pull request, or says in its description what it leaves for later.