Node.js Cleye localization is the work of making a typed command-line application understandable to people working in different languages while preserving the commands and flags the program actually accepts. Anyone searching for Cleye `cli()`, `command()`, typed flags, automatic help, `strictFlags`, unknown flag suggestions and double-hyphen passthrough needs to distinguish executable tokens from explanatory prose. Cleye provides structures for parsing and documenting an interface. It does not automatically make every translated name into a valid command, nor does it choose culturally appropriate examples for users.
Consider a safe `report-preview` program with a positional report name, a `–format` choice and a numeric `–limit` flag. A reader in Portuguese or Japanese may appreciate local-language help explaining these choices, but the software still expects specific flag names and machine-oriented choice values unless the developer deliberately registers alternatives. A typed converter can reject a translated numeric convention. An unknown flag may be rejected under `strictFlags`, and the `–` marker can route subsequent arguments differently. An accurate guide must say which behavior the actual installed application uses.
This guide follows Cleye’s commands, typed flag functions, aliases, defaults, synchronous schemas, Boolean negation, end-of-flags handling, generated help and multilingual terminal tests. It connects common mistakes to specific repairs, tests real invocation outcomes and closes with FAQs and a four-week implementation plan. Its aim is independent practical use: readers can find the correct command in their own language, supply valid values and recover from errors without being shown imaginary syntax.
Quick answer: the key boundaries
- Keep real commands and accepted flags literal.
- Explain machine values separately from translations of their meaning.
- Test strictness, defaults, Boolean negation and end-of-flags explicitly.
- Ship local-language help inside the package users actually install.
1. Cleye parses syntax; the application owns meaning
Cleye is a typed command-line development library for Node.js. Its configuration describes flags, positionals, commands and help information, while the application decides what those inputs do. Translating a help description can improve comprehension, but that change alone does not alter the parser. The first job is to identify the registered command names, the flag keys and the actual types. A useful guide should show an exact working invocation before discussing the finer points of translation. A reader’s ability to complete a harmless task is more important than matching every English phrase.
2. Root CLI and child command have different scopes
The `cli()` function establishes an application’s entry point and its options. The `command()` function can register named subcommands with their own parameters, flags, callbacks and help. Readers need an accurate route from executable name to the child command they want. Do not translate a command name into a new executable token unless a real alias exists. If a child inherits a setting such as strict unknown-flag handling, verify it in the application’s actual configuration. Root help and child help should be tested separately rather than summarized as if they were identical.
3. Typed flag functions are binding rules
Flag declarations can use functions such as String, Number and Boolean, or structured descriptors that also contain aliases, defaults and descriptions. These are not merely input hints. A number is converted according to the active parser, and an unsupported value may fail regardless of local-language expectations. Show the exact input shape accepted by the program. A guide that says a numeric limit can be written in any format may prompt a user to supply a comma decimal separator the converter does not accept. Include a valid and a deliberately invalid example.
4. Machine values and translated meanings must be distinct
A format value such as json, yaml or csv may be an application-defined choice. Its display meaning can be explained in the reader’s language, but the token remains literal unless a compatible alias is implemented. This same distinction applies to short flag aliases and enum-like converters. A translation should show one column for what the user types and another for what it means. It should never mix prose and code in a way that makes a placeholder look like a fixed literal value.
5. Strictness controls the treatment of unknown flags
Cleye documents `strictFlags` for rejecting unsupported flag names; in relevant cases it can offer close-spelling suggestions. A suggestion is not an automatic correction. The user must still run the intended command using an accepted flag. When strictness is not enabled, unknown flags may be made available for other handling, so the article should not promise an error in every program. Investigate the actual root and child settings, including whether inheritance has been overridden. A good recovery message names the accepted spelling and indicates what action to take next.
6. The double-hyphen boundary protects forwarded data
The `–` marker signals end-of-flags behavior. Cleye’s documentation describes access to the following arguments and permits a defined parameter shape for passthrough input. This is useful for a program that wraps another tool or needs a filename beginning with a hyphen. Explain precisely which arguments belong to the current CLI and which are being passed along. Do not translate or restyle the two hyphens. They are executable syntax. Provide a harmless example and inspect the received data rather than relying on a screenshot.
7. Help and version are their own user experience
Common help flags can be managed automatically, and version handling can be configured. That does not establish that every generated phrase is localized or that a particular application’s version flag exists. The safest approach is to test the deployed binary’s help and version behavior directly, then translate application-owned descriptions and examples. If a developer provides a custom help renderer, check that it still displays registered options, aliases and required parameters. Help that looks polished but sends readers to unsupported syntax is worse than a modest, accurate screen.
8. Defaults must be verified where they are defined
Cleye’s documentation notes a distinction between defaults specified in flag configuration and defaults inside some schema integrations, which may apply only when the flag is present. Therefore a translated line such as ‘uses five unless supplied’ must be tested for the absent case as well as a provided value. Prepare a small matrix: absent, valid input and invalid input. Describe the actual resulting value for each. Never use a translation to conceal a discrepancy between the application developer’s intent and the program’s behavior.
9. Custom converters create new contracts
The library supports custom flag type functions, and it documents format helpers such as constrained choice values, comma-separated lists and numerical ranges. A locale may use a different punctuation convention, but the converter’s input grammar remains the deciding factor. A reader needs to know whether to type a comma, a repeated flag or a specific machine token. Explain accepted examples without promising regional variants that were never implemented. Check one successful and one unsuccessful input and record the parsed values.
10. Boolean negation requires configured behavior
The exact support for negated Boolean flags can depend on application settings. A translated explanation should not turn ‘off’ into an invented language-specific switch. Show how the actual executable expresses true and false, and document the default so readers can decide whether they need a flag at all. A good guide also distinguishes a Boolean state from a missing option. Confirm both paths with execution and observe the callback’s received value, rather than assuming semantics from the name.
11. Callbacks and process lifecycle are separate concerns
A Cleye command can invoke an application callback, including asynchronous work in supported patterns. Parsing a value successfully does not guarantee that the requested operation finishes or that a promise is handled correctly. For a translation lesson, keep examples read-only and inspect both the parsed input and the final output. Differentiate parser errors, application validation errors and runtime failures. That distinction lets the reader choose a valid remedy rather than trying different flag spellings when the program itself has a bug.
12. Delivery must be tested from a clean installation
A TypeScript source file may work in development and fail after bundling or publishing because entry points, module resolution, Node.js versions or locale resources differ. Build the package users actually run, test its executable name and verify root and child help in a clean environment. Use Unicode sample names and shell-specific quoting where platforms are claimed. Capture stdout, stderr and exit status separately. Locale fallback must remain readable even when a target-language catalog is not available.
13. Write for discovery and independent success
A practical multilingual guide should answer: Which command do I choose, which token do I type, what value is accepted and what should I do when it fails? These are not abstract translation questions. They are the user decisions that make a tool approachable. Ask a target-language reader to execute a harmless preview and recover from one unknown flag. If they must inspect source code or original English help, revise the exact explanation that caused confusion and run the same test again.
48 concrete troubleshooting investigations
Investigation 1: Registered command
What happens. A local-language guide gives a translated command name as an executable verb. Why. Commands must be registered by the application. That distinction determines whether the documentation is an executable guide or merely an attractive paraphrase.
What to change. Keep actual route tokens in code examples and translate their meaning beside them. How to prove it. Root-to-child invocation reaches the intended callback. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 2: Command alias
What happens. A shortcut is promised although no command alias was configured. Why. Alias names are executable behavior rather than ordinary prose. Be careful not to infer behavior from translated terminology; use the actual parsed value as evidence.
What to change. Use only registered command aliases or implement and test a new one. How to prove it. Both documented spellings invoke the same command. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 3: Root flag scope
What happens. A child-only flag is shown at the root level. Why. Root and command-specific configuration are different boundaries. One read-only test prevents this mistake from reaching shell scripts that people may rely on later.
What to change. Capture help for the correct scope and label each flag accordingly. How to prove it. Every demonstrated invocation uses accepted scope. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 4: Child flag scope
What happens. A guide assumes all root flags are available inside every child command. Why. Inheritance and override behavior depend on configuration. Place the recognized token in code styling and keep the language explanation in ordinary prose.
What to change. Check the actual registered command options. How to prove it. The child accepts exactly the flags the guide claims. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 5: CamelCase key
What happens. The code contains someBoolean while the guide invents –someBoolean syntax. Why. Cleye supports command-line naming conventions that may use hyphens. A newcomer should be able to identify the required action without guessing a new option name.
What to change. Take literal flag spellings from the generated CLI help. How to prove it. The published example parses successfully. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 6: Short alias
What happens. An editor picks an unregistered short letter based on another language. Why. Aliases must be part of the flag descriptor. Use a real packaged executable because development runners can hide missing resources and entry-point mistakes.
What to change. Keep the real alias and its purpose distinct. How to prove it. The short and long forms map to the same parsed key. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 7: Alias collision
What happens. Two flags are assigned a common -f alias in a growing command. Why. One short spelling cannot identify both intents reliably. The change belongs either in application code or in explanatory copy; decide which before changing both.
What to change. Audit registered aliases before introducing them. How to prove it. Every alias resolves without ambiguity. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 8: String flag
What happens. A value is described as a numeric limit although the type is String. Why. The declared converter determines the resulting type. Terminal presentation is only one part of correctness. What the callback receives matters equally.
What to change. Match help wording to the real type and application validation. How to prove it. The callback receives the expected string. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 9: Number flag
What happens. A localized sample uses words as though a numeric flag accepts them. Why. Number conversion does not infer human-language number words. That distinction determines whether the documentation is an executable guide or merely an attractive paraphrase.
What to change. Give accepted number tokens and an error example. How to prove it. A valid value converts and invalid text is rejected. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 10: Boolean flag
What happens. Help says users should enter translated yes or no values after a switch. Why. Boolean input has parser-specific syntax. Be careful not to infer behavior from translated terminology; use the actual parsed value as evidence.
What to change. Show the actual presence and value behavior rather than assuming natural words. How to prove it. True and false tests match the received state. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 11: Boolean negation
What happens. A guide invents –no-preview although the application disables negation. Why. Negated flags depend on booleanFlagNegation settings. One read-only test prevents this mistake from reaching shell scripts that people may rely on later.
What to change. Document enabled behavior and test both forms where supported. How to prove it. A rejected negation is never advertised as valid. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 12: Default string
What happens. The page claims a default file format that the schema does not supply. Why. Defaults must come from the actual flag configuration. Place the recognized token in code styling and keep the language explanation in ordinary prose.
What to change. Declare and document the real default at the supported level. How to prove it. The absent case receives the promised value. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 13: Schema default
What happens. A Zod default is assumed to apply when the flag is omitted entirely. Why. Cleye’s docs warn some schema defaults run only when a flag is present. A newcomer should be able to identify the required action without guessing a new option name.
What to change. Use the flag-level default when required and verify absence. How to prove it. Omission and explicit input have tested results. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 14: Synchronous schema
What happens. A guide claims asynchronous validation is awaited inside flag conversion. Why. Supported schema integrations require synchronous parsing. Use a real packaged executable because development runners can hide missing resources and entry-point mistakes.
What to change. Keep async checks after argument parsing rather than hiding them in the schema. How to prove it. No unhandled promise occurs during a bad input. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 15: oneOf value
What happens. A local-language synonym is substituted for a machine choice such as json. Why. The enum-like converter accepts only registered alternatives. The change belongs either in application code or in explanatory copy; decide which before changing both.
What to change. List each literal choice and explain its meaning separately. How to prove it. All documented values parse and an unsupported one fails. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 16: Range value
What happens. A port outside a bounded numeric range is described as acceptable. Why. The range helper validates its specified boundaries. Terminal presentation is only one part of correctness. What the callback receives matters equally.
What to change. Explain the actual endpoints with a simple example. How to prove it. Both boundary tests and a rejected outside value are observed. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 17: Comma list
What happens. A translated sample uses semicolons for the documented comma-list input. Why. Machine separators are parser syntax rather than local punctuation. That distinction determines whether the documentation is an executable guide or merely an attractive paraphrase.
What to change. Retain the expected delimiter and explain it. How to prove it. Two list items reach the callback in the correct order. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 18: Array flag
What happens. Help implies the flag accepts only one value although the type is a list. Why. An array-valued flag may accept repeated input. Be careful not to infer behavior from translated terminology; use the actual parsed value as evidence.
What to change. Demonstrate the configured list syntax using two harmless values. How to prove it. The resulting collection has the expected length. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 19: Equal sign
What happens. An editor removes the equal sign in –format=json thinking it is typography. Why. Value delimiters form part of accepted CLI grammar. One read-only test prevents this mistake from reaching shell scripts that people may rely on later.
What to change. Show the supported forms as literal code. How to prove it. The installed parser accepts each printed form. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 20: Colon delimiter
What happens. A translated invocation changes the colon used by a supported input form. Why. Specific delimiter punctuation can be executable syntax. Place the recognized token in code styling and keep the language explanation in ordinary prose.
What to change. Document punctuation exactly as supported by the parser. How to prove it. The provided value is parsed correctly. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 21: Combined aliases
What happens. A guide combines short flags without checking whether every one exists. Why. Bundled short-option behavior depends on registered aliases. A newcomer should be able to identify the required action without guessing a new option name.
What to change. Demonstrate only supported combinations. How to prove it. Combined input yields the intended collection of flags. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 22: Missing flag value
What happens. The example ends with –format but supplies no format name. Why. A typed option may require a value token. Use a real packaged executable because development runners can hide missing resources and entry-point mistakes.
What to change. Show a complete invocation and identify the value placeholder. How to prove it. The incomplete case fails with a clear next step. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 23: Unknown strict flag
What happens. The manual says unknown flags are ignored but strictFlags is on. Why. Strict mode can reject names the application does not recognize. The change belongs either in application code or in explanatory copy; decide which before changing both.
What to change. Explain strictness and show the correct recognized spelling. How to prove it. Bad syntax fails and corrected syntax succeeds. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 24: Unknown loose flag
What happens. The guide promises an error although strictFlags is disabled. Why. Unknown flags may be made available for application handling. Terminal presentation is only one part of correctness. What the callback receives matters equally.
What to change. Explain the program’s actual unknownFlags policy. How to prove it. An unknown input has an explicitly documented outcome. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 25: Did-you-mean hint
What happens. A suggestion is described as though the parser changed and ran the input automatically. Why. Diagnostic suggestions do not execute corrected commands. That distinction determines whether the documentation is an executable guide or merely an attractive paraphrase.
What to change. Tell readers to rerun using the accepted spelling. How to prove it. The original typo fails and correction works. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 26: Command override
What happens. A child command behaves differently from its parent’s strictFlags setting. Why. Commands can override inherited behavior. Be careful not to infer behavior from translated terminology; use the actual parsed value as evidence.
What to change. Document the effective setting for each route. How to prove it. Both parent and child tests show intended distinction. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 27: Double hyphen
What happens. A filename starting with – is interpreted as an option. Why. Without a separator the parser may treat data as flags. One read-only test prevents this mistake from reaching shell scripts that people may rely on later.
What to change. Place — at the supported boundary. How to prove it. A dash-prefixed filename reaches the intended parameter. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 28: Passthrough values
What happens. Arguments after — are incorrectly described as root options. Why. Cleye exposes end-of-flags inputs separately. Place the recognized token in code styling and keep the language explanation in ordinary prose.
What to change. Show exactly which component receives those strings. How to prove it. The downstream data array is observed without modification. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 29: Named positional
What happens. A translated example omits the required report name. Why. The parameter declaration defines a positional input. A newcomer should be able to identify the required action without guessing a new option name.
What to change. Show the literal route followed by the required sample value. How to prove it. The callback receives the expected report name. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 30: Optional positional
What happens. The manual tells users to type square brackets literally. Why. Brackets can indicate optionality rather than actual characters. Use a real packaged executable because development runners can hide missing resources and entry-point mistakes.
What to change. Explain notation and supply a concrete working value. How to prove it. Omitted and provided cases both have known results. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 31: Variadic positional
What happens. An example expects many files but documents only one item. Why. Rest parameters can accept collections of values. The change belongs either in application code or in explanatory copy; decide which before changing both.
What to change. Show how additional values are placed after the route. How to prove it. Two sample items arrive separately. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 32: Help disabled
What happens. The guide recommends –help although automatic help was disabled. Why. The help option can be configured off. Terminal presentation is only one part of correctness. What the callback receives matters equally.
What to change. Document the actual alternate help route or enable the feature. How to prove it. Reader can reach help using a published invocation. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 33: Help renderer
What happens. A custom help function omits the required positional name. Why. Display customization may lose vital parser facts. That distinction determines whether the documentation is an executable guide or merely an attractive paraphrase.
What to change. Compare rendered help against registered parameter and flag definitions. How to prove it. A reader sees every required input and alias. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 34: Version option
What happens. An article claims –version exists without configured version support. Why. Automatic version handling needs a version setting. Be careful not to infer behavior from translated terminology; use the actual parsed value as evidence.
What to change. Configure version or remove the inaccurate instruction. How to prove it. Printed version matches the installed package. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 35: Child help
What happens. A screenshot of root help is presented as the child’s complete instructions. Why. Each command can have its own help surface. One read-only test prevents this mistake from reaching shell scripts that people may rely on later.
What to change. Capture and translate route-specific help independently. How to prove it. Child help lists child-relevant flags. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 36: Long translation
What happens. A German option description pushes short flags off a narrow screen. Why. Text length and terminal cell width affect usability. Place the recognized token in code styling and keep the language explanation in ordinary prose.
What to change. Use concise phrases and verify short terminal columns. How to prove it. Names and meanings remain easy to pair. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 37: RTL text
What happens. An Arabic description visually reorders Latin flags. Why. Bidirectional rendering affects appearance separately from argv. A newcomer should be able to identify the required action without guessing a new option name.
What to change. Isolate executable code and test target-language layout. How to prove it. The reader can copy the exact recognized token. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 38: Unicode input
What happens. A Japanese report name appears differently inside a callback. Why. Terminal and shell encodings affect strings around the parser. Use a real packaged executable because development runners can hide missing resources and entry-point mistakes.
What to change. Use actual Unicode test values and capture received data. How to prove it. No characters are silently lost. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 39: Space quoting
What happens. A filename with spaces is split into several positionals on one shell. Why. Shell preprocessing occurs before Cleye sees argv. The change belongs either in application code or in explanatory copy; decide which before changing both.
What to change. Provide verified quoting for every supported shell. How to prove it. The callback receives a single intended filename. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 40: Environment expansion
What happens. A dollar-sign value changes before reaching the parser. Why. Shell expansion is not the same as Cleye conversion. Terminal presentation is only one part of correctness. What the callback receives matters equally.
What to change. State when expansion is desired and show safe quoting. How to prove it. The observed value matches the explanation. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 41: Callback promise
What happens. A command appears successful even though asynchronous work did not finish. Why. The application must manage its callback lifecycle. That distinction determines whether the documentation is an executable guide or merely an attractive paraphrase.
What to change. Await supported asynchronous work and handle failures. How to prove it. A read-only async task completes before process exit. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 42: Application error
What happens. A report-not-found failure is explained as a parser syntax error. Why. Successful parsing does not guarantee the requested operation works. Be careful not to infer behavior from translated terminology; use the actual parsed value as evidence.
What to change. Separate application validation from input grammar issues. How to prove it. The user gets a relevant next action. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 43: Standard error
What happens. A tester reads only stdout and misses invalid-flag messages. Why. Help and failures can use different output streams. One read-only test prevents this mistake from reaching shell scripts that people may rely on later.
What to change. Capture stdout and stderr independently. How to prove it. The failure explanation is observable where expected. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 44: Exit status
What happens. A test treats a displayed error as success. Why. Output text alone does not prove successful completion. Place the recognized token in code styling and keep the language explanation in ordinary prose.
What to change. Assert process status for help valid input and invalid input. How to prove it. Statuses match the application’s declared behavior. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 45: Bundle resources
What happens. Translated help disappears after building the Node distribution. Why. Bundlers can omit locale files or alter module resolution. A newcomer should be able to identify the required action without guessing a new option name.
What to change. Test a clean installation of the final package. How to prove it. All claimed locale resources load correctly. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 46: Runtime version
What happens. An example relies on newer Node syntax than the supported environment. Why. Tooling and module features depend on runtime version. Use a real packaged executable because development runners can hide missing resources and entry-point mistakes.
What to change. State and test supported Node.js versions. How to prove it. The released executable starts and prints help. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 47: Locale fallback
What happens. A requested translation is absent and the CLI shows a blank help screen. Why. The application needs explicit fallback rules. The change belongs either in application code or in explanatory copy; decide which before changing both.
What to change. Provide a readable fallback without changing command syntax. How to prove it. Unknown locale still yields usable help. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Investigation 48: Independent reader
What happens. A reviewer likes the translated text but cannot use the CLI. Why. Editorial review and completed user task are separate measures. Terminal presentation is only one part of correctness. What the callback receives matters equally.
What to change. Ask an unfamiliar reader to run and repair a safe preview. How to prove it. The reader succeeds without original-language documentation. Keep the tested command, output, process status, locale and installed package version alongside the explanation. A reviewer should be able to reproduce the behavior without trusting an old screenshot or a developer’s memory.
Frequently asked questions
Does Cleye automatically translate flags?
No. It is a typed command-line development tool. The application must provide local-language descriptions and decide whether to register any additional aliases. A translated word in help is not automatically an accepted command token.
What is strictFlags for?
When enabled, it rejects unknown flags and can suggest close spellings. A suggestion is not an automatic correction, and disabling strictness may permit application-specific handling of unknown flags instead. Describe the actual program setting.
What happens after –?
The literal double hyphen ends normal flag interpretation. Cleye documents ways to access the following tokens as passthrough data. Those tokens are not necessarily parsed as flags for the current command.
Can an allowed value be translated?
Its meaning can be translated. The value itself, such as json or csv in a oneOf converter, remains a registered machine token unless software explicitly recognizes another form. Keep values and explanations separate.
Why is a schema default not always enough?
The project documentation notes that some schema validation applies only when a flag is present. Use the supported flag-level default where the absence case needs one, and verify with a real omitted-flag test.
Are Boolean negated flags universal?
No. They depend on the effective configuration. Verify the actual application’s supported positive and negative forms, and clearly state the default.
What is the difference between parsing and a completed command?
Parsing produces typed input. A callback may still fail, reject business-level values or perform asynchronous work. Guide readers toward the correct layer of recovery rather than blaming every later failure on flag syntax.
How do you demonstrate multilingual readiness?
Give the final installed command to a target-language reader. Ask them to discover a safe route, choose a format, set a limit and recover from an unknown flag. If they cannot do so without English source material, revise the relevant instruction and retest.
A four-week implementation and release plan
Week 1 — establish commands and typed inputs
Create a read-only report-preview command with a name parameter, format choice, numeric limit and Boolean display setting. Record the real flags, command routes, aliases, defaults and strictFlags settings. Capture help, a valid preview, a wrong number, an unknown flag and an end-of-flags example. Observe actual parsed values. The purpose of this week is to know what the program does before asking translators to explain it.
Week 2 — write local-language guidance and validate help
Translate the purpose of each command and flag, keeping machine tokens and choice values literal. Test English plus two target languages, including one different script where appropriate. Examine root and child help on narrow terminals; check whether aliases and required parameters remain visible. Ask a reader to copy each example exactly. If someone types a translated flag instead of the real one, revise the presentation and rerun the example.
Week 3 — test parsing boundaries and installed packages
Test strict and permissive unknown-flag behavior, Boolean negation, — passthrough, custom converters, valid and invalid choices, and defaults with omitted flags. Capture stdout, stderr, result values and exit status. Build the actual Node package, install it cleanly and confirm help and catalogs survive packaging. Check supported Node versions and shell quoting with Unicode sample names. Include a missing-locale fallback case.
Week 4 — run independent task completion
Give an installed executable and target-language guide to someone who has never seen the source configuration. Ask them to find the report-preview route, choose a valid format, set a limit and recover from an unsupported flag. Watch for confusing placeholders, machine choices and command scope. Revise those points and repeat the test. Establish an ownership rule: any change to a flag, alias, type, command name or strictness setting triggers a review of all language materials.
Release acceptance
A multilingual Cleye CLI is useful when people can predict and execute the interface they are reading about. The help explains real commands, accepted values, default behavior, strictness and the role of the double-hyphen marker. It also makes a distinction between parser failures and problems inside application callbacks. The final product is not the translated text alone; it is a clean executable and accurate instructions that let readers complete a task independently.