Translate Like a Pro | 9050 — .NET docopt.net Localization, Usage Grammar, C# Source Generator, Help Text and Release QA

.NET docopt.net localization starts with a distinctive design: the usage message is not merely a help page but part of the grammar used to recognize a program’s arguments. Searches for docopt.net C# usage patterns, source generator, .docopt.txt, translated help, options and CLI errors therefore need more than advice to translate sentences naturally. The writer must preserve executable command words, grammar punctuation and option relationships while making the surrounding explanation accurate for another language.

Suppose a small C# utility displays a read-only status note using status-note show <project> [–format=<kind>]. A French user wants to understand the project placeholder, a Portuguese user wants to distinguish the –format choice from a file path, and an Arabic user must copy the left-to-right syntax correctly. Rewriting the grammar keyword show as an unrelated translated verb might alter what the parser accepts. Rewriting the descriptive sentence below it is ordinarily safe, provided the same accepted patterns remain intact.

This guide explains the differences between legacy and newer docopt.net APIs, the Usage and Options sections, option defaults, branches and repetition, source-generator workflows for C# 9 or later, files ending in .docopt.txt, and safe error handling. It builds from a small example toward multilingual publication and release QA. The examples focus on reading data and explaining behavior rather than modifying external systems; each translated guide should be checked against the compiled program it accompanies.

Quick answer: a reliable international command-line guide

Keep the actual executable options, argument grammar and aliases unchanged unless the application intentionally supports additional spellings.
Translate task explanations, recovery advice, help descriptions and examples in natural language for the reader.
Use a disposable, read-only example so that a first test cannot overwrite someone else’s work.
Test successful use, a request for help, a missing input and an unknown token with the released build.
Check Unicode, narrow terminals, right-to-left presentation, quoting and exit status separately.

Start with the user’s job, not the parser’s internal vocabulary

Someone encountering .NET docopt.net for the first time usually has a straightforward question: which command should I enter, which values may I replace, and how do I know that it worked? The technical reference is indispensable to the programmer, but a useful guide begins at the reader’s desk. Show a safe invocation, name what it does, then explain the syntax only to the depth needed to prevent a mistake. A command-line reference becomes more useful when each unfamiliar term is connected to an observable result.

For a C# developer maintaining a multilingual read-only project status CLI, the difference between a literal token and a replaceable value is fundamental. The words printed by the application can be translated. The actual option names are an agreement between code and user, often also depended upon by scripts. A locale can shape explanation, examples and formatting without secretly breaking that agreement. When an application really does offer language-specific aliases, register and test them as public features rather than assuming that fluent translation makes them executable.

The first job of review is to identify four layers: the shell turns a typed line into arguments; .NET docopt.net interprets the argument grammar; the application checks whether the requested operation is meaningful; and the terminal displays messages. A failure in one layer may look like a problem in another. A path containing spaces can be split by the shell. A misspelled option may be rejected by the parser. A missing file may be rejected by the application. Accented letters may be correct in memory but displayed with the wrong terminal encoding. Diagnosis begins by finding the layer, not blaming the language.

A small, read-only example you can reason about

using DocoptNet;
const string help = @"Read-only project status.
Usage:
  status-note show <project> [--format=<kind>]
  status-note (-h | --help)
Options:
  -h --help        Display help.
  --format=<kind>  Display style [default: short].
";
static int Show(IDictionary<string, ArgValue> args) {
  Console.WriteLine("Parsed: " + args["<project>"]);
  return 0;
}
return Docopt.CreateParser(help).Parse(args).Match(
  Show,
  result => { Console.WriteLine(result.Help); return 0; },
  result => { Console.Error.WriteLine(result.Usage); return 2; });

The sample is deliberately educational and read-only. It shows the public shape of the command and the relevant parser APIs without requiring a live service or personal data. Treat any filenames, project identifiers and directories in the examples as disposable test fixtures. Install the library and compiler or runtime required by the chosen version, then compile or run the sample locally before depending on exact output strings. Library versions and application wrappers can alter the final diagnostic text.

A valid invocation:

status-note show atlas --format=short

A deliberate input error:

status-note show

The second command is a teaching instrument, not a recommended work command. The point is to make a predictable mistake in a safe fixture and see which condition the parser or application reports. Note three observations: what text appears on standard output, what text appears on standard error, and what exit status the process returns. A human reader may notice only the message; an automated script often depends on the status. Translators should review both forms of communication.

How to read every line of a localized command

Literal program name: the executable invoked in a particular installation; replace it only when packaging gives it a different name.
Literal option: a name beginning with one or two hyphens, recognized only if the application registers it.
Replaceable value: a sample project name, filename, path, number or enum value; not all translated values are valid.
Grammar punctuation: brackets, vertical bars, equals signs and angle brackets may carry syntactic meaning in help or usage specifications.
Human explanation: sentences explaining purpose, consequences and recovery; these should read naturally in the target language.

A practical translation worksheet has two columns. In the first, copy the exact command fragment as accepted by the program. In the second, write what that fragment does in plain language. Do not treat those columns as alternative spellings of the same thing. The reader should be able to copy the first column and understand the second. This small discipline prevents a large class of errors, including translated flags that cannot run, placeholders mistaken for required literal text, and natural-language paraphrases that sound reassuring but hide an important condition.

The declaration and option contract

1. Usage text is executable grammar

docopt.net parses a Usage section to recognize commands and their relationships; it is not only a decorative summary of existing code.

A translator replaces the literal command word show with a paraphrase in the grammar, changing what successful invocations must look like.

A useful way to investigate this is to keep the command and the output together. Ask which part is a fixed program token, which part is data supplied by the reader, and which part is an explanation that may vary by language. A revision should improve the reader’s next action without changing executable meaning.

Practical check: Compare accepted commands before and after any localized help change and keep an invariant list of public tokens. Record the input, the observed result and the relevant version or environment. If the output differs from the prose, update the explanation to fit the behavior rather than making an untested claim. For French, Portuguese and Arabic, ask a fluent reader to identify the exact characters that must remain unchanged and the words that can be explained naturally.

2. The Usage header

A correctly structured Usage section tells the parser how program invocation patterns begin and repeat; arbitrary headings are not equivalent.

An editor translates the grammar header without checking the parser and the application stops recognizing the intended patterns.

The practical question is not whether the translation sounds natural in isolation, but whether a reader can use it to predict what the application accepts and what happens when a condition is not met. State the limit openly, show the smallest informative example, and resist inventing features the library does not promise.

Practical check: Test a candidate localized help string with the same parser API before putting it into a shipped executable. Record the input, the observed result and the relevant version or environment. If the output differs from the prose, update the explanation to fit the behavior rather than making an untested claim. For French, Portuguese and Arabic, ask a fluent reader to identify the exact characters that must remain unchanged and the words that can be explained naturally.

3. Options section semantics

Option descriptions explain how named flags accept values and may declare defaults, making this section both informative and structurally significant.

A translated options table accidentally changes –format=<kind> to a different token, so the parser does not map the intended value.

This matters especially when a guide is read by someone who cannot consult the English source. They need an instruction that stands alone: the purpose, the permissible form, the outcome and a way to recover. Check whether a fluent reviewer interprets the sample in the same way as the running program.

Practical check: Preserve functional option names and value-binding syntax; translate descriptions in their own fields. Record the input, the observed result and the relevant version or environment. If the output differs from the prose, update the explanation to fit the behavior rather than making an untested claim. For French, Portuguese and Arabic, ask a fluent reader to identify the exact characters that must remain unchanged and the words that can be explained naturally.

4. Required placeholders

The <project> placeholder stands for required user data in the status-note example; it is not the literal text a user must type.

A help page asks a reader to copy the angle brackets and then fails to explain the missing project error.

Treat the parser as one component of a larger human task. The user’s intention may be simple, but a successful command still crosses layers: shell parsing, argument interpretation, application checks and visible output. The explanation should identify the component responsible for the condition being discussed.

Practical check: Show a real sample such as atlas and separately identify the replaceable placeholder. Record the input, the observed result and the relevant version or environment. If the output differs from the prose, update the explanation to fit the behavior rather than making an untested claim. For French, Portuguese and Arabic, ask a fluent reader to identify the exact characters that must remain unchanged and the words that can be explained naturally.

5. Square brackets indicate optionality

In docopt grammar, [item] indicates an optional component of an invocation, distinct from the ordinary punctuation of prose.

A translation deletes the brackets as stylistic clutter and unintentionally turns optional –format into a mandatory input.

In international documentation, the most costly errors are often small. A single changed hyphen, an omitted mandatory value or an untested default can turn an otherwise professional translation into a dead end. Prefer tested literal examples to decorative variation; explain the reason for every important constraint.

Practical check: Run both status-note show atlas and the form with –format; compare parser results. Record the input, the observed result and the relevant version or environment. If the output differs from the prose, update the explanation to fit the behavior rather than making an untested claim. For French, Portuguese and Arabic, ask a fluent reader to identify the exact characters that must remain unchanged and the words that can be explained naturally.

6. Parentheses group alternatives

Parentheses and vertical bars can describe grouped choices such as (-h | –help), with semantics beyond typography.

A formatting pass removes the vertical bar and creates a pattern readers cannot execute as intended.

A translated help sentence should lead toward correct action, not merely describe a class name. Name the decision a user faces, show what happens with a valid example, then compare a controlled invalid example. If both examples produce the same result, investigate the actual configuration before finalizing the guide.

Practical check: Keep grammar punctuation in code-styled blocks and test every branch of an alternation. Record the input, the observed result and the relevant version or environment. If the output differs from the prose, update the explanation to fit the behavior rather than making an untested claim. For French, Portuguese and Arabic, ask a fluent reader to identify the exact characters that must remain unchanged and the words that can be explained naturally.

7. Ellipses mean repetition

The three-dot repetition marker can allow multiple occurrences; it is not a vague invitation to type any extra text.

A translator changes <file>… to a prose phrase and destroys the intended multiple-file grammar.

There is a useful distinction between a happy-path demo and a durable reference. The demo shows how something works once; the reference teaches how to recognize wrong input, uncertain defaults and environment-dependent behavior. Readers who can recover without guessing have gained a transferable skill.

Practical check: Supply two and three values in a fixture and inspect the resulting parsed structure. Record the input, the observed result and the relevant version or environment. If the output differs from the prose, update the explanation to fit the behavior rather than making an untested claim. For French, Portuguese and Arabic, ask a fluent reader to identify the exact characters that must remain unchanged and the words that can be explained naturally.

Required values, alternatives and defaults

8. Literal command words

Words such as show in a Usage pattern can be literal commands, whereas words inside angle brackets identify placeholders.

A multilingual team translates both kinds identically and silently changes the tool’s public command interface.

Practical check: Annotate command literals and placeholders differently in the translator’s reference copy. Record the input, the observed result and the relevant version or environment. If the output differs from the prose, update the explanation to fit the behavior rather than making an untested claim. For French, Portuguese and Arabic, ask a fluent reader to identify the exact characters that must remain unchanged and the words that can be explained naturally.

9. The reference Python lineage

docopt.net follows the docopt language tradition but its APIs and typed C# integration differ from reference Python docopt.

A guide imports Python-specific docopt examples and claims their C# API signatures work unmodified.

Practical check: Use docopt.net documentation and compile a C# example rather than copying Python code. Record the input, the observed result and the relevant version or environment. If the output differs from the prose, update the explanation to fit the behavior rather than making an untested claim. For French, Portuguese and Arabic, ask a fluent reader to identify the exact characters that must remain unchanged and the words that can be explained naturally.

10. Newer CreateParser API

The documented newer API uses Docopt.CreateParser(help).Parse(args) and exposes typed result variants for success and help or error pathways.

An outdated tutorial calls a legacy API but labels its sample as the recommended source-generator workflow.

Practical check: Name which API variant is shown and keep examples internally consistent. Record the input, the observed result and the relevant version or environment. If the output differs from the prose, update the explanation to fit the behavior rather than making an untested claim. For French, Portuguese and Arabic, ask a fluent reader to identify the exact characters that must remain unchanged and the words that can be explained naturally.

11. Match result handling

Match can direct successful arguments, help and input errors into distinct handlers; each one should produce appropriate output and status.

A translated guide sends parse failure down the successful data path, producing a misleading preview.

Practical check: Test one valid command, –help and one invalid command, capturing each handler result. Record the input, the observed result and the relevant version or environment. If the output differs from the prose, update the explanation to fit the behavior rather than making an untested claim. For French, Portuguese and Arabic, ask a fluent reader to identify the exact characters that must remain unchanged and the words that can be explained naturally.

12. Pattern matching on results

C# pattern matching can distinguish IArgumentsResult, IHelpResult, IVersionResult and IInputErrorResult in documented scenarios.

A developer assumes result variants are always identical regardless of whether version support was configured.

Practical check: Inspect the actual parser configuration and cover every returned case required by the selected API. Record the input, the observed result and the relevant version or environment. If the output differs from the prose, update the explanation to fit the behavior rather than making an untested claim. For French, Portuguese and Arabic, ask a fluent reader to identify the exact characters that must remain unchanged and the words that can be explained naturally.

13. Source generator is optional

docopt.net offers a C# source generator for projects using a suitable compiler and version, but ordinary parser APIs also exist.

A beginner thinks they must add code generation for a five-line CLI before learning the grammar.

Practical check: Start with simple parsing, then explain why generated typed arguments help larger applications. Record the input, the observed result and the relevant version or environment. If the output differs from the prose, update the explanation to fit the behavior rather than making an untested claim. For French, Portuguese and Arabic, ask a fluent reader to identify the exact characters that must remain unchanged and the words that can be explained naturally.

14. Files ending .docopt.txt

The source generator can discover an external usage file whose name ends in .docopt.txt, making documentation a build input.

A translation pipeline stores locale files under a different extension and assumes they are all automatically compiled.

Practical check: Inspect build inclusion, generated class names and which locale’s file is actually used. Record the input, the observed result and the relevant version or environment. If the output differs from the prose, update the explanation to fit the behavior rather than making an untested claim. For French, Portuguese and Arabic, ask a fluent reader to identify the exact characters that must remain unchanged and the words that can be explained naturally.

Help text, error messages and documentation

15. String-constant generation

The documented generator also supports usage text embedded as an appropriate C# string constant under its supported workflow.

Editors rewrite the constant as interpolated prose and accidentally change parse-sensitive grammar punctuation.

Practical check: Keep grammar content deterministic and compile the exact string the application will ship. Record the input, the observed result and the relevant version or environment. If the output differs from the prose, update the explanation to fit the behavior rather than making an untested claim. For French, Portuguese and Arabic, ask a fluent reader to identify the exact characters that must remain unchanged and the words that can be explained naturally.

16. Compile-time typed arguments

A generated type can make incompatible changes to a Usage declaration visible during compilation rather than only at runtime.

A help update changes argument names but call sites still access an older generated property and fail to build.

Practical check: Treat compilation failures as evidence of a changed contract, not merely an inconvenience to suppress. Record the input, the observed result and the relevant version or environment. If the output differs from the prose, update the explanation to fit the behavior rather than making an untested claim. For French, Portuguese and Arabic, ask a fluent reader to identify the exact characters that must remain unchanged and the words that can be explained naturally.

17. Generated code and version pinning

Source-generator behavior depends on package and compiler versions; a sample must state the relevant documented API family.

A guide copied from a different release generates a different class surface than the application’s code expects.

Practical check: Pin package versions in the example project and rebuild generated artifacts in a clean environment. Record the input, the observed result and the relevant version or environment. If the output differs from the prose, update the explanation to fit the behavior rather than making an untested claim. For French, Portuguese and Arabic, ask a fluent reader to identify the exact characters that must remain unchanged and the words that can be explained naturally.

18. Default values are meaningful

An options description can specify a default, such as [default: short], and this affects the parsed result when omitted.

A translator changes the default label to a different value without updating its functional meaning.

Practical check: Test the invocation with –format omitted and confirm which actual value is delivered. Record the input, the observed result and the relevant version or environment. If the output differs from the prose, update the explanation to fit the behavior rather than making an untested claim. For French, Portuguese and Arabic, ask a fluent reader to identify the exact characters that must remain unchanged and the words that can be explained naturally.

19. Value labels versus accepted values

A placeholder like <kind> identifies a value slot, but accepted values such as short may be application-defined rather than translated labels.

A localized help page tells readers to use a translated display name that the application rejects.

Practical check: Use a tested literal value in examples and translate the explanation of the value separately. Record the input, the observed result and the relevant version or environment. If the output differs from the prose, update the explanation to fit the behavior rather than making an untested claim. For French, Portuguese and Arabic, ask a fluent reader to identify the exact characters that must remain unchanged and the words that can be explained naturally.

20. Help and version branches

Help and version are distinct result paths with their own display and status behavior when configured.

A reader invoking –help is incorrectly told they must first supply the required project name.

Practical check: Test help without project arguments and check any version-specific branch separately. Record the input, the observed result and the relevant version or environment. If the output differs from the prose, update the explanation to fit the behavior rather than making an untested claim. For French, Portuguese and Arabic, ask a fluent reader to identify the exact characters that must remain unchanged and the words that can be explained naturally.

21. Input errors versus semantic errors

The parser can decide whether the tokens match Usage syntax, but application rules decide whether a project exists or a format is valid.

A document claims a parsed project identifier proves the underlying project is real.

Practical check: Run a syntactically valid nonexistent project and explain the second-stage application check. Record the input, the observed result and the relevant version or environment. If the output differs from the prose, update the explanation to fit the behavior rather than making an untested claim. For French, Portuguese and Arabic, ask a fluent reader to identify the exact characters that must remain unchanged and the words that can be explained naturally.

International terminals, accessibility and safe examples

22. ArgValue types

The newer API can expose argument values as ArgValue entries rather than arbitrary strings; code must interpret them correctly.

A translation tutorial treats all results as simple strings, obscuring Booleans or repeated collections.

Practical check: Inspect the real ArgValue for command branches, values and absent options in a fixture. Record the input, the observed result and the relevant version or environment. If the output differs from the prose, update the explanation to fit the behavior rather than making an untested claim. For French, Portuguese and Arabic, ask a fluent reader to identify the exact characters that must remain unchanged and the words that can be explained naturally.

23. Legacy Apply API

Older documentation shows Docopt.Apply and dictionary-like results; it should not be mixed casually with newer Match examples.

A beginner combines a legacy Apply sample with generated-type code and gets confusing compile errors.

Practical check: Keep separate minimal examples when discussing migration and identify the actual package version. Record the input, the observed result and the relevant version or environment. If the output differs from the prose, update the explanation to fit the behavior rather than making an untested claim. For French, Portuguese and Arabic, ask a fluent reader to identify the exact characters that must remain unchanged and the words that can be explained naturally.

24. Error recovery language

An input error should identify expected usage and tell the reader how to correct the offending command, not blame translation.

A localized error simply says ‘invalid’ with no command that would demonstrate the right pattern.

Practical check: Write one specific correction for a missing project, then test the reader can use it. Record the input, the observed result and the relevant version or environment. If the output differs from the prose, update the explanation to fit the behavior rather than making an untested claim. For French, Portuguese and Arabic, ask a fluent reader to identify the exact characters that must remain unchanged and the words that can be explained naturally.

25. Unicode project names

A project identifier may contain non-ASCII characters, but passing through the parser is distinct from downstream lookup and normalization.

A guide promises that any Unicode spelling finds the same project even though names are case- or normalization-sensitive.

Practical check: Test composed and decomposed forms and state how the application’s project lookup handles them. Record the input, the observed result and the relevant version or environment. If the output differs from the prose, update the explanation to fit the behavior rather than making an untested claim. For French, Portuguese and Arabic, ask a fluent reader to identify the exact characters that must remain unchanged and the words that can be explained naturally.

26. Right-to-left usage examples

Right-to-left instructional prose can disrupt how left-to-right Usage syntax appears when punctuation shares a paragraph.

A novice copies a reversed equals sign or option prefix from an Arabic help screen.

Practical check: Isolate code-styled Usage blocks and independently copy each command into the target terminal. Record the input, the observed result and the relevant version or environment. If the output differs from the prose, update the explanation to fit the behavior rather than making an untested claim. For French, Portuguese and Arabic, ask a fluent reader to identify the exact characters that must remain unchanged and the words that can be explained naturally.

27. CJK line wrapping

Translated longer descriptions can wrap unpredictably in console widths based on fonts and glyph width.

A formatter makes the optionality brackets appear attached to the wrong option after a line break.

Practical check: Test help at narrow terminal widths and preserve clear indentation between grammar and explanation. Record the input, the observed result and the relevant version or environment. If the output differs from the prose, update the explanation to fit the behavior rather than making an untested claim. For French, Portuguese and Arabic, ask a fluent reader to identify the exact characters that must remain unchanged and the words that can be explained naturally.

28. Console encoding and streams

C# strings may carry Unicode correctly while console output still depends on encoding, fonts, shell and platform.

An editor declares the localization broken although only the terminal display environment differs.

Practical check: Compare captured output bytes, terminal rendering, stdout and stderr before assigning a cause. Record the input, the observed result and the relevant version or environment. If the output differs from the prose, update the explanation to fit the behavior rather than making an untested claim. For French, Portuguese and Arabic, ask a fluent reader to identify the exact characters that must remain unchanged and the words that can be explained naturally.

Release compatibility, testing and reader recovery

29. Application exit codes

The code calling the parser must return predictable status for success, help and bad usage.

An integration test assumes a printed error implies a nonzero status, but the handler returned zero.

Practical check: Add assertions for the main return code and show an error pathway that intentionally returns failure. Record the input, the observed result and the relevant version or environment. If the output differs from the prose, update the explanation to fit the behavior rather than making an untested claim. For French, Portuguese and Arabic, ask a fluent reader to identify the exact characters that must remain unchanged and the words that can be explained naturally.

30. Localization file ownership

When usage text is compiled or generated into types, a translation change is a code-contract change requiring developer review.

Language editors update a .docopt.txt file without realizing it changes the generated argument structure.

Practical check: Review grammar diffs with engineers and prose diffs with fluent language reviewers in one release. Record the input, the observed result and the relevant version or environment. If the output differs from the prose, update the explanation to fit the behavior rather than making an untested claim. For French, Portuguese and Arabic, ask a fluent reader to identify the exact characters that must remain unchanged and the words that can be explained naturally.

31. Untrusted project input

A parser that accepts a project string does not authorize file access, network calls or shell execution with that value.

A tutorial concatenates an untrusted parsed value into a system command merely because parsing succeeded.

Practical check: Keep the example read-only, avoid shell interpolation and validate any downstream resource use. Record the input, the observed result and the relevant version or environment. If the output differs from the prose, update the explanation to fit the behavior rather than making an untested claim. For French, Portuguese and Arabic, ask a fluent reader to identify the exact characters that must remain unchanged and the words that can be explained naturally.

32. Reader acceptance testing

The final check is whether a new user can copy a valid command, recognize replaceable values and recover from an error.

A beautifully translated usage grammar receives praise but no one tries executing it.

Practical check: Give an independent reader an empty workspace and ask them to run show atlas, display help and repair a missing argument. Record the input, the observed result and the relevant version or environment. If the output differs from the prose, update the explanation to fit the behavior rather than making an untested claim. For French, Portuguese and Arabic, ask a fluent reader to identify the exact characters that must remain unchanged and the words that can be explained naturally.

Six realistic reader journeys

Case 1: An editor translating a .docopt.txt file

The editor is asked to translate the heading and option descriptions in a file that the C# generator treats as build input.

Protect Usage grammar punctuation and executable tokens, then rebuild to detect changed generated API members.

A dependable answer to this situation names both what the user may control and what they must leave intact. First give the minimum safe invocation and the observable result; then add one deliberate error that reveals the boundary. If a solution depends on an operating system, package version or application-level rule, say so next to the instruction. This avoids implying a universal parser feature where there is only a local implementation choice.

Case 2: A Portuguese contributor with a new project name

The contributor runs status-note show São-Paulo and expects a preview without mutating a repository.

Verify shell argument capture and application lookup independently, keeping project spelling rules explicit.

Case 3: An Arabic manual with mixed directions

The article contains an isolated example with –format=short next to right-to-left explanatory sentences.

Check the code block by copying it, not by evaluating only how it looks in a screenshot.

Case 4: A team adding a second output format

A new value long is added as an application-recognized format while the Usage pattern stays structurally the same.

Explain the new literal value and update the option description without inventing a new flag spelling.

Case 5: A build pipeline changing generator versions

Compilation produces a different generated argument member after a package upgrade.

Pin versions, inspect generated output and treat API changes as intentional migration work.

Case 6: A user who requests help without arguments

The help command should be usable before the user knows which project exists.

Test -h and –help branches independently from the required show <project> branch.

Build a multilingual test matrix that catches real errors

A useful test matrix has rows for ordinary input, missing required input, optional input omitted, an unknown option, a value containing whitespace, a non-ASCII value, a help request and an automated invocation. Give it columns for the exact command, the expected parsed meaning, visible output, error output, process status, locale and platform. A checkmark only means something when the expected observation is recorded. The test must use the packaged application, because translated resources can be missing from a release even when development tests passed.

Do not confuse language checking with execution checking. One reviewer can verify fluency and cultural readability; a second can check command syntax and result interpretation; and a third, unfamiliar with the text, can attempt to complete a task using nothing else. In French, Portuguese and Arabic, collect at least one example containing a filename or value that users of the target locale might actually type. Avoid private data, secrets and real production resources. A strong fixture is plausible enough to reveal layout and encoding problems but harmless if a command fails.

For narrow terminal testing, start with a compact viewport and inspect how option labels, placeholders and descriptions wrap. For right-to-left reading, isolate command lines from surrounding paragraphs and verify the copied characters, especially ASCII hyphens and equals signs. For Unicode inputs, inspect argument capture before downstream lookup or filesystem operations. When an error message is confusing, note whether the parser, application or terminal produced it. Better prose helps only after the source of the error is understood.

A four-week path from basic understanding to a reliable release

Week 1 — learn the real grammar

Install the documented dependency and run a read-only sample. Write a short inventory of every accepted option, alias, required value, optional value and help path. Use a valid invocation, a missing-value invocation and an unknown flag. Separate parser-produced errors from application-produced checks. Record the exact versions and the test shell. Before writing any translated manual, establish which spellings are genuinely supported.

Week 2 — draft reader-first help

Write three introductory paragraphs explaining the reader’s task and the essential syntax. Prepare natural sentences for French, Portuguese and Arabic, while keeping command tokens literal in isolated examples. Define a glossary distinguishing options, placeholders, values, commands and application states. Review the rendered help rather than raw strings alone, and test whether someone unfamiliar with the code can identify a safe first action.

Week 3 — exercise the difficult boundaries

Add cases for Unicode filenames, values with spaces, omitted defaults, invalid values, narrow terminal output and mixed-direction prose. Capture stdout, stderr and process status independently. When a test fails, locate the layer responsible before changing text. Repeat the same commands against the packaged artifact and confirm that compiled resources or generated documentation have not drifted from the executable grammar.

Week 4 — independent review and maintenance

Give the translated document and a clean test environment to readers who have not seen the source. Ask them to run one successful command, use –help or the documented help mechanism, and correct a deliberate mistake without guidance. Incorporate concrete observations, archive example invocations and note any environment-dependent limits. Keep later option changes tied to a review of every localized command example.

Frequently asked questions

Can I translate the word Usage?

Only after checking how the chosen docopt.net parser recognizes section grammar. A label used by the parser is not ordinary decorative prose.

To verify the answer in a real installation, use the smallest safe command that isolates this question, and compare the output with the application’s documented argument contract. Distinguish literal program syntax from explanatory wording so the result remains usable when the reader’s primary language changes.

Does docopt.net parse my help message?

Yes. The Usage and Options structure describes executable patterns; preserving that structure is essential.

Should I change show to another language?

Not in a translation alone. It is a literal command token unless the application intentionally introduces and tests another accepted command.

What does .docopt.txt do?

It can be a source-generator input under the documented file-naming convention; it is more than a standalone help document.

Is the source generator mandatory?

No. The project also documents parser APIs; source generation adds strongly typed integration when appropriate.

What does <project> mean?

It is a placeholder for a user-supplied value, not the text to type literally. A valid example replaces it with a project name.

Are parser errors the same as project lookup failures?

No. Matching the grammar and resolving a real project are separate operations with different recovery steps.

What is the safest first exercise?

Use the read-only status-note fixture with one successful command, one –help request and one deliberately missing project argument.

A final publishing checklist

The first paragraphs answer the likely search question and give the reader an immediate mental model.
The code examples are safe, runnable with the stated library and contain only accepted option names.
Help and recovery messages are natural-language explanations, not untested alternative grammar.
Missing arguments, defaults, unknown options and status codes have been checked against the target build.
Shell quoting, Unicode inputs, CJK widths and bidirectional presentation are reviewed separately.
Primary library documentation is linked so a developer can verify version-sensitive details.

The goal of .NET docopt.net localization is not to make an international CLI look as if it were originally written in another language while leaving its users to guess how it works. The goal is to give them a trustworthy route from question to command, from command to result and from mistake to recovery. A helpful guide tells the reader what stays fixed, what can change, why the distinction exists and how to verify the answer without risk.