Translate Like a Pro | 8580 — UnJS citty CLI Localization, defineCommand, Nested Subcommands, Usage Rendering and QA

UnJS citty makes command definitions compact, but that compactness can blur an important line: meta descriptions and argument explanations are for people, while argument names, subcommand selectors and execution paths are identifiers. This practical UnJS citty localization guide explains how to translate command-line help, configuration guidance and error recovery without altering the program’s grammar. It focuses on real search needs: making UnJS citty help understandable, avoiding translated flags that fail, and checking multilingual command-line releases systematically.

A team in Indonesia runs an inventory summary, another in Spain reads command help, and a scheduled process in Singapore calls the same nested command with numeric inputs. All users need the same operation, even when they read different words. The recurring problem is the boundary between what a person should understand and what software must recognize. A translation may look elegant while copying its examples produces a rejected option, a wrong path or an unintended side effect. We will use HarborLedger, a fictional tool used by port volunteers to prepare daily inventory reports as a fictional, concrete teaching case and keep every implementation decision tied to a test.

You will learn how defineCommand(), meta name/version/description, args definitions, runMain(), runCommand(), parseArgs(), renderUsage(), showUsage() and optional lazy subcommands affect localization, which texts may safely vary, how to review error paths, what to test in multilingual terminals and how to prepare a release that remains compatible with automation. The guide has a quick answer, a carefully separated code example, progressive technical chapters, diagnostic investigations, a language and platform test plan, frequently asked questions and practical next steps. Its scope is UnJS citty, not general language theory or unrelated translation software.

Quick answer: translate the explanation without silently changing the command

Treat every copyable command as a test case rather than as prose.
Write for a reader who has never learned the original English help text.
Protect parser identifiers, flag spellings, subcommand tokens and returned data keys.
Translate descriptions, warnings, prompts and recovery guidance when the application controls them.
Use genuine samples that readers can execute in a safe test folder.
Test a successful path, help, an invalid invocation and Unicode filenames.
Measure terminal formatting at narrow widths and check screen-reader readability.
Document the installed package version and release limitations.

For HarborLedger, a fictional tool used by port volunteers to prepare daily inventory reports, a useful early test is not whether every sentence is fluent. Ask a reader to choose an operation, predict what files it will affect, copy the published command, and explain what the result means. Compare that observed behavior with an English-language control run of the same binary. Only then refine rhythm, terminology and tone.

Chapter 1 — First principles: a multilingual CLI has two simultaneous readers

Citty’s usage renderers and lifecycle helpers are useful building blocks, not a guarantee that a program has built-in translation catalogs. Locales, error wording and testing need a deliberate application layer. A human sees lines on a screen and makes choices based on them. A program consumes tokens, types, state and paths. If one sentence describes an option incorrectly, the human can select a command that the parser never intended. That is why translation quality includes practical software validation, not just bilingual review. In a world-facing product, the same error can be magnified by automated documentation, tutorials and copied snippets.

Preserve command identifiers, args keys, required argument types, Boolean semantics, recognized help/version flag spellings and the shape of parsed args. Localize meta descriptions, guidance and app-owned error text with context. The most important design decision is to write down the boundary before extracting the first phrase. An argument called –config is not the English word "configuration" merely because it resembles one; its leading dashes make it a named input that scripts may depend on. A descriptive phrase such as "load a configuration file" can be translated freely, because it explains the token rather than constituting it.

Use a four-column inventory: visible source text, purpose, whether it is parser-significant, and the owner of the change. Classify headings, commands, values, errors, examples, help output and machine-readable records separately. When a string is both visible and executable, such as a command label, maintainers must consciously choose whether to keep a language-neutral token or introduce aliases with backward compatibility. Neither option is obtained by changing a translation file alone.

For a JavaScript or TypeScript developer maintaining a small but growing CLI with nested tasks and translated documentation, the practical outcome is a clear distinction between readability and compatibility. A localized interface can feel natural even when a command literal remains in English, provided it is presented as an exact token and paired with a useful explanation. The reader should never have to guess which part of an example is something to type and which part is instructional commentary.

Chapter 2 — A small executable example with a strict translation boundary

The following code is an illustrative starting point for the documented public API of UnJS citty. Install and lock the actual package version used by your project, then run it on a disposable fixture before adapting it. The example is not a full application and intentionally does not invent built-in locale selection: the surrounding application can choose translated descriptions while preserving the declared inputs.

import { defineCommand, runMain } from "citty";

const main = defineCommand({
  meta: {
    name: "harborledger",
    version: "1.0.0",
    description: "Prepare daily inventory reports"
  },
  args: {
    day: { type: "positional", required: true, description: "Day label" },
    dryRun: { type: "boolean", description: "Preview without writing files" }
  },
  run({ args }) {
    console.log(args.day, args.dryRun);
  }
});
runMain(main);

Notice the difference between the identifiers in the code and the English phrases the person reads. The identifiers have a direct relationship to parsing and downstream code. The English descriptions are candidates for a locale-specific resource. If a user asks for German or Japanese help, it is reasonable to construct equivalent descriptions in that language; it is not reasonable to assume the parser begins recognizing new command names without changing and testing its command declarations.

Define stable argument and subcommand identifiers in code, assemble localized meta descriptions at startup, and render usage from the selected command definition; compare parsed results and side effects across languages. The translation layer should be narrow enough to debug. If a parser fails before application code has selected a locale, explain what localization control the application actually has and what remains owned by the dependency. A guide earns trust by naming that limitation rather than pretending that every third-party parser error can be translated with an invented switch.

Chapter 3 — A complete work path: from one source command to a multilingual release

Begin with the installed tool rather than a translated screen mockup. Save a real help transcript, a valid command with a known output, a missing-value case and an unknown-flag case. Create a disposable workspace; then make one locale variant, keeping command definitions identical. A native-language reviewer should know exactly what to type and why, and a developer should be able to prove that the parser and the application’s outputs have not changed unintentionally.

Next, choose a real language fallback policy. A partial translation is common in an early release. Define whether the fallback is English, whether missing resources produce an explicit marker in development, and how defaults behave when no locale is selected. This is an application responsibility unless the dependency specifically documents it. Locale values such as fr-FR and pt-BR identify language preferences; they should not automatically alter internal flag names or configuration keys.

Finally, test your help and examples as one connected product. A screenshot can demonstrate how the text looks, but it cannot show whether a copied command works or a destination file was silently overwritten. For every public tutorial, save the exact command, fixture, expected file diff, expected status and any redacted stderr. That record gives translators, testers and maintainers a shared explanation of what the software actually does.

Chapter 4 — Technical decisions and investigations

The following investigations are grouped as progressive teaching cases. Each starts with something a reader can observe, traces the technical reason, proposes a controlled change and names evidence that would justify release. They are not interchangeable with generic translation advice: each case reflects how UnJS citty connects visible guidance to execution.

1. Meta name

In HarborLedger, a fictional tool used by port volunteers to prepare daily inventory reports, consider this situation: A localized onboarding article rewrites meta.name into a translated product title that does not match the executable a user runs. The name helps users recognize the invocation and appears in generated usage; changing it by language can mislead scripts. Because a command line is read by people and interpreted by software, its apparent wording can hide a second meaning. The essential question is which part of the display is merely explanatory and which part controls a parser or side effect.

A workable response is specific: Keep the shipped executable name and translate the descriptive sentence about what it does. Preserve a baseline transcript in the project test suite. It should be possible to explain a changed behavior as a deliberate software change, not as an unnoticed consequence of translating an example.

Proof matters more than confidence in the wording. Compare renderUsage output and real shell invocation in two locales. Re-run the test without an interactive terminal. A correct multilingual user experience must not corrupt redirected data or stall an automated job while waiting for a prompt that nobody can answer.

2. Meta description

In HarborLedger, a fictional tool used by port volunteers to prepare daily inventory reports, consider this situation: The description in meta is translated accurately but becomes three sentences too long for generated help. Auto-generated usage combines short metadata with command and argument details in limited terminal space. Many failures first appear as an innocent documentation mismatch. The reader copies what appears to be a valid instruction; the actual executable rejects it or accepts it with a different interpretation. That makes runnable examples an unusually valuable editorial check.

A workable response is specific: Write a concise task description suitable for help and move extended teaching paragraphs to the guide. Pair a human reading test with a machine assertion. The human catches ambiguity and discoverability problems; the assertion catches broken tokens, wrong types and unintended state changes.

Proof matters more than confidence in the wording. Capture 40, 60 and 80 column help and ask readers to find the right command. Finally, look at accessibility: can the reader distinguish the key token from explanatory prose, and can the failure be understood without color, emoji or perfect visual alignment?

3. Meta version

In HarborLedger, a fictional tool used by port volunteers to prepare daily inventory reports, consider this situation: A translated help page places a regional release label in the version field. Version values should identify a particular package and executable build, not a prose title. Do not judge a proposed localization only in isolation. Follow the value from documentation through shell tokenization, parser validation, application logic and output. A change may be harmless in help and consequential several steps later.

A workable response is specific: Preserve the real version number and put localized release context in accompanying notes. Keep the repair small. A translation change should not quietly enable permissive parsing, alter a default or introduce a different output format. Record such changes separately if they are actually required.

Proof matters more than confidence in the wording. Compare –version output across locales and confirm the same artifact reports the same value. The approval question is whether another person can repeat the task and reach the same result. Document the package version, the command, the selected locale, the file or object that changed, and the reason the output matches the instruction.

4. Required positional

In HarborLedger, a fictional tool used by port volunteers to prepare daily inventory reports, consider this situation: An argument defined as type positional and required true is described as optional in a translated command guide. The declaration drives validation; inconsistent prose teaches users an invocation that cannot succeed. A controlled fixture removes guesswork. Choose values that make success, rejection and accidental modification easy to distinguish. This is especially important for tools that operate on files, publish reports or modify state.

A workable response is specific: Explain why the argument is needed and show one valid concrete value in the command example. Instead of asking whether the sentence sounds polished, ask a new reader to predict the effect before pressing Enter. If the prediction is wrong, rewrite the explanation and retest the real invocation.

Proof matters more than confidence in the wording. Run with no value, one value and an empty quoted value to inspect behavior. Do not confuse one passing happy path with a complete check. Repeat a nearby invalid input and confirm the reader is told what to change, rather than being offered vague advice or a false success message.

5. Boolean option

In HarborLedger, a fictional tool used by port volunteers to prepare daily inventory reports, consider this situation: The CLI’s dryRun Boolean is translated as a phrase implying the program will definitely write files. Readers make real operational decisions from help; negating a safety feature can invert their expectation. Because a command line is read by people and interpreted by software, its apparent wording can hide a second meaning. The essential question is which part of the display is merely explanatory and which part controls a parser or side effect.

A workable response is specific: Translate the exact effect in positive language and distinguish preview from commit behavior. Preserve a baseline transcript in the project test suite. It should be possible to explain a changed behavior as a deliberate software change, not as an unnoticed consequence of translating an example.

Proof matters more than confidence in the wording. Check absent and present Boolean arguments and verify the underlying file side effects. Re-run the test without an interactive terminal. A correct multilingual user experience must not corrupt redirected data or stall an automated job while waiting for a prompt that nobody can answer.

6. Argument key

In HarborLedger, a fictional tool used by port volunteers to prepare daily inventory reports, consider this situation: A reviewer changes the source key from dryRun to translated text inside the command definition only. The run callback reads args.dryRun; a new key is not merely a new label. Many failures first appear as an innocent documentation mismatch. The reader copies what appears to be a valid instruction; the actual executable rejects it or accepts it with a different interpretation. That makes runnable examples an unusually valuable editorial check.

A workable response is specific: Keep parsed keys stable and localize their descriptions as separately supplied strings. Pair a human reading test with a machine assertion. The human catches ambiguity and discoverability problems; the assertion catches broken tokens, wrong types and unintended state changes.

Proof matters more than confidence in the wording. Execute a valid call and inspect the callback’s args object with a fixed schema. Finally, look at accessibility: can the reader distinguish the key token from explanatory prose, and can the failure be understood without color, emoji or perfect visual alignment?

7. Typecast rules

In HarborLedger, a fictional tool used by port volunteers to prepare daily inventory reports, consider this situation: The documentation says that every numeric-looking argument is a safe integer without checking the actual type declaration. Parser coercion and application-level constraints are separate; a converted number may still be outside allowed range. Do not judge a proposed localization only in isolation. Follow the value from documentation through shell tokenization, parser validation, application logic and output. A change may be harmless in help and consequential several steps later.

A workable response is specific: Declare and validate the type and range deliberately, then describe what the user should enter. Keep the repair small. A translation change should not quietly enable permissive parsing, alter a default or introduce a different output format. Record such changes separately if they are actually required.

Proof matters more than confidence in the wording. Test decimals, negative values, missing arguments and boundary values on the pinned version. The approval question is whether another person can repeat the task and reach the same result. Document the package version, the command, the selected locale, the file or object that changed, and the reason the output matches the instruction.

8. Built-in –help

In HarborLedger, a fictional tool used by port volunteers to prepare daily inventory reports, consider this situation: A custom argument is named help and the team expects citty’s built-in –help handling to remain unchanged. Citty documents that automatic help flags can be disabled when the command defines conflicting names or aliases. A controlled fixture removes guesswork. Choose values that make success, rejection and accidental modification easy to distinguish. This is especially important for tools that operate on files, publish reports or modify state.

A workable response is specific: Avoid collisions unless intentionally overriding behavior, and document how to access assistance. Instead of asking whether the sentence sounds polished, ask a new reader to predict the effect before pressing Enter. If the prediction is wrong, rewrite the explanation and retest the real invocation.

Proof matters more than confidence in the wording. Run –help and -h in the packaged entry point and inspect exit status and output. Do not confuse one passing happy path with a complete check. Repeat a nearby invalid input and confirm the reader is told what to change, rather than being offered vague advice or a false success message.

9. Built-in –version

In HarborLedger, a fictional tool used by port volunteers to prepare daily inventory reports, consider this situation: A developer defines a version argument name to collect file versions and accidentally changes the expected CLI version behavior. The same flag word can refer to package identity or a domain argument, and readers need an unambiguous contract. Because a command line is read by people and interpreted by software, its apparent wording can hide a second meaning. The essential question is which part of the display is merely explanatory and which part controls a parser or side effect.

A workable response is specific: Choose a distinct argument name for domain-specific version concepts and preserve the documented package flag. Preserve a baseline transcript in the project test suite. It should be possible to explain a changed behavior as a deliberate software change, not as an unnoticed consequence of translating an example.

Proof matters more than confidence in the wording. Run –version and -v and compare against package metadata. Re-run the test without an interactive terminal. A correct multilingual user experience must not corrupt redirected data or stall an automated job while waiting for a prompt that nobody can answer.

10. Nested command selector

In HarborLedger, a fictional tool used by port volunteers to prepare daily inventory reports, consider this situation: The CLI contains a nested report summary command, but a translated manual inserts a localized intermediate command token. Nested selectors are structural navigation recognized by the command tree; changed words imply a different route. Many failures first appear as an innocent documentation mismatch. The reader copies what appears to be a valid instruction; the actual executable rejects it or accepts it with a different interpretation. That makes runnable examples an unusually valuable editorial check.

A workable response is specific: Show the exact command path and translate a short description of each task in a table. Pair a human reading test with a machine assertion. The human catches ambiguity and discoverability problems; the assertion catches broken tokens, wrong types and unintended state changes.

Proof matters more than confidence in the wording. Exercise each path from root to leaf using copied examples. Finally, look at accessibility: can the reader distinguish the key token from explanatory prose, and can the failure be understood without color, emoji or perfect visual alignment?

11. Lazy subcommand module

In HarborLedger, a fictional tool used by port volunteers to prepare daily inventory reports, consider this situation: A translated guide says a subcommand always exists even when its module is loaded conditionally and can fail at runtime. Asynchronous or lazy command loading changes when validation, errors and help can be observed. Do not judge a proposed localization only in isolation. Follow the value from documentation through shell tokenization, parser validation, application logic and output. A change may be harmless in help and consequential several steps later.

A workable response is specific: Test the packaged lazy module boundary and provide a helpful recovery explanation if loading fails. Keep the repair small. A translation change should not quietly enable permissive parsing, alter a default or introduce a different output format. Record such changes separately if they are actually required.

Proof matters more than confidence in the wording. Run the command in clean production build and a deliberately missing-module fixture. The approval question is whether another person can repeat the task and reach the same result. Document the package version, the command, the selected locale, the file or object that changed, and the reason the output matches the instruction.

12. runMain

In HarborLedger, a fictional tool used by port volunteers to prepare daily inventory reports, consider this situation: A tutorial replaces runMain with a similarly named helper because it reads better in translated prose. runMain is an API that supplies entry-point behavior, usage handling and graceful error management. A controlled fixture removes guesswork. Choose values that make success, rejection and accidental modification easy to distinguish. This is especially important for tools that operate on files, publish reports or modify state.

A workable response is specific: Keep the actual import and call in code; translate the explanation of its responsibilities. Instead of asking whether the sentence sounds polished, ask a new reader to predict the effect before pressing Enter. If the prediction is wrong, rewrite the explanation and retest the real invocation.

Proof matters more than confidence in the wording. Run the executable with a valid action and with a missing argument. Do not confuse one passing happy path with a complete check. Repeat a nearby invalid input and confirm the reader is told what to change, rather than being offered vague advice or a false success message.

13. runCommand

In HarborLedger, a fictional tool used by port volunteers to prepare daily inventory reports, consider this situation: A service embeds a citty command programmatically but the guide claims it behaves identically to a full shell entry point. runCommand parses and runs commands without the full supervision wrapper used by runMain. Because a command line is read by people and interpreted by software, its apparent wording can hide a second meaning. The essential question is which part of the display is merely explanatory and which part controls a parser or side effect.

A workable response is specific: Document the difference between programmatic invocation and human CLI startup in the chosen integration. Preserve a baseline transcript in the project test suite. It should be possible to explain a changed behavior as a deliberate software change, not as an unnoticed consequence of translating an example.

Proof matters more than confidence in the wording. Compare returned result, errors and process effects for a controlled command. Re-run the test without an interactive terminal. A correct multilingual user experience must not corrupt redirected data or stall an automated job while waiting for a prompt that nobody can answer.

14. parseArgs

In HarborLedger, a fictional tool used by port volunteers to prepare daily inventory reports, consider this situation: A translated example changes an argument name in the args definition but still calls parseArgs with the old test fixture. The parser’s output keys derive from the definitions and values; mismatching them produces misleading examples. Many failures first appear as an innocent documentation mismatch. The reader copies what appears to be a valid instruction; the actual executable rejects it or accepts it with a different interpretation. That makes runnable examples an unusually valuable editorial check.

A workable response is specific: Keep definitions and tests as one versioned set and translate only surrounding explanation. Pair a human reading test with a machine assertion. The human catches ambiguity and discoverability problems; the assertion catches broken tokens, wrong types and unintended state changes.

Proof matters more than confidence in the wording. Assert parsed values for Boolean, positional and default cases in a small unit test. Finally, look at accessibility: can the reader distinguish the key token from explanatory prose, and can the failure be understood without color, emoji or perfect visual alignment?

15. renderUsage

In HarborLedger, a fictional tool used by port volunteers to prepare daily inventory reports, consider this situation: A site wants a custom translated help page but builds all formatting manually despite citty exposing renderUsage. A renderer can provide consistent structure while translated descriptions supply the human wording. Do not judge a proposed localization only in isolation. Follow the value from documentation through shell tokenization, parser validation, application logic and output. A change may be harmless in help and consequential several steps later.

A workable response is specific: Render a locale-specific command definition and inspect the resulting string before presenting it. Keep the repair small. A translation change should not quietly enable permissive parsing, alter a default or introduce a different output format. Record such changes separately if they are actually required.

Proof matters more than confidence in the wording. Compare rendered usage at the root and one subcommand, checking visible options against real parsing. The approval question is whether another person can repeat the task and reach the same result. Document the package version, the command, the selected locale, the file or object that changed, and the reason the output matches the instruction.

16. showUsage

In HarborLedger, a fictional tool used by port volunteers to prepare daily inventory reports, consider this situation: A script uses showUsage in a code path expected to return a string rather than print it. Documentation distinguishes rendering a string from printing usage to the console. A controlled fixture removes guesswork. Choose values that make success, rejection and accidental modification easy to distinguish. This is especially important for tools that operate on files, publish reports or modify state.

A workable response is specific: Use renderUsage for text capture and showUsage for deliberate display when appropriate. Instead of asking whether the sentence sounds polished, ask a new reader to predict the effect before pressing Enter. If the prediction is wrong, rewrite the explanation and retest the real invocation.

Proof matters more than confidence in the wording. Redirect stdout in a test and check whether the intended message appears exactly once. Do not confuse one passing happy path with a complete check. Repeat a nearby invalid input and confirm the reader is told what to change, rather than being offered vague advice or a false success message.

17. setup lifecycle

In HarborLedger, a fictional tool used by port volunteers to prepare daily inventory reports, consider this situation: A translated guide implies setup always runs after the action, but the program actually performs setup first. Citty documents setup, run and cleanup hooks as lifecycle stages; timing matters for diagnostics and resources. Because a command line is read by people and interpreted by software, its apparent wording can hide a second meaning. The essential question is which part of the display is merely explanatory and which part controls a parser or side effect.

A workable response is specific: Explain initialization in task language, and avoid putting a potentially failing write in an ambiguous phase. Preserve a baseline transcript in the project test suite. It should be possible to explain a changed behavior as a deliberate software change, not as an unnoticed consequence of translating an example.

Proof matters more than confidence in the wording. Record the order of hooks under success and a controlled failure. Re-run the test without an interactive terminal. A correct multilingual user experience must not corrupt redirected data or stall an automated job while waiting for a prompt that nobody can answer.

18. cleanup lifecycle

In HarborLedger, a fictional tool used by port volunteers to prepare daily inventory reports, consider this situation: A help message promises an export is complete before cleanup finishes releasing a temporary file. The completion claim is only accurate when all required work is finished and failures handled. Many failures first appear as an innocent documentation mismatch. The reader copies what appears to be a valid instruction; the actual executable rejects it or accepts it with a different interpretation. That makes runnable examples an unusually valuable editorial check.

A workable response is specific: Use careful wording for in-progress and completed states, including cleanup errors that may matter to users. Pair a human reading test with a machine assertion. The human catches ambiguity and discoverability problems; the assertion catches broken tokens, wrong types and unintended state changes.

Proof matters more than confidence in the wording. Run a temporary-file fixture and confirm files are left in the expected state. Finally, look at accessibility: can the reader distinguish the key token from explanatory prose, and can the failure be understood without color, emoji or perfect visual alignment?

19. Async handler

In HarborLedger, a fictional tool used by port volunteers to prepare daily inventory reports, consider this situation: A nested command returns a Promise and the documentation suggests its result is always immediately available. Async tasks can fail after parsing; a help page must distinguish accepted input from completed work. Do not judge a proposed localization only in isolation. Follow the value from documentation through shell tokenization, parser validation, application logic and output. A change may be harmless in help and consequential several steps later.

A workable response is specific: Use correct awaiting in code and report completion only after the operation really resolves. Keep the repair small. A translation change should not quietly enable permissive parsing, alter a default or introduce a different output format. Record such changes separately if they are actually required.

Proof matters more than confidence in the wording. Inject a rejected Promise and inspect error and exit behavior. The approval question is whether another person can repeat the task and reach the same result. Document the package version, the command, the selected locale, the file or object that changed, and the reason the output matches the instruction.

20. Plugin integration

In HarborLedger, a fictional tool used by port volunteers to prepare daily inventory reports, consider this situation: A team adds custom plugin processing and the translated guide calls it core citty behavior. Pluggable features and application-specific extensions are not automatically guaranteed across installations. A controlled fixture removes guesswork. Choose values that make success, rejection and accidental modification easy to distinguish. This is especially important for tools that operate on files, publish reports or modify state.

A workable response is specific: Identify which features belong to the installed package and which require the program’s own plugin. Instead of asking whether the sentence sounds polished, ask a new reader to predict the effect before pressing Enter. If the prediction is wrong, rewrite the explanation and retest the real invocation.

Proof matters more than confidence in the wording. Build a minimal installation without the plugin and a configured installation, then compare. Do not confuse one passing happy path with a complete check. Repeat a nearby invalid input and confirm the reader is told what to change, rather than being offered vague advice or a false success message.

21. Unicode terminals

In HarborLedger, a fictional tool used by port volunteers to prepare daily inventory reports, consider this situation: Inventory labels include Thai or Arabic characters and the team tests only English ASCII in the terminal. Correct string parsing is necessary but not sufficient for legibility, bidirectional order or screen reader access. Because a command line is read by people and interpreted by software, its apparent wording can hide a second meaning. The essential question is which part of the display is merely explanatory and which part controls a parser or side effect.

A workable response is specific: Test real Unicode input and keep identifiers separate from localized descriptions when scripts differ. Preserve a baseline transcript in the project test suite. It should be possible to explain a changed behavior as a deliberate software change, not as an unnoticed consequence of translating an example.

Proof matters more than confidence in the wording. Compare captured input, generated usage and accessible reading order on supported environments. Re-run the test without an interactive terminal. A correct multilingual user experience must not corrupt redirected data or stall an automated job while waiting for a prompt that nobody can answer.

22. Release compatibility

In HarborLedger, a fictional tool used by port volunteers to prepare daily inventory reports, consider this situation: The citty version is changed and a localized guide promises a behavior demonstrated only by an older README. An evolving CLI library can revise helpers, flags or implementation assumptions across releases. Many failures first appear as an innocent documentation mismatch. The reader copies what appears to be a valid instruction; the actual executable rejects it or accepts it with a different interpretation. That makes runnable examples an unusually valuable editorial check.

A workable response is specific: Pin the actual version, rerun executable examples and update prose only after the tested behavior is known. Pair a human reading test with a machine assertion. The human catches ambiguity and discoverability problems; the assertion catches broken tokens, wrong types and unintended state changes.

Proof matters more than confidence in the wording. Save release-tagged snapshots for help, parse output and error cases, and review them before launch. Finally, look at accessibility: can the reader distinguish the key token from explanatory prose, and can the failure be understood without color, emoji or perfect visual alignment?

Chapter 5 — A multilingual terminal testing matrix

Compare –help, –version, required positional errors, nested command paths, Boolean parsing, lazy module loading, Unicode input, stdout/stderr and noninteractive execution across selected locales. For a small international launch, begin with ten representative locales rather than claiming to cover every language. Languages are not merely a stress test for string length: they can expose issues with spacing, display direction, case changes, input methods, font availability and cultural assumptions. Use native review for final wording; machines can establish parser invariants, but they cannot decide whether instructions are respectful or understandable.

ar-EG Arabic: check copying from right-to-left prose into an otherwise left-to-right command and confirm digit/flag order
de-DE German: check compound descriptions and whether long help options wrap without hiding the important verb
es-ES Spanish: check whether option explanations keep the distinction between read-only preview and actual write
fr-FR French: check accented filenames, apostrophes and whether failure recovery is unambiguous
hi-IN Hindi: check Devanagari input and visually confusable punctuation in a narrow terminal
id-ID Indonesian: check concise word choice and whether task names identify the intended file operation
ja-JP Japanese: check kanji and kana filenames, half-width/full-width characters and copyable flag spellings
pt-BR Brazilian Portuguese: check longer explanations and sample paths with diacritics while preserving default values
th-TH Thai: check combining marks and Unicode rendering in help and diagnostic text
zh-CN Simplified Chinese: check Chinese path strings and whether technical option names remain visibly separate from explanations

Do not assume a given locale implies a particular script, proficiency level or platform. A Brazilian Portuguese reader may use a US English keyboard; an Arabic reader may run a headless Linux server. Locale selection, terminal encoding, filesystem behavior and shell are distinct variables. Test them separately so the team knows whether a problem belongs to translation, display, operating system or dependency behavior.

Chapter 6 — A four-week implementation and review plan

Week 1: capture the contract

Inventory every command, option, positional argument, output field and app-owned visible string. Install a locked release, collect a baseline help transcript and build a fixture for successful and failed invocations. The deliverable is a classification of translatable prose versus executable identifiers, plus a short list of user tasks the article must teach.

For UnJS citty, make the evidence practical: save the exact shell invocation, the parser-facing identifiers, the user-facing sentence, the observed result and the responsible reviewer. Include a failed command so the guide demonstrates recovery as well as success. A completed week means these artifacts exist and a reader can repeat the task; it does not mean merely that translation files have been filled.

Week 2: create one complete locale

Write translation keys for descriptions and recovery messages. Avoid hidden string concatenation. Apply the locale choice at an explicit boundary, then rerun the same commands with identical fixtures. Have one native reader explain each action before seeing its actual result. Review where translation makes a caution less specific.

Week 3: exercise difficult environments

Add two non-Latin filename tests, one right-to-left help review, a narrow terminal capture, and a headless run with stdout redirected. Exercise every parsing failure represented in the guide and verify that any structured output remains parseable. Use actual build artifacts, not code snippets detached from packaging.

Week 4: release with evidence

Freeze a reviewed glossary, update examples to match the pinned binary, publish a concise version note and keep a rollback copy. Sign off on parser invariants, native-language task success, accessibility, error recovery and release reproducibility. Assign an owner for each unfinished locale rather than hiding incompleteness behind a default translation.

Chapter 7 — FAQs for maintainers and translators

Can we translate every command and flag?

Not automatically. Those spellings may be parser tokens consumed by scripts and code. Explain them in the reader’s language; introduce localized aliases only through an intentional compatible software change with tested conflict handling. In HarborLedger, a fictional tool used by port volunteers to prepare daily inventory reports, the concrete check is whether the same task remains reproducible for a person using another language. Instead of asking whether the sentence sounds polished, ask a new reader to predict the effect before pressing Enter. If the prediction is wrong, rewrite the explanation and retest the real invocation.

Does the package provide automatic locale selection?

Do not assume it does. Check the installed release’s documentation. When localization is application-owned, choose a locale explicitly and pass translated descriptive text at construction time, keeping fallback rules visible. In HarborLedger, a fictional tool used by port volunteers to prepare daily inventory reports, the concrete check is whether the same task remains reproducible for a person using another language. Preserve a baseline transcript in the project test suite. It should be possible to explain a changed behavior as a deliberate software change, not as an unnoticed consequence of translating an example.

How should we deal with a library error that remains in English?

Distinguish the dependency’s diagnostic from the application’s recovery guidance. Record the exact error, avoid unsupported claims about translating internals and provide a localized next step that identifies the rejected input. In HarborLedger, a fictional tool used by port volunteers to prepare daily inventory reports, the concrete check is whether the same task remains reproducible for a person using another language. Pair a human reading test with a machine assertion. The human catches ambiguity and discoverability problems; the assertion catches broken tokens, wrong types and unintended state changes.

Should we translate example file paths?

Paths in runnable commands must refer to real fixtures. You can explain a path in translation and supply an appropriate local fixture, but arbitrary word replacement inside a path may make a copied example fail. In HarborLedger, a fictional tool used by port volunteers to prepare daily inventory reports, the concrete check is whether the same task remains reproducible for a person using another language. Keep the repair small. A translation change should not quietly enable permissive parsing, alter a default or introduce a different output format. Record such changes separately if they are actually required.

What about technical words that lack a natural translation?

Use a short definition rather than a fabricated equivalent. Keep the actual flag or key in code type and add an explanation of its purpose and consequence. Consistency matters more than mechanical word-for-word matching. In HarborLedger, a fictional tool used by port volunteers to prepare daily inventory reports, the concrete check is whether the same task remains reproducible for a person using another language. Instead of asking whether the sentence sounds polished, ask a new reader to predict the effect before pressing Enter. If the prediction is wrong, rewrite the explanation and retest the real invocation.

How do we test Chinese, Arabic or Hindi help?

Use genuine terminal rendering with representative input, not only browser screenshots. Verify character integrity, wraps, copying, text direction and underlying parser results. Where possible, include a native-language task review. In HarborLedger, a fictional tool used by port volunteers to prepare daily inventory reports, the concrete check is whether the same task remains reproducible for a person using another language. Preserve a baseline transcript in the project test suite. It should be possible to explain a changed behavior as a deliberate software change, not as an unnoticed consequence of translating an example.

Can a translation alter exit codes?

It should not unless application behavior is intentionally changed. A diagnostic may be translated while the process status remains useful to scripts. Test success and failure separately and inspect both stdout and stderr. In HarborLedger, a fictional tool used by port volunteers to prepare daily inventory reports, the concrete check is whether the same task remains reproducible for a person using another language. Pair a human reading test with a machine assertion. The human catches ambiguity and discoverability problems; the assertion catches broken tokens, wrong types and unintended state changes.

Is a fluent machine translation enough?

No. It may miss command grammar, units, irreversibility and the difference between data and instructions. Run copyable examples, request a task-focused review and check the actual program output before release. In HarborLedger, a fictional tool used by port volunteers to prepare daily inventory reports, the concrete check is whether the same task remains reproducible for a person using another language. Keep the repair small. A translation change should not quietly enable permissive parsing, alter a default or introduce a different output format. Record such changes separately if they are actually required.

What is the best evidence for the article’s correctness?

A locked package version, executable examples, parser-output assertions, expected file effects, captured help, invalid-input recovery and approval from a native-language reviewer are more useful than an unsupported claim that the instructions are clear. In HarborLedger, a fictional tool used by port volunteers to prepare daily inventory reports, the concrete check is whether the same task remains reproducible for a person using another language. Instead of asking whether the sentence sounds polished, ask a new reader to predict the effect before pressing Enter. If the prediction is wrong, rewrite the explanation and retest the real invocation.

How do we prevent regressions next month?

Treat the documentation as a tested companion to the CLI. Rerun examples after package upgrades, compare flag inventories and help snapshots, and update translations when the behavior or wording actually changes. In HarborLedger, a fictional tool used by port volunteers to prepare daily inventory reports, the concrete check is whether the same task remains reproducible for a person using another language. Preserve a baseline transcript in the project test suite. It should be possible to explain a changed behavior as a deliberate software change, not as an unnoticed consequence of translating an example.

Chapter 8 — What proficiency looks like

A professional localization is a reliable bridge between the user’s intention and the software’s actual action. The reader can identify which task to choose, distinguish harmless preview from irreversible change, copy a verified command and recover when an input fails. The program continues to recognize the same interface, produce stable data and report problems through channels that human and automated consumers can understand.

The aim for a JavaScript or TypeScript developer maintaining a small but growing CLI with nested tasks and translated documentation is not simply more translated words. It is less guessing, fewer broken examples, safer execution and documentation that remains trustworthy through upgrades. Start with one command, one realistic error and one multilingual test fixture. Then grow deliberately, verifying every promise you put in front of a reader.