This F# Argu localization guide explains how to localize F# Argu CLI usage, discriminated union options, IArgParserTemplate messages, errors and configuration documentation. It is written for F# and .NET developers maintaining cross-platform command-line applications, including readers who are preparing their first multilingual release. The practical rule is that a good translation makes a command understandable without changing what the program actually accepts. Exact options, inputs and output contracts must be tested, not guessed from the language of the surrounding explanation.
Consider MuseumRoute, a fictional museum inventory tool used to coordinate exhibition object transfers. A teammate in Germany needs accurate help, a teammate in Japan must read a failure, and a scheduled process still runs the same command. The central question is what should change for the human reader and what must remain identical for the software. In this F# Argu tutorial, we begin with a reliable mental model, examine a small code or schema illustration, then work through concrete failure investigations and a multilingual release plan.
The short answer: Argu derives argument parsing and usage from F# discriminated unions and supports configuration readers as well as command-line input. Translate Usage descriptions, guidance, app-owned errors, command examples and explanations of default and configuration precedence; protect discriminated union case identity, generated option spellings, case payload types, nested command structure and configuration key names. The chapters below explain when that distinction is easy, when it fails, how to recover and how to check the result without pretending F# Argu offers translation features it does not document.
Quick reference — what to translate in F# Argu
- Use stable literal command names and flags in every runnable example.
- Translate descriptions, warning explanations, headings and app-owned help where the program permits it.
- Do not confuse a value identifier with its natural-language explanation.
- Treat missing values, unknown flags and failed conversions as failure, not successful execution.
- Check actual parser outputs, exit codes and file effects for each display language.
- Test Unicode paths, narrow terminals and copied commands.
- Record the exact dependency and runtime versions used by published examples.
- Use native-language readers to assess decisions and recovery, not simply grammatical fluency.
Chapter 1 — The central problem for F# Argu
F# Argu appears in a command-line application at the boundary between a person’s task and the computer’s strict input grammar. A user may believe an option means one thing because of a translated sentence, while the parser performs something else because it recognizes a fixed sequence of tokens. That is the point at which localization becomes an engineering reliability issue. Successful output may look the same across languages, but if the person selected the wrong action, the guide has failed. Every example should name the input, describe the intended effect, identify the limits of the command and show a verifiable result.
The useful first distinction is between the code path that identifies an action and the language used to describe it. In this setting, discriminated union case identity, generated option spellings, case payload types, nested command structure and configuration key names are not interchangeable with prose. A translation team should ask whether each visible word is a recognized token, a displayed label, a value taken from a file or a human instruction. Sometimes a word is both a UI label and a command name; in that case the implementation owner must decide intentionally about compatibility. A translator cannot solve that interface-design decision by choosing a fluent synonym.
Chapter 2 — What the library provides, and what it does not
The relevant API surface is ArgumentParser.Create, ParseCommandLine and the IArgParserTemplate Usage member. Argu derives argument parsing and usage from F# discriminated unions and supports configuration readers as well as command-line input. Study the public documentation for the actual version before changing any code. A library can be excellent at validating options and still expose no built-in system for choosing French, Japanese or Arabic message catalogs. The safe design is to maintain a small application-controlled language layer for human-facing material, using documented parser extension points when they exist and keeping the parser’s own identity stable.
Argu offers customization points, but changing the language of displayed documentation is not the same as changing the generated parser grammar; confirm the installed NuGet version. This matters whenever a team promises readers that an installation supports a particular behavior. If a message is owned by the dependency, a truthful guide distinguishes the error it prints from any explanatory wording the application adds. It must never imply that an unverified API exists. Users deserve a precise distinction between a library feature, an optional application feature and an editorial convention in documentation.
Chapter 3 — A small implementation illustration
The following illustration identifies the technical boundary used in the rest of the guide. It is deliberately small so a newcomer can see each input’s role. Install the dependency version required by the actual application and compile or run the example in a disposable working directory. Where an API is version-sensitive, treat the excerpt as a conceptual mapping until it has passed the version-specific test suite.
open Argu
type CliArgs =
| Working_Directory of path: string
| Dry_Run
interface IArgParserTemplate with
member this.Usage =
match this with
| Working_Directory _ -> "Directory containing source files"
| Dry_Run -> "Describe changes without writing files"
let parser = ArgumentParser.Create<CliArgs>(programName = "museumroute")
let parsed = parser.ParseCommandLine(inputs = [| "--dry-run" |])Read the code twice. First follow the path from the arguments typed by a human to the parser’s typed result. Then look for the explanatory sentences. The former is an executable contract; the latter may be localized where the implementation permits it. For MuseumRoute, a fictional museum inventory tool used to coordinate exhibition object transfers, choose a harmless sample input, make the same invocation under two display languages, and compare the underlying parsed values. If those values differ after only the message text changes, investigate before distributing the translation.
Chapter 4 — A reader’s workflow before advanced options
A first-time user needs to know what the utility does, the minimum valid command, where the input file comes from, whether execution writes anything and what a successful result looks like. Put those facts ahead of exhaustive option tables. Use a short command example in fixed-width formatting, followed by an explanation of each variable field and a warning about real side effects. The reader should be able to recognize which text is something to type and which text is a description. If an optional flag makes a destructive task safer, explain only the behavior that has been implemented and tested.
In MuseumRoute, a fictional museum inventory tool used to coordinate exhibition object transfers, an effective guide might begin with inspecting a sample input rather than performing the final export immediately. That sequence reduces risk and provides a verification point: the operator can inspect a row count or file summary, confirm the target directory and only then execute the next step. Once that short path works in English, repeat the same behavioral test in the translated interface. The translated narrative can change rhythm and examples, but it must not invent a preview action or silently switch to a different output path.
Chapter 5 — Build a small catalog with a strong boundary
A practical catalog uses stable message keys for human-facing sentences such as help.summary, error.bad_value and next_step.open_report. The key is not a command flag and should not be shown as a copyable invocation. Store values with context: which command uses the sentence, whether it names a file, whether placeholders are typed values and whether an error could mean an irreversible operation failed. A translator can then choose a natural sentence instead of translating isolated fragments that produce strange grammar when assembled.
Placeholders deserve explicit definitions. If a message includes a filename, preserve the actual filename rather than translating its components. If it includes a number, keep its quantity and units faithful, choosing a display format that does not alter the accepted command grammar. If it includes a token such as –help, keep that token exact in code formatting. Add examples of singular and plural quantities where the catalog implementation supports them. When it does not, write separate complete messages for the known cases rather than making up an unsupported pluralization facility.
Chapter 6 — Review errors as instructional moments
The useful error path tells the reader what failed, what remains unchanged and what action to try next. An unknown flag should not produce advice intended for a missing file; a bad number should identify the range or accepted syntax; a permissions failure should not be presented as an invalid option. Translate the reason and recovery in complete sentences. Keep machine statuses and diagnostic channels aligned with the actual result, particularly when a command can run in unattended automation.
Do not rely on the emotional tone of an error alone. A polite sentence that hides an invalid result is less useful than a concise correction. In MuseumRoute, a fictional museum inventory tool used to coordinate exhibition object transfers, write a test in which the operator gives a wrong option and observes both the output and the absence of unintended changes. Then ask a reader to repair the command without consulting a developer. If the reader cannot locate the exact rejected input or decide what to change, revise the message and repeat the task. The goal is independent recovery.
Chapter 7 — Inputs are not always natural language
Some strings travel through a CLI unchanged because they identify paths, files, hosts, formats, external records or protocol values. Their letters may resemble ordinary words, but replacing them with a translation can break a workflow or target a different object. Treat source-file names and record identifiers as data unless there is an explicit mapping contract. A localized help sentence can explain the purpose of a value while its executable spelling stays stable. This rule protects both individual users and scripts that depend on earlier examples.
The same care applies to spaces, punctuation and Unicode. A copied command may be altered by smart quotes, typographic dashes, bidi display or missing shell escaping before the application even begins parsing. Test from the final rendered page, not just the editor. Inspect the bytes received by the process when debugging. A successfully displayed accented filename proves little if the program has actually opened another path. Keep a disposable directory with representative filenames and compare the result across locales.
Chapter 8 — A workable multilingual QA matrix
Choose languages based on actual users, then extend the test set to cover different structural risks. Longer compound words expose wrapping problems; Japanese or Chinese tests non-Latin glyphs and width; Arabic exposes mixed-direction punctuation; filenames with combining accents expose encoding assumptions. Test a terminal at approximately 40 columns and one at a comfortable desktop width. Capture plain text as well as screenshots. For errors, test a bad option, a missing value and a valid syntactic command that fails later for a domain reason.
Separate four dimensions in your evidence: human comprehension, parsing correctness, output contract and effects on the filesystem or external service. A fluent language review can approve the first while failing to notice the others. A unit test can approve the parser while overlooking whether a reader thinks a write operation is read-only. Pair these two kinds of checking. Preserve real command invocations and observed outcomes, and re-run them after changing either the code or its explanatory text.
Chapter 9 — How to maintain a trustworthy release
Localization is not finished when a string table is complete. A release should state the supported runtime and dependency version, show the commands that were tested, identify unsupported locales or message types and include an approachable place to report a broken example. Reviewers should distinguish wording corrections from changes to token grammar and configuration precedence. Never assume a new package release has preserved every detail merely because compilation succeeds.
The immediate next step for F# and .NET developers maintaining cross-platform command-line applications is to choose one representative command and trace it from documented help through parsing to an observable effect. Write a valid-case test and a failure-case test. Translate the explanations, compare the same command in another language, and ask a reader to predict the outcome. That small, verifiable loop provides a reliable foundation for larger catalogs and complex command trees.
Chapter 10 — Twenty practical F# Argu investigations
The following investigations are intentionally concrete. Each describes a different point where text and software behavior can drift apart. Work through them with disposable inputs, compare what the reader sees with what the parser does, and update documentation only after observing the result. Some are display faults, some are parsing mistakes and others reveal unsafe assumptions about data or release versions.
Investigation 1 — A case is renamed to translate the displayed switch
Working_Directory becomes a locale-specific case identifier in the source and the generated option spelling changes. This is worth isolating because MuseumRoute, a fictional museum inventory tool used to coordinate exhibition object transfers must remain usable when one operator reads a different language from another. Begin by reproducing the exact input and recording what the operator expected, rather than editing the translation immediately. The discrepancy is not just a question of style; it can affect whether somebody completes the intended task or trusts an incorrect result.
Argu derives CLI syntax from typed union definitions; a name edit can affect callers. In F# Argu, this distinction belongs to the boundary between discriminated union case identity, generated option spellings, case payload types, nested command structure and configuration key names and Usage descriptions, guidance, app-owned errors, command examples and explanations of default and configuration precedence. Observe which component is responsible before changing anything. A change to explanatory text should not become a change to a parser identifier, required input, validation predicate or machine data. When the apparent error arises from a shell command, inspect tokenization before the parser sees the input.
The practical correction is specific: Keep the case stable and localize its Usage text unless a versioned alias is intentionally introduced. Keep the repair narrow enough to review and revert. Then revise the translated explanation so it tells a first-time user what the command requires and what observable outcome to expect. If no public library feature supports the proposed change, state the limitation and implement an application-owned layer rather than disguising an assumption as a documented capability.
Verification: Invoke the previous exact token and assert the same case value is produced. Use a small fixture and record the observed result, not only a screenshot of the help screen. Ask a second person to repeat the task from the published instructions. A pass means they can choose the right action, preserve the relevant input and explain the result without guessing. If the command behaves correctly but the reader chooses the wrong action, the localization is still incomplete.
Investigation 2 — The Usage member omits the real side effect
An option description says ‘prepare export’ but it actually overwrites an inventory file. This is worth isolating because MuseumRoute, a fictional museum inventory tool used to coordinate exhibition object transfers must remain usable when one operator reads a different language from another. Begin by reproducing the exact input and recording what the operator expected, rather than editing the translation immediately. The discrepancy is not just a question of style; it can affect whether somebody completes the intended task or trusts an incorrect result.
Friendly prose is still a promise about program behavior. In F# Argu, this distinction belongs to the boundary between discriminated union case identity, generated option spellings, case payload types, nested command structure and configuration key names and Usage descriptions, guidance, app-owned errors, command examples and explanations of default and configuration precedence. Observe which component is responsible before changing anything. A change to explanatory text should not become a change to a parser identifier, required input, validation predicate or machine data. When the issue involves a displayed default, compare the text with the actual resolved value.
The practical correction is specific: State whether the operation reads, writes or replaces data, and mention a genuine preview path only if supported. Keep the repair narrow enough to review and revert. Then revise the translated explanation so it tells a first-time user what the command requires and what observable outcome to expect. If no public library feature supports the proposed change, state the limitation and implement an application-owned layer rather than disguising an assumption as a documented capability.
Verification: Run against a disposable copy and compare resulting files with the described outcome. Use a small fixture and record the observed result, not only a screenshot of the help screen. Ask a second person to repeat the task from the published instructions. A pass means they can choose the right action, preserve the relevant input and explain the result without guessing. If the command behaves correctly but the reader chooses the wrong action, the localization is still incomplete.
Investigation 3 — Program title is mistaken for an executable name
A Spanish guide instructs users to run a translated title rather than museumroute. This is worth isolating because MuseumRoute, a fictional museum inventory tool used to coordinate exhibition object transfers must remain usable when one operator reads a different language from another. Begin by reproducing the exact input and recording what the operator expected, rather than editing the translation immediately. The discrepancy is not just a question of style; it can affect whether somebody completes the intended task or trusts an incorrect result.
Program names and PATH resolution are operating-system concepts, not automatically translated UI text. In F# Argu, this distinction belongs to the boundary between discriminated union case identity, generated option spellings, case payload types, nested command structure and configuration key names and Usage descriptions, guidance, app-owned errors, command examples and explanations of default and configuration precedence. Observe which component is responsible before changing anything. A change to explanatory text should not become a change to a parser identifier, required input, validation predicate or machine data. When the issue appears only in another locale, inspect the exact same argv and parsed values in the source language.
The practical correction is specific: Keep the literal executable in code examples while translating the explanation and purpose. Keep the repair narrow enough to review and revert. Then revise the translated explanation so it tells a first-time user what the command requires and what observable outcome to expect. If no public library feature supports the proposed change, state the limitation and implement an application-owned layer rather than disguising an assumption as a documented capability.
Verification: Copy the command from the actual page to a fresh shell and run it. Use a small fixture and record the observed result, not only a screenshot of the help screen. Ask a second person to repeat the task from the published instructions. A pass means they can choose the right action, preserve the relevant input and explain the result without guessing. If the command behaves correctly but the reader chooses the wrong action, the localization is still incomplete.
Investigation 4 — An optional argument is described as mandatory
The translated help says a folder must always be supplied despite a configured fallback. This is worth isolating because MuseumRoute, a fictional museum inventory tool used to coordinate exhibition object transfers must remain usable when one operator reads a different language from another. Begin by reproducing the exact input and recording what the operator expected, rather than editing the translation immediately. The discrepancy is not just a question of style; it can affect whether somebody completes the intended task or trusts an incorrect result.
Union syntax and optionality determine what input the parser requires; prose does not. In F# Argu, this distinction belongs to the boundary between discriminated union case identity, generated option spellings, case payload types, nested command structure and configuration key names and Usage descriptions, guidance, app-owned errors, command examples and explanations of default and configuration precedence. Observe which component is responsible before changing anything. A change to explanatory text should not become a change to a parser identifier, required input, validation predicate or machine data. When error handling is involved, inspect stderr and process exit status as well as the visible message.
The practical correction is specific: Explain the true fallback and show both minimal and explicit invocation forms. Keep the repair narrow enough to review and revert. Then revise the translated explanation so it tells a first-time user what the command requires and what observable outcome to expect. If no public library feature supports the proposed change, state the limitation and implement an application-owned layer rather than disguising an assumption as a documented capability.
Verification: Run zero-argument and explicit-argument cases and compare parsed results. Use a small fixture and record the observed result, not only a screenshot of the help screen. Ask a second person to repeat the task from the published instructions. A pass means they can choose the right action, preserve the relevant input and explain the result without guessing. If the command behaves correctly but the reader chooses the wrong action, the localization is still incomplete.
Investigation 5 — A value’s type changes during a documentation refactor
A port number gets treated as a string because a case payload was changed with its Usage label. This is worth isolating because MuseumRoute, a fictional museum inventory tool used to coordinate exhibition object transfers must remain usable when one operator reads a different language from another. Begin by reproducing the exact input and recording what the operator expected, rather than editing the translation immediately. The discrepancy is not just a question of style; it can affect whether somebody completes the intended task or trusts an incorrect result.
Typed union payloads are part of the application’s contract and downstream matching. In F# Argu, this distinction belongs to the boundary between discriminated union case identity, generated option spellings, case payload types, nested command structure and configuration key names and Usage descriptions, guidance, app-owned errors, command examples and explanations of default and configuration precedence. Observe which component is responsible before changing anything. A change to explanatory text should not become a change to a parser identifier, required input, validation predicate or machine data. When the apparent error arises from a shell command, inspect tokenization before the parser sees the input.
The practical correction is specific: Keep type changes in a separate reviewed code change; localize descriptions independently. Keep the repair narrow enough to review and revert. Then revise the translated explanation so it tells a first-time user what the command requires and what observable outcome to expect. If no public library feature supports the proposed change, state the limitation and implement an application-owned layer rather than disguising an assumption as a documented capability.
Verification: Assert that input 8080 becomes an integer and malformed input fails. Use a small fixture and record the observed result, not only a screenshot of the help screen. Ask a second person to repeat the task from the published instructions. A pass means they can choose the right action, preserve the relevant input and explain the result without guessing. If the command behaves correctly but the reader chooses the wrong action, the localization is still incomplete.
Investigation 6 — Environment settings secretly override the command
An operator supplies one directory, but a configuration reader loads another source and the manual hides precedence. This is worth isolating because MuseumRoute, a fictional museum inventory tool used to coordinate exhibition object transfers must remain usable when one operator reads a different language from another. Begin by reproducing the exact input and recording what the operator expected, rather than editing the translation immediately. The discrepancy is not just a question of style; it can affect whether somebody completes the intended task or trusts an incorrect result.
Configuration readers can affect resolved values even when the command-line text is fluent. In F# Argu, this distinction belongs to the boundary between discriminated union case identity, generated option spellings, case payload types, nested command structure and configuration key names and Usage descriptions, guidance, app-owned errors, command examples and explanations of default and configuration precedence. Observe which component is responsible before changing anything. A change to explanatory text should not become a change to a parser identifier, required input, validation predicate or machine data. When the issue involves a displayed default, compare the text with the actual resolved value.
The practical correction is specific: Document the tested precedence and display effective values where safe. Keep the repair narrow enough to review and revert. Then revise the translated explanation so it tells a first-time user what the command requires and what observable outcome to expect. If no public library feature supports the proposed change, state the limitation and implement an application-owned layer rather than disguising an assumption as a documented capability.
Verification: Set conflicting fixture values and inspect which directory the application actually uses. Use a small fixture and record the observed result, not only a screenshot of the help screen. Ask a second person to repeat the task from the published instructions. A pass means they can choose the right action, preserve the relevant input and explain the result without guessing. If the command behaves correctly but the reader chooses the wrong action, the localization is still incomplete.
Investigation 7 — A secret value is repeated in help output
A generalized localization diagnostic prints the entire parsed configuration, including a token. This is worth isolating because MuseumRoute, a fictional museum inventory tool used to coordinate exhibition object transfers must remain usable when one operator reads a different language from another. Begin by reproducing the exact input and recording what the operator expected, rather than editing the translation immediately. The discrepancy is not just a question of style; it can affect whether somebody completes the intended task or trusts an incorrect result.
Explanatory output must not expose credentials just because a parser makes values available. In F# Argu, this distinction belongs to the boundary between discriminated union case identity, generated option spellings, case payload types, nested command structure and configuration key names and Usage descriptions, guidance, app-owned errors, command examples and explanations of default and configuration precedence. Observe which component is responsible before changing anything. A change to explanatory text should not become a change to a parser identifier, required input, validation predicate or machine data. When the issue appears only in another locale, inspect the exact same argv and parsed values in the source language.
The practical correction is specific: Redact secrets, separate safe option names from sensitive values and review logging levels. Keep the repair narrow enough to review and revert. Then revise the translated explanation so it tells a first-time user what the command requires and what observable outcome to expect. If no public library feature supports the proposed change, state the limitation and implement an application-owned layer rather than disguising an assumption as a documented capability.
Verification: Supply a dummy secret in CI and assert that it never appears in stdout or stderr. Use a small fixture and record the observed result, not only a screenshot of the help screen. Ask a second person to repeat the task from the published instructions. A pass means they can choose the right action, preserve the relevant input and explain the result without guessing. If the command behaves correctly but the reader chooses the wrong action, the localization is still incomplete.
Investigation 8 — Wrong command level receives the option
A guide puts a subcommand-specific switch before the root command where the active parser rejects it. This is worth isolating because MuseumRoute, a fictional museum inventory tool used to coordinate exhibition object transfers must remain usable when one operator reads a different language from another. Begin by reproducing the exact input and recording what the operator expected, rather than editing the translation immediately. The discrepancy is not just a question of style; it can affect whether somebody completes the intended task or trusts an incorrect result.
Argu’s contextual command syntax must be documented with its actual nesting. In F# Argu, this distinction belongs to the boundary between discriminated union case identity, generated option spellings, case payload types, nested command structure and configuration key names and Usage descriptions, guidance, app-owned errors, command examples and explanations of default and configuration precedence. Observe which component is responsible before changing anything. A change to explanatory text should not become a change to a parser identifier, required input, validation predicate or machine data. When error handling is involved, inspect stderr and process exit status as well as the visible message.
The practical correction is specific: Provide a full command example, not a decontextualized option fragment. Keep the repair narrow enough to review and revert. Then revise the translated explanation so it tells a first-time user what the command requires and what observable outcome to expect. If no public library feature supports the proposed change, state the limitation and implement an application-owned layer rather than disguising an assumption as a documented capability.
Verification: Test root and child invocations separately under each language. Use a small fixture and record the observed result, not only a screenshot of the help screen. Ask a second person to repeat the task from the published instructions. A pass means they can choose the right action, preserve the relevant input and explain the result without guessing. If the command behaves correctly but the reader chooses the wrong action, the localization is still incomplete.
Investigation 9 — A Usage message is selected using the machine locale only
The language is driven by the server’s culture even when a user explicitly requests another interface language. This is worth isolating because MuseumRoute, a fictional museum inventory tool used to coordinate exhibition object transfers must remain usable when one operator reads a different language from another. Begin by reproducing the exact input and recording what the operator expected, rather than editing the translation immediately. The discrepancy is not just a question of style; it can affect whether somebody completes the intended task or trusts an incorrect result.
Culture defaults and user display preferences are separate inputs. In F# Argu, this distinction belongs to the boundary between discriminated union case identity, generated option spellings, case payload types, nested command structure and configuration key names and Usage descriptions, guidance, app-owned errors, command examples and explanations of default and configuration precedence. Observe which component is responsible before changing anything. A change to explanatory text should not become a change to a parser identifier, required input, validation predicate or machine data. When the apparent error arises from a shell command, inspect tokenization before the parser sees the input.
The practical correction is specific: Choose an explicit locale policy, document fallback and avoid changing parser keys. Keep the repair narrow enough to review and revert. Then revise the translated explanation so it tells a first-time user what the command requires and what observable outcome to expect. If no public library feature supports the proposed change, state the limitation and implement an application-owned layer rather than disguising an assumption as a documented capability.
Verification: Set conflicting preferences and confirm the chosen message set is predictable. Use a small fixture and record the observed result, not only a screenshot of the help screen. Ask a second person to repeat the task from the published instructions. A pass means they can choose the right action, preserve the relevant input and explain the result without guessing. If the command behaves correctly but the reader chooses the wrong action, the localization is still incomplete.
Investigation 10 — Error handling hides a nonzero exit
A handler catches a parse failure and returns a success status after printing a translated error. This is worth isolating because MuseumRoute, a fictional museum inventory tool used to coordinate exhibition object transfers must remain usable when one operator reads a different language from another. Begin by reproducing the exact input and recording what the operator expected, rather than editing the translation immediately. The discrepancy is not just a question of style; it can affect whether somebody completes the intended task or trusts an incorrect result.
Automation cannot infer success from a reassuring sentence; it relies on process status. In F# Argu, this distinction belongs to the boundary between discriminated union case identity, generated option spellings, case payload types, nested command structure and configuration key names and Usage descriptions, guidance, app-owned errors, command examples and explanations of default and configuration precedence. Observe which component is responsible before changing anything. A change to explanatory text should not become a change to a parser identifier, required input, validation predicate or machine data. When the issue involves a displayed default, compare the text with the actual resolved value.
The practical correction is specific: Preserve failure codes and include a concrete correction in the language selected for display. Keep the repair narrow enough to review and revert. Then revise the translated explanation so it tells a first-time user what the command requires and what observable outcome to expect. If no public library feature supports the proposed change, state the limitation and implement an application-owned layer rather than disguising an assumption as a documented capability.
Verification: Run a bad option in a CI step and require a nonzero result. Use a small fixture and record the observed result, not only a screenshot of the help screen. Ask a second person to repeat the task from the published instructions. A pass means they can choose the right action, preserve the relevant input and explain the result without guessing. If the command behaves correctly but the reader chooses the wrong action, the localization is still incomplete.
Investigation 11 — The documentation assumes every error comes from Argu
An invalid path passes parsing but fails later during file IO, yet the manual blames the parser. This is worth isolating because MuseumRoute, a fictional museum inventory tool used to coordinate exhibition object transfers must remain usable when one operator reads a different language from another. Begin by reproducing the exact input and recording what the operator expected, rather than editing the translation immediately. The discrepancy is not just a question of style; it can affect whether somebody completes the intended task or trusts an incorrect result.
Argument validation and filesystem operations fail at different stages. In F# Argu, this distinction belongs to the boundary between discriminated union case identity, generated option spellings, case payload types, nested command structure and configuration key names and Usage descriptions, guidance, app-owned errors, command examples and explanations of default and configuration precedence. Observe which component is responsible before changing anything. A change to explanatory text should not become a change to a parser identifier, required input, validation predicate or machine data. When the issue appears only in another locale, inspect the exact same argv and parsed values in the source language.
The practical correction is specific: Separate parser errors from domain and IO errors, with a targeted repair for each. Keep the repair narrow enough to review and revert. Then revise the translated explanation so it tells a first-time user what the command requires and what observable outcome to expect. If no public library feature supports the proposed change, state the limitation and implement an application-owned layer rather than disguising an assumption as a documented capability.
Verification: Test a syntactically valid missing file and a syntactically invalid option independently. Use a small fixture and record the observed result, not only a screenshot of the help screen. Ask a second person to repeat the task from the published instructions. A pass means they can choose the right action, preserve the relevant input and explain the result without guessing. If the command behaves correctly but the reader chooses the wrong action, the localization is still incomplete.
Investigation 12 — A formatted help width hides a Unicode token
An 80-character help layout wraps inside a Japanese label and makes the following option look attached. This is worth isolating because MuseumRoute, a fictional museum inventory tool used to coordinate exhibition object transfers must remain usable when one operator reads a different language from another. Begin by reproducing the exact input and recording what the operator expected, rather than editing the translation immediately. The discrepancy is not just a question of style; it can affect whether somebody completes the intended task or trusts an incorrect result.
Visual columns are not identical to Unicode character counts or terminal cell widths. In F# Argu, this distinction belongs to the boundary between discriminated union case identity, generated option spellings, case payload types, nested command structure and configuration key names and Usage descriptions, guidance, app-owned errors, command examples and explanations of default and configuration precedence. Observe which component is responsible before changing anything. A change to explanatory text should not become a change to a parser identifier, required input, validation predicate or machine data. When error handling is involved, inspect stderr and process exit status as well as the visible message.
The practical correction is specific: Use tested wrapping, preserve code token integrity and avoid hardcoded English alignments. Keep the repair narrow enough to review and revert. Then revise the translated explanation so it tells a first-time user what the command requires and what observable outcome to expect. If no public library feature supports the proposed change, state the limitation and implement an application-owned layer rather than disguising an assumption as a documented capability.
Verification: Render at narrow widths and inspect copying of exact flags. Use a small fixture and record the observed result, not only a screenshot of the help screen. Ask a second person to repeat the task from the published instructions. A pass means they can choose the right action, preserve the relevant input and explain the result without guessing. If the command behaves correctly but the reader chooses the wrong action, the localization is still incomplete.
Investigation 13 — A decimal number accepts different syntax than help claims
A German help example uses a comma separator but the actual parser accepts only a period. This is worth isolating because MuseumRoute, a fictional museum inventory tool used to coordinate exhibition object transfers must remain usable when one operator reads a different language from another. Begin by reproducing the exact input and recording what the operator expected, rather than editing the translation immediately. The discrepancy is not just a question of style; it can affect whether somebody completes the intended task or trusts an incorrect result.
Display culture does not automatically select the parser’s numeric input culture. In F# Argu, this distinction belongs to the boundary between discriminated union case identity, generated option spellings, case payload types, nested command structure and configuration key names and Usage descriptions, guidance, app-owned errors, command examples and explanations of default and configuration precedence. Observe which component is responsible before changing anything. A change to explanatory text should not become a change to a parser identifier, required input, validation predicate or machine data. When the apparent error arises from a shell command, inspect tokenization before the parser sees the input.
The practical correction is specific: Publish exact accepted inputs and describe any separate localized display rules. Keep the repair narrow enough to review and revert. Then revise the translated explanation so it tells a first-time user what the command requires and what observable outcome to expect. If no public library feature supports the proposed change, state the limitation and implement an application-owned layer rather than disguising an assumption as a documented capability.
Verification: Test 1.5 and 1,5 in the target runtime and state results accurately. Use a small fixture and record the observed result, not only a screenshot of the help screen. Ask a second person to repeat the task from the published instructions. A pass means they can choose the right action, preserve the relevant input and explain the result without guessing. If the command behaves correctly but the reader chooses the wrong action, the localization is still incomplete.
Investigation 14 — An enum-like value is translated without a mapping
A documented command uses a translated value for a recognized object state and is rejected. This is worth isolating because MuseumRoute, a fictional museum inventory tool used to coordinate exhibition object transfers must remain usable when one operator reads a different language from another. Begin by reproducing the exact input and recording what the operator expected, rather than editing the translation immediately. The discrepancy is not just a question of style; it can affect whether somebody completes the intended task or trusts an incorrect result.
Typed values can be machine identifiers even when their names resemble natural language. In F# Argu, this distinction belongs to the boundary between discriminated union case identity, generated option spellings, case payload types, nested command structure and configuration key names and Usage descriptions, guidance, app-owned errors, command examples and explanations of default and configuration precedence. Observe which component is responsible before changing anything. A change to explanatory text should not become a change to a parser identifier, required input, validation predicate or machine data. When the issue involves a displayed default, compare the text with the actual resolved value.
The practical correction is specific: Keep accepted tokens unchanged and give a glossary for human explanation. Keep the repair narrow enough to review and revert. Then revise the translated explanation so it tells a first-time user what the command requires and what observable outcome to expect. If no public library feature supports the proposed change, state the limitation and implement an application-owned layer rather than disguising an assumption as a documented capability.
Verification: Exercise every copyable state value with the real parser. Use a small fixture and record the observed result, not only a screenshot of the help screen. Ask a second person to repeat the task from the published instructions. A pass means they can choose the right action, preserve the relevant input and explain the result without guessing. If the command behaves correctly but the reader chooses the wrong action, the localization is still incomplete.
Investigation 15 — A renamed environment key breaks an existing deployment
An editor translates an environment variable name in documentation but the reader’s deployment still uses the old key. This is worth isolating because MuseumRoute, a fictional museum inventory tool used to coordinate exhibition object transfers must remain usable when one operator reads a different language from another. Begin by reproducing the exact input and recording what the operator expected, rather than editing the translation immediately. The discrepancy is not just a question of style; it can affect whether somebody completes the intended task or trusts an incorrect result.
External configuration names are integration contracts distinct from prose. In F# Argu, this distinction belongs to the boundary between discriminated union case identity, generated option spellings, case payload types, nested command structure and configuration key names and Usage descriptions, guidance, app-owned errors, command examples and explanations of default and configuration precedence. Observe which component is responsible before changing anything. A change to explanatory text should not become a change to a parser identifier, required input, validation predicate or machine data. When the issue appears only in another locale, inspect the exact same argv and parsed values in the source language.
The practical correction is specific: Preserve literal environment keys unless the application supports tested aliases. Keep the repair narrow enough to review and revert. Then revise the translated explanation so it tells a first-time user what the command requires and what observable outcome to expect. If no public library feature supports the proposed change, state the limitation and implement an application-owned layer rather than disguising an assumption as a documented capability.
Verification: Load the same fixture environment under two locales and compare resolved settings. Use a small fixture and record the observed result, not only a screenshot of the help screen. Ask a second person to repeat the task from the published instructions. A pass means they can choose the right action, preserve the relevant input and explain the result without guessing. If the command behaves correctly but the reader chooses the wrong action, the localization is still incomplete.
Investigation 16 — Conflicting options are described as compatible
A translation says two modes may be combined even though the application rejects or prioritizes one. This is worth isolating because MuseumRoute, a fictional museum inventory tool used to coordinate exhibition object transfers must remain usable when one operator reads a different language from another. Begin by reproducing the exact input and recording what the operator expected, rather than editing the translation immediately. The discrepancy is not just a question of style; it can affect whether somebody completes the intended task or trusts an incorrect result.
Behavioral constraints must be reflected in help, not inferred from independent option descriptions. In F# Argu, this distinction belongs to the boundary between discriminated union case identity, generated option spellings, case payload types, nested command structure and configuration key names and Usage descriptions, guidance, app-owned errors, command examples and explanations of default and configuration precedence. Observe which component is responsible before changing anything. A change to explanatory text should not become a change to a parser identifier, required input, validation predicate or machine data. When error handling is involved, inspect stderr and process exit status as well as the visible message.
The practical correction is specific: State precedence or mutual exclusion using observed behavior. Keep the repair narrow enough to review and revert. Then revise the translated explanation so it tells a first-time user what the command requires and what observable outcome to expect. If no public library feature supports the proposed change, state the limitation and implement an application-owned layer rather than disguising an assumption as a documented capability.
Verification: Run both options together and assert the documented response. Use a small fixture and record the observed result, not only a screenshot of the help screen. Ask a second person to repeat the task from the published instructions. A pass means they can choose the right action, preserve the relevant input and explain the result without guessing. If the command behaves correctly but the reader chooses the wrong action, the localization is still incomplete.
Investigation 17 — A help example contains typographic dashes
A publishing system replaces ASCII hyphens in –dry-run with lookalikes. This is worth isolating because MuseumRoute, a fictional museum inventory tool used to coordinate exhibition object transfers must remain usable when one operator reads a different language from another. Begin by reproducing the exact input and recording what the operator expected, rather than editing the translation immediately. The discrepancy is not just a question of style; it can affect whether somebody completes the intended task or trusts an incorrect result.
A visually similar character can be an unrecognized byte sequence for the parser. In F# Argu, this distinction belongs to the boundary between discriminated union case identity, generated option spellings, case payload types, nested command structure and configuration key names and Usage descriptions, guidance, app-owned errors, command examples and explanations of default and configuration precedence. Observe which component is responsible before changing anything. A change to explanatory text should not become a change to a parser identifier, required input, validation predicate or machine data. When the apparent error arises from a shell command, inspect tokenization before the parser sees the input.
The practical correction is specific: Keep exact snippets in code and verify the final rendered page copy. Keep the repair narrow enough to review and revert. Then revise the translated explanation so it tells a first-time user what the command requires and what observable outcome to expect. If no public library feature supports the proposed change, state the limitation and implement an application-owned layer rather than disguising an assumption as a documented capability.
Verification: Compare clipboard bytes from the published example with the accepted argv. Use a small fixture and record the observed result, not only a screenshot of the help screen. Ask a second person to repeat the task from the published instructions. A pass means they can choose the right action, preserve the relevant input and explain the result without guessing. If the command behaves correctly but the reader chooses the wrong action, the localization is still incomplete.
Investigation 18 — A default directory is presented as universal
A translated guide assumes the same home folder on Windows, macOS and Linux. This is worth isolating because MuseumRoute, a fictional museum inventory tool used to coordinate exhibition object transfers must remain usable when one operator reads a different language from another. Begin by reproducing the exact input and recording what the operator expected, rather than editing the translation immediately. The discrepancy is not just a question of style; it can affect whether somebody completes the intended task or trusts an incorrect result.
Paths and permission models vary; machine configuration remains environment-dependent. In F# Argu, this distinction belongs to the boundary between discriminated union case identity, generated option spellings, case payload types, nested command structure and configuration key names and Usage descriptions, guidance, app-owned errors, command examples and explanations of default and configuration precedence. Observe which component is responsible before changing anything. A change to explanatory text should not become a change to a parser identifier, required input, validation predicate or machine data. When the issue involves a displayed default, compare the text with the actual resolved value.
The practical correction is specific: Use platform-neutral explanations and document concrete tested examples per platform. Keep the repair narrow enough to review and revert. Then revise the translated explanation so it tells a first-time user what the command requires and what observable outcome to expect. If no public library feature supports the proposed change, state the limitation and implement an application-owned layer rather than disguising an assumption as a documented capability.
Verification: Run a sandbox case on each supported OS and verify the resolved folder. Use a small fixture and record the observed result, not only a screenshot of the help screen. Ask a second person to repeat the task from the published instructions. A pass means they can choose the right action, preserve the relevant input and explain the result without guessing. If the command behaves correctly but the reader chooses the wrong action, the localization is still incomplete.
Investigation 19 — An exception message is mistaken for translatable help
A conversion exception originates from .NET and is presented as if it were a stable Argu catalog key. This is worth isolating because MuseumRoute, a fictional museum inventory tool used to coordinate exhibition object transfers must remain usable when one operator reads a different language from another. Begin by reproducing the exact input and recording what the operator expected, rather than editing the translation immediately. The discrepancy is not just a question of style; it can affect whether somebody completes the intended task or trusts an incorrect result.
Framework exceptions, parser errors and application guidance have different owners. In F# Argu, this distinction belongs to the boundary between discriminated union case identity, generated option spellings, case payload types, nested command structure and configuration key names and Usage descriptions, guidance, app-owned errors, command examples and explanations of default and configuration precedence. Observe which component is responsible before changing anything. A change to explanatory text should not become a change to a parser identifier, required input, validation predicate or machine data. When the issue appears only in another locale, inspect the exact same argv and parsed values in the source language.
The practical correction is specific: Add contextual repair in an application-controlled layer rather than editing brittle raw exception text. Keep the repair narrow enough to review and revert. Then revise the translated explanation so it tells a first-time user what the command requires and what observable outcome to expect. If no public library feature supports the proposed change, state the limitation and implement an application-owned layer rather than disguising an assumption as a documented capability.
Verification: Test the actual exception path in the deployed version and review safe output. Use a small fixture and record the observed result, not only a screenshot of the help screen. Ask a second person to repeat the task from the published instructions. A pass means they can choose the right action, preserve the relevant input and explain the result without guessing. If the command behaves correctly but the reader chooses the wrong action, the localization is still incomplete.
Investigation 20 — A dependency update silently changes generated help
The NuGet lock changes and usage snapshots differ despite no explicit localization edit. This is worth isolating because MuseumRoute, a fictional museum inventory tool used to coordinate exhibition object transfers must remain usable when one operator reads a different language from another. Begin by reproducing the exact input and recording what the operator expected, rather than editing the translation immediately. The discrepancy is not just a question of style; it can affect whether somebody completes the intended task or trusts an incorrect result.
Generated help is tied to parser definitions and version behavior. In F# Argu, this distinction belongs to the boundary between discriminated union case identity, generated option spellings, case payload types, nested command structure and configuration key names and Usage descriptions, guidance, app-owned errors, command examples and explanations of default and configuration precedence. Observe which component is responsible before changing anything. A change to explanatory text should not become a change to a parser identifier, required input, validation predicate or machine data. When error handling is involved, inspect stderr and process exit status as well as the visible message.
The practical correction is specific: Treat changed snapshots as a review requirement and regenerate language examples as necessary. Keep the repair narrow enough to review and revert. Then revise the translated explanation so it tells a first-time user what the command requires and what observable outcome to expect. If no public library feature supports the proposed change, state the limitation and implement an application-owned layer rather than disguising an assumption as a documented capability.
Verification: Compare recognized flags, parsed cases and exit codes in a matrix for the previous and candidate versions. Use a small fixture and record the observed result, not only a screenshot of the help screen. Ask a second person to repeat the task from the published instructions. A pass means they can choose the right action, preserve the relevant input and explain the result without guessing. If the command behaves correctly but the reader chooses the wrong action, the localization is still incomplete.
Chapter 11 — A four-week practical learning route
Week 1: build the inventory
Read the exact option definitions and versioned docs. List every public command, value type, displayed help description and error channel. Run one correct example and one incorrect example before making changes. Assign each text to either executable grammar, human-facing explanation or user data. Make a baseline transcript and simple expected-output fixture. For F# Argu, keep the work anchored to ArgumentParser.Create, ParseCommandLine and the IArgParserTemplate Usage member; choose tests that expose that library’s actual parse and help behavior instead of inventing generic controls.
Week 2: translate one end-to-end task
Select a high-frequency user need and prepare a complete localized help journey, including a valid command and a recovery message. Keep the original parser tokens stable. Review placeholders, paths, default values and safety warnings with an engineer. Let a native-language reader attempt the task without an expert standing by. For F# Argu, keep the work anchored to ArgumentParser.Create, ParseCommandLine and the IArgParserTemplate Usage member; choose tests that expose that library’s actual parse and help behavior instead of inventing generic controls.
Week 3: stress the boundaries
Test Unicode filenames, spaces, narrower terminals, missing arguments, invalid values, unknown commands and noninteractive execution. Capture exact argv, parsed values, output streams and effects. Compare against the original language. Investigate any difference, including a failure that appears successful or a help instruction that copies incorrectly. For F# Argu, keep the work anchored to ArgumentParser.Create, ParseCommandLine and the IArgParserTemplate Usage member; choose tests that expose that library’s actual parse and help behavior instead of inventing generic controls.
Week 4: release and maintain
Lock supported versions, package approved translated text, rerun the fixture matrix and write down known limits. Have another reviewer verify the first-use task and the failure recovery. Publish the precise commands that were tested. Plan a regression run for future compiler, runtime and dependency upgrades. For F# Argu, keep the work anchored to ArgumentParser.Create, ParseCommandLine and the IArgParserTemplate Usage member; choose tests that expose that library’s actual parse and help behavior instead of inventing generic controls.
Chapter 12 — Frequently asked questions about F# Argu localization
What should I translate first?
Begin with the shortest successful invocation, its help explanation, a single invalid-input recovery and the user’s next decision. This captures an end-to-end task rather than an arbitrary collection of strings. Verify the command before expanding the language catalog. In the context of F# Argu, remember that Argu derives argument parsing and usage from F# discriminated unions and supports configuration readers as well as command-line input.
May I translate command flags into the reader’s language?
Not by editing documentation alone. A flag is an executable token. You may design aliases in the application if that is a justified compatibility project, but a prose translation must not pretend the software recognizes unimplemented names. In the context of F# Argu, remember that Argu derives argument parsing and usage from F# discriminated unions and supports configuration readers as well as command-line input.
Can the translated page change the defaults?
An explanation may clarify the current default but it should not silently reconfigure the application. Defaults, environment precedence and validation are behaviors to test. Write down the effective value observed with no explicit flags and keep the guide consistent with that observation. In the context of F# Argu, remember that Argu derives argument parsing and usage from F# discriminated unions and supports configuration readers as well as command-line input.
What if the framework prints English errors?
Distinguish dependency-owned output from app-owned messages. Use documented extension points where available; otherwise add a truthful contextual explanation and point users to a valid invocation. Do not claim that a nonexistent locale option solves the problem. In the context of F# Argu, remember that Argu derives argument parsing and usage from F# discriminated unions and supports configuration readers as well as command-line input.
How much do Unicode tests prove?
A successful UTF-8 rendering test shows one part of the experience. The application must also preserve path values, typed results, quoting and side effects. Validate actual machine behavior and have a reader assess comprehension in their language. In the context of F# Argu, remember that Argu derives argument parsing and usage from F# discriminated unions and supports configuration readers as well as command-line input.
Should translated prose appear in machine-readable output?
Only if the format deliberately defines human-facing fields. Stable identifiers and structured data often have consumers that depend on exact values. If a machine schema genuinely needs localization, make it an explicit versioned contract rather than an incidental wording change. In the context of F# Argu, remember that Argu derives argument parsing and usage from F# discriminated unions and supports configuration readers as well as command-line input.
Which languages make a useful first test matrix?
Use your actual audience first. For structural coverage, include one longer-word language, a non-Latin script, a right-to-left sample and the original English source, plus a representative path with accents and spaces. Native reviewer input matters because text that renders correctly can still mislead. In the context of F# Argu, remember that Argu derives argument parsing and usage from F# discriminated unions and supports configuration readers as well as command-line input.
Can an automatic translation replace manual validation?
Automatic systems can assist with drafts but cannot prove command compatibility, side effects, units or the correctness of error recovery. A reviewer should run the command, compare the outcome, explain the intended action and check technical terms against the product’s behavior. In the context of F# Argu, remember that Argu derives argument parsing and usage from F# discriminated unions and supports configuration readers as well as command-line input.
How do I measure whether a guide is useful?
Ask someone unfamiliar with the program to complete a realistic task, predict what changes, and recover from a deliberate invalid input. Measure completion, errors and time spent guessing, rather than relying only on a fluent style or a positive reaction to the page. In the context of F# Argu, remember that Argu derives argument parsing and usage from F# discriminated unions and supports configuration readers as well as command-line input.
How should I handle right-to-left text?
Keep exact command tokens in clearly separated code runs, watch punctuation ordering, check logical copying from the page and verify the shell receives the intended bytes. Mixed scripts can be visually deceptive even when the underlying string is valid. In the context of F# Argu, remember that Argu derives argument parsing and usage from F# discriminated unions and supports configuration readers as well as command-line input.
What belongs in a release checklist?
At minimum: locked runtime and dependency versions, a valid-command fixture, error-path fixture, help output, parsed-value assertions, Unicode path test, actual file-effect comparison, native-language review and a record of known limits. In the context of F# Argu, remember that Argu derives argument parsing and usage from F# discriminated unions and supports configuration readers as well as command-line input.
When should a translation be rejected?
Reject it when a reader cannot tell what the command will change, when a copyable example fails, when a safety caveat disappears, when a data token changes unexpectedly or when a failed invocation appears successful. These are functional faults, not stylistic preferences. In the context of F# Argu, remember that Argu derives argument parsing and usage from F# discriminated unions and supports configuration readers as well as command-line input.
Chapter 13 — What professional quality looks like
A trustworthy multilingual CLI guide lets a user identify the intended task, copy a real command, understand which files or records may change and recover from a predictable error. The translation should sound natural, but natural language is not the only success criterion. The application must still parse the same inputs and produce the same promised result. Versioned examples and task-based language review bring those two requirements together.
For MuseumRoute, a fictional museum inventory tool used to coordinate exhibition object transfers, the final standard is straightforward: the reader should not need an English-speaking engineer to make the operation safe and understandable. Keep exact tokens exact, explain machine values clearly, test non-Latin text where users need it, and revise the words when readers misinterpret a step. That combination is more useful than a long untranslated API reference or an attractive help page built on commands that do not run.