This Erlang/OTP argparse localization guide explains how to localize Erlang argparse command help, command trees, escript errors, handler names and Unicode terminal messages. It is written for Erlang developers producing escripts, administrative commands and reliable operations tools, 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 RiverWatch, a fictional river-monitoring team that summarizes sensor reports for several municipalities. 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 Erlang/OTP argparse 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: argparse was introduced in Erlang/OTP 26 and models a command as a tree with arguments and optional handlers. Translate help headings, option explanations, user-owned warnings, examples and operator recovery guidance; protect command keys, positional argument names and types, option spellings, handler map keys, program name and expected process status. The chapters below explain when that distinction is easy, when it fails, how to recover and how to check the result without pretending Erlang/OTP argparse offers translation features it does not document.
Quick reference — what to translate in Erlang/OTP argparse
- 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 Erlang/OTP argparse
Erlang/OTP argparse 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, command keys, positional argument names and types, option spellings, handler map keys, program name and expected process status 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 argparse:run/3 and command specifications in maps. argparse was introduced in Erlang/OTP 26 and models a command as a tree with arguments and optional handlers. 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.
the module generates usage and errors, but the exact customizability of library-owned messages is version-specific; translating text never authorizes changing command maps or callback contracts. 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.
%% Minimal documented concept for OTP 26+:
cli() ->
#{arguments => [
#{name => left, type => integer},
#{name => right, type => integer}
],
handler => fun(#{left := L, right := R}) ->
io:format("~B~n", [L * R])
end}.
main(Args) ->
argparse:run(Args, cli(), #{progname => multiply}).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 RiverWatch, a fictional river-monitoring team that summarizes sensor reports for several municipalities, 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 RiverWatch, a fictional river-monitoring team that summarizes sensor reports for several municipalities, 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 RiverWatch, a fictional river-monitoring team that summarizes sensor reports for several municipalities, 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 Erlang developers producing escripts, administrative commands and reliable operations tools 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 Erlang/OTP argparse 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 command key is translated but the dispatch tree is not
A localized example invokes resumir while the parser’s nested command map still recognizes summary. This is worth isolating because RiverWatch, a fictional river-monitoring team that summarizes sensor reports for several municipalities 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.
Command names are branch selectors in the command tree and do not become aliases when their description changes. In Erlang/OTP argparse, this distinction belongs to the boundary between command keys, positional argument names and types, option spellings, handler map keys, program name and expected process status and help headings, option explanations, user-owned warnings, examples and operator recovery guidance. 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: Retain the documented selector or explicitly register and test a compatible alias. 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 the same operation with every copyable example and assert the expected handler is selected. 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 — A parent argument vanishes from child documentation
The report subcommand inherits a station argument but the localized help omits it. This is worth isolating because RiverWatch, a fictional river-monitoring team that summarizes sensor reports for several municipalities 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.
argparse collects arguments along the command path, so the final invocation needs all required fields. In Erlang/OTP argparse, this distinction belongs to the boundary between command keys, positional argument names and types, option spellings, handler map keys, program name and expected process status and help headings, option explanations, user-owned warnings, examples and operator recovery guidance. 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: Explain inherited inputs beside the nested command example, not only on the root page. 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 child with and without the parent argument and inspect the 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 3 — A handler map pattern fails after renaming a field
A technical translator changes the argument name from station to punto in an Erlang specification. This is worth isolating because RiverWatch, a fictional river-monitoring team that summarizes sensor reports for several municipalities 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.
The callback matches named keys in a parsed map; changing names without code changes can cause a failure. In Erlang/OTP argparse, this distinction belongs to the boundary between command keys, positional argument names and types, option spellings, handler map keys, program name and expected process status and help headings, option explanations, user-owned warnings, examples and operator recovery guidance. 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 declared argument names stable or perform an explicit API refactor separately. 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 the valid command and assert that the matched map contains the original atom key. 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 — A program assumes argparse exists on every runtime
An escript is deployed on OTP 25 after documentation was written against OTP 28. This is worth isolating because RiverWatch, a fictional river-monitoring team that summarizes sensor reports for several municipalities 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.
The built-in argparse module was introduced in OTP 26, so older runtimes cannot satisfy the example. In Erlang/OTP argparse, this distinction belongs to the boundary between command keys, positional argument names and types, option spellings, handler map keys, program name and expected process status and help headings, option explanations, user-owned warnings, examples and operator recovery guidance. 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 minimum supported OTP and provide a version check, not an unsupported promise. 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: Execute the release binary under the declared supported runtimes. 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 numerical sensor reading is localized as free text
The guide replaces a machine-recognized decimal value with one using a local digit separator. This is worth isolating because RiverWatch, a fictional river-monitoring team that summarizes sensor reports for several municipalities 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.
Type conversion belongs to the parser; a visible language does not automatically change accepted numeric syntax. In Erlang/OTP argparse, this distinction belongs to the boundary between command keys, positional argument names and types, option spellings, handler map keys, program name and expected process status and help headings, option explanations, user-owned warnings, examples and operator recovery guidance. 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: Give exact accepted numbers in runnable commands and explain display conventions outside the code. 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 negative, fractional and boundary values, checking parsed types and units. 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 — An unknown command returns a misleading success status
A wrapper prints a translated unknown-command explanation and exits zero. This is worth isolating because RiverWatch, a fictional river-monitoring team that summarizes sensor reports for several municipalities 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.
Invalid command selection must not look like completed processing to automation. In Erlang/OTP argparse, this distinction belongs to the boundary between command keys, positional argument names and types, option spellings, handler map keys, program name and expected process status and help headings, option explanations, user-owned warnings, examples and operator recovery guidance. 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 a nonzero status and send the diagnostic to the appropriate output channel. 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: Call an unknown subcommand from a test script and assert a failure exit code. 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 — The usage template rearranges away required arguments
An ambitious translated template emphasizes options but never shows positional inputs. This is worth isolating because RiverWatch, a fictional river-monitoring team that summarizes sensor reports for several municipalities 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.
Templates change display organization, not the underlying requirement for positional arguments. In Erlang/OTP argparse, this distinction belongs to the boundary between command keys, positional argument names and types, option spellings, handler map keys, program name and expected process status and help headings, option explanations, user-owned warnings, examples and operator recovery guidance. 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: Display usage and argument explanations together in a way that preserves the complete command shape. 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: Ask a reader to assemble a valid command from the translated help alone. 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 — A hidden command is described as removed
A help change hides a maintenance subcommand and the manual claims it no longer works. This is worth isolating because RiverWatch, a fictional river-monitoring team that summarizes sensor reports for several municipalities 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.
Suppressing a command from generated help is not equivalent to deleting its handler. In Erlang/OTP argparse, this distinction belongs to the boundary between command keys, positional argument names and types, option spellings, handler map keys, program name and expected process status and help headings, option explanations, user-owned warnings, examples and operator recovery guidance. 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: Describe discoverability separately from access policy and maintain a security review for sensitive operations. 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: Call the command directly in an authorized sandbox to verify actual behavior. 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 path with spaces becomes two positional values
An example passes a station archive file with spaces unquoted. This is worth isolating because RiverWatch, a fictional river-monitoring team that summarizes sensor reports for several municipalities 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.
The shell splits tokens before argparse sees them, independently from the locale of the help text. In Erlang/OTP argparse, this distinction belongs to the boundary between command keys, positional argument names and types, option spellings, handler map keys, program name and expected process status and help headings, option explanations, user-owned warnings, examples and operator recovery guidance. 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: Provide shell-specific quoting and avoid converting typographic quotation marks into executable syntax. 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: Inspect the received argv and confirm the file opens as one path. 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 — Unicode name is altered during help translation
A non-Latin station name is treated as translatable prose inside the command example. This is worth isolating because RiverWatch, a fictional river-monitoring team that summarizes sensor reports for several municipalities 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.
User data and proper names are values, not localization keys. In Erlang/OTP argparse, this distinction belongs to the boundary between command keys, positional argument names and types, option spellings, handler map keys, program name and expected process status and help headings, option explanations, user-owned warnings, examples and operator recovery guidance. 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 the name unchanged in commands, explain it separately and preserve the expected encoding. 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 the same test file with its exact Unicode name and compare checksums. 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 — An argument type changes by accident
An option described as a count is silently changed from integer to string when developers alter help. This is worth isolating because RiverWatch, a fictional river-monitoring team that summarizes sensor reports for several municipalities 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.
The type property controls parser conversion; it must not be modified as part of textual translation. In Erlang/OTP argparse, this distinction belongs to the boundary between command keys, positional argument names and types, option spellings, handler map keys, program name and expected process status and help headings, option explanations, user-owned warnings, examples and operator recovery guidance. 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: Review schema diffs and keep human labels independent from parsed types. 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 the handler receives an integer for a supported count in every locale. 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 generated diagnostic is claimed to be editable without checking
The translation plan assumes every library error string has a public locale hook. This is worth isolating because RiverWatch, a fictional river-monitoring team that summarizes sensor reports for several municipalities 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.
The library may own some wording; support depends on the installed OTP release and exposed APIs. In Erlang/OTP argparse, this distinction belongs to the boundary between command keys, positional argument names and types, option spellings, handler map keys, program name and expected process status and help headings, option explanations, user-owned warnings, examples and operator recovery guidance. 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: Label app-owned messages separately and provide a faithful fallback where direct localization is unavailable. 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: Inspect actual error output on the tested release and match it with the guide’s promise. 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 child command is ambiguously named in translation
Two different operations receive the same translated heading and users choose the wrong one. This is worth isolating because RiverWatch, a fictional river-monitoring team that summarizes sensor reports for several municipalities 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.
Even with stable machine tokens, a human-facing label can lose an important distinction. In Erlang/OTP argparse, this distinction belongs to the boundary between command keys, positional argument names and types, option spellings, handler map keys, program name and expected process status and help headings, option explanations, user-owned warnings, examples and operator recovery guidance. 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 action-oriented descriptions that distinguish read-only inspection from data modification. 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: Ask native-language users to predict each subcommand’s effect before seeing the implementation. 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 — A root program name is not the installed executable
Examples use a translated title in place of the actual escript executable name. This is worth isolating because RiverWatch, a fictional river-monitoring team that summarizes sensor reports for several municipalities 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.
The program name used in usage and the shell executable must correspond to the installed artifact. In Erlang/OTP argparse, this distinction belongs to the boundary between command keys, positional argument names and types, option spellings, handler map keys, program name and expected process status and help headings, option explanations, user-owned warnings, examples and operator recovery guidance. 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: Make the runnable path exact and translate only its surrounding 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: Execute the published quick-start snippet in a clean installation directory. 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 — Error output contaminates a stream consumed by another tool
A translated failure explanation is printed where a downstream CSV parser expects rows. This is worth isolating because RiverWatch, a fictional river-monitoring team that summarizes sensor reports for several municipalities 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.
Human diagnostics and structured data are separate interfaces. In Erlang/OTP argparse, this distinction belongs to the boundary between command keys, positional argument names and types, option spellings, handler map keys, program name and expected process status and help headings, option explanations, user-owned warnings, examples and operator recovery guidance. 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: Route faults to stderr and preserve stdout as the documented machine output. 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: Pipe stdout into a strict reader and assert that bad inputs yield no fabricated data. 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 — An argument in a parent command is duplicated below
A translated guide asks users to supply the same station identifier twice. This is worth isolating because RiverWatch, a fictional river-monitoring team that summarizes sensor reports for several municipalities 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.
Command inheritance can already provide the field to nested handlers. In Erlang/OTP argparse, this distinction belongs to the boundary between command keys, positional argument names and types, option spellings, handler map keys, program name and expected process status and help headings, option explanations, user-owned warnings, examples and operator recovery guidance. 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: Document one authoritative command layout that mirrors the active command specification. 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: Capture argv and handler map to ensure each intended value appears once. 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 — The operator cannot distinguish help from an error
Both a –help request and an invalid input display nearly identical translated banners. This is worth isolating because RiverWatch, a fictional river-monitoring team that summarizes sensor reports for several municipalities 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 deliberate help request and a failure have different user expectations and process semantics. In Erlang/OTP argparse, this distinction belongs to the boundary between command keys, positional argument names and types, option spellings, handler map keys, program name and expected process status and help headings, option explanations, user-owned warnings, examples and operator recovery guidance. 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: Add a concise explanatory message for failures and preserve the intended status codes. 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 help and invalid syntax separately, including the absence of side effects. 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 — Terminal columns obscure a critical unit
The help alignment wraps a flow-rate unit onto a distant line in a narrow terminal. This is worth isolating because RiverWatch, a fictional river-monitoring team that summarizes sensor reports for several municipalities 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.
Long translated text and multilingual glyph widths can break fixed column assumptions. In Erlang/OTP argparse, this distinction belongs to the boundary between command keys, positional argument names and types, option spellings, handler map keys, program name and expected process status and help headings, option explanations, user-owned warnings, examples and operator recovery guidance. 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 plain labels with explicit units and inspect narrow and wide console rendering. 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: Show the output at 40 and 100 columns and ask a reader to identify the unit. 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 — A flag’s literal punctuation is converted in publishing
An editorial tool changes ASCII hyphens or quotes within runnable snippets. This is worth isolating because RiverWatch, a fictional river-monitoring team that summarizes sensor reports for several municipalities 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 parser recognizes exact bytes, while typography tools operate for display quality. In Erlang/OTP argparse, this distinction belongs to the boundary between command keys, positional argument names and types, option spellings, handler map keys, program name and expected process status and help headings, option explanations, user-owned warnings, examples and operator recovery guidance. 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: Render commands as code and validate copying from the live page. 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 copied bytes against a verified fixture before publication. 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 — Localized help lags behind a newly added subcommand
A software release adds export but French documentation still lists only inspect and summary. This is worth isolating because RiverWatch, a fictional river-monitoring team that summarizes sensor reports for several municipalities 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.
Command trees and help inventories must remain synchronized across languages. In Erlang/OTP argparse, this distinction belongs to the boundary between command keys, positional argument names and types, option spellings, handler map keys, program name and expected process status and help headings, option explanations, user-owned warnings, examples and operator recovery guidance. 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: Regenerate command inventories and translate the new descriptions before release. 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 accepted command paths with every locale’s help list. 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 Erlang/OTP argparse, keep the work anchored to argparse:run/3 and command specifications in maps; 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 Erlang/OTP argparse, keep the work anchored to argparse:run/3 and command specifications in maps; 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 Erlang/OTP argparse, keep the work anchored to argparse:run/3 and command specifications in maps; 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 Erlang/OTP argparse, keep the work anchored to argparse:run/3 and command specifications in maps; choose tests that expose that library’s actual parse and help behavior instead of inventing generic controls.
Chapter 12 — Frequently asked questions about Erlang/OTP argparse 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 Erlang/OTP argparse, remember that argparse was introduced in Erlang/OTP 26 and models a command as a tree with arguments and optional handlers.
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 Erlang/OTP argparse, remember that argparse was introduced in Erlang/OTP 26 and models a command as a tree with arguments and optional handlers.
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 Erlang/OTP argparse, remember that argparse was introduced in Erlang/OTP 26 and models a command as a tree with arguments and optional handlers.
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 Erlang/OTP argparse, remember that argparse was introduced in Erlang/OTP 26 and models a command as a tree with arguments and optional handlers.
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 Erlang/OTP argparse, remember that argparse was introduced in Erlang/OTP 26 and models a command as a tree with arguments and optional handlers.
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 Erlang/OTP argparse, remember that argparse was introduced in Erlang/OTP 26 and models a command as a tree with arguments and optional handlers.
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 Erlang/OTP argparse, remember that argparse was introduced in Erlang/OTP 26 and models a command as a tree with arguments and optional handlers.
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 Erlang/OTP argparse, remember that argparse was introduced in Erlang/OTP 26 and models a command as a tree with arguments and optional handlers.
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 Erlang/OTP argparse, remember that argparse was introduced in Erlang/OTP 26 and models a command as a tree with arguments and optional handlers.
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 Erlang/OTP argparse, remember that argparse was introduced in Erlang/OTP 26 and models a command as a tree with arguments and optional handlers.
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 Erlang/OTP argparse, remember that argparse was introduced in Erlang/OTP 26 and models a command as a tree with arguments and optional handlers.
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 Erlang/OTP argparse, remember that argparse was introduced in Erlang/OTP 26 and models a command as a tree with arguments and optional handlers.
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 RiverWatch, a fictional river-monitoring team that summarizes sensor reports for several municipalities, 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.