Cocona CLI localization in .NET means giving international users accurate commands, understandable parameter descriptions and reliable help without changing the syntax that the executable really accepts. Developers searching for CoconaApp, AddCommand, ICoconaLocalizer, Microsoft.Extensions.Localization, IStringLocalizer, ArgumentAttribute and multilingual help need a concrete workflow. Cocona builds command-line applications from delegates or public methods, but a translated description is not an automatically registered command alias. This guide explains that boundary before showing how to test it.
Consider a harmless report-preview application used by colleagues in Japan, France and Brazil. It has a literal preview command, a file argument, an optional row limit and a verbose switch. Users should be able to discover each option in their language while typing the exact flags used by the program. They also need to know whether a limit is required, how missing values are treated and whether the published executable contains all language resources. A beautiful help screenshot does not establish that an installed tool will run.
The following practical guide covers Cocona minimal-style and class-based commands, typed option binding, command groups, localization services, custom help, parser diagnostics, Unicode paths and distribution. It separates documented framework capabilities from choices that belong to the application. Examples favour read-only report previews rather than destructive actions, and each topic provides a test a reader or maintainer can reproduce. The aim is a CLI that people can use independently, not merely one that appears translated.
Quick answer: what to localize and what to preserve
- Translate descriptions and recovery guidance; preserve literal executable command names unless aliases are registered.
- Verify typed parameters, requiredness and defaults using the installed application.
- Wire resource lookup explicitly and test generated help separately from handler messages.
- Test Unicode paths, multiple shells, missing catalogs, exit codes and packaged artifacts.
A practical Cocona report-preview example
Start with a tiny, read-only application rather than translating a complicated deployment utility. The example below registers a named command, accepts a filename as a positional argument and an optional limit as a typed option. It prints a summary instead of opening or editing the file. The generated help will tell you the exact option names for the package and Cocona version you installed. A production tool can replace the print action with a carefully validated read-only preview, but the first translation test should remain safe and observable.
using Cocona;
var app = CoconaApp.Create();
app.AddCommand("preview", ([Argument] string file, int limit = 10, bool verbose = false) =>
{
Console.WriteLine($"File: {file}; limit: {limit}; verbose: {verbose}");
}).WithDescription("Preview a report without modifying files.");
app.Run();After compiling, first use the generated root help and preview help to confirm the actual grammar; then run a safe invocation with a file name such as sample.csv and a numeric limit. The exact executable name depends on your build and launch method. In multilingual documentation, show the real executable that users install rather than copying an internal project placeholder. To localize help descriptions, use the documented Cocona localization integration and test the registered adapter in your own project. The snippet demonstrates parsing, not automatic translation.
How to design an accurate multilingual Cocona interface
1. Command language is not command identity
The principle. Cocona binds a registered command route to executable behavior. Human-language explanations can differ by locale, but the parser still matches configured command names and aliases. Changing the label of preview in a manual does not create a French or Japanese route. This distinction matters because command-line documentation is operational: the reader will often copy an instruction exactly and expect the same result.
Reader-facing example. Publish a two-column instruction: command to type on one side, explanation in the selected language on the other. Treat new aliases as product changes, with collision review, compatibility notes and tests in every supported shell. Present real tokens and replaceable values separately, so that a translated sentence does not become an unsupported command.
Verification. Run the original token and a proposed translated token. The latter should work only when explicitly registered; otherwise the guide must never suggest it. Record the command that the installed binary actually accepts. Save the installed version, selected locale, invocation and outcome. Where behavior is application-specific, say so instead of presenting an untested convention as a universal Cocona rule.
2. Minimal API entry point
The principle. The CoconaApp minimal style lets a developer create an app and register delegates with AddCommand. Parameters on these delegates help determine the command interface. The clarity of the C# source is useful, but a public-facing guide should begin from generated help and real invocations. This distinction matters because command-line documentation is operational: the reader will often copy an instruction exactly and expect the same result.
Reader-facing example. A preview action may take a string file name and an optional numeric limit. It is preferable to teach one working invocation before explaining AddCommand internals to a new reader. Present real tokens and replaceable values separately, so that a translated sentence does not become an unsupported command.
Verification. Build the simple program and capture –help as well as a successful preview. Check the parameter spellings that appear, rather than assuming C# identifiers automatically become the desired display words. Save the installed version, selected locale, invocation and outcome. Where behavior is application-specific, say so instead of presenting an untested convention as a universal Cocona rule.
3. Class-based commands
The principle. Cocona can also treat public methods as commands. In the class-based style, multiple public command methods can form subcommands and CommandAttribute can explicitly specify the route. This is different from reading a method name in a source listing. This distinction matters because command-line documentation is operational: the reader will often copy an instruction exactly and expect the same result.
Reader-facing example. A maintenance utility may expose Inspect and Summarize methods. The published command spelling needs to match the effective attributes and configuration; descriptive translations should explain their purpose without silently renaming them. Present real tokens and replaceable values separately, so that a translated sentence does not become an unsupported command.
Verification. Ask a reviewer to discover a subcommand from root help, invoke its help and run a read-only task. Keep examples in sync when methods or attributes change. Save the installed version, selected locale, invocation and outcome. Where behavior is application-specific, say so instead of presenting an untested convention as a universal Cocona rule.
4. Command names and collisions
The principle. A translated command alias can collide with another existing command, a shortened name or an inherited option-like command. Such collisions are not linguistic style issues; they can change where an invocation goes. This distinction matters because command-line documentation is operational: the reader will often copy an instruction exactly and expect the same result.
Reader-facing example. Before adding alternate-language routes, map root commands, children, aliases and reserved help or version routes. Where two languages propose the same word for different operations, choose an unambiguous product policy. Present real tokens and replaceable values separately, so that a translated sentence does not become an unsupported command.
Verification. Test every route from the installed binary and report where an ambiguous token resolves. Do not promise auto-detection or locale-sensitive command names unless the app implements them. Save the installed version, selected locale, invocation and outcome. Where behavior is application-specific, say so instead of presenting an untested convention as a universal Cocona rule.
5. Options are typed parameters
The principle. A delegate parameter typically becomes an option unless marked as a positional argument. Types determine what the parser can bind; converting an input to an integer, Boolean or another type is not something translated prose can override. This distinction matters because command-line documentation is operational: the reader will often copy an instruction exactly and expect the same result.
Reader-facing example. If an instruction says a row limit accepts any number, it may encourage decimal punctuation that the integer binder rejects. Show a concrete integer and distinguish the value from its translated description. Present real tokens and replaceable values separately, so that a translated sentence does not become an unsupported command.
Verification. Test absent, valid and malformed input while logging the bound value in a safe harness. A translation is correct only if the shown example produces the advertised type. Save the installed version, selected locale, invocation and outcome. Where behavior is application-specific, say so instead of presenting an untested convention as a universal Cocona rule.
6. Requiredness and nullable values
The principle. The documented Cocona behavior distinguishes ordinary nonnullable parameters, nullable parameters and Boolean values. A nullable string can make a parameter non-mandatory; that does not mean that an empty string or the word null is interchangeable with omission. This distinction matters because command-line documentation is operational: the reader will often copy an instruction exactly and expect the same result.
Reader-facing example. Use a plain-language sentence such as: omit the name option to use the application default; otherwise give one file name. Confirm the actual default in the implementation instead of inventing it in documentation. Present real tokens and replaceable values separately, so that a translated sentence does not become an unsupported command.
Verification. Compare no option, an empty quoted token and a normal value. Show which invokes the handler, which fails and which results in null on the tested version. Save the installed version, selected locale, invocation and outcome. Where behavior is application-specific, say so instead of presenting an untested convention as a universal Cocona rule.
7. Booleans are switches
The principle. A Boolean parameter is commonly a switch rather than a text field expecting translated words for yes and no. Its false default should be explained as behavior, not as a requirement to type a localized truth word. This distinction matters because command-line documentation is operational: the reader will often copy an instruction exactly and expect the same result.
Reader-facing example. For verbose mode, show the literal supported switch and its omission. Do not add an invented –oui, –ja or –sim flag merely because readers speak those languages. Present real tokens and replaceable values separately, so that a translated sentence does not become an unsupported command.
Verification. Run with and without the flag and print the bound Boolean in a controlled example. Test a supposed negated form separately instead of assuming every library shares the same syntax. Save the installed version, selected locale, invocation and outcome. Where behavior is application-specific, say so instead of presenting an untested convention as a universal Cocona rule.
8. Positional ArgumentAttribute
The principle. The Argument attribute marks a value as positional. A name in a usage display may guide the reader, yet the shell still passes positional tokens according to the command grammar. This distinction matters because command-line documentation is operational: the reader will often copy an instruction exactly and expect the same result.
Reader-facing example. A report path can contain spaces or a non-Latin filename. A translated example should identify the path as replaceable data, not as a command word or literal placeholder. Present real tokens and replaceable values separately, so that a translated sentence does not become an unsupported command.
Verification. Test an ordinary file name, one with spaces and one starting with a dash. Provide shell-specific quoting or an end-of-options strategy only when the target executable supports it. Save the installed version, selected locale, invocation and outcome. Where behavior is application-specific, say so instead of presenting an untested convention as a universal Cocona rule.
9. Multiple positional values
The principle. Cocona documents array arguments for commands such as copying several sources and one destination. This is more subtle than a single filename because token order becomes part of the contract. This distinction matters because command-line documentation is operational: the reader will often copy an instruction exactly and expect the same result.
Reader-facing example. A guide to safe preview aggregation can state that source paths precede a destination label. Avoid vague phrases that make a final parameter seem optional when the program requires it. Present real tokens and replaceable values separately, so that a translated sentence does not become an unsupported command.
Verification. Capture the exact received array and final value. Try zero, one and several source tokens and explain how the command decides where each belongs. Save the installed version, selected locale, invocation and outcome. Where behavior is application-specific, say so instead of presenting an untested convention as a universal Cocona rule.
10. Defaults in help
The principle. Developers can define optional parameters or defaults in signatures. Translation must not make a static default appear universal if configuration, installed version or locale changes it. This distinction matters because command-line documentation is operational: the reader will often copy an instruction exactly and expect the same result.
Reader-facing example. If –limit defaults to ten, show both the absent-option result and the explicit ten. Do not say a different value is a locale default unless software really selects it. Present real tokens and replaceable values separately, so that a translated sentence does not become an unsupported command.
Verification. Build a minimal input matrix with default, override and invalid value. Regenerate help after a code change and compare examples against the actual bound values. Save the installed version, selected locale, invocation and outcome. Where behavior is application-specific, say so instead of presenting an untested convention as a universal Cocona rule.
11. Help and version discovery
The principle. Cocona supplies built-in help behavior, commonly through -h and –help, and a version route may be available according to configuration. Help itself is a user-facing task that must succeed before the user knows any application commands. This distinction matters because command-line documentation is operational: the reader will often copy an instruction exactly and expect the same result.
Reader-facing example. Give the user a root help line, then a child help line if the app has subcommands. Avoid claiming a custom flag is always present merely because another tool uses it. Present real tokens and replaceable values separately, so that a translated sentence does not become an unsupported command.
Verification. Execute help and version checks on the packaged application. Check exit status, punctuation, line wrapping and whether a missing locale still produces usable guidance. Save the installed version, selected locale, invocation and outcome. Where behavior is application-specific, say so instead of presenting an untested convention as a universal Cocona rule.
12. Root and child help
The principle. A root command listing answers which operations exist, while command-specific help explains accepted parameters for one operation. Combining both into one giant translation makes the reader search rather than act. This distinction matters because command-line documentation is operational: the reader will often copy an instruction exactly and expect the same result.
Reader-facing example. For an app with preview and inspect, link each operation from the overview and place command-specific examples alongside its own flags. Preserve the exact command order. Present real tokens and replaceable values separately, so that a translated sentence does not become an unsupported command.
Verification. Test root help, each child help and an invalid child. A reader should recover without reading source code or knowing the English explanation. Save the installed version, selected locale, invocation and outcome. Where behavior is application-specific, say so instead of presenting an untested convention as a universal Cocona rule.
13. Descriptions and metadata
The principle. WithDescription and related annotations describe purpose and can influence generated help. A description is not a validator: it can claim the option accepts a country code while the binder accepts arbitrary text. This distinction matters because command-line documentation is operational: the reader will often copy an instruction exactly and expect the same result.
Reader-facing example. Write descriptions that answer why the flag exists, what value it expects and what happens if omitted. Use a separate validation rule for restrictions not enforced by type binding. Present real tokens and replaceable values separately, so that a translated sentence does not become an unsupported command.
Verification. Change one description, render help and inspect the resulting UI. Then deliberately provide an unsupported value to make sure the documentation and code enforce the same rule. Save the installed version, selected locale, invocation and outcome. Where behavior is application-specific, say so instead of presenting an untested convention as a universal Cocona rule.
14. Localization service ownership
The principle. The Cocona documentation describes integrating Microsoft.Extensions.Localization with ICoconaLocalizer for descriptions. The example uses a MicrosoftExtensionLocalizationCoconaLocalizer helper that is not included in the Cocona core package. This distinction matters because command-line documentation is operational: the reader will often copy an instruction exactly and expect the same result.
Reader-facing example. Treat the localization adapter as explicit application wiring rather than assuming a hidden built-in auto-translation feature. Review registration, lifetime, message keys and fallback culture. Present real tokens and replaceable values separately, so that a translated sentence does not become an unsupported command.
Verification. Compile with the actual adapter included, load each resource catalog and compare displayed command descriptions. A missing service registration is a deployment defect, not a translator error. Save the installed version, selected locale, invocation and outcome. Where behavior is application-specific, say so instead of presenting an untested convention as a universal Cocona rule.
15. IStringLocalizer and output messages
The principle. IStringLocalizer can supply application-owned strings inside handlers, such as the sentence shown after preview. This is related to, but distinct from, metadata translation in help. This distinction matters because command-line documentation is operational: the reader will often copy an instruction exactly and expect the same result.
Reader-facing example. Keep keys and substitution positions stable. Translate the sentence around a filename or count, not the raw filename and not a value sent to downstream software. Present real tokens and replaceable values separately, so that a translated sentence does not become an unsupported command.
Verification. Test a message with a number, a Unicode filename and a missing resource key. Confirm placeholders remain attached to the intended values and do not produce a confusing fallback. Save the installed version, selected locale, invocation and outcome. Where behavior is application-specific, say so instead of presenting an untested convention as a universal Cocona rule.
16. Resource identifiers and culture
The principle. Locale selection needs a deliberate policy. A user may have a language preference, a terminal encoding and an operating-system culture that are not the same thing; they should not be conflated. This distinction matters because command-line documentation is operational: the reader will often copy an instruction exactly and expect the same result.
Reader-facing example. Define a precedence rule such as explicit application language selection followed by supported environment default and an English fallback. Tell users how to change the choice without altering data. Present real tokens and replaceable values separately, so that a translated sentence does not become an unsupported command.
Verification. Use fixed test cultures and record which resource key resolved. Check neutral and regional variants independently when their phrasing differs. Save the installed version, selected locale, invocation and outcome. Where behavior is application-specific, say so instead of presenting an untested convention as a universal Cocona rule.
17. Help localization versus parser errors
The principle. A localized title does not guarantee parser-generated errors or command suggestions are translated. Some wording comes from Cocona, some from .NET and some from the application’s own validation. This distinction matters because command-line documentation is operational: the reader will often copy an instruction exactly and expect the same result.
Reader-facing example. Audit help, unknown-command errors, missing-option errors, conversion failures and handler exceptions as separate message owners. Assign each a practical recovery instruction. Present real tokens and replaceable values separately, so that a translated sentence does not become an unsupported command.
Verification. Trigger one error from each layer. Record the actual message, where it appears and whether a target-language reader can correct it without interpreting raw runtime exceptions. Save the installed version, selected locale, invocation and outcome. Where behavior is application-specific, say so instead of presenting an untested convention as a universal Cocona rule.
18. Help transformer customization
The principle. Cocona documents an advanced help-transformer extension. Custom presentation can improve localization, but it can also remove essential syntax, aliases or arguments. This distinction matters because command-line documentation is operational: the reader will often copy an instruction exactly and expect the same result.
Reader-facing example. A custom renderer should preserve command routes, required flags and human-readable descriptions. Decorative banners must not push the first working command below the visible screen. Present real tokens and replaceable values separately, so that a translated sentence does not become an unsupported command.
Verification. Compare standard and customized help for completeness, then run an accessibility check with plain terminals and narrow columns. Verify no option silently disappears. Save the installed version, selected locale, invocation and outcome. Where behavior is application-specific, say so instead of presenting an untested convention as a universal Cocona rule.
19. Unknown option policy
The principle. The framework normally treats unrecognized options as errors. An IgnoreUnknownOptions attribute can relax that behavior in specific contexts, so documentation cannot assume rejection everywhere. This distinction matters because command-line documentation is operational: the reader will often copy an instruction exactly and expect the same result.
Reader-facing example. If a wrapper forwards options to another tool, describe exactly which layer handles an unknown flag. Do not imply that ignoring means the option was understood or accepted. Present real tokens and replaceable values separately, so that a translated sentence does not become an unsupported command.
Verification. Run a misspelled option at each command level. Verify whether it is rejected, forwarded or ignored and teach the precise next action. Save the installed version, selected locale, invocation and outcome. Where behavior is application-specific, say so instead of presenting an untested convention as a universal Cocona rule.
20. Misspelled command suggestions
The principle. Cocona can suggest similar registered commands. The suggestion is a recovery aid; it does not silently execute the nearest command. This distinction matters because command-line documentation is operational: the reader will often copy an instruction exactly and expect the same result.
Reader-facing example. Localized help should distinguish the wrong token from a suggested valid one, particularly for languages with different scripts. A user should understand that correction still requires a fresh invocation. Present real tokens and replaceable values separately, so that a translated sentence does not become an unsupported command.
Verification. Enter a near miss and an unrelated token. Confirm that suggested command names are real and that none change due to translation alone. Save the installed version, selected locale, invocation and outcome. Where behavior is application-specific, say so instead of presenting an untested convention as a universal Cocona rule.
21. Option-like commands
The principle. Cocona supports option-like commands that resemble switches but invoke separate behavior. Its documentation warns that earlier arguments may be ignored in such paths, and these routes are not ordinary flags. This distinction matters because command-line documentation is operational: the reader will often copy an instruction exactly and expect the same result.
Reader-facing example. Avoid presenting an option-like command as if it modifies a preview action. Explain that it branches into a distinct operation and show what following arguments belong to it. Present real tokens and replaceable values separately, so that a translated sentence does not become an unsupported command.
Verification. Test option-like behavior with parameters before and after it. Capture which action is run, because misleading translations can turn a help or status operation into an unintended command. Save the installed version, selected locale, invocation and outcome. Where behavior is application-specific, say so instead of presenting an untested convention as a universal Cocona rule.
22. Hidden operations and honest menus
The principle. A HiddenAttribute can keep certain commands out of generated help. Hiding an operation is not security and a translator must not resurrect it in a visible list without product approval. This distinction matters because command-line documentation is operational: the reader will often copy an instruction exactly and expect the same result.
Reader-facing example. Use separate internal and public command catalogs. A guide for ordinary users should only cover supported visible routes, while administrators have appropriately scoped operational material. Present real tokens and replaceable values separately, so that a translated sentence does not become an unsupported command.
Verification. Compare displayed commands with the supported public contract and authorization rules. Verify that the app enforces permission independent of help visibility. Save the installed version, selected locale, invocation and outcome. Where behavior is application-specific, say so instead of presenting an untested convention as a universal Cocona rule.
23. Validation is not translation
The principle. Cocona validation can reject a value after parsing, and application rules may reject a value after the handler begins. Translated error text must not mask which layer failed. This distinction matters because command-line documentation is operational: the reader will often copy an instruction exactly and expect the same result.
Reader-facing example. A row limit may parse as an integer but exceed an application maximum. Explain the accepted range and show a valid alternative; do not call every failure a malformed number. Present real tokens and replaceable values separately, so that a translated sentence does not become an unsupported command.
Verification. Test a type error, an out-of-range number and a domain error separately. Recovery guidance must differ, and process status should reflect failure accurately. Save the installed version, selected locale, invocation and outcome. Where behavior is application-specific, say so instead of presenting an untested convention as a universal Cocona rule.
24. Exit status and automation
The principle. Human-readable language may vary, but machine consumers still need reliable exit codes and structured output. A successful CLI invocation is not defined by a green sentence in a screenshot. This distinction matters because command-line documentation is operational: the reader will often copy an instruction exactly and expect the same result.
Reader-facing example. If a preview command fails to read a file, it should not report a success exit code simply because the message was localized. Tell readers which outputs are for humans and which are stable machine signals. Present real tokens and replaceable values separately, so that a translated sentence does not become an unsupported command.
Verification. Capture stdout, stderr and the process return code for success, input error and runtime failure in every locale. Compare semantics, not identical translated words. Save the installed version, selected locale, invocation and outcome. Where behavior is application-specific, say so instead of presenting an untested convention as a universal Cocona rule.
25. Structured data must remain structured
The principle. JSON keys, command-line option names and file formats are external contracts. They should not change as a side effect of choosing a translated message catalog. This distinction matters because command-line documentation is operational: the reader will often copy an instruction exactly and expect the same result.
Reader-facing example. Offer a machine-readable mode with fixed documented field names where appropriate. If a human-friendly table is localized, make clear that it is not a stable serialization format. Present real tokens and replaceable values separately, so that a translated sentence does not become an unsupported command.
Verification. Compare a JSON result from two language settings and check the same fields and values. Only display labels should vary under a presentation-only localization policy. Save the installed version, selected locale, invocation and outcome. Where behavior is application-specific, say so instead of presenting an untested convention as a universal Cocona rule.
26. Unicode paths and normalization
The principle. Unicode covers many representations, including combining accents and different normalization forms. A printed label can look right while a filesystem lookup uses a different byte sequence or path policy. This distinction matters because command-line documentation is operational: the reader will often copy an instruction exactly and expect the same result.
Reader-facing example. Use real test files with accented Latin, CJK and spaced names. Do not promise normalization or transliteration unless the application performs it deliberately. Present real tokens and replaceable values separately, so that a translated sentence does not become an unsupported command.
Verification. Inspect the actual argument passed to the .NET handler and file access result. Repeat on supported operating systems, since path and terminal behavior can differ. Save the installed version, selected locale, invocation and outcome. Where behavior is application-specific, say so instead of presenting an untested convention as a universal Cocona rule.
27. Right-to-left and bidirectional text
The principle. Arabic and Hebrew help can place left-to-right tokens beside right-to-left prose. Visual order can differ from logical order, making it easy to copy the wrong characters. This distinction matters because command-line documentation is operational: the reader will often copy an instruction exactly and expect the same result.
Reader-facing example. Keep exact command tokens in a clearly isolated code span and place translated explanations separately. Avoid inserting invisible direction marks into executable strings. Present real tokens and replaceable values separately, so that a translated sentence does not become an unsupported command.
Verification. Copy each published command into a plain terminal and compare code points when rendering is suspicious. The goal is successful execution, not only visual symmetry. Save the installed version, selected locale, invocation and outcome. Where behavior is application-specific, say so instead of presenting an untested convention as a universal Cocona rule.
28. Windows and Unix shells
The principle. PowerShell, cmd.exe, bash and zsh do not share all quoting, escaping and environment syntax. A localization guide should not treat them as a single generic shell. This distinction matters because command-line documentation is operational: the reader will often copy an instruction exactly and expect the same result.
Reader-facing example. Show platform-specific examples when a path contains spaces, dollar signs or backslashes. Prefer read-only tests that make the received argument visible. Present real tokens and replaceable values separately, so that a translated sentence does not become an unsupported command.
Verification. Run the stated examples in each claimed shell. If one requires different quoting, explain the reason rather than blaming Cocona or translated text. Save the installed version, selected locale, invocation and outcome. Where behavior is application-specific, say so instead of presenting an untested convention as a universal Cocona rule.
29. Completion scripts
The principle. Cocona offers shell completion features for Bash and zsh. Completion can be another layer of user guidance, but generated completions must reflect real commands, not imagined translated aliases. This distinction matters because command-line documentation is operational: the reader will often copy an instruction exactly and expect the same result.
Reader-facing example. Check that descriptions in completion menus remain readable and that completion candidates match the registered grammar. A suggestion from completion is not proof that a command is supported. Present real tokens and replaceable values separately, so that a translated sentence does not become an unsupported command.
Verification. Install completion in a clean user profile, test top-level and nested completion, and compare returned candidates with actual help. Save the installed version, selected locale, invocation and outcome. Where behavior is application-specific, say so instead of presenting an untested convention as a universal Cocona rule.
30. GenericHost integration
The principle. Cocona can integrate with Microsoft.Extensions.Hosting. This influences configuration, service registration and startup, which in turn determine whether language resources are available. This distinction matters because command-line documentation is operational: the reader will often copy an instruction exactly and expect the same result.
Reader-facing example. If the CLI works in development but loses translations when run as a hosted service or scheduled job, inspect DI configuration and culture initialization instead of rewriting all text. Present real tokens and replaceable values separately, so that a translated sentence does not become an unsupported command.
Verification. Run the same help and preview tests through the real launch mechanism. Record configuration sources and the effective locale used during service creation. Save the installed version, selected locale, invocation and outcome. Where behavior is application-specific, say so instead of presenting an untested convention as a universal Cocona rule.
31. Cocona.Lite tradeoffs
The principle. Cocona.Lite provides a lighter route without the normal Microsoft.Extensions dependencies. That changes the assumptions a localization example can make about dependency injection and service wiring. This distinction matters because command-line documentation is operational: the reader will often copy an instruction exactly and expect the same result.
Reader-facing example. Do not copy a full Cocona localization snippet into a Lite project without verifying supported APIs. Explain the choice of runtime and how application-owned strings will be supplied. Present real tokens and replaceable values separately, so that a translated sentence does not become an unsupported command.
Verification. Compile a tiny localization smoke test with the exact package installed. Confirm whether help descriptions and messages receive the selected language. Save the installed version, selected locale, invocation and outcome. Where behavior is application-specific, say so instead of presenting an untested convention as a universal Cocona rule.
32. Messages containing values
The principle. A localized message often combines an invariant token with a user-supplied name, count or date. Translators need freedom to reorder sentences while preserving typed data and safety. This distinction matters because command-line documentation is operational: the reader will often copy an instruction exactly and expect the same result.
Reader-facing example. Use named or indexed placeholders consistently, avoid concatenating fragments and give context to translators. Never convert a file path into a translated pseudo-path. Present real tokens and replaceable values separately, so that a translated sentence does not become an unsupported command.
Verification. Run examples with plural counts, RTL names and percent symbols. Ensure the final message identifies the correct variable rather than swapping names and quantities. Save the installed version, selected locale, invocation and outcome. Where behavior is application-specific, say so instead of presenting an untested convention as a universal Cocona rule.
33. Numbers, dates and cultures
The principle. A display locale may format dates and numbers differently from the argument parser’s invariant syntax. An instruction can be friendly while still prescribing machine-compatible inputs. This distinction matters because command-line documentation is operational: the reader will often copy an instruction exactly and expect the same result.
Reader-facing example. State input grammar separately from output formatting. If an option requires an ISO date or dot-decimal value, display that literal form even for users who normally write another convention. Present real tokens and replaceable values separately, so that a translated sentence does not become an unsupported command.
Verification. Test one recognized value and one regionally familiar but unsupported value. Show the exact accepted input instead of promising automatic locale-aware parsing. Save the installed version, selected locale, invocation and outcome. Where behavior is application-specific, say so instead of presenting an untested convention as a universal Cocona rule.
34. Security and secrets
The principle. Localized help can accidentally teach users to place credentials into shell history or logs. The translation must preserve security warnings and avoid exposing hidden arguments. This distinction matters because command-line documentation is operational: the reader will often copy an instruction exactly and expect the same result.
Reader-facing example. Where credentials are necessary, prefer secure input methods or documented environment policy. A translation should distinguish a secret from a harmless sample name and never publish production-looking tokens. Present real tokens and replaceable values separately, so that a translated sentence does not become an unsupported command.
Verification. Scan translated examples and logs for secrets. Confirm validation and masking work across supported locales, since language changes must not weaken privacy behavior. Save the installed version, selected locale, invocation and outcome. Where behavior is application-specific, say so instead of presenting an untested convention as a universal Cocona rule.
35. Packaging resource files
The principle. A program may load translations when run from source yet omit RESX or other resources in a published executable. Packaging must be part of the localization acceptance test. This distinction matters because command-line documentation is operational: the reader will often copy an instruction exactly and expect the same result.
Reader-facing example. Build a Release artifact, move it to a clean directory and run help in each language. Pay attention to trimmed or single-file publishing when used, rather than assuming every resource survives bundling. Present real tokens and replaceable values separately, so that a translated sentence does not become an unsupported command.
Verification. Inspect the installed output and compare help with the developer build. A missing catalog should trigger the documented fallback, not an empty string or exception. Save the installed version, selected locale, invocation and outcome. Where behavior is application-specific, say so instead of presenting an untested convention as a universal Cocona rule.
36. User testing and editorial repair
The principle. Fluent translation is not the same as completing a task. An unfamiliar reader must choose a command, enter parameters and recover from a mistake without inspecting the C# source. This distinction matters because command-line documentation is operational: the reader will often copy an instruction exactly and expect the same result.
Reader-facing example. Give a read-only report preview task to people in two languages. Observe which word they treat as a flag, which default they assume and whether they misread the error. Present real tokens and replaceable values separately, so that a translated sentence does not become an unsupported command.
Verification. Revise the particular instruction that caused confusion and rerun the same test. Keep the accepted invocation and release version in the evidence. Save the installed version, selected locale, invocation and outcome. Where behavior is application-specific, say so instead of presenting an untested convention as a universal Cocona rule.
37. Versioned documentation
The principle. A CLI changes when its command routes, aliases, parameter types or resource format change. Longform guidance becomes unreliable when it describes an older binary. This distinction matters because command-line documentation is operational: the reader will often copy an instruction exactly and expect the same result.
Reader-facing example. Associate documentation with a release and identify which options are demonstrated. A new optional field may need new examples in every locale, while a removed alias requires a migration note. Present real tokens and replaceable values separately, so that a translated sentence does not become an unsupported command.
Verification. Automate a check that each published command still appears in help and works on the supported release. Never rely only on translator approval. Save the installed version, selected locale, invocation and outcome. Where behavior is application-specific, say so instead of presenting an untested convention as a universal Cocona rule.
Diagnostic cases: symptom, reason and repair
These diagnostic cases are designed as independent checks. They separate failures in language resources, shell syntax, parser behavior, runtime validation and distribution. A reproducible case contains an invocation, the active language, a visible result and a correction. The goal is not to win an argument about wording: it is to help a user finish a legitimate task.
Case 1: A Japanese filename fails
Likely cause. The shell or filesystem may be involved even if the displayed text is correct. The same apparent symptom may arise at a different layer, so check the result rather than assuming that translation is the entire explanation.
Practical repair and proof. Use a tiny diagnostic command to print the received path, then test an existing file. Keep the same filename across comparison runs. Re-run the original failing invocation and a known-good counterpart, capturing both the human message and the underlying command outcome. An explanation is complete when the reader knows what to type next and why it works.
Case 2: The help heading is English
Likely cause. The application may be localizing handler strings but not Cocona metadata. The same apparent symptom may arise at a different layer, so check the result rather than assuming that translation is the entire explanation.
Practical repair and proof. Inspect ICoconaLocalizer registration and resource keys, then run root and child help in the selected culture. Re-run the original failing invocation and a known-good counterpart, capturing both the human message and the underlying command outcome. An explanation is complete when the reader knows what to type next and why it works.
Case 3: A nullable option is described as required
Likely cause. The prose may have been copied from a nonnullable signature. The same apparent symptom may arise at a different layer, so check the result rather than assuming that translation is the entire explanation.
Practical repair and proof. Compare the actual handler signature with the help, and test missing, blank and supplied values. Re-run the original failing invocation and a known-good counterpart, capturing both the human message and the underlying command outcome. An explanation is complete when the reader knows what to type next and why it works.
Case 4: The translated alias fails
Likely cause. A label in a resource file is not a parser registration. The same apparent symptom may arise at a different layer, so check the result rather than assuming that translation is the entire explanation.
Practical repair and proof. Show the literal command and remove the invented alias from examples unless an implemented alias is verified. Re-run the original failing invocation and a known-good counterpart, capturing both the human message and the underlying command outcome. An explanation is complete when the reader knows what to type next and why it works.
Case 5: The row limit accepts punctuation differently
Likely cause. Typed binding and cultural formatting have been confused. The same apparent symptom may arise at a different layer, so check the result rather than assuming that translation is the entire explanation.
Practical repair and proof. Specify the accepted input notation and test raw parsing independently of display formatting. Re-run the original failing invocation and a known-good counterpart, capturing both the human message and the underlying command outcome. An explanation is complete when the reader knows what to type next and why it works.
Case 6: Help works from source but not after publishing
Likely cause. Satellite resources or configuration may be absent in the distribution. The same apparent symptom may arise at a different layer, so check the result rather than assuming that translation is the entire explanation.
Practical repair and proof. Test the packaged artifact from an empty directory with no developer resource path available. Re-run the original failing invocation and a known-good counterpart, capturing both the human message and the underlying command outcome. An explanation is complete when the reader knows what to type next and why it works.
Case 7: A subcommand runs the wrong handler
Likely cause. A route or alias collision may exist. The same apparent symptom may arise at a different layer, so check the result rather than assuming that translation is the entire explanation.
Practical repair and proof. Inspect command registrations and test one named route at a time against a safe visible action identifier. Re-run the original failing invocation and a known-good counterpart, capturing both the human message and the underlying command outcome. An explanation is complete when the reader knows what to type next and why it works.
Case 8: A Boolean example requires a word
Likely cause. A switch was explained as if it were a free-text option. The same apparent symptom may arise at a different layer, so check the result rather than assuming that translation is the entire explanation.
Practical repair and proof. Show the documented presence or absence behavior and verify the handler value. Re-run the original failing invocation and a known-good counterpart, capturing both the human message and the underlying command outcome. An explanation is complete when the reader knows what to type next and why it works.
Case 9: Unknown flags disappear silently
Likely cause. A command may have been configured to ignore unknown options. The same apparent symptom may arise at a different layer, so check the result rather than assuming that translation is the entire explanation.
Practical repair and proof. Audit IgnoreUnknownOptions usage and document where unrecognized tokens go, rather than claiming they were valid. Re-run the original failing invocation and a known-good counterpart, capturing both the human message and the underlying command outcome. An explanation is complete when the reader knows what to type next and why it works.
Case 10: A help transformer hides required arguments
Likely cause. The custom renderer prioritizes appearance over completeness. The same apparent symptom may arise at a different layer, so check the result rather than assuming that translation is the entire explanation.
Practical repair and proof. Compare it to default help and require every obligatory parameter and alias to remain visible. Re-run the original failing invocation and a known-good counterpart, capturing both the human message and the underlying command outcome. An explanation is complete when the reader knows what to type next and why it works.
Case 11: RTL help copies backwards
Likely cause. Text direction and token isolation may be wrong. The same apparent symptom may arise at a different layer, so check the result rather than assuming that translation is the entire explanation.
Practical repair and proof. Place exact syntax separately and test pasted commands in a real terminal with the intended script. Re-run the original failing invocation and a known-good counterpart, capturing both the human message and the underlying command outcome. An explanation is complete when the reader knows what to type next and why it works.
Case 12: Translated samples break on PowerShell
Likely cause. Shell tokenization differs from POSIX quoting. The same apparent symptom may arise at a different layer, so check the result rather than assuming that translation is the entire explanation.
Practical repair and proof. Provide tested PowerShell and Bash versions, especially for spaces, dollar signs and backslashes. Re-run the original failing invocation and a known-good counterpart, capturing both the human message and the underlying command outcome. An explanation is complete when the reader knows what to type next and why it works.
Case 13: Completion suggests nonexistent aliases
Likely cause. Completion candidates and registered routes are out of sync. The same apparent symptom may arise at a different layer, so check the result rather than assuming that translation is the entire explanation.
Practical repair and proof. Regenerate completion from the installed command definition and execute each important candidate. Re-run the original failing invocation and a known-good counterpart, capturing both the human message and the underlying command outcome. An explanation is complete when the reader knows what to type next and why it works.
Case 14: An out-of-range number is called a parse error
Likely cause. Application validation and type binding are separate layers. The same apparent symptom may arise at a different layer, so check the result rather than assuming that translation is the entire explanation.
Practical repair and proof. Explain the legal range and report a practical alternative without changing the machine token. Re-run the original failing invocation and a known-good counterpart, capturing both the human message and the underlying command outcome. An explanation is complete when the reader knows what to type next and why it works.
Case 15: A background job uses English
Likely cause. The service process may run under a default culture with no interactive user locale. The same apparent symptom may arise at a different layer, so check the result rather than assuming that translation is the entire explanation.
Practical repair and proof. Choose and log an explicit supported culture in noninteractive environments. Re-run the original failing invocation and a known-good counterpart, capturing both the human message and the underlying command outcome. An explanation is complete when the reader knows what to type next and why it works.
Case 16: A log entry changes shape by language
Likely cause. Human text is being used as if it were machine-readable data. The same apparent symptom may arise at a different layer, so check the result rather than assuming that translation is the entire explanation.
Practical repair and proof. Keep structured event fields stable, and localize only display messages where downstream consumers allow it. Re-run the original failing invocation and a known-good counterpart, capturing both the human message and the underlying command outcome. An explanation is complete when the reader knows what to type next and why it works.
Case 17: A translation drops placeholder values
Likely cause. The resource string may have changed placeholder numbers or formatting. The same apparent symptom may arise at a different layer, so check the result rather than assuming that translation is the entire explanation.
Practical repair and proof. Run a multilingual snapshot with two distinguishable names and a count to detect swapped or missing values. Re-run the original failing invocation and a known-good counterpart, capturing both the human message and the underlying command outcome. An explanation is complete when the reader knows what to type next and why it works.
Case 18: Users assume hidden means protected
Likely cause. Help visibility was mistaken for authorization. The same apparent symptom may arise at a different layer, so check the result rather than assuming that translation is the entire explanation.
Practical repair and proof. Enforce access controls in application code and do not rely on HiddenAttribute as a security boundary. Re-run the original failing invocation and a known-good counterpart, capturing both the human message and the underlying command outcome. An explanation is complete when the reader knows what to type next and why it works.
Frequently asked questions
Does Cocona automatically translate an entire CLI?
No. It generates a typed interface and offers integration points for localization. Application developers still choose resources, culture selection, supported command aliases and error-message ownership. For any published example, keep a tested invocation and note which part is description, which part is accepted input and which part is application policy.
What does ICoconaLocalizer do?
It participates in localizing Cocona command descriptions through explicitly configured application services. The upstream example uses an adapter that is not bundled in the core package, so verify your project’s implementation. For any published example, keep a tested invocation and note which part is description, which part is accepted input and which part is application policy.
Can I translate –help into a new flag?
You may translate its explanation. A new executable flag is supported only if the application explicitly registers and tests it; otherwise the literal existing token should be shown. For any published example, keep a tested invocation and note which part is description, which part is accepted input and which part is application policy.
Are options and arguments the same?
No. An option is named in the invocation, while an Argument-marked value is positional. Mislabeling this distinction can make a correct-looking example fail. For any published example, keep a tested invocation and note which part is description, which part is accepted input and which part is application policy.
How does localization interact with .NET culture?
Culture can influence resource lookup and display formatting. It does not by itself guarantee that command parser tokens or accepted input formats change. Test the effective runtime separately. For any published example, keep a tested invocation and note which part is description, which part is accepted input and which part is application policy.
What is the safest sample task?
A read-only report preview that prints the parsed file, a row limit and chosen message language. It permits validation without modifying user files or relying on production credentials. For any published example, keep a tested invocation and note which part is description, which part is accepted input and which part is application policy.
Does Cocona.Lite use the same localization setup?
Do not assume so. Its lightweight dependency model differs from the full package; compile and test the specific version and application wiring before publishing instructions. For any published example, keep a tested invocation and note which part is description, which part is accepted input and which part is application policy.
How do I test missing translations?
Remove or simulate a missing target-language resource, invoke help and one normal command, and verify the documented fallback remains intelligible and complete. For any published example, keep a tested invocation and note which part is description, which part is accepted input and which part is application policy.
Can the help text be accessible in right-to-left languages?
Yes with careful separation of executable tokens, correctly shaped language text, tested terminal widths and copy-and-paste checks. A screenshot alone is insufficient. For any published example, keep a tested invocation and note which part is description, which part is accepted input and which part is application policy.
What is the release acceptance rule?
A new reader should discover a valid route, supply a correct argument, recover from an invalid option and obtain the expected result from the installed binary in the chosen language. For any published example, keep a tested invocation and note which part is description, which part is accepted input and which part is application policy.
Four-week teaching and release plan
Week 1 — establish the real grammar
Create a non-destructive preview command using both minimal and class-based patterns as appropriate. Record exact executable route, Argument-marked path, typed limit, Boolean switch and defaults. Capture help and three error cases on the installed project version. Assign ownership for parsing versus application validation. The deliverable for this stage is a concise test record with the actual command, observed output, selected culture and any correction to the user guide.
Week 2 — build and review language resources
Register the localization services, create English plus two target-language catalogs and choose a documented culture fallback. Translate descriptions, prompts and recovery messages while preserving executable tokens and placeholders. Have two reviewers copy every sample command, checking that no translated label is mistaken for a flag. The deliverable for this stage is a concise test record with the actual command, observed output, selected culture and any correction to the user guide.
Week 3 — validate terminal and package behavior
Run unknown option, missing input, invalid number, Unicode pathname, right-to-left display and shell quoting cases. Record stdout, stderr and exit code. Build a production Release artifact and verify resources outside the development tree; include a missing-catalog test and any supported completion scripts. The deliverable for this stage is a concise test record with the actual command, observed output, selected culture and any correction to the user guide.
Week 4 — independent usability and maintenance
Ask unfamiliar readers to discover and complete a read-only task without English documentation. Observe confusion about route selection, defaults, error recovery and placeholders. Correct those explanations, rerun tests and make command grammar changes trigger a translation review before the next release. The deliverable for this stage is a concise test record with the actual command, observed output, selected culture and any correction to the user guide.
Publication acceptance: what a reader should be able to do
A strong multilingual CLI is one a newcomer can use: find help, choose a registered route, supply a correctly typed value, recognize a helpful error and complete a task using a clean installation. The application must not silently change its machine contracts when its explanatory language changes. Treat translations, command specifications and release artifacts as connected parts of the same experience, and refresh this guide whenever the relevant command definition changes.