Translate Like a Pro | 9100 — TypeScript cmd-ts Localization, Typed Decoders, Options, Positionals, Errors and Completion QA

TypeScript cmd-ts localization requires more than translating a help screen. Developers looking for cmd-ts CLI localization, typed command-line parsers, positional arguments, option descriptions, nested subcommands and multilingual error messages need a method that keeps a command’s behavior stable. A user should be able to copy a working example, understand which value is expected and recover from a failed parse without guessing at the program’s intent.

Imagine atlas-check, a small read-only command that checks a local catalog and prints a report. Contributors in different countries use the same script, but the people reading its help may prefer French, Arabic or Japanese. If an instruction translates –language into a word the program does not accept, the documentation has become misleading. If a custom decoder rejects a value without identifying the expected type, even fluent text is not useful.

cmd-ts is a type-driven TypeScript command-line parsing library with composable options, positionals and decoding, including facilities for nested commands and completion. That makes it an interesting translation problem: a string can be a command identity, a help description, a display name, an input value or a diagnostic. We will separate those roles, work through realistic failures, then build a test plan for international CLI releases. Examples illustrate a safe read-only tool; they are not claims about automatic locale support inside cmd-ts.

Quick answer: translate meaning, preserve executable behavior

For TypeScript cmd-ts, begin with the smallest verified command, then translate the task description, parameter explanations, recovery instructions and human-facing summaries. Never assume that an option, typed value, command alias or generated error has been translated merely because a nearby sentence is now readable. The core of this guide is the difference between typed argument decoding and the language used to explain a decoder failure. Make each behavior observable with a harmless fixture, a copied invocation, its parsed inputs, stdout, stderr and the process exit status.

One read-only example to understand first

Our teaching example is atlas-check, a fictional read-only catalog validator used by contributors across countries. It exists to show the boundary between parser grammar and explanatory language, not to demonstrate a complete production translation system. The following code is illustrative of documented APIs; verify its dependencies, imports and exact syntax in your project before adapting it. For a reader, the key question is whether the real command accepts –language and a positional input path and whether the reported result is faithful to what was requested.

import { command, run, string, positional, option } from "cmd-ts";

const inspect = command({
  name: "atlas-check",
  description: "Inspect a local catalog without changing it.",
  args: {
    input: positional({ type: string, displayName: "file" }),
    language: option({ long: "language", type: string })
  },
  handler: ({ input, language }) => {
    console.log(JSON.stringify({ input, language, mode: "read-only" }));
  }
});
run(inspect, process.argv.slice(2));

Read the example slowly. The application’s task is to inspect existing information, not rewrite it. The executable or class name identifies a program; an option identifies a choice; a positional is a slot for actual input data. The description explains a choice to a person. Changing the description should not alter the typed value produced for the handler. Before you translate anything, execute a reference command with a small nonprivate fixture and save the successful result and one useful failure case.

Start with a dependable mental model

Type readers are contracts

A cmd-ts type reader converts a token into a typed value; translating a label cannot make an unsupported value valid. Treat decoding as application behavior and translation as a separate explanation layer. A reader who sees a French description of a number must still enter the numeric representation that the installed decoder actually accepts.

In TypeScript cmd-ts, this is not an abstract distinction. A reader sees a line of help, chooses a token, types a value, and expects a result. A change is safe only when the program’s accepted syntax, the intended operation and the reader’s understanding remain aligned. When reviewing this part, place the translated instruction next to the actual parser declaration and the observed output; resolve any mismatch before publishing that instruction.

The meaning of positional displayName

The displayName shown beside a positional is a presentation hint, not necessarily a newly accepted argument. In a usage line, file should stand for a path; a tutorial must make clear that the reader supplies the path value rather than literally typing file.

Option long names are stable input

The long field supplies an executable option name. A translator can choose a better sentence for language but cannot claim a localized spelling exists until code actually registers and tests that alias. Scripts, shell history and third-party tools depend on exact tokens.

Command nesting is a navigation problem

Nested command trees have separate grammar and help contexts. Translating a nested command description while leaving its parent help unexplained can strand the reader; record a valid complete invocation from root command to leaf and document that hierarchy.

Decode errors require recovery

The crucial question is not whether a parse error is grammatically correct; it is whether the reader knows which argument failed and what kind of value would pass. Keep the name and allowed format discoverable, even when a dependency generates part of the diagnostic.

Help, completion and typing are separate outputs

Completion proposals can contain executable subcommand names or values rather than prose. Do not translate those into unsupported tokens merely because the help description has been localized. Verify completion, help and actual parsing against one command definition.

How to plan a multilingual release without changing the command contract

Identify the task before translating

Begin by naming exactly what the reader wants to do, what input is required, what result appears, and whether the operation has side effects. Keep this first task deliberately small. The user should not have to read an entire manual before discovering the shortest command that works. Preserve a reference execution with its argument array, parsed object, visible output and process status.

For atlas-check, a fictional read-only catalog validator used by contributors across countries, the reviewer should be able to answer a practical question: what would a person type, what would the program actually read, and what evidence demonstrates the operation was correct? A description that cannot be checked with a harmless input is not yet reliable documentation. Use exact input and result examples rather than promising a general outcome based on a screen label.

Inventory executable and human-facing strings

Divide every visible string into an executable token, value placeholder, description, validation explanation, result label, data field or external identifier. Give each category an owner. An executable token belongs to the program grammar; prose belongs to a reviewed language resource or documentation. This inventory prevents someone from translating a value that another program relies upon.

Choose a real language policy

Decide whether language is chosen by an explicit flag, a user preference or a suitable environment variable. Explain precedence and fallback in one short paragraph. Do not claim that a CLI library automatically follows the system language unless the installed application demonstrates it. Failures caused by missing resources need an understandable fallback rather than empty output.

Test the command rather than its appearance

The critical acceptance condition is the same intended operation from the same logical inputs in each language. Compare parsed field values, exit status, output format and file effects. A help screen can be visually perfect while an example command is wrong. Conversely, a command can succeed while a reader misunderstands what it will do; both outcomes require review.

Separate parser errors from application errors

A malformed flag, an invalid typed value, a missing file and a failed domain operation are different problems. The correction depends on which layer failed. A good localized explanation names the field or action the person can change, does not leak secrets and never converts a failure into a misleading success report.

Write for readers who will copy the example

Use copyable code blocks and keep real filenames, option spellings and schema keys intact. Explain placeholders outside the code when necessary. On mixed-direction pages, isolate each executable command. Test a command copied from the actual published page rather than a source draft; markup and rendering can change punctuation.

Practical investigations: what breaks and how to correct it

The following 38 situations are independent troubleshooting lessons rather than steps that must be performed in sequence. Begin with the failure that resembles your user’s problem. Each case separates what a person encounters from the cause, the narrow repair and a test that can show whether the repair worked. This avoids the expensive habit of rewriting every translated string when the real problem is one option, type converter, path or output channel.

1. Command name chosen for fluent translation

Imagine a contributor rewrites the command name property into a translated noun and old invocations stop finding the operation. For atlas-check, a fictional read-only catalog validator used by contributors across countries, the important question is whether the reader’s intended action actually reaches the right parser field and the right operation. A sentence can look polished and still misdirect the reader toward an invalid input or a false conclusion.

The name is part of the executable command identity; cmd-ts does not interpret natural-language synonyms by meaning. Treat the difference as an observable contract: the source command, the translated instruction and the program’s output should all describe the same behavior. If the user has to infer an undocumented option or a missing value, the guide needs repair before it is reliable.

Keep one stable command identifier and translate only the adjacent description unless registered aliases are an explicit feature. Keep the correction scoped to the responsible layer. A language editor may refine the phrasing, but a command grammar change must be reviewed like a software change; the two decisions should never be confused.

Run both the reference invocation and the new documentation’s copyable example against the same built artifact. Record the complete invocation, the selected language, the observed value or outcome and the failure status when appropriate. A second reader should be able to reproduce the result without access to the author’s private environment.

2. A positional file placeholder misread as a literal

Imagine the help page presents FILE as though it is a reserved keyword, so a reader enters FILE instead of an actual path. For atlas-check, a fictional read-only catalog validator used by contributors across countries, the important question is whether the reader’s intended action actually reaches the right parser field and the right operation. A sentence can look polished and still misdirect the reader toward an invalid input or a false conclusion.

The positional displayName describes a slot and its expected value; it is not the filename the program should read. Treat the difference as an observable contract: the source command, the translated instruction and the program’s output should all describe the same behavior. If the user has to infer an undocumented option or a missing value, the guide needs repair before it is reliable.

Use a visually distinct placeholder with a sentence showing a real sample path and a statement about whether the program changes it. Keep the correction scoped to the responsible layer. A language editor may refine the phrasing, but a command grammar change must be reviewed like a software change; the two decisions should never be confused.

Ask an unfamiliar reader to identify the required input and successfully inspect a harmless fixture file. Record the complete invocation, the selected language, the observed value or outcome and the failure status when appropriate. A second reader should be able to reproduce the result without access to the author’s private environment.

3. A number decoder rejects a localized decimal

Imagine a Spanish-language guide shows 2,5 for a typed numeric option but the selected decoder expects a different numeric syntax. For atlas-check, a fictional read-only catalog validator used by contributors across countries, the important question is whether the reader’s intended action actually reaches the right parser field and the right operation. A sentence can look polished and still misdirect the reader toward an invalid input or a false conclusion.

A language’s display punctuation and the reader’s machine format are not guaranteed to match; type decoders control the accepted representation. Treat the difference as an observable contract: the source command, the translated instruction and the program’s output should all describe the same behavior. If the user has to infer an undocumented option or a missing value, the guide needs repair before it is reliable.

Publish the accepted numeric format exactly and explain regional conventions separately; add locale parsing only as an intentional code feature. Keep the correction scoped to the responsible layer. A language editor may refine the phrasing, but a command grammar change must be reviewed like a software change; the two decisions should never be confused.

Test 2.5, 2,5, empty text and nonnumeric text, recording parsed value and error for each. Record the complete invocation, the selected language, the observed value or outcome and the failure status when appropriate. A second reader should be able to reproduce the result without access to the author’s private environment.

4. A custom decoder returns a vague failure

Imagine the validator rejects an identifier with no explanation beyond invalid input, making the user repeat the same mistake. For atlas-check, a fictional read-only catalog validator used by contributors across countries, the important question is whether the reader’s intended action actually reaches the right parser field and the right operation. A sentence can look polished and still misdirect the reader toward an invalid input or a false conclusion.

Custom type readers know the permitted structure, but their error communication must be coordinated with application messages and parser output. Treat the difference as an observable contract: the source command, the translated instruction and the program’s output should all describe the same behavior. If the user has to infer an undocumented option or a missing value, the guide needs repair before it is reliable.

Describe the expected shape without revealing sensitive values; provide one valid and one invalid example beside the option. Keep the correction scoped to the responsible layer. A language editor may refine the phrasing, but a command grammar change must be reviewed like a software change; the two decisions should never be confused.

Exercise a boundary value and check the error explains a safe correction rather than asking users to experiment blindly. Record the complete invocation, the selected language, the observed value or outcome and the failure status when appropriate. A second reader should be able to reproduce the result without access to the author’s private environment.

5. Nested command grammar becomes ambiguous

Imagine a translation places subcommand options before the subcommand name although the actual grammar requires another order. For atlas-check, a fictional read-only catalog validator used by contributors across countries, the important question is whether the reader’s intended action actually reaches the right parser field and the right operation. A sentence can look polished and still misdirect the reader toward an invalid input or a false conclusion.

A command tree is parsed structurally; moving the pieces in prose can be as damaging as translating the tokens. Treat the difference as an observable contract: the source command, the translated instruction and the program’s output should all describe the same behavior. If the user has to infer an undocumented option or a missing value, the guide needs repair before it is reliable.

Show a complete executable invocation including root, subcommand, positional and option, then explain the segments in the order users type them. Keep the correction scoped to the responsible layer. A language editor may refine the phrasing, but a command grammar change must be reviewed like a software change; the two decisions should never be confused.

Use the command’s own parser to run the example and compare selected handler and parsed values. Record the complete invocation, the selected language, the observed value or outcome and the failure status when appropriate. A second reader should be able to reproduce the result without access to the author’s private environment.

6. Completion suggests a nonexistent translated command

Imagine the shell completion menu offers a translated command label that looks helpful but cannot be executed. For atlas-check, a fictional read-only catalog validator used by contributors across countries, the important question is whether the reader’s intended action actually reaches the right parser field and the right operation. A sentence can look polished and still misdirect the reader toward an invalid input or a false conclusion.

Completion output is often a list of recognized tokens rather than an inventory of explanatory names. Treat the difference as an observable contract: the source command, the translated instruction and the program’s output should all describe the same behavior. If the user has to infer an undocumented option or a missing value, the guide needs repair before it is reliable.

Keep completion candidates tied to registered commands and accepted values; add localized descriptions only if the completion interface supports them. Keep the correction scoped to the responsible layer. A language editor may refine the phrasing, but a command grammar change must be reviewed like a software change; the two decisions should never be confused.

Accept one suggested candidate automatically in a shell fixture and confirm the same command handler runs. Record the complete invocation, the selected language, the observed value or outcome and the failure status when appropriate. A second reader should be able to reproduce the result without access to the author’s private environment.

7. An optional value is documented as required

Imagine the tutorial tells readers that the language option must always appear, although the actual program has a fallback. For atlas-check, a fictional read-only catalog validator used by contributors across countries, the important question is whether the reader’s intended action actually reaches the right parser field and the right operation. A sentence can look polished and still misdirect the reader toward an invalid input or a false conclusion.

Documentation about requiredness is a claim about application policy, not a choice of word order. Treat the difference as an observable contract: the source command, the translated instruction and the program’s output should all describe the same behavior. If the user has to infer an undocumented option or a missing value, the guide needs repair before it is reliable.

Explain the effective default and how to override it; verify that source-level optionality and the help statement agree. Keep the correction scoped to the responsible layer. A language editor may refine the phrasing, but a command grammar change must be reviewed like a software change; the two decisions should never be confused.

Compare the no-option invocation against an explicit-option invocation and record the effective locale. Record the complete invocation, the selected language, the observed value or outcome and the failure status when appropriate. A second reader should be able to reproduce the result without access to the author’s private environment.

8. A required value is advertised as optional

Imagine a reader follows a translated example with no input path and receives an immediate parser failure. For atlas-check, a fictional read-only catalog validator used by contributors across countries, the important question is whether the reader’s intended action actually reaches the right parser field and the right operation. A sentence can look polished and still misdirect the reader toward an invalid input or a false conclusion.

A positional in the schema may require a value even when a translator casually says you can include it. Treat the difference as an observable contract: the source command, the translated instruction and the program’s output should all describe the same behavior. If the user has to infer an undocumented option or a missing value, the guide needs repair before it is reliable.

Use a required-value example first and label any optional variants only after testing the actual schema. Keep the correction scoped to the responsible layer. A language editor may refine the phrasing, but a command grammar change must be reviewed like a software change; the two decisions should never be confused.

Run zero-argument and one-argument fixtures; confirm help and errors agree about required input. Record the complete invocation, the selected language, the observed value or outcome and the failure status when appropriate. A second reader should be able to reproduce the result without access to the author’s private environment.

9. A boolean control is described as a valued option

Imagine the page instructs someone to type –verbose true even when the program expects a presence flag. For atlas-check, a fictional read-only catalog validator used by contributors across countries, the important question is whether the reader’s intended action actually reaches the right parser field and the right operation. A sentence can look polished and still misdirect the reader toward an invalid input or a false conclusion.

Argument types establish whether a following token belongs to the flag or becomes an unexpected positional. Treat the difference as an observable contract: the source command, the translated instruction and the program’s output should all describe the same behavior. If the user has to infer an undocumented option or a missing value, the guide needs repair before it is reliable.

Explain the accepted switch form, not a convenient prose analogy, and test whether false requires a separate mechanism. Keep the correction scoped to the responsible layer. A language editor may refine the phrasing, but a command grammar change must be reviewed like a software change; the two decisions should never be confused.

Try presence, absence and an extra literal true; record what the parser actually accepts. Record the complete invocation, the selected language, the observed value or outcome and the failure status when appropriate. A second reader should be able to reproduce the result without access to the author’s private environment.

10. A short alias collides with another option

Imagine a language-specific abbreviation is added to help without checking whether the same short flag already names a different option. For atlas-check, a fictional read-only catalog validator used by contributors across countries, the important question is whether the reader’s intended action actually reaches the right parser field and the right operation. A sentence can look polished and still misdirect the reader toward an invalid input or a false conclusion.

Short flags are constrained identifiers and collisions make the interface confusing or invalid. Treat the difference as an observable contract: the source command, the translated instruction and the program’s output should all describe the same behavior. If the user has to infer an undocumented option or a missing value, the guide needs repair before it is reliable.

Inventory all short aliases at every command level before considering any new language-specific abbreviation. Keep the correction scoped to the responsible layer. A language editor may refine the phrasing, but a command grammar change must be reviewed like a software change; the two decisions should never be confused.

Parse every short and long form in a test command and compare the intended typed field. Record the complete invocation, the selected language, the observed value or outcome and the failure status when appropriate. A second reader should be able to reproduce the result without access to the author’s private environment.

11. A help translation hides default value

Imagine the summary says that the command reads a UTF-8 catalog but leaves out which locale is used when –language is omitted. For atlas-check, a fictional read-only catalog validator used by contributors across countries, the important question is whether the reader’s intended action actually reaches the right parser field and the right operation. A sentence can look polished and still misdirect the reader toward an invalid input or a false conclusion.

The effective fallback is part of the user-visible result; missing that information causes output that appears inconsistent across machines. Treat the difference as an observable contract: the source command, the translated instruction and the program’s output should all describe the same behavior. If the user has to infer an undocumented option or a missing value, the guide needs repair before it is reliable.

Document how locale selection works in the application, including the precedence of explicit option and environment settings. Keep the correction scoped to the responsible layer. A language editor may refine the phrasing, but a command grammar change must be reviewed like a software change; the two decisions should never be confused.

Run with option omitted, with the environment changed and with an explicit option; compare chosen locale. Record the complete invocation, the selected language, the observed value or outcome and the failure status when appropriate. A second reader should be able to reproduce the result without access to the author’s private environment.

12. A decoding example accidentally mutates data

Imagine a tutorial adds a write or import handler simply to demonstrate successful parsing in a supposedly read-only guide. For atlas-check, a fictional read-only catalog validator used by contributors across countries, the important question is whether the reader’s intended action actually reaches the right parser field and the right operation. A sentence can look polished and still misdirect the reader toward an invalid input or a false conclusion.

Technical examples should expose parsing behavior without expanding the operation or implying that the library carries out writes automatically. Treat the difference as an observable contract: the source command, the translated instruction and the program’s output should all describe the same behavior. If the user has to infer an undocumented option or a missing value, the guide needs repair before it is reliable.

Use a handler that prints a checked result or a JSON fixture; describe explicitly that it does not edit any file. Keep the correction scoped to the responsible layer. A language editor may refine the phrasing, but a command grammar change must be reviewed like a software change; the two decisions should never be confused.

Snapshot fixture files before and after running the sample and assert that no unexpected change occurred. Record the complete invocation, the selected language, the observed value or outcome and the failure status when appropriate. A second reader should be able to reproduce the result without access to the author’s private environment.

13. An unknown option error is hard to find

Imagine the help page discusses the desired feature but gives no clue that the parser rejects one misspelled dash-prefixed name. For atlas-check, a fictional read-only catalog validator used by contributors across countries, the important question is whether the reader’s intended action actually reaches the right parser field and the right operation. A sentence can look polished and still misdirect the reader toward an invalid input or a false conclusion.

A reader who sees only a wall of translated prose cannot identify the canonical spelling that fixes the input. Treat the difference as an observable contract: the source command, the translated instruction and the program’s output should all describe the same behavior. If the user has to infer an undocumented option or a missing value, the guide needs repair before it is reliable.

Quote the unsupported token safely, name the supported spelling and show a runnable correction alongside the explanation. Keep the correction scoped to the responsible layer. A language editor may refine the phrasing, but a command grammar change must be reviewed like a software change; the two decisions should never be confused.

Test misspelling and corrected command and verify different status codes and an understandable recovery path. Record the complete invocation, the selected language, the observed value or outcome and the failure status when appropriate. A second reader should be able to reproduce the result without access to the author’s private environment.

14. A string reader treats path content as a label

Imagine the translated guide replaces an actual directory name with a localized term, and the application looks in the wrong place. For atlas-check, a fictional read-only catalog validator used by contributors across countries, the important question is whether the reader’s intended action actually reaches the right parser field and the right operation. A sentence can look polished and still misdirect the reader toward an invalid input or a false conclusion.

cmd-ts can parse an argument as a string without knowing that its value refers to a path or external resource. Treat the difference as an observable contract: the source command, the translated instruction and the program’s output should all describe the same behavior. If the user has to infer an undocumented option or a missing value, the guide needs repair before it is reliable.

Keep real path data untouched; translate the surrounding purpose and protect example filenames from automatic substitutions. Keep the correction scoped to the responsible layer. A language editor may refine the phrasing, but a command grammar change must be reviewed like a software change; the two decisions should never be confused.

Create two different real files and verify that the documentation reads the one it names. Record the complete invocation, the selected language, the observed value or outcome and the failure status when appropriate. A second reader should be able to reproduce the result without access to the author’s private environment.

15. A handler prints translated JSON field names

Imagine a script that consumes the output breaks when the application changes the key input to a different-language word. For atlas-check, a fictional read-only catalog validator used by contributors across countries, the important question is whether the reader’s intended action actually reaches the right parser field and the right operation. A sentence can look polished and still misdirect the reader toward an invalid input or a false conclusion.

The command handler controls machine output independently of parsing; localized explanations do not justify changing established schema keys. Treat the difference as an observable contract: the source command, the translated instruction and the program’s output should all describe the same behavior. If the user has to infer an undocumented option or a missing value, the guide needs repair before it is reliable.

Keep schema fields stable, offer localized human summaries on a separate channel, and version intentional data-format changes. Keep the correction scoped to the responsible layer. A language editor may refine the phrasing, but a command grammar change must be reviewed like a software change; the two decisions should never be confused.

Feed English and Japanese outputs to a JSON contract test and compare keys, types and identifiers. Record the complete invocation, the selected language, the observed value or outcome and the failure status when appropriate. A second reader should be able to reproduce the result without access to the author’s private environment.

16. A help format is assumed to be fully customizable

Imagine a maintainer asserts that cmd-ts automatically loads gettext catalogs even though the demonstrated example never configures such resources. For atlas-check, a fictional read-only catalog validator used by contributors across countries, the important question is whether the reader’s intended action actually reaches the right parser field and the right operation. A sentence can look polished and still misdirect the reader toward an invalid input or a false conclusion.

A library’s ability to show descriptions does not prove it ships a general language selection system. Treat the difference as an observable contract: the source command, the translated instruction and the program’s output should all describe the same behavior. If the user has to infer an undocumented option or a missing value, the guide needs repair before it is reliable.

Identify text provided by the application and text generated by the installed dependency; customize only documented surfaces. Keep the correction scoped to the responsible layer. A language editor may refine the phrasing, but a command grammar change must be reviewed like a software change; the two decisions should never be confused.

Review the installed release documentation and capture real help output before making any feature claim. Record the complete invocation, the selected language, the observed value or outcome and the failure status when appropriate. A second reader should be able to reproduce the result without access to the author’s private environment.

17. A decoder error loses the offending option

Imagine the translated text says the value is invalid but not whether it belongs to –language or the file positional. For atlas-check, a fictional read-only catalog validator used by contributors across countries, the important question is whether the reader’s intended action actually reaches the right parser field and the right operation. A sentence can look polished and still misdirect the reader toward an invalid input or a false conclusion.

People need a link between the message and an action; a generic message makes trial and error costly. Treat the difference as an observable contract: the source command, the translated instruction and the program’s output should all describe the same behavior. If the user has to infer an undocumented option or a missing value, the guide needs repair before it is reliable.

Display the canonical option or positional role in a stable code span, then explain what acceptable input looks like. Keep the correction scoped to the responsible layer. A language editor may refine the phrasing, but a command grammar change must be reviewed like a software change; the two decisions should never be confused.

Trigger two different invalid arguments and ask a reader to identify which field they must change in each case. Record the complete invocation, the selected language, the observed value or outcome and the failure status when appropriate. A second reader should be able to reproduce the result without access to the author’s private environment.

18. An option value is mistaken for a command

Imagine a user enters a language code before a required subcommand because a translated walkthrough puts it at the beginning. For atlas-check, a fictional read-only catalog validator used by contributors across countries, the important question is whether the reader’s intended action actually reaches the right parser field and the right operation. A sentence can look polished and still misdirect the reader toward an invalid input or a false conclusion.

The same word can be a value or command token depending on the position and schema; prose must preserve that grammar. Treat the difference as an observable contract: the source command, the translated instruction and the program’s output should all describe the same behavior. If the user has to infer an undocumented option or a missing value, the guide needs repair before it is reliable.

Annotate the invocation in order: executable, command, flags, values and positionals, keeping code copyable as one line. Keep the correction scoped to the responsible layer. A language editor may refine the phrasing, but a command grammar change must be reviewed like a software change; the two decisions should never be confused.

Compare the walkthrough with the selected handler and typed argument object after running it. Record the complete invocation, the selected language, the observed value or outcome and the failure status when appropriate. A second reader should be able to reproduce the result without access to the author’s private environment.

19. A nested command’s help omits parent context

Imagine a contributor finds the correct leaf options but does not know which parent command activates them. For atlas-check, a fictional read-only catalog validator used by contributors across countries, the important question is whether the reader’s intended action actually reaches the right parser field and the right operation. A sentence can look polished and still misdirect the reader toward an invalid input or a false conclusion.

Context-free help can be accurate locally while making a task impossible globally. Treat the difference as an observable contract: the source command, the translated instruction and the program’s output should all describe the same behavior. If the user has to infer an undocumented option or a missing value, the guide needs repair before it is reliable.

Give a full path from the root command to the leaf and provide a short breadcrumb sentence in every language. Keep the correction scoped to the responsible layer. A language editor may refine the phrasing, but a command grammar change must be reviewed like a software change; the two decisions should never be confused.

Have a reader navigate from root –help to a subcommand task without viewing the source code. Record the complete invocation, the selected language, the observed value or outcome and the failure status when appropriate. A second reader should be able to reproduce the result without access to the author’s private environment.

20. A command version change alters error wording

Imagine an upgraded dependency changes a generated type error while the site’s translated recovery instructions quote old wording. For atlas-check, a fictional read-only catalog validator used by contributors across countries, the important question is whether the reader’s intended action actually reaches the right parser field and the right operation. A sentence can look polished and still misdirect the reader toward an invalid input or a false conclusion.

Generated messages are unstable across releases unless the library promises otherwise; literal quote-based support can age quickly. Treat the difference as an observable contract: the source command, the translated instruction and the program’s output should all describe the same behavior. If the user has to infer an undocumented option or a missing value, the guide needs repair before it is reliable.

Lock and record the dependency version, rewrite instructions around the failure meaning and maintain versioned snapshots. Keep the correction scoped to the responsible layer. A language editor may refine the phrasing, but a command grammar change must be reviewed like a software change; the two decisions should never be confused.

Run the error fixture before and after the upgrade and compare recognized field, recovery content and exit status. Record the complete invocation, the selected language, the observed value or outcome and the failure status when appropriate. A second reader should be able to reproduce the result without access to the author’s private environment.

21. Multiple values are documented as a single string

Imagine a tutorial shows comma-separated item IDs though the actual option reader expects separate repeated flags or a typed sequence. For atlas-check, a fictional read-only catalog validator used by contributors across countries, the important question is whether the reader’s intended action actually reaches the right parser field and the right operation. A sentence can look polished and still misdirect the reader toward an invalid input or a false conclusion.

A list’s human presentation does not define how command tokens are split or decoded. Treat the difference as an observable contract: the source command, the translated instruction and the program’s output should all describe the same behavior. If the user has to infer an undocumented option or a missing value, the guide needs repair before it is reliable.

Inspect the installed type reader and parser declaration, then show the exact accepted sequence in code. Keep the correction scoped to the responsible layer. A language editor may refine the phrasing, but a command grammar change must be reviewed like a software change; the two decisions should never be confused.

Pass two distinct fixture IDs and verify both are present as separate typed results rather than one combined string. Record the complete invocation, the selected language, the observed value or outcome and the failure status when appropriate. A second reader should be able to reproduce the result without access to the author’s private environment.

22. A localized placeholder becomes a validation rule

Imagine someone changes displayName to a translated phrase and assumes the decoder now accepts localized values. For atlas-check, a fictional read-only catalog validator used by contributors across countries, the important question is whether the reader’s intended action actually reaches the right parser field and the right operation. A sentence can look polished and still misdirect the reader toward an invalid input or a false conclusion.

A placeholder is a readable label; type conversion remains governed by the reader and its error conditions. Treat the difference as an observable contract: the source command, the translated instruction and the program’s output should all describe the same behavior. If the user has to infer an undocumented option or a missing value, the guide needs repair before it is reliable.

Keep a single public value grammar and explain it in each language, or intentionally build and test locale-aware decoding. Keep the correction scoped to the responsible layer. A language editor may refine the phrasing, but a command grammar change must be reviewed like a software change; the two decisions should never be confused.

Submit values from two locales and compare the real decoded object, not only the help string. Record the complete invocation, the selected language, the observed value or outcome and the failure status when appropriate. A second reader should be able to reproduce the result without access to the author’s private environment.

23. An error is printed twice in a wrapper

Imagine a Node wrapper catches the library’s error, prints a translated sentence, then also exposes a second English stack trace. For atlas-check, a fictional read-only catalog validator used by contributors across countries, the important question is whether the reader’s intended action actually reaches the right parser field and the right operation. A sentence can look polished and still misdirect the reader toward an invalid input or a false conclusion.

Multiple uncoordinated layers can overwhelm readers and leak implementation detail in normal failures. Treat the difference as an observable contract: the source command, the translated instruction and the program’s output should all describe the same behavior. If the user has to infer an undocumented option or a missing value, the guide needs repair before it is reliable.

Choose one user-facing diagnostic path, preserve a safe debug mode for developers, and maintain the correct failure status. Keep the correction scoped to the responsible layer. A language editor may refine the phrasing, but a command grammar change must be reviewed like a software change; the two decisions should never be confused.

Capture normal and debug outputs and confirm each has an appropriate audience and no private tokens. Record the complete invocation, the selected language, the observed value or outcome and the failure status when appropriate. A second reader should be able to reproduce the result without access to the author’s private environment.

24. A colorized help screen copies poorly

Imagine a terminal theme makes a highlighted flag readable visually but leaves escape sequences when someone copies output to an issue tracker. For atlas-check, a fictional read-only catalog validator used by contributors across countries, the important question is whether the reader’s intended action actually reaches the right parser field and the right operation. A sentence can look polished and still misdirect the reader toward an invalid input or a false conclusion.

Formatting is not identical to content, and style codes must not become part of a shell command or parser input. Treat the difference as an observable contract: the source command, the translated instruction and the program’s output should all describe the same behavior. If the user has to infer an undocumented option or a missing value, the guide needs repair before it is reliable.

Provide a plain-text path for documentation and automated checks; treat colors as optional decoration. Keep the correction scoped to the responsible layer. A language editor may refine the phrasing, but a command grammar change must be reviewed like a software change; the two decisions should never be confused.

Disable color and compare the visible instructions and exact command tokens with the colored rendering. Record the complete invocation, the selected language, the observed value or outcome and the failure status when appropriate. A second reader should be able to reproduce the result without access to the author’s private environment.

25. Mixed-language help obscures input types

Imagine a localized description explains the task but its file, number and language arguments remain unlabeled in the synopsis. For atlas-check, a fictional read-only catalog validator used by contributors across countries, the important question is whether the reader’s intended action actually reaches the right parser field and the right operation. A sentence can look polished and still misdirect the reader toward an invalid input or a false conclusion.

The user needs a map from each token to its type and purpose; translation alone is not sufficient. Treat the difference as an observable contract: the source command, the translated instruction and the program’s output should all describe the same behavior. If the user has to infer an undocumented option or a missing value, the guide needs repair before it is reliable.

Add a concise parameter glossary showing syntax, value example and effect, without changing the parser declaration. Keep the correction scoped to the responsible layer. A language editor may refine the phrasing, but a command grammar change must be reviewed like a software change; the two decisions should never be confused.

Ask a reader to infer the correct value for every position before running the example. Record the complete invocation, the selected language, the observed value or outcome and the failure status when appropriate. A second reader should be able to reproduce the result without access to the author’s private environment.

26. A command tree appears valid but never reaches a handler

Imagine the application registers a nested parser definition while the translated example points to an obsolete command path. For atlas-check, a fictional read-only catalog validator used by contributors across countries, the important question is whether the reader’s intended action actually reaches the right parser field and the right operation. A sentence can look polished and still misdirect the reader toward an invalid input or a false conclusion.

A successful help render does not demonstrate that the requested handler actually runs when the reader follows it. Treat the difference as an observable contract: the source command, the translated instruction and the program’s output should all describe the same behavior. If the user has to infer an undocumented option or a missing value, the guide needs repair before it is reliable.

Test a non-destructive observable output from the intended leaf handler and keep examples tied to current command registration. Keep the correction scoped to the responsible layer. A language editor may refine the phrasing, but a command grammar change must be reviewed like a software change; the two decisions should never be confused.

Run the documented invocation and assert both handler identity and parsed values. Record the complete invocation, the selected language, the observed value or outcome and the failure status when appropriate. A second reader should be able to reproduce the result without access to the author’s private environment.

27. A command is copied from translated documentation

Imagine a user copies an example that contains a translated flag spelling, and the program rejects it before reaching the intended read-only task. For atlas-check, a fictional read-only catalog validator used by contributors across countries, the important question is whether the reader’s intended action actually reaches the right parser field and the right operation. A sentence can look polished and still misdirect the reader toward an invalid input or a false conclusion.

The parser identifies literal option tokens, not the meaning a translator intended; a sentence and an executable switch have different owners. Treat the difference as an observable contract: the source command, the translated instruction and the program’s output should all describe the same behavior. If the user has to infer an undocumented option or a missing value, the guide needs repair before it is reliable.

Print the actual accepted switch in a code span and translate the explanation beside it. Add a new alias only through a separately tested compatibility change. Keep the correction scoped to the responsible layer. A language editor may refine the phrasing, but a command grammar change must be reviewed like a software change; the two decisions should never be confused.

Copy the command from every language page into a clean shell, and compare parsed arguments and results with the original English fixture. Record the complete invocation, the selected language, the observed value or outcome and the failure status when appropriate. A second reader should be able to reproduce the result without access to the author’s private environment.

28. Quoting a filename that contains spaces

Imagine a reader passes a report named annual review.txt without quotes and sees an unexpected second positional value. For atlas-check, a fictional read-only catalog validator used by contributors across countries, the important question is whether the reader’s intended action actually reaches the right parser field and the right operation. A sentence can look polished and still misdirect the reader toward an invalid input or a false conclusion.

The shell splits the command line before the library parses it. A fluent help paragraph cannot repair tokenization that occurred earlier. Treat the difference as an observable contract: the source command, the translated instruction and the program’s output should all describe the same behavior. If the user has to infer an undocumented option or a missing value, the guide needs repair before it is reliable.

Show a correctly quoted example for each supported shell, explain why the quotes matter, and preserve the actual filename without translating it. Keep the correction scoped to the responsible layer. A language editor may refine the phrasing, but a command grammar change must be reviewed like a software change; the two decisions should never be confused.

Capture the argument array received by the program on the platforms you support; assert that the path is one value rather than two. Record the complete invocation, the selected language, the observed value or outcome and the failure status when appropriate. A second reader should be able to reproduce the result without access to the author’s private environment.

29. Handling a filename beginning with a dash

Imagine an operator inspects a file called -sample.json, but the parser interprets its name as an option. For atlas-check, a fictional read-only catalog validator used by contributors across countries, the important question is whether the reader’s intended action actually reaches the right parser field and the right operation. A sentence can look polished and still misdirect the reader toward an invalid input or a false conclusion.

Option recognition and file naming occupy the same visual space. Some parsers support an explicit end-of-options delimiter, while others need a documented alternative path. Treat the difference as an observable contract: the source command, the translated instruction and the program’s output should all describe the same behavior. If the user has to infer an undocumented option or a missing value, the guide needs repair before it is reliable.

Test whether the installed parser recognizes — as an option terminator; if it does not, demonstrate an absolute or ./ relative path instead. Keep the correction scoped to the responsible layer. A language editor may refine the phrasing, but a command grammar change must be reviewed like a software change; the two decisions should never be confused.

Run the actual unusual filename against a harmless fixture and confirm the exact file was read without treating its first characters as a switch. Record the complete invocation, the selected language, the observed value or outcome and the failure status when appropriate. A second reader should be able to reproduce the result without access to the author’s private environment.

30. An Arabic help page with English command syntax

Imagine a right-to-left paragraph rearranges punctuation around –help, an equal sign and a path, and copying the line fails. For atlas-check, a fictional read-only catalog validator used by contributors across countries, the important question is whether the reader’s intended action actually reaches the right parser field and the right operation. A sentence can look polished and still misdirect the reader toward an invalid input or a false conclusion.

Bidirectional display rules can reorder visible punctuation without changing logical character order, leaving readers unsure which portion is executable. Treat the difference as an observable contract: the source command, the translated instruction and the program’s output should all describe the same behavior. If the user has to infer an undocumented option or a missing value, the guide needs repair before it is reliable.

Keep entire examples in isolated code blocks; explain the right-to-left sentence separately and avoid weaving shell syntax into mixed-direction prose. Keep the correction scoped to the responsible layer. A language editor may refine the phrasing, but a command grammar change must be reviewed like a software change; the two decisions should never be confused.

Copy from the rendered page, inspect code points and received argv, and have a right-to-left-language reviewer finish the same task. Record the complete invocation, the selected language, the observed value or outcome and the failure status when appropriate. A second reader should be able to reproduce the result without access to the author’s private environment.

31. A Japanese terminal with narrow width

Imagine a localized usage screen wraps option names in the middle and makes a required value appear to belong to the next option. For atlas-check, a fictional read-only catalog validator used by contributors across countries, the important question is whether the reader’s intended action actually reaches the right parser field and the right operation. A sentence can look polished and still misdirect the reader toward an invalid input or a false conclusion.

Line breaks come from terminal width, Unicode display width and the chosen formatter; character count alone is not enough. Treat the difference as an observable contract: the source command, the translated instruction and the program’s output should all describe the same behavior. If the user has to infer an undocumented option or a missing value, the guide needs repair before it is reliable.

Use a real CJK terminal test, verify formatter behavior, and split long explanations into short independent sentences without altering the syntax column. Keep the correction scoped to the responsible layer. A language editor may refine the phrasing, but a command grammar change must be reviewed like a software change; the two decisions should never be confused.

Compare help at 40, 60 and 100 columns, using a native-language reader to verify each option remains visually attached to its meaning. Record the complete invocation, the selected language, the observed value or outcome and the failure status when appropriate. A second reader should be able to reproduce the result without access to the author’s private environment.

32. A Turkish locale changes letter casing

Imagine a command resolver or search routine treats case folding as a language-neutral operation and gives inconsistent results around dotted and dotless I. For atlas-check, a fictional read-only catalog validator used by contributors across countries, the important question is whether the reader’s intended action actually reaches the right parser field and the right operation. A sentence can look polished and still misdirect the reader toward an invalid input or a false conclusion.

Program tokens often require invariant normalization. Locale-sensitive casing of identifiers can unintentionally change which option or command is recognized. Treat the difference as an observable contract: the source command, the translated instruction and the program’s output should all describe the same behavior. If the user has to infer an undocumented option or a missing value, the guide needs repair before it is reliable.

Keep canonical identifiers stable and move locale-aware casing to human-facing text only; use explicit comparison rules when command aliases are supported. Keep the correction scoped to the responsible layer. A language editor may refine the phrasing, but a command grammar change must be reviewed like a software change; the two decisions should never be confused.

Run identifier tests under Turkish and English locales, including a negative case, and compare the parser’s selected operation. Record the complete invocation, the selected language, the observed value or outcome and the failure status when appropriate. A second reader should be able to reproduce the result without access to the author’s private environment.

33. Windows Unicode path differs from a Unix run

Imagine a multilingual user enters a filename with accented characters; the desktop run finds the document while the automated build fails to resolve it. For atlas-check, a fictional read-only catalog validator used by contributors across countries, the important question is whether the reader’s intended action actually reaches the right parser field and the right operation. A sentence can look polished and still misdirect the reader toward an invalid input or a false conclusion.

Operating systems, terminal encodings, runtimes and filesystem normalization differ. A displayed string is not proof that equivalent file bytes reach the application. Treat the difference as an observable contract: the source command, the translated instruction and the program’s output should all describe the same behavior. If the user has to infer an undocumented option or a missing value, the guide needs repair before it is reliable.

Keep paths as user data, use the runtime’s supported path APIs, and test the exact packaged binary instead of relying on an editor terminal. Keep the correction scoped to the responsible layer. A language editor may refine the phrasing, but a command grammar change must be reviewed like a software change; the two decisions should never be confused.

Inspect the received path and actual file identity on Windows and Unix; include a decomposed-accent test when the target filesystem makes it relevant. Record the complete invocation, the selected language, the observed value or outcome and the failure status when appropriate. A second reader should be able to reproduce the result without access to the author’s private environment.

34. Localized text escapes into JSON output

Imagine a pipeline expects a JSON object with a stable field name but receives a translated key or a preface sentence in stdout. For atlas-check, a fictional read-only catalog validator used by contributors across countries, the important question is whether the reader’s intended action actually reaches the right parser field and the right operation. A sentence can look polished and still misdirect the reader toward an invalid input or a false conclusion.

Human-oriented prose and machine-readable output use different contracts. A parser upgrade can make this distinction visible if help or warnings are printed unexpectedly. Treat the difference as an observable contract: the source command, the translated instruction and the program’s output should all describe the same behavior. If the user has to infer an undocumented option or a missing value, the guide needs repair before it is reliable.

Reserve stdout for the documented data format, use stderr for human recovery, and only localize fields explicitly defined as display text in the schema. Keep the correction scoped to the responsible layer. A language editor may refine the phrasing, but a command grammar change must be reviewed like a software change; the two decisions should never be confused.

Parse the output with a strict JSON consumer and compare stable keys and value types under two locales; reject any extra banner. Record the complete invocation, the selected language, the observed value or outcome and the failure status when appropriate. A second reader should be able to reproduce the result without access to the author’s private environment.

35. A translated error hides failure status

Imagine the program displays a helpful sentence but returns a success exit code after an unknown flag or missing value. For atlas-check, a fictional read-only catalog validator used by contributors across countries, the important question is whether the reader’s intended action actually reaches the right parser field and the right operation. A sentence can look polished and still misdirect the reader toward an invalid input or a false conclusion.

The operating system and automation tools use exit status, not linguistic politeness, to decide whether a task completed. Treat the difference as an observable contract: the source command, the translated instruction and the program’s output should all describe the same behavior. If the user has to infer an undocumented option or a missing value, the guide needs repair before it is reliable.

Handle parse and validation failures with the intended nonzero status; reserve zero for successful read-only operations and ordinary help according to the application’s policy. Keep the correction scoped to the responsible layer. A language editor may refine the phrasing, but a command grammar change must be reviewed like a software change; the two decisions should never be confused.

Capture stdout, stderr and process status separately for valid, invalid and help invocations; verify the intended distinctions survive translation. Record the complete invocation, the selected language, the observed value or outcome and the failure status when appropriate. A second reader should be able to reproduce the result without access to the author’s private environment.

36. A locale catalog is missing from a release bundle

Imagine a clean installation shows raw translation keys or a blank message even though development tests passed. For atlas-check, a fictional read-only catalog validator used by contributors across countries, the important question is whether the reader’s intended action actually reaches the right parser field and the right operation. A sentence can look polished and still misdirect the reader toward an invalid input or a false conclusion.

The editor’s working directory can contain resources that the published application does not package; the parser may not know about catalogs at all. Treat the difference as an observable contract: the source command, the translated instruction and the program’s output should all describe the same behavior. If the user has to infer an undocumented option or a missing value, the guide needs repair before it is reliable.

Bundle application-owned resources explicitly, choose a reviewed fallback, and record a diagnostic for missing keys rather than silently displaying nonsense. Keep the correction scoped to the responsible layer. A language editor may refine the phrasing, but a command grammar change must be reviewed like a software change; the two decisions should never be confused.

Install from the distributed package in an empty environment and run the same help, error and status-message fixtures for every claimed language. Record the complete invocation, the selected language, the observed value or outcome and the failure status when appropriate. A second reader should be able to reproduce the result without access to the author’s private environment.

37. An error echoes a sensitive argument

Imagine a recovery message repeats a token supplied on the command line that contains a temporary password or private path. For atlas-check, a fictional read-only catalog validator used by contributors across countries, the important question is whether the reader’s intended action actually reaches the right parser field and the right operation. A sentence can look polished and still misdirect the reader toward an invalid input or a false conclusion.

Debugging convenience can reveal secrets in terminal history, CI logs, screenshots or support tickets; translation must not amplify that disclosure. Treat the difference as an observable contract: the source command, the translated instruction and the program’s output should all describe the same behavior. If the user has to infer an undocumented option or a missing value, the guide needs repair before it is reliable.

Use fake values for error fixtures, redact sensitive parameters in public diagnostics, and keep the actionable recovery instruction separate from the raw input. Keep the correction scoped to the responsible layer. A language editor may refine the phrasing, but a command grammar change must be reviewed like a software change; the two decisions should never be confused.

Search captured stdout, stderr and logs for known test secrets and assert that no prohibited value appears under any locale. Record the complete invocation, the selected language, the observed value or outcome and the failure status when appropriate. A second reader should be able to reproduce the result without access to the author’s private environment.

38. The user mistakes help for permission to execute

Imagine a translated description of an inspection tool says that it repairs or approves records although the binary only reads and reports them. For atlas-check, a fictional read-only catalog validator used by contributors across countries, the important question is whether the reader’s intended action actually reaches the right parser field and the right operation. A sentence can look polished and still misdirect the reader toward an invalid input or a false conclusion.

Verbs carry operational promises. Translating inspect as fix can change a reader’s decision even if every option and file path remains correct. Treat the difference as an observable contract: the source command, the translated instruction and the program’s output should all describe the same behavior. If the user has to infer an undocumented option or a missing value, the guide needs repair before it is reliable.

Describe the actual side effect or lack of one in the opening line, the success message and the error recovery; have product owners review action verbs. Keep the correction scoped to the responsible layer. A language editor may refine the phrasing, but a command grammar change must be reviewed like a software change; the two decisions should never be confused.

Ask a new reader to predict what changes before running the command, then compare that prediction with filesystem and output observations. Record the complete invocation, the selected language, the observed value or outcome and the failure status when appropriate. A second reader should be able to reproduce the result without access to the author’s private environment.

A complete reader exercise: from an unfamiliar CLI to reliable translation

Exercise 1: Establish the reference

First, install or build the version your project actually distributes in an isolated environment. Copy the shortest valid invocation into a plain-text file and note the working directory. Put a harmless sample input at the stated path. Run the command and record the result before touching any language strings; this is your reference case.

Exercise 2: Check the reader’s mental model

Second, ask an unfamiliar reader to explain the reference command aloud. Which word is the executable? Which token selects a command or option? Which text is data? Which output signals success? The answers reveal terminology gaps much earlier than a long linguistic review. Write the missing explanations in concise paragraphs.

Exercise 3: Copy from the translated page

Third, prepare a translated explanation of that same invocation. Keep command names, flags, values required by a machine schema and real paths stable. Translate the purpose and recovery instructions. Have the reader copy the command directly from the rendered page, not from a developer’s source file or an unrendered draft.

Exercise 4: Recover from a real error

Fourth, introduce a safe error: omit one required input or supply a value of the wrong type. Let the reader attempt recovery from the translated diagnostic. Record the first incorrect guess. Revise the explanation to identify the relevant parameter, show one valid form and distinguish parsing failure from application-level failure.

Exercise 5: Stress Unicode and rendering

Fifth, repeat with a non-Latin filename and a narrow terminal. Observe whether the path remains intact, help stays readable, and the program reports the same logical result. An international release has succeeded only when usable meaning survives the entire chain from the web page to the running command.

A four-week learning and implementation plan

Week 1 — build the source-of-truth command inventory

Document every supported option and subcommand with its value type, default, requiredness, aliases and actual side effects. Run one success and one failure fixture. Mark strings as executable syntax, application text or generated dependency text. Resolve ambiguous ownership before translation begins.

Week 2 — localize the reader’s decisions

Draft two or three language variants of the first-use help and one recovery path. Keep commands runnable, use explicit values, and make the promise of the operation realistic. Review terminology with a person who understands both the domain and the target language, not merely the sentence structure.

Week 3 — test the boundaries

Run invalid flags, missing values, unexpected positionals, repeated options, Unicode filenames, right-to-left excerpts, narrow terminals and redirected output. Compare typed parsed values, stdout, stderr and exit codes. Reject commands that appear successful after a failure or instructions that cause the wrong operation.

Week 4 — verify the distributed release

Install the actual artifact with its packaged resources in a clean environment. Rerun the fixture matrix, record the runtime and dependency versions, and ask a new reader to complete a realistic task without author assistance. Publish limitations honestly and retain tests for future upgrades.

Frequently asked questions

Should I translate command names and flags?

Translate the description of what the flag does, but keep –language and a positional input path as executable tokens unless the application explicitly registers compatible localized aliases. A copied command is a technical instruction, not prose. Verify the parser accepts every alias you publish.

How do I know an example really works?

Build the documented version of TypeScript cmd-ts, run the command against an isolated fixture and save the parsed inputs, result and status. Repeat after copying from the published page. Do not infer correctness from a syntactically attractive snippet or an old screenshot.

What if a generated error stays in English?

First find which layer owns the error: terminal, shell, TypeScript cmd-ts, decoder or application. Localize application-owned messages where supported; explain a dependency error accurately when customization is unavailable. Never invent a built-in language catalog without documentation and a test.

Does Unicode display prove Unicode correctness?

No. A terminal can display a filename while the application reads a different path, or the copied command may contain a different sequence of characters. Test bytes or code points where appropriate, actual file access and the resulting operation across supported platforms.

Can I change decimal points or other numeric formats?

Only where the application’s value conversion accepts the new representation. A reader-facing number may follow local conventions, but a value in a copyable command has to meet the parser’s real grammar. Run both forms before documenting either.

What do I do when the library version changes?

Treat version upgrades as compatibility events. Rebuild test fixtures, compare accepted tokens, defaults, help, errors and exit status, then update the article if needed. Record what you tested instead of assuming a new version retains the same generated text.

Should a locale alter JSON or CSV keys?

Not silently. Machine-readable keys, delimiters and typed values are contracts with other programs. Put translated wording in designated display fields or a separate human report, and version an intentional schema change rather than slipping it into a language pack.

How can a reader tell the guide is trustworthy?

They can run one short example, predict its effects, find a clear failure recovery and compare the outcome with what the guide promised. This evidence is stronger than keyword density, word count or a convincing explanation unsupported by a working command.

Can automatic translation handle the entire CLI?

It can assist with draft wording, but cannot prove that a parser recognizes a flag, that a typed converter accepts a regional value, that a file is unchanged, or that an error reports failure correctly. Validate machine behavior and reader understanding separately.

What is the first task if time is limited?

Translate the smallest real user task: a valid command, the purpose of its inputs, a predictable success output and one repair instruction. Test those four things under two locales. Then expand to the rest of the command tree without sacrificing correctness.

References and related translation learning

Library examples are sensitive to version and configuration. Consult the official or project documentation below for the actual TypeScript cmd-ts API in your build. The complementary translation material explains broader questions of meaning, source-to-target fidelity and responsible multilingual publication; this article stays focused on this particular command-line framework.

The lasting principle is simple: the reader should be able to perform the same real task safely in any supported language. For TypeScript cmd-ts, preserve recognized tokens and typed inputs, explain commands and failures clearly, and verify what the program does rather than assuming a translation is correct because its sentences sound natural.