Node.js Sade CLI localization makes command-line help, error recovery and examples understandable across languages while preserving the exact flags and commands a JavaScript program recognizes. Readers searching for Sade command aliases, optional arguments, global options, default values, generated –help or multilingual CLI testing need a reliable map between Sade’s command definitions and the sentences visible in a terminal. Translation should make that map clearer, not invent alternate syntax.
Imagine a small team building a read-only project inventory tool. The tool can list a project’s assets, show a summary and accept an optional result limit. A collaborator who reads Spanish may know the translation of ‘list’ but the terminal still expects the registered command list. Worse, if an example puts an optional argument before a required one, Sade may pass values to the wrong handler positions. A polished guide can therefore be technically wrong even when every sentence is grammatical.
This practical guide follows Sade’s documented Program API, global option ordering, .command, .option, .example, aliases, single-command mode and parse behavior. It uses non-destructive examples, explores what the library generates automatically and then teaches a testing method for messages supplied by your application. Readers should leave able to tell what can be translated, what must stay literal and how to make an error useful.
Quick answer: what to localize and what to keep literal
- Keep registered commands, flags, stable data keys, accepted values and exit semantics accurate.
- Translate reader-facing descriptions, task guidance, application messages and recovery steps as complete natural sentences.
- Check working commands, printed help and failure messages in the version actually shipped.
- Use harmless test fixtures, Unicode input and an independent reader to verify that the explanation leads to a correct action.
Start with the real command rather than a translated guess
Sade is a Node.js command-line interface helper whose official documentation describes default commands, git-like subcommands, flags, aliases, defaults, type casting, required and optional positional arguments and generated help. It is not a multilingual translation engine. The application must provide translated descriptions, templates, custom errors and output messages while keeping registered tokens and handler contracts consistent.
One detail is particularly important: Sade’s configuration methods change scope after a command is declared. The official documentation advises defining global version information and options first. That matters to translators because a statement like ‘this option works for every command’ is verifiable only if the option is actually global in the built program. A help screenshot alone may not reveal a scope mistake until someone runs a child command.
Start with one safe inventory action and record three forms: root help, child help and a valid action. Use fixed command names in the runnable examples and complete translated sentences around them. For multilingual validation, capture stdout, stderr and process exit status; then give a reader unfamiliar with the implementation one task that requires interpreting a missing-argument message and completing the command correctly.
A small, read-only Node.js Sade example
#!/usr/bin/env node
const sade = require('sade');
const cli = sade('inventory');
cli.version('1.0.0')
.option('--locale', 'Language used for human-facing messages', 'en');
cli.command('list <project> [category]')
.describe('Preview project inventory without changing files')
.option('--limit', 'Maximum items to display', 10)
.example('list sample-project --limit 5')
.action((project, category, opts) => {
console.log(JSON.stringify({
project, category: category || 'all', limit: opts.limit
}));
});
cli.parse(process.argv);This Sade example is deliberately read-only. It declares a required project, optional category, global locale field and per-command limit. It demonstrates parsing and a machine-readable object, not complete localization: the application would still need catalogs for .describe, .option, examples and human-facing errors. Sade’s documented parse method expects process.argv, not process.argv.slice(2). Confirm the actual installed Sade version before adopting command syntax.
The practical field guide: Node.js Sade localization decisions
1. Program name and invocation
What the software and the language each do. Calling sade with a program name establishes the visible root identity used in generated usage; the translation should not substitute a friendly title for the executable name.
Example for a reader. A distributed team installs an executable called inventory and sees that same literal name in every locale’s copyable examples. A good guide gives the reader a specific value to supply, says what the command will do with it, and distinguishes the program’s accepted spelling from the translated explanation.
How to check and repair it. Run the packaged binary through its real command name, not just a Node source file, and compare the usage prefix with the installed launcher. Compare a working case with one predictable failure and one boundary case. That three-part comparison helps identify whether the difficulty is command syntax, application logic, input encoding or an unclear sentence.
2. Global options before commands
What the software and the language each do. The official guide says global options and version information should be declared before the first command because later configuration methods apply to the current child.
Example for a reader. A contributor adds –locale after defining list and expects it to work everywhere, but its scope may be narrower than the published guide promises. A good guide gives the reader a specific value to supply, says what the command will do with it, and distinguishes the program’s accepted spelling from the translated explanation.
How to check and repair it. Compare root and child help and execute the supposed global flag on multiple registered commands to verify scope. Compare a working case with one predictable failure and one boundary case. That three-part comparison helps identify whether the difficulty is command syntax, application logic, input encoding or an unclear sentence.
3. Version flags
What the software and the language each do. Sade automatically provides –version and -v, using the version set on Program; localized prose should not turn version retrieval into a custom action.
Example for a reader. A user asks what software build they are running before reporting an untranslated error to support. A good guide gives the reader a specific value to supply, says what the command will do with it, and distinguishes the program’s accepted spelling from the translated explanation.
How to check and repair it. Run both built-in spellings from a clean package and verify the displayed number matches the installed artifact. Compare a working case with one predictable failure and one boundary case. That three-part comparison helps identify whether the difficulty is command syntax, application logic, input encoding or an unclear sentence.
4. Required positional syntax
What the software and the language each do. In a command usage string, angle brackets denote required positional arguments and control handler argument order.
Example for a reader. The list command requires a project identifier; documentation that makes project optional sends readers into a missing-argument failure. A good guide gives the reader a specific value to supply, says what the command will do with it, and distinguishes the program’s accepted spelling from the translated explanation.
How to check and repair it. Invoke the route without the project and check that help identifies the absent value and a useful correction. Compare a working case with one predictable failure and one boundary case. That three-part comparison helps identify whether the difficulty is command syntax, application logic, input encoding or an unclear sentence.
5. Optional positional syntax
What the software and the language each do. Square brackets in a usage pattern denote optional positions, but their placement matters when combined with required values.
Example for a reader. A user may pass a category after the project, yet a translated guide accidentally reverses the order in a sample command. A good guide gives the reader a specific value to supply, says what the command will do with it, and distinguishes the program’s accepted spelling from the translated explanation.
How to check and repair it. Test project-only and project-plus-category forms and inspect the handler arguments separately. Compare a working case with one predictable failure and one boundary case. That three-part comparison helps identify whether the difficulty is command syntax, application logic, input encoding or an unclear sentence.
6. Positional handler order
What the software and the language each do. Sade passes defined positional arguments into the action handler in order before the options object; translation must respect that mapping.
Example for a reader. The guide says list photos project-a while the parser expects list project-a photos, producing a misleading summary rather than an obvious syntax error. A good guide gives the reader a specific value to supply, says what the command will do with it, and distinguishes the program’s accepted spelling from the translated explanation.
How to check and repair it. Capture a simple handler output for each documented example and verify which value became project and category. Compare a working case with one predictable failure and one boundary case. That three-part comparison helps identify whether the difficulty is command syntax, application logic, input encoding or an unclear sentence.
7. Commands as literal tokens
What the software and the language each do. Each command route defined by .command becomes part of the accepted interface, distinct from a description of its purpose.
Example for a reader. A Spanish explanation may call list ‘mostrar elementos’ while the actual invocation still starts with inventory list. A good guide gives the reader a specific value to supply, says what the command will do with it, and distinguishes the program’s accepted spelling from the translated explanation.
How to check and repair it. Test every public command name from the translated article, and avoid introducing synonyms unless they are registered. Compare a working case with one predictable failure and one boundary case. That three-part comparison helps identify whether the difficulty is command syntax, application logic, input encoding or an unclear sentence.
8. Nested command routes
What the software and the language each do. Sade treats command words before the first positional token in a usage pattern as the route, so multiword subcommands need precise examples.
Example for a reader. A program supports cache inspect; a guide presents inspect cache because it reads more naturally in another language. A good guide gives the reader a specific value to supply, says what the command will do with it, and distinguishes the program’s accepted spelling from the translated explanation.
How to check and repair it. Run root and nested help and confirm the exact route shown is the one that reaches the intended handler. Compare a working case with one predictable failure and one boundary case. That three-part comparison helps identify whether the difficulty is command syntax, application logic, input encoding or an unclear sentence.
9. Command aliases
What the software and the language each do. Aliases are actual alternate names configured for a command; they need collision checks and may appear in command-specific rather than general help.
Example for a reader. An alias named ls might be a convenience for list, but translators should not assume an unrelated local word is also accepted. A good guide gives the reader a specific value to supply, says what the command will do with it, and distinguishes the program’s accepted spelling from the translated explanation.
How to check and repair it. Execute each registered alias and verify it invokes the canonical handler with identical positional and option behavior. Compare a working case with one predictable failure and one boundary case. That three-part comparison helps identify whether the difficulty is command syntax, application logic, input encoding or an unclear sentence.
10. Alias collision policy
What the software and the language each do. The Sade documentation places responsibility for alias conflicts on the application developer, not on an automatic global resolution layer.
Example for a reader. A new shortcut accidentally duplicates an existing command name after a feature update, making the first matching route difficult to predict. A good guide gives the reader a specific value to supply, says what the command will do with it, and distinguishes the program’s accepted spelling from the translated explanation.
How to check and repair it. Create a command-and-alias inventory and reject duplicate or ambiguous spellings before publishing localized usage examples. Compare a working case with one predictable failure and one boundary case. That three-part comparison helps identify whether the difficulty is command syntax, application logic, input encoding or an unclear sentence.
11. Option aliases
What the software and the language each do. Sade option definitions can include a short and long flag form, and the value passed to a handler follows parser configuration.
Example for a reader. A guide uses -l and –limit interchangeably although only one was registered; users copying the short example get the wrong result. A good guide gives the reader a specific value to supply, says what the command will do with it, and distinguishes the program’s accepted spelling from the translated explanation.
How to check and repair it. Compare every printed alias pair with the actual .option registration and test both forms. Compare a working case with one predictable failure and one boundary case. That three-part comparison helps identify whether the difficulty is command syntax, application logic, input encoding or an unclear sentence.
12. Option descriptions
What the software and the language each do. The description argument of .option is user-visible prose and a natural translation target; the flag string itself is not merely prose.
Example for a reader. An English help line says ‘Maximum items to display’ while a French guide explains the same behavior more naturally without renaming –limit. A good guide gives the reader a specific value to supply, says what the command will do with it, and distinguishes the program’s accepted spelling from the translated explanation.
How to check and repair it. Check generated root and child help for correct descriptions and a runnable value after each option. Compare a working case with one predictable failure and one boundary case. That three-part comparison helps identify whether the difficulty is command syntax, application logic, input encoding or an unclear sentence.
13. Default option values
What the software and the language each do. A default is a parser-provided value when the user omits an option, and its inferred or configured type can influence the handler.
Example for a reader. A numeric limit defaults to ten, but a translated example wrongly implies that the user must always supply –limit. A good guide gives the reader a specific value to supply, says what the command will do with it, and distinguishes the program’s accepted spelling from the translated explanation.
How to check and repair it. Compare the omitted option with an explicit –limit 10 and an alternative count, then document what the installed parser returns. Compare a working case with one predictable failure and one boundary case. That three-part comparison helps identify whether the difficulty is command syntax, application logic, input encoding or an unclear sentence.
14. Type casting of defaults
What the software and the language each do. The documentation describes casting of supplied values relative to configured default types, so the text must not claim all inputs are raw strings.
Example for a reader. A limit default of 10 is numeric; a user passes a word and expects a friendly localized validation message. A good guide gives the reader a specific value to supply, says what the command will do with it, and distinguishes the program’s accepted spelling from the translated explanation.
How to check and repair it. Test numbers, negative values, decimals and invalid strings, then add domain validation where automatic parsing is insufficient. Compare a working case with one predictable failure and one boundary case. That three-part comparison helps identify whether the difficulty is command syntax, application logic, input encoding or an unclear sentence.
15. Boolean flags
What the software and the language each do. An option without a configured value is generally used as a presence flag, not as a natural-language yes/no question.
Example for a reader. The –verbose option changes logging behavior, but the guide should not tell users to type –verbose oui or another word afterward. A good guide gives the reader a specific value to supply, says what the command will do with it, and distinguishes the program’s accepted spelling from the translated explanation.
How to check and repair it. Run the presence and absence forms, checking that a trailing positional argument is not accidentally consumed. Compare a working case with one predictable failure and one boundary case. That three-part comparison helps identify whether the difficulty is command syntax, application logic, input encoding or an unclear sentence.
16. Generated root help
What the software and the language each do. Sade builds a root help screen listing available commands and global options; translating only the child descriptions leaves root navigation partially inaccessible.
Example for a reader. A new reader begins with inventory –help and needs to know which route provides a harmless summary before experimenting. A good guide gives the reader a specific value to supply, says what the command will do with it, and distinguishes the program’s accepted spelling from the translated explanation.
How to check and repair it. Capture the actual root screen and check command summaries, version, global options and the next suggested help command. Compare a working case with one predictable failure and one boundary case. That three-part comparison helps identify whether the difficulty is command syntax, application logic, input encoding or an unclear sentence.
17. Generated child help
What the software and the language each do. Command-specific help describes the route, local options and registered examples, which must be checked separately from the root page.
Example for a reader. A translator fixes the root summary but forgets that list –help still displays outdated English examples from a previous build. A good guide gives the reader a specific value to supply, says what the command will do with it, and distinguishes the program’s accepted spelling from the translated explanation.
How to check and repair it. Run help for every child and compare the same semantics across locales, not just visual style. Compare a working case with one predictable failure and one boundary case. That three-part comparison helps identify whether the difficulty is command syntax, application logic, input encoding or an unclear sentence.
18. Describe versus command signature
What the software and the language each do. .describe adds explanatory text while .command establishes accepted syntax; confusing the two causes translators to present natural sentences as executable verbs.
Example for a reader. A description reads ‘Preview project assets’ but the handler is invoked with list; the prose should clarify the task without changing the command string. A good guide gives the reader a specific value to supply, says what the command will do with it, and distinguishes the program’s accepted spelling from the translated explanation.
How to check and repair it. Inspect the code declaration and generated usage together before editing descriptions. Compare a working case with one predictable failure and one boundary case. That three-part comparison helps identify whether the difficulty is command syntax, application logic, input encoding or an unclear sentence.
19. Example registration
What the software and the language each do. .example adds help examples and prefixes them with the program name, so an example should contain the route and arguments in the documented expected form.
Example for a reader. If the writer includes the program name twice, the help shows a duplicated command that will not run when copied. A good guide gives the reader a specific value to supply, says what the command will do with it, and distinguishes the program’s accepted spelling from the translated explanation.
How to check and repair it. Inspect generated examples and copy each into a clean shell exactly as a novice would. Compare a working case with one predictable failure and one boundary case. That three-part comparison helps identify whether the difficulty is command syntax, application logic, input encoding or an unclear sentence.
20. Required-before-optional order
What the software and the language each do. The Sade manual states that required positional arguments should come before optional ones in usage definitions.
Example for a reader. A command pattern puts [category] before <project> and then readers cannot predict which handler parameter receives their first value. A good guide gives the reader a specific value to supply, says what the command will do with it, and distinguishes the program’s accepted spelling from the translated explanation.
How to check and repair it. Reorder the software definition only with proper change approval; meanwhile document the currently supported safe syntax. Compare a working case with one predictable failure and one boundary case. That three-part comparison helps identify whether the difficulty is command syntax, application logic, input encoding or an unclear sentence.
21. Single-command mode
What the software and the language each do. The Sade Program can be configured for a single-command presentation, with root help that differs from a multi-command application.
Example for a reader. A small one-purpose tool should not display an invented Available Commands panel just to match screenshots from another package. A good guide gives the reader a specific value to supply, says what the command will do with it, and distinguishes the program’s accepted spelling from the translated explanation.
How to check and repair it. Check whether the installed program is single-command and translate only sections that actually appear. Compare a working case with one predictable failure and one boundary case. That three-part comparison helps identify whether the difficulty is command syntax, application logic, input encoding or an unclear sentence.
22. Automatic –help behavior
What the software and the language each do. Sade supplies help handling; a guide should not promise a home-grown –help argument whose behavior differs from the library.
Example for a reader. A user expects –help to display usage, but a custom handler prints a raw object because the application misroutes flags. A good guide gives the reader a specific value to supply, says what the command will do with it, and distinguishes the program’s accepted spelling from the translated explanation.
How to check and repair it. Test root and child –help as subprocesses and verify that help finishes successfully without executing the data action. Compare a working case with one predictable failure and one boundary case. That three-part comparison helps identify whether the difficulty is command syntax, application logic, input encoding or an unclear sentence.
23. Insufficient arguments
What the software and the language each do. The documented behavior reports inadequate required values; a good localization adds context rather than hiding the input contract.
Example for a reader. A novice types inventory list with no project and needs to know what identifier to add and where it goes. A good guide gives the reader a specific value to supply, says what the command will do with it, and distinguishes the program’s accepted spelling from the translated explanation.
How to check and repair it. Capture the real error, keep literal route spelling and present one valid corrected invocation nearby. Compare a working case with one predictable failure and one boundary case. That three-part comparison helps identify whether the difficulty is command syntax, application logic, input encoding or an unclear sentence.
24. Unknown command handling
What the software and the language each do. An unknown command should not be silently reframed as a translated alias unless the application explicitly registers that alias.
Example for a reader. A user types inventario instead of inventory and receives an error; the documentation should help them find the recognized executable and route. A good guide gives the reader a specific value to supply, says what the command will do with it, and distinguishes the program’s accepted spelling from the translated explanation.
How to check and repair it. Test representative unknown commands and distinguish shell command-not-found from Sade’s own parser errors. Compare a working case with one predictable failure and one boundary case. That three-part comparison helps identify whether the difficulty is command syntax, application logic, input encoding or an unclear sentence.
25. Parse argv shape
What the software and the language each do. The upstream API documents prog.parse(process.argv); passing a sliced array can change positions and make working examples fail unexpectedly.
Example for a reader. A copied Node snippet uses process.argv.slice(2) because another library required it; help and action behavior are then inconsistent. A good guide gives the reader a specific value to supply, says what the command will do with it, and distinguishes the program’s accepted spelling from the translated explanation.
How to check and repair it. Follow the exact Sade API and test both the development entry point and the installed package launcher. Compare a working case with one predictable failure and one boundary case. That three-part comparison helps identify whether the difficulty is command syntax, application logic, input encoding or an unclear sentence.
26. Underlying parser configuration
What the software and the language each do. Sade exposes parsing options that integrate with its argument parser, so overrides can alter aliases and defaults in ways a translated guide must reflect.
Example for a reader. A developer passes parse options that replace a previously declared short alias; an older manual still promises the old behavior. A good guide gives the reader a specific value to supply, says what the command will do with it, and distinguishes the program’s accepted spelling from the translated explanation.
How to check and repair it. Inspect final parse settings and compare resolved options in a test invocation rather than trusting only declarations. Compare a working case with one predictable failure and one boundary case. That three-part comparison helps identify whether the difficulty is command syntax, application logic, input encoding or an unclear sentence.
27. Hyphenated option keys
What the software and the language each do. The documentation notes that hyphenated flag names can be accessed as declared within the handler; guessing camelCase names can corrupt application behavior.
Example for a reader. A handler expects opts[‘dry-run’] while a translated example or code snippet invents opts.dryRun without a conversion layer. A good guide gives the reader a specific value to supply, says what the command will do with it, and distinguishes the program’s accepted spelling from the translated explanation.
How to check and repair it. Inspect the actual options object and write samples using the correct property names. Compare a working case with one predictable failure and one boundary case. That three-part comparison helps identify whether the difficulty is command syntax, application logic, input encoding or an unclear sentence.
28. Shell quoting of project names
What the software and the language each do. Project identifiers may contain spaces or punctuation, requiring shell quoting independent of the translation language.
Example for a reader. A Japanese project folder is named Coastal Archive 2026; an example without quotes splits it into several positional arguments. A good guide gives the reader a specific value to supply, says what the command will do with it, and distinguishes the program’s accepted spelling from the translated explanation.
How to check and repair it. Test quoted and unquoted values in Bash and PowerShell and document one portable, verified form per environment. Compare a working case with one predictable failure and one boundary case. That three-part comparison helps identify whether the difficulty is command syntax, application logic, input encoding or an unclear sentence.
29. Unicode filenames and paths
What the software and the language each do. Node.js and Sade can pass Unicode strings, but filesystem encoding and terminal rendering remain separate hazards.
Example for a reader. An Arabic project name parses successfully but fails when a different process assumes ASCII-only paths. A good guide gives the reader a specific value to supply, says what the command will do with it, and distinguishes the program’s accepted spelling from the translated explanation.
How to check and repair it. Test parsing, file lookup and output rendering independently and report which layer failed rather than blaming translation generically. Compare a working case with one predictable failure and one boundary case. That three-part comparison helps identify whether the difficulty is command syntax, application logic, input encoding or an unclear sentence.
30. Internationalized output templates
What the software and the language each do. Sade handles the argument interface, not the grammar of final application sentences; localize complete messages with placeholders.
Example for a reader. A result sentence that reads ‘Found 1 asset’ must have appropriate plurals and word order for the target language. A good guide gives the reader a specific value to supply, says what the command will do with it, and distinguishes the program’s accepted spelling from the translated explanation.
How to check and repair it. Test zero, one and several results with a catalog that preserves project names and counts as data. Compare a working case with one predictable failure and one boundary case. That three-part comparison helps identify whether the difficulty is command syntax, application logic, input encoding or an unclear sentence.
31. Error output and exit code
What the software and the language each do. A translated warning must not return a success status if the tool actually failed; help and errors have different automation implications.
Example for a reader. A CI pipeline relies on nonzero status to stop a broken inventory scan, regardless of whether humans read English or Spanish. A good guide gives the reader a specific value to supply, says what the command will do with it, and distinguishes the program’s accepted spelling from the translated explanation.
How to check and repair it. Capture stdout, stderr and exit codes for invalid syntax and domain failures on every supported platform. Compare a working case with one predictable failure and one boundary case. That three-part comparison helps identify whether the difficulty is command syntax, application logic, input encoding or an unclear sentence.
32. TTY and no-color behavior
What the software and the language each do. Terminal decoration can help navigation, but the text must remain useful in a pipe, log or assistive technology reader.
Example for a reader. A cloud automation job captures raw help without color, while a desktop terminal renders ANSI sequences differently. A good guide gives the reader a specific value to supply, says what the command will do with it, and distinguishes the program’s accepted spelling from the translated explanation.
How to check and repair it. Inspect no-color and noninteractive output and ensure that meaning does not rely on color, spacing or emoji alone. Compare a working case with one predictable failure and one boundary case. That three-part comparison helps identify whether the difficulty is command syntax, application logic, input encoding or an unclear sentence.
33. Package bin mapping
What the software and the language each do. An npm bin entry determines how users invoke a packaged CLI; examples using node src/index.js may fail after publication.
Example for a reader. A package installs an executable named inventory, but a translation guide shows a path that exists only in the repository checkout. A good guide gives the reader a specific value to supply, says what the command will do with it, and distinguishes the program’s accepted spelling from the translated explanation.
How to check and repair it. Install the tarball into a clean project and run the published root and child invocations. Compare a working case with one predictable failure and one boundary case. That three-part comparison helps identify whether the difficulty is command syntax, application logic, input encoding or an unclear sentence.
34. Version and dependency upgrades
What the software and the language each do. CLI behavior may change when Sade or its underlying parser changes, so screenshot-based translations should be tested against the version actually shipped.
Example for a reader. A release updates a dependency and changes parsing of a short flag, leaving translated documentation apparently correct but functionally stale. A good guide gives the reader a specific value to supply, says what the command will do with it, and distinguishes the program’s accepted spelling from the translated explanation.
How to check and repair it. Pin tested versions, review upstream change notes and rerun the command matrix before release. Compare a working case with one predictable failure and one boundary case. That three-part comparison helps identify whether the difficulty is command syntax, application logic, input encoding or an unclear sentence.
35. Security and untrusted strings
What the software and the language each do. Project names and other arguments may be arbitrary user data; localizing output must not turn them into shell commands or executable templates.
Example for a reader. A malicious-looking project name contains quotes and backticks; a reporting tool should display it safely rather than interpolate it into a subprocess command. A good guide gives the reader a specific value to supply, says what the command will do with it, and distinguishes the program’s accepted spelling from the translated explanation.
How to check and repair it. Use harmless but adversarial test strings and keep display escaping separate from command execution logic. Compare a working case with one predictable failure and one boundary case. That three-part comparison helps identify whether the difficulty is command syntax, application logic, input encoding or an unclear sentence.
36. Copy-paste usability
What the software and the language each do. A guide’s practical value comes from whether readers can copy one command, understand the result and recover independently.
Example for a reader. Ask a novice to list five items in a project, inspect help and fix a missing required project without looking at JavaScript source. A good guide gives the reader a specific value to supply, says what the command will do with it, and distinguishes the program’s accepted spelling from the translated explanation.
How to check and repair it. Record the attempted invocation, not just the reader’s opinion, and revise any help line that causes a predictable mistake. Compare a working case with one predictable failure and one boundary case. That three-part comparison helps identify whether the difficulty is command syntax, application logic, input encoding or an unclear sentence.
Three longer case studies: apply the rules in the field
1. A Spanish read-only inventory guide
An inventory team builds a CLI that prints project assets. The Spanish manual initially translates list into a natural verb, but no matching alias is registered. A reader cannot run the example. The team keeps the literal command and improves surrounding explanations, describing the expected project name and limit. It also tests root help and list –help independently, because the latter displays command-specific examples and options. The repaired guide lets a reader copy a real invocation, understand the resulting count and recover from a missing project.
2. An optional argument appears in the wrong place
A JavaScript developer adds an optional category and edits a usage line, while translators revise prose from an older screenshot. The updated command expects project first and category second, but the translated article reverses them. The parser still produces values, making the mistake hard to spot. The team adds a read-only handler test that prints parsed positions, then reruns every sample command. Documentation becomes evidence-led: it describes the installed program’s actual positional order rather than the sequence that reads best in natural language.
3. An npm package differs from the development checkout
Everything works in a local repository where the script is called with node src/cli.js. After publishing an npm package, users see a bin command with different working-directory assumptions. The translated guide references internal paths and fails at the first line. A clean-install test reveals the problem immediately. The team changes only the new guide, preserving stable software commands, and captures root help, child help, Unicode paths and failure status from the installed artifact. This prevents a polished article from being dependent on developer-specific setup.
A repeatable multilingual acceptance test
A strong Node.js Sade translation is not simply a file full of translated strings. It is an interaction that can be completed correctly. Begin with an ordinary reader task and an exact executable. Record the version, terminal, locale, actual command, parsed values, visible output and exit code. Change one language variable at a time. If a failure occurs, ask whether the reader copied a real flag, misunderstood the position of an argument, supplied an unsupported format, or encountered a missing resource. Each explanation requires a different correction.
- Capture root help and every supported child command’s help, including headings, examples and default values.
- Run one successful read-only invocation in each locale, recording exact tokens and parsed results.
- Run a missing-required-input case and verify that the error identifies a copyable correction.
- Run an invalid-value case; check typed parsing, validation advice, stderr and nonzero exit status when appropriate.
- Check spaces, Unicode filenames, diacritics, combining marks and bidirectional punctuation where relevant.
- Inspect both a wide terminal and a narrow one, plus output redirected to a file without interactive styling.
- Build or install the real distributable artifact from a clean environment so translations do not depend on developer paths.
- Keep machine-readable output and accepted command tokens stable unless a deliberate, versioned software change says otherwise.
- Ask an independent reader to complete the task and recover from one mistake using only the published help.
Vocabulary that makes CLI translation easier
- Command
- An executable route recognized by the program; its translated description is not necessarily an accepted alias.
- Option or flag
- A named input, sometimes a switch and sometimes a key that consumes a value. The registered spelling is part of the interface.
- Positional argument
- An input whose location in the command matters. Natural-language word order does not redefine this location.
- Default
- The value used when an input is omitted, which can differ from a mandatory value and from a maximum limit.
- Locale
- A language and regional context for messages and formats; it does not automatically translate machine identifiers.
- Fallback
- The deliberate behavior when a translated message is unavailable. It should preserve meaning rather than silently lose essential instructions.
- Exit code
- The machine-readable result of command success or failure, which must remain dependable for scripts.
- Copyable example
- A tested command using an actual registered route and representative harmless input, not a decorative approximation.
Frequently asked questions
Is Sade a translation framework?
No. It builds and parses a Node.js command-line interface. You can localize application-supplied descriptions, examples and output, but you need your own message catalog and language-selection rules.
Should I translate the list command?
Ordinarily keep the registered route literal. A localized description can explain its purpose. Localized aliases are possible only when they are explicitly implemented and tested for collisions.
How are required arguments marked?
In Sade command usage strings, angle brackets indicate required positional arguments and square brackets indicate optional ones. Their order controls handler parameters.
Why does a global option not appear everywhere?
The official API warns that global configuration belongs before command declarations. Inspect the source declaration order and run each command to verify actual scope.
Does Sade generate help automatically?
Yes, it generates root and command-specific help based on definitions. That help still needs meaningful descriptions and tested examples from the application.
Why is my handler receiving the wrong argument?
Inspect the usage pattern, required and optional order, and handler signature. Sade passes defined positions in order, so a translated example with reordered positions can break tasks.
Can defaults be localized?
Translate what a default means, not a machine value that the parser uses. Test any number parsing, choice validation and locale-specific display outside the argument layer.
What array should parse receive?
The upstream Sade documentation shows process.argv directly. Do not copy slicing conventions from another parser without checking the installed API.
What should I test at release?
Root help, each child help, every advertised flag, aliases, required arguments, invalid values, Unicode project names, packaged bin invocation and exit status.
What is a strong reader task?
Give someone the package and ask them to list five items from a named project, use child help and correct a missing argument without inspecting implementation code.
Four-week practical learning and release plan
Week 1 — map the actual executable
Create a small read-only fixture and record the installed library version, all registered commands, input contracts and generated usage. Capture successful and failing invocations before translating any prose. For each displayed token, mark whether it is a literal command, a placeholder, a value, a sentence or an output field. This inventory prevents friendly translations from becoming false instructions.
Week 2 — write complete human-facing explanations
Prepare natural descriptions, complete output sentences and recovery messages in the intended languages. Preserve commands and values unless software deliberately registers aliases. Include the meaning of defaults, ranges, optional inputs and quoting. Use target-language reviewers who understand the reader’s task but do not need to inspect the implementation. Check fallback behavior with one deliberately missing harmless catalog entry.
Week 3 — test boundaries, packaging and Unicode
Run copied commands under target locales and realistic shells, exercising Unicode paths, spaces, negative and invalid values, missing arguments and terminal width. Capture all output and status codes. Install the distributable artifact in a clean environment and confirm the language resources are actually present. Keep separate checks for machine-consumed output, since a polished translated message can otherwise break automation.
Week 4 — independent completion and maintenance
Give a reader the guide and ask them to finish a task, interpret one failure and retry without a developer. Observe where they hesitate and correct the exact wording or example. Rebuild help snapshots and retest after changing a command, dependency or message catalog. Keep a short release record containing tested locales, commands and unresolved limitations so future updates have a clear baseline.
Final checklist: meaning and executable truth
The practical standard for Node.js Sade is independent completion. A reader should know what command to type, which part of the input is a value, why an option is available, what output to expect, and how to recover if the command is refused. The best translation makes technical syntax less intimidating without falsifying it. Keep the scope of the program modest when teaching, use real fixtures, explain the boundary between parser and application, and document any feature you have not tested as conditional rather than universal.