Node.js mri localization is the practical work of making CLI help and error explanations multilingual while keeping the argument parser’s accepted tokens, aliases, boolean rules and output shape stable. If you are searching for mri argv parsing examples, mri aliases, boolean versus string options, unknown flag behavior, Unicode command lines or a lightweight alternative to minimist and yargs-parser, the key is to separate parsing from translation rather than assuming one library handles both.
The npm mri package is deliberately small: it scans command-line arguments and returns a JavaScript object containing named options and an underscore array for positional values. It can use alias, boolean, string, default and unknown settings. But it is not a full localization framework, does not by itself write a multilingual help page, and does not validate the meaning of every application-specific option. The program around mri must supply accurate help, diagnostics, locale fallback and safety checks.
This world-facing guide follows a fictional read-only command called public-index, used to preview the titles of sample public records without changing the files. It shows how to describe Node.js mri behavior for people reading in French, Japanese, Spanish, Arabic and other languages, how to avoid false promises borrowed from other parsers, and how to verify that a localized instruction really produces the intended result. The first checklist gives the shortest practical answer; the examples and investigations supply the detail.
Fast answer for a stable multilingual Node CLI
- Keep executable flags and registered aliases stable; translate their descriptions.
- Pass user arguments through process.argv.slice(2), not the entire runtime argument vector.
- Define the intended boolean and string flags instead of relying on accidental type inference.
- Check defaults and positional values before writing examples that readers will copy.
- Do not claim mri provides generated help, resource catalogs or all yargs-parser options.
- Treat unknown-flag handling and the specific configured alias map as testable behavior.
- Validate application values after parsing; a string result is not proof of a supported locale.
- Keep structured output keys and exit status separate from human language.
- Test Unicode text, quoting, path data, terminal layout and clean installation.
A minimal parsing example that does not modify any files
const mri = require('mri');
const parsed = mri(process.argv.slice(2), {
alias: { l: 'locale', n: 'limit' },
string: ['locale'],
boolean: ['verbose', 'help'],
default: { locale: 'en', limit: 5, verbose: false }
});
if (parsed.help) {
console.log('Usage: public-index [--locale TAG] [--limit N]');
process.exitCode = 0;
} else {
// Read-only demo: print the parser result only; no files are opened.
console.log(JSON.stringify(parsed, null, 2));
}The code illustrates parsing and an application-owned help branch, not completed internationalization. Real programs should add input validation, supported locale catalogs, responsible error streams and safe task behavior. It is not claiming to read a file, or that the help line is automatically translated by mri. Check this illustrative API against the project’s pinned package version, especially where boolean defaults influence what follows a flag.
What mri provides, and what your application must provide
An argument parser answers a narrow technical question: how should a list of received string tokens become structured data? It does not know whether a language tag exists, whether an input path is authorized, whether the target file is private or whether a message sounds natural to a reader. That distinction stops many translation mistakes before they enter an article or application.
The result’s option keys and positional underscore array are implementation data. They should not be casually translated when downstream code expects them. Human help can describe those keys in Arabic or Japanese while preserving the stable executable tokens. Similarly, a JSON output schema consumed by another program may need to remain language-neutral even when ordinary terminal prose changes.
Defaults are important because they can affect both visible behavior and type inference. A default boolean may cause a following token to be interpreted differently than a default string. A writer who checks only the final English help line can miss that change. For a reliable guide, record the configured options and test exact argv vectors.
mri’s deliberate minimalism is useful when the surrounding program handles validation, usage generation and errors itself. It also means tutorials must not silently import features from minimist or yargs-parser. Compare explicit supported options and data shapes, not performance claims from historical benchmarks, when deciding what the program can promise to international users.
Localization must answer a practical reader question: which exact flag is available, what value does it take, what is the default, what happens if it is omitted and what recovery step is offered on error? A good translation explains those facts in a natural sentence without inventing parser behavior.
Detailed field investigations: from tokens to trustworthy multilingual instructions
1. mri is a parser, not a complete CLI
Start with the confusing result a user might actually see: A reader expects mri itself to print multilingual usage help from a single configuration option. The implementation reason is important: The package converts an array of tokens into a parsed object but does not supply a full application help system.
Build human-facing help and translation catalogs in the application and keep parsing rules separately tested. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Call mri with a safe argument array, then show how the application renders its own help. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
2. process.argv.slice(2)
A polished translated page can hide this precise problem: A translated tutorial passes all of process.argv and the runtime path becomes an apparent positional argument. It occurs because Node supplies runtime and script entries before the user’s command-line tokens.
Use the documented user-argument slice and explain what arrives at the parser. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Print a sanitized argv snapshot and compare it with the expected parsed positional values. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
3. stable –locale flag
Consider an international user copying an example and getting the wrong result. An editor changes –locale into a translated switch, but existing scripts still invoke the old token. At the parser boundary, mri recognizes names from the input and the configured alias map, not meanings inferred from translated prose.
Leave stable option tokens intact and translate their descriptions and examples around them. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Try –locale ja-JP and the unsupported localized spelling. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
4. alias map
This issue is worth testing separately from fluency: A translation says -l and –locale are equivalent without registering the alias. Its technical explanation is that mri can map configured aliases to the same parsed value, but this behavior is not automatic.
Define and test aliases explicitly while documenting one canonical long spelling. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Pass each alias separately and verify the same effective value is available. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
5. alias fan-out
Start with the confusing result a user might actually see: Help names a single alias even though the configured parser exposes several equivalent keys in its result. The implementation reason is important: An alias declaration can replicate values across multiple parsed object properties.
Document which external spellings are supported but avoid exposing redundant internal keys as distinct options. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Inspect the parse result for each accepted token and compare corresponding fields. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
6. boolean list
A polished translated page can hide this precise problem: A help example uses –verbose false with the expectation that the next token will be converted to a boolean value. It occurs because Boolean declaration changes how the parser treats following strings and flag presence.
Show the tested boolean syntax; explain whether a false form exists in this particular program. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Compare absent flag, present flag and the textual false case against a read-only fixture. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
7. string list
Consider an international user copying an example and getting the wrong result. A numeric-looking identifier loses a leading zero after parsing because the option was not marked as a string. At the parser boundary, mri can infer numeric values unless a key is explicitly configured to stay a string.
List identifiers, account-independent codes and formatted values as strings when their exact text matters. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Parse –code 0012 with and without string configuration and compare the result. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
8. default object
This issue is worth testing separately from fluency: The guide says –limit defaults to five, but the configured defaults object contains another value. Its technical explanation is that A default can supply a value and influence type inference during parsing.
Keep displayed defaults synchronized with the actual configuration, not with a copied sentence. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Parse an empty argument list and inspect the resulting limit. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
9. boolean default coercion
Start with the confusing result a user might actually see: A non-boolean value after a flag becomes positional because the configured default for that flag is true. The implementation reason is important: The package uses configured default types when deciding how to interpret incoming values.
Explain that type inference affects token consumption, not only the final output type. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Test –foo bar with and without a boolean default and compare the underscore array. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
10. number inference
A polished translated page can hide this precise problem: A translated example uses a decimal comma, but the parser yields a string rather than the expected number. It occurs because JavaScript numeric syntax and human number formatting are different concerns.
Keep CLI numeric input grammar literal and localize units and explanations separately. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Try 3.5, 3,5 and an invalid number in a safe test. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
11. negative numbers
Consider an international user copying an example and getting the wrong result. A negative numeric value is mistaken for a new short option in an unverified command example. At the parser boundary, Minus-prefixed values may interact with short-flag parsing and require exact syntax testing.
Document the tested way to supply negative values and do not infer from another parser library. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Try each supported negative-value form and inspect whether the intended value is bound. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
12. short flag groups
This issue is worth testing separately from fluency: A tutorial assumes every grouped short flag consumes the next value exactly as minimist does. Its technical explanation is that mri documents short-group behavior that can differ from minimist for similar token sequences.
Use source-specific examples and explicitly verify which member receives a value. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Parse -abc hello with the actual installed mri version and record the result. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
13. single-dash ambiguity
Start with the confusing result a user might actually see: Readers confuse -mode with –mode because a translated screenshot makes both look like a long option. The implementation reason is important: Single- and double-hyphen token syntax is significant for command-line parsing.
Write copyable switch spellings and do not replace doubled hyphens with typographic dashes. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Inspect raw argv bytes from a copied command and verify accepted syntax. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
14. en dash typography
A polished translated page can hide this precise problem: A word processor turns –locale into an en dash followed by locale and a pasted command stops working. It occurs because Typography corrections can corrupt executable tokens without visibly changing the paragraph’s meaning.
Mark code tokens as literal and prohibit smart punctuation transformations inside snippets. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Copy directly from the published article and compare bytes with a tested command. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
15. underscore array
Consider an international user copying an example and getting the wrong result. The translated help says positional arguments have named object fields even though mri stores them under _. At the parser boundary, The result’s underscore property is used for positional values in the documented parser model.
Give positional values application-level names after validation; explain the intermediate shape accurately. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Parse two harmless positionals and inspect _. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
16. the — delimiter
This issue is worth testing separately from fluency: A filename beginning with a dash looks like an option when an example omits a terminator. Its technical explanation is that The actual parser’s treatment of the conventional double-dash marker must be checked rather than assumed from another package.
Publish tested delimiter examples only and explain when values become positional data. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Feed a dash-prefixed fixture after — and inspect the output with the installed version. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
17. unknown callback
Start with the confusing result a user might actually see: A guide implies unknown flags are silently ignored although the application configured an unknown handler. The implementation reason is important: mri supports an unknown callback whose behavior differs from many other parsers.
Describe how the program handles unsupported flags and do not continue normal work after an unexpected invalid input. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Pass an unsupported flag and assert the documented result. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
18. unknown stops parsing
A polished translated page can hide this precise problem: A translated help example promises the parser will continue reading every later flag after an unknown one. It occurs because mri’s documented unknown-handling path terminates parsing when an unknown flag is encountered.
Make the instruction explicit and avoid claims based on minimist’s handling of unknown options. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Place a known flag after an unknown one and inspect the actual result. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
19. unknown handler preconditions
Consider an international user copying an example and getting the wrong result. An application assumes unknown detection works with a callback alone, so unexpected flags slip through. At the parser boundary, The documented behavior of options.unknown depends on the relevant parser configuration, including alias information.
Test the exact configured allowlist rather than treating a callback as a security perimeter. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Supply a typo with and without a populated alias map and compare behavior. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
20. unsupported advanced options
This issue is worth testing separately from fluency: A migration guide copies yargs-parser’s coerce, count and configuration settings into mri. Its technical explanation is that mri deliberately has a smaller configuration surface than larger parsers.
Restrict claims to supported options and implement needed validation in application code. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Audit each configuration key against the installed package’s documented API. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
21. stopEarly confusion
Start with the confusing result a user might actually see: A reader expects an options.stopEarly setting to halt parsing after the first positional token. The implementation reason is important: mri does not advertise the same stopEarly configuration API as minimist.
Avoid copying another parser’s behavior and document the tested token-order policy of this program. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Mix positional and option tokens in several orders and compare parsed output. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
22. dot-notation keys
A polished translated page can hide this precise problem: An article claims –db.host is expanded into nested data as yargs-parser might do. It occurs because mri’s documented comparison notes that dot-nested flags are not treated like yargs-parser’s nested configuration.
Use an explicit application configuration mapper if nested semantics are needed. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Parse a harmless dotted key and inspect the actual object structure. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
23. JSON output keys
Consider an international user copying an example and getting the wrong result. A language review translates keys such as locale and limit in the program’s JSON result. At the parser boundary, Machine-readable property names are protocol elements once consumers depend on them.
Keep output keys stable while translating text labels shown to human users. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Feed a locale-specific sample through the same JSON consumer before and after translation. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
24. help is application-owned
This issue is worth testing separately from fluency: An article says mri automatically generates usage text and gives readers a nonexistent parser method. Its technical explanation is that mri focuses on parsing and returns an object; output formatting belongs to surrounding code.
Implement and test a separate –help branch, or link to the actual CLI framework if another one is used. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Run –help and check the application’s real text and exit status. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
25. help option as boolean
Start with the confusing result a user might actually see: A command’s –help value becomes an unexpected string and the intended early exit is skipped. The implementation reason is important: The application must classify help as a boolean input and respond to its parsed state.
Include help in the boolean configuration and check it before performing any operation. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Run –help with missing normal inputs and confirm no work begins. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
26. misspelled language
A polished translated page can hide this precise problem: A user types –langage and receives a generic message that incorrectly blames the requested language code. It occurs because An unknown option spelling differs from a valid switch whose value is unsupported.
Explain the typo separately from locale-registry validation and offer the supported token. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Test the misspelled switch and an unsupported locale value as distinct cases. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
27. unsupported locale value
Consider an international user copying an example and getting the wrong result. The parser accepts –locale xx-XX, but the article says the requested translation is active. At the parser boundary, Parsing a string does not mean a matching catalog exists or loaded successfully.
Validate against the actual supported-locale list and implement an explicit fallback response. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Request an absent catalog and inspect which language the application really displays. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
28. locale precedence
This issue is worth testing separately from fluency: The tutorial assumes system language always wins, even when a –locale argument is supplied. Its technical explanation is that mri itself only parses argv; prioritizing CLI, environment and configuration is application logic.
Document the implemented precedence clearly with one deliberate conflict example. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Set conflicting values in a safe test and assert which catalog is selected. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
29. pluralized status
Start with the confusing result a user might actually see: An application builds ‘1 files’ or an awkward translated phrase by concatenating fixed fragments. The implementation reason is important: Natural plural forms require complete messages with language-specific forms, outside a lightweight flag parser.
Use localization resources that can express plural selection and preserve numeric data independently. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Test zero, one and several results in each target language. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
30. Arabic direction
A polished translated page can hide this precise problem: A terminal displays Arabic text around –locale and a Latin filename in a visually confusing order. It occurs because Bidirectional rendering affects mixed scripts and punctuation without changing the parsed token values.
Place literal invocation strings separately and check both visual order and copying behavior. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Have a bilingual reviewer copy commands and inspect exact argv sequences. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
31. CJK display width
Consider an international user copying an example and getting the wrong result. Japanese help wrapped by the application’s own formatter causes aligned switches to look disconnected from descriptions. At the parser boundary, Full-width characters and terminal dimensions require real layout tests rather than byte counts.
Test narrow terminals and choose concise wording that still makes each option understandable. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Capture 60-column and 100-column displays for the compiled CLI. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
32. Unicode input preservation
This issue is worth testing separately from fluency: A translated example modifies an accented filename into a different normalized form before lookup. Its technical explanation is that Parsing and filesystem normalization are separate application behaviors and can vary by operating system.
Do not rewrite user-supplied path data unless there is a deliberately implemented normalization policy. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Use NFC and NFD fixtures and compare actual file access in a sandbox. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
33. shell quoting
Start with the confusing result a user might actually see: A path with spaces reaches mri as two values because a guide shows unquoted shell syntax. The implementation reason is important: The shell divides input into argv tokens before mri is called.
Use shell-specific quoted examples and avoid implying Node repairs split tokens automatically. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Log sanitized raw argv for one path containing spaces across supported shells. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
34. stdout and stderr
A polished translated page can hide this precise problem: The application prints a localized error into stdout, where a pipeline expects machine data. It occurs because A parser-only package does not decide which stream should receive application diagnostics.
Reserve stdout for the documented result and stderr for actionable human errors. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Capture streams separately for unknown flags and valid commands. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
35. exit status
Consider an international user copying an example and getting the wrong result. The CLI prints ‘success’ in a translated string while returning a nonzero status after validation. At the parser boundary, Process status and visible prose are independent application responsibilities.
Map successful help, parse rejection and domain failure to documented statuses that do not vary by locale. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Assert the same status for each failure class in English and another language. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
36. unchecked input security
This issue is worth testing separately from fluency: The application treats parsed option values as safe and concatenates them into a shell command. Its technical explanation is that A parser returns user-controlled values; it does not sanitize them for command execution.
Validate allowed values and pass arguments safely to child processes without shell interpolation. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Use an inert punctuation-rich fixture and verify that no extra process action occurs. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
37. special object keys
Start with the confusing result a user might actually see: A CLI accepts arbitrary option names and copies them into application configuration without a key policy. The implementation reason is important: The returned JavaScript object can contain keys that need careful treatment in downstream object merges.
Use an explicit allowlist and safe object handling rather than treating parsed data as trusted settings. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Test reserved-looking keys in a sandbox and inspect the downstream merge path. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
38. secret values
A polished translated page can hide this precise problem: A translation troubleshooting example exposes a real token while trying to illustrate a failed command. It occurs because Raw argv can contain credentials or personal paths and should not be published casually.
Use dummy nonfunctional values and redact sensitive diagnostics before publication. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Search generated screenshots and logs for secrets and personal identifiers. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
39. read-only sample accuracy
Consider an international user copying an example and getting the wrong result. An article calls a tool read-only but its sample command overwrites an output file. At the parser boundary, The parser merely classifies arguments; side effects live in application logic after parsing.
Use harmless fixtures and describe precisely what the sample program does and does not do. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Trace a sample invocation and confirm no write operation occurs. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
40. no automatic validation
This issue is worth testing separately from fluency: A translation promises strict value checking simply because a flag was declared as a string. Its technical explanation is that mri’s parsing does not replace application-specific constraints, ranges or authorization checks.
Validate parsed values before carrying out tasks, and describe the real rejection behavior. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Supply out-of-range and malformed values and verify a targeted failure. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
41. version-specific behavior
Start with the confusing result a user might actually see: A tutorial copies assumptions from a newer package without testing the installed mri revision. The implementation reason is important: Even lightweight parsers should be pinned in the dependency lockfile and reviewed when upgraded.
State the tested package version and keep code examples aligned with that revision. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Install from a clean lockfile and replay the safe parsing fixtures. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
42. minimist comparison
A polished translated page can hide this precise problem: A writer treats mri as a fully compatible drop-in replacement and copies all minimist examples. It occurs because Similar APIs have documented differences in short flags, unknown handling and supported options.
Compare the needed behaviors one by one and document which are not equivalent. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Run the same argv set with each library and inspect the actual results rather than assuming parity. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
43. yargs-parser comparison
Consider an international user copying an example and getting the wrong result. An article treats mri as a substitute for full yargs-parser configuration and localization features. At the parser boundary, mri intentionally has a smaller parsing feature set, so application code may need extra work.
Avoid claiming unsupported nested configuration, coercion or generated usage facilities. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Review each declared feature against the package README and packaged behavior. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
44. no color mode
This issue is worth testing separately from fluency: Error meaning is communicated only by a red color code in a translated terminal message. Its technical explanation is that Presentation belongs to the surrounding CLI and color cannot be relied on in logs or screen readers.
Use textual Warning or Error wording and test a plain-text display. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Run output with color disabled and check whether the message remains actionable. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
45. reader comprehension
Start with the confusing result a user might actually see: A sentence is linguistically polished but the reader still cannot tell whether –limit takes a number. The implementation reason is important: A complete help experience requires type, accepted values, default and consequence, not just lexical accuracy.
Give readers an explicit valid example beside natural prose and an invalid example only when useful. Make the revised explanation concrete enough that someone can predict the result before running the command. Avoid changing stable flag names merely to make them resemble a translated noun; avoid making promises about automatic language support, authorization or file writes that the application does not actually provide.
Ask a new user to predict the result, execute the command and explain the output. Capture the input argv array, the returned object, any application-level validation outcome and the exact help or diagnostic displayed. Compare these observations with what a new reader understands from the localized text. A translation can only be called operationally correct when it teaches a command that the packaged application accepts and describes its consequences truthfully.
Practical design for multilingual help around a small parser
Begin with a written option contract. For each flag, record its spelling, aliases, declared boolean or string treatment, default, accepted values and what downstream code does with the parsed result. Put the translation text in a separate resource table. This prevents translators from confusing a value like ‘fr-FR’ with a phrase like ‘Show the report in French.’
Validate with a deliberate positive and negative matrix. An absent option, a present boolean, a string value, a numeric-looking identifier, a repeated flag, a misplaced positional and an unknown option should not all be described by the same generic message. Each can lead to a different parsed object or recovery step. Use a safe program that merely prints its configuration while developing the examples.
Specify locale precedence in the application. If –locale wins over an environment variable and the default is English, verify that policy with tests. If unsupported languages fall back to English, tell the user what happened. mri accepts a string; it does not guarantee any translation resources exist, and its output alone is not a successful catalog selection.
Build human messages as complete phrases, not concatenations. Pluralization, grammatical agreement and variable placement differ between languages. For values that contain personal information or credentials, choose harmless test placeholders, and avoid printing raw argv in logs that could be published. Distinguish safe explanations from actual user data and command protocol keys.
Review the real terminal, not only the web article. A Japanese description may wrap in a narrow console; mixed Arabic and Latin tokens may appear in an unfamiliar visual order; curly quotes copied from a page can break shell parsing. Check the copied argument bytes and use a competent language reviewer to test whether the meaning is actionable.
Finally, verify the lockfile-installed artifact and the help it produces. A code example that works in one editor is not sufficient if a published package is missing a catalog, if an unknown flag takes an unexpected path or if a consumer relies on stable JSON keys. Make the release checklist prove both natural communication and stable machine behavior.
Frequently asked questions
Does mri automatically translate flags and errors?
No. It is a compact argument parser. The application must provide readable help, translate user-facing messages and validate locale selection, while protecting accepted flag spellings.
Why use options.string for numeric-looking values?
Some identifiers have leading zeros or exact formatting that must remain intact. Parsing them as numbers can destroy that identity even if the screen appears to display the same value.
Does options.unknown always reject mistakes?
Check the documented preconditions and installed behavior. The presence of a callback alone should not be treated as a complete application security or validation policy.
How does mri differ from minimist?
The documented behavior differs for certain short-flag groups, unknown option handling and available configuration options. Test the actual arguments instead of treating the two packages as exact substitutes.
Does mri generate –help automatically?
No. A program can parse a help flag and render its own usage text or use another component, but the guide must attribute that behavior to the correct layer.
Can I translate result object property names?
Not casually if application code or an external consumer depends on them. Translate explanatory labels, while keeping structured keys and command syntax stable unless versioned migration is planned.
Does a parsed –locale value mean translation loaded?
No. The application must resolve the requested tag against actual resources and describe its fallback behavior when that language is unsupported.
How do I test Unicode paths?
Check what the shell passed in argv, what mri returned and what the file-access code did. Use only harmless fixtures and avoid conflating a parser result with filesystem success.
How should failure messages be delivered?
Keep them accurate, actionable and separate from machine-facing data. Where appropriate, use stderr and a documented nonzero status for rejected input.
Release-ready QA checklist
- Pin the mri version in a lockfile and document the test runtime.
- Inventory aliases, string keys, boolean keys, defaults and unknown handling.
- Compare supported argv examples and returned objects across every supported locale.
- Test misspelled flags, wrong value types and unsupported locale tags separately.
- Verify help is provided by the application and does not trigger normal work.
- Keep structured output keys, stdout, stderr and statuses stable.
- Check copied option tokens, narrow CJK layout and Arabic mixed-script readability.
- Run clean-package tests without access to development-only resource files.
- Use dummy input data and remove secrets or private paths from screenshots.
- Ask an unfamiliar user to invoke a safe command and recover from a deliberate error.
Official package reading and related articles
The mri package README and API documentation describe aliases, boolean and string configuration, defaults, unknown handling and documented differences from minimist and yargs-parser. Continue with Master Art of Translation and the Translate Like a Pro series index. This guide is focused on mri’s parser-only behavior; it does not replace the site’s existing minimist or yargs-parser articles.
The strongest international command-line guide connects words to observable behavior. A reader should know exactly which tokens to type, which values are permitted, what the program will do and how to recover from an error. A program should keep its machine contract even when the prose becomes more natural in another language.