Python defopt localization starts with a practical question: how can a command-line interface built from ordinary Python functions explain itself to readers in several languages without breaking the commands that already work? Developers looking for defopt.run, type hints, supported docstring styles, argparse-style usage messages, subcommands and CLI conversion errors need to separate translated explanations from executable syntax. defopt derives many command-line decisions from a function signature and its documentation. Changing the language of a description does not change the parameter types or the names the parser accepts.
Imagine a safe report-preview function accepting a region name and an optional row count. A French or Japanese reader needs to understand what the region means, why the row count defaults to a particular value and which characters to copy into the terminal. They must not be told to replace a recognized option with an improvised translated flag. A Python type conversion error, shell quoting mistake and application-level report error are also three different events, each requiring distinct recovery guidance.
This educational guide explains the defopt model from functions and docstrings to type conversion, choices, subcommands, error reporting, Unicode and packaged entry points. It uses a read-only example and detailed investigations of things that frequently go wrong in multilingual command-line help. The conclusion is a repeatable release method: another-language reader can find an operation, provide valid arguments and recover from mistakes using the actual executable rather than translated guesses.
Quick answer: what must stay correct
- Function signatures and Python annotations define actual input behavior.
- Translate descriptions and guidance, not undocumented command spellings.
- Test docstring extraction, conversions, subcommands and error messages separately.
- Check Unicode values and packaged console entry points, not only browser screenshots.
1. A function signature is a promise
defopt creates a terminal interface around an existing Python function. A function can remain directly callable in Python; the CLI supplies strings from the shell and defopt interprets them according to supported type information. A required positional value cannot be made optional by writing a gentler description. A keyword-only argument, default value and annotation each affect the user’s real interaction. Begin any translation by recording a tiny working function, its signature, installed package version and exact generated help. The objective is to explain what works, not to invent more flexible behavior.
2. Use the documentation styles deliberately
The official defopt documentation supports type information and parameter explanations drawn from recognized docstrings, including Sphinx conventions and supported Google or NumPy styles. The structure of a docstring may be parser input, not merely decoration. A localized rewrite that loses an indented parameter description may also lose it from help. Keep the documentation markers and expected names intact, translate natural-language explanations, and run help generation after every revision. Ask whether a user can identify purpose, requiredness, acceptable input and an example without reading Python source.
3. Type hints constrain valid language
A parameter annotated as int does not accept every culturally familiar representation of a number. A comma decimal convention, a translated truth word or a localized enumeration member may not pass conversion. Describe value shape with examples that actually work. The conversion should be observed by printing or testing the resulting Python value in a safe harness. An authoritative-looking translated help page is harmful if it invites a form the parser rejects. This is why linguistic and technical review must remain connected but distinct.
4. Union order changes what arrives
defopt documents that union members may be tried in order, with special cases. A broad string parser can accept an input before a more specific converter gets the chance. Therefore an expression such as ‘integer or text’ may be an inadequate explanation of actual behavior. If identical-looking values can become different Python types depending on the declared union order, show examples of that outcome. A translator cannot decide that a locale-specific value should be parsed differently unless code implements that rule.
5. Optional is not the same as blank
An omitted flag, an explicit empty shell token, a None-related type annotation and a default parameter value describe different possibilities. Do not teach people to type a translated version of None unless that literal input has been supported and tested. Explain the specific command-line omission behavior instead. Where a missing value is recoverable, help should say what to supply or which flag to omit. The reader should not have to infer the rule from an exception traceback.
6. Subcommands are executable routes
defopt can expose multiple functions through command routes. Each command can have different accepted arguments, and nesting may introduce more than one level of selection. A target-language explanation can translate a command’s purpose while keeping its registered route literal. Any proposed translated alias is a software feature: it needs implementation, collision review and tests. Document root help and command-specific help separately. A user who knows the general purpose but not the exact route still cannot run the application.
7. The shell acts before the parser
Bash, PowerShell and other command processors split arguments, interpret quotes and may expand variables before Python sees argv. A translated example containing spaces, dollar signs or non-ASCII characters must be checked in the supported shell. Do not blame defopt for a value split in the shell, and do not claim that one quote convention is portable everywhere. A good tutorial isolates literal syntax from replaceable user data and uses dedicated examples when platforms differ.
8. Help and errors have different owners
The library may format parser help and type conversion errors, the Python runtime may supply exception text and the application may print report-specific failures. Translating just the function’s docstring does not guarantee that every message is localized. Assign ownership: descriptions, parser messages, application validation, unexpected exceptions and shell diagnostics. Each requires an appropriate test. A failed type conversion should produce useful next steps; a missing report should not be described as a syntax error.
9. Unicode has multiple stages
Unicode in help is not the same as Unicode in pathnames or data arguments. A Japanese description may display correctly while an input filename is altered by shell quoting or downstream path handling. Include samples with accented names, CJK text, right-to-left explanations, combining sequences and spaces. Confirm the actual value received by the function, not just the appearance of a screenshot. If normalization or locale-sensitive comparison matters, implement it consciously in the application rather than claiming defopt automatically performs that policy.
10. Package the language resources
An application can work from its development directory and fail when installed from a wheel or launched through a console entry point. Translation resources may have been omitted, relative paths may resolve differently and output encoding may depend on the environment. Always build and install the artifact readers receive. Capture the Python and defopt versions, supported shells, locale selection, help and failure outcomes. Make fallback behavior explicit when a target language is unavailable.
11. Teach recovery, not merely syntax
The best help text names the next useful action. Instead of ‘invalid value’, say which option failed, what kind of value is expected and show an acceptable example where safe. Keep the actual option token literal. A target-language reader should be able to recover after missing a positional, passing a wrong type or choosing an unsupported value. Separate recoverable user mistakes from unexpected bugs so that the copy does not promise a repair that cannot succeed.
12. An independent reader is the test
After translating, hand a clean installation to someone who has not read the Python function. Ask them to find a report-preview command, supply region and row count, view help for a child command and correct one deliberately malformed invocation. Observe where the reader hesitates. If they translate a switch instead of copying its literal spelling, make the explanation more explicit. Store the revised example, output and exit status with the release tests so later code changes trigger a renewed language review.
Forty-three practical investigations and repair tests
Investigation 1: Required positional
Situation. The preview requires a region but the translated example omits it. Underlying distinction. A required function parameter cannot disappear from the parser by translating prose. At this boundary, help text is trustworthy only when it describes the installed program rather than the writer’s idealized version of it.
Repair. Show a complete invocation with the region after the program name. Proof. A missing region fails and a valid region reaches the function. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 2: Keyword-only count
Situation. A reader types a row count as an unnamed second positional. Underlying distinction. A keyword-only parameter defines a distinct command-line calling convention. The failure is easy to miss in a language-only review: a sentence can be fluent while a copied command is impossible to execute.
Repair. Print the actual accepted option spelling and show its value. Proof. The function receives the intended integer when invoked correctly. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 3: Default rows
Situation. The guide says every row is shown when the CLI actually chooses a fixed default. Underlying distinction. A Python parameter default remains active when a user omits the option. Readers need a next action rather than a vague promise; the test makes the difference between explanation and executable fact visible.
Repair. State the declared default and demonstrate omission. Proof. Calls with and without an explicit count produce documented different values. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 4: Sphinx type field
Situation. An editor translates the syntax inside a :type parameter marker. Underlying distinction. defopt can treat docstring type information as structured data. Do not silently change application behavior to make a sentence sound natural. If a genuine alias is wanted, version and test that change.
Repair. Keep the marker grammar while translating explanatory sentences. Proof. Help still documents and converts the declared type. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 5: Google-style indentation
Situation. A localized docstring loses the indentation of a parameter entry. Underlying distinction. The parser depends on recognizable documentation structure. Accurate multilingual support requires attention to input data, parser interpretation and displayed feedback as separate stages.
Repair. Preserve supported Google docstring formatting and regenerate help. Proof. Each argument explanation remains visible. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 6: NumPy parameter block
Situation. A rewritten paragraph merges type and description into an unrecognized section. Underlying distinction. Supported NumPy-style parsing relies on a recognizable block structure. A translation is only useful if someone can predict which command is valid and what the application will do with its values.
Repair. Review parameter headers and their indented content. Proof. Generated help includes every relevant parameter. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 7: Docstring contradiction
Situation. The prose calls a field a string while Python annotations make it integer. Underlying distinction. Type conversion follows the actual effective type definition. At this boundary, help text is trustworthy only when it describes the installed program rather than the writer’s idealized version of it.
Repair. Resolve contradictory descriptions before localization approval. Proof. An integer-looking input becomes an integer. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 8: Missing description
Situation. The translation leaves a terse parameter name without its purpose. Underlying distinction. The program may display only whatever information the author supplies. The failure is easy to miss in a language-only review: a sentence can be fluent while a copied command is impossible to execute.
Repair. Add a short explanation of the user’s decision and expected form. Proof. A new reader can choose a valid value from help. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 9: Long translated sentence
Situation. Japanese or German help wraps an option name away from its meaning. Underlying distinction. Longer descriptions exceed terminal width and reduce discoverability. Readers need a next action rather than a vague promise; the test makes the difference between explanation and executable fact visible.
Repair. Use plain concise wording and test narrow displays. Proof. Names and descriptions remain associated at sixty columns. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 10: Enum value
Situation. A local-language guide replaces a choice token with its translated meaning. Underlying distinction. Program-defined acceptable values are not automatically translated. Do not silently change application behavior to make a sentence sound natural. If a genuine alias is wanted, version and test that change.
Repair. List literal choices followed by their meanings. Proof. Every listed token works and an unsupported token fails clearly. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 11: Boolean presence
Situation. The manual tells readers to type a translated yes word after a switch. Underlying distinction. Boolean handling is governed by the parser and annotation. Accurate multilingual support requires attention to input data, parser interpretation and displayed feedback as separate stages.
Repair. Demonstrate the installed library’s supported true and false forms. Proof. The received Python Boolean matches both examples. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 12: Float separator
Situation. A decimal example uses a comma in a context expecting a dot. Underlying distinction. Machine conversion does not automatically follow every regional convention. A translation is only useful if someone can predict which command is valid and what the application will do with its values.
Repair. Document the accepted numeric spelling with a target-language explanation. Proof. A valid float converts and the alternate form has a documented outcome. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 13: Negative integer
Situation. A negative value is confused with a flag. Underlying distinction. Dash-prefixed input can interact with option parsing. At this boundary, help text is trustworthy only when it describes the installed program rather than the writer’s idealized version of it.
Repair. Find and show a syntax the installed parser accepts for negative values. Proof. The function receives the actual negative number. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 14: Empty string
Situation. An example treats two quotes as identical to omission. Underlying distinction. The shell can deliver an empty string argument rather than no argument. The failure is easy to miss in a language-only review: a sentence can be fluent while a copied command is impossible to execute.
Repair. Distinguish empty from absent in a simple test. Proof. Both forms have independently checked results. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 15: None representation
Situation. A guide asks the reader to type a localized name for None. Underlying distinction. Optional typing and string input are different conceptual layers. Readers need a next action rather than a vague promise; the test makes the difference between explanation and executable fact visible.
Repair. Explain how to omit the value according to the installed interface. Proof. The function sees the documented omitted-value state. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 16: Union precedence
Situation. An int-or-str union accepts a token through a different branch than expected. Underlying distinction. Union conversion tries its supported branches in a defined order. Do not silently change application behavior to make a sentence sound natural. If a genuine alias is wanted, version and test that change.
Repair. Explain precedence using a concrete ambiguous token. Proof. The test records both resulting value and Python type. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 17: String before integer
Situation. An unrestricted string branch consumes input intended as integer. Underlying distinction. A broad parser can succeed before later alternatives. Accurate multilingual support requires attention to input data, parser interpretation and displayed feedback as separate stages.
Repair. Choose a less ambiguous type or document the actual behavior. Proof. An integer-looking input is shown with its real final type. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 18: Custom parser
Situation. A special date converter accepts only a prescribed representation. Underlying distinction. The application’s converter has grammar beyond the user’s spoken language. A translation is only useful if someone can predict which command is valid and what the application will do with its values.
Repair. Show exactly which date tokens work and warn against ambiguity. Proof. A good fixture parses and a reversed date does not silently change meaning. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 19: List input
Situation. The translated help does not say how to enter two regions. Underlying distinction. A list annotation can require particular repetition or grouping syntax. At this boundary, help text is trustworthy only when it describes the installed program rather than the writer’s idealized version of it.
Repair. Use the actual installed parser’s list input convention. Proof. Two entries arrive as a two-element collection. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 20: Tuple shape
Situation. The guide provides fewer values than a fixed-length tuple requires. Underlying distinction. Typed tuples have cardinality and ordering rules. The failure is easy to miss in a language-only review: a sentence can be fluent while a copied command is impossible to execute.
Repair. Explain the role of each field and the required count. Proof. Valid and missing-element cases are tested. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 21: Variadic input
Situation. The description says a single report even though many names can be passed. Underlying distinction. A variadic parameter captures a sequence rather than one scalar. Readers need a next action rather than a vague promise; the test makes the difference between explanation and executable fact visible.
Repair. Show zero one and multiple arguments where supported. Proof. The resulting tuple or list has the correct size. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 22: Subcommand route
Situation. A translated title is mistaken for the executable command. Underlying distinction. Registered function routes are parser identifiers. Do not silently change application behavior to make a sentence sound natural. If a genuine alias is wanted, version and test that change.
Repair. Keep exact command names in a small command tree. Proof. Root help and child invocation agree. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 23: Nested command
Situation. A user skips the parent command in a multi-level route. Underlying distinction. Nested routing requires the defined hierarchy. Accurate multilingual support requires attention to input data, parser interpretation and displayed feedback as separate stages.
Repair. Print every literal route token in order. Proof. Help at each depth leads to a valid final invocation. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 24: Child-specific option
Situation. A parameter for one function is described as global. Underlying distinction. Each command may have a distinct signature. A translation is only useful if someone can predict which command is valid and what the application will do with its values.
Repair. Capture help and accepted flags for the selected child. Proof. The flag succeeds only in documented contexts. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 25: Unknown translated switch
Situation. A localized example introduces a never-registered alias. Underlying distinction. Description editing does not register additional options. At this boundary, help text is trustworthy only when it describes the installed program rather than the writer’s idealized version of it.
Repair. Remove the invented spelling or implement a real tested alias. Proof. Original and new aliases behave as explicitly claimed. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 26: Typos in flags
Situation. A user enters –limt and sees an unfamiliar error. Underlying distinction. A misspelling differs from a translated option name. The failure is easy to miss in a language-only review: a sentence can be fluent while a copied command is impossible to execute.
Repair. Write recovery that names the correct literal switch. Proof. Rerunning the corrected invocation succeeds. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 27: Missing value
Situation. A required option appears alone without its argument. Underlying distinction. A flag expecting a value cannot infer what the writer intended. Readers need a next action rather than a vague promise; the test makes the difference between explanation and executable fact visible.
Repair. Show a full example and distinguish placeholders from literal values. Proof. The missing case fails with useful guidance. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 28: Shell spaces
Situation. A report filename contains spaces and splits into extra tokens. Underlying distinction. The shell processes quoting before defopt receives argv. Do not silently change application behavior to make a sentence sound natural. If a genuine alias is wanted, version and test that change.
Repair. Supply separate Bash and PowerShell examples if both supported. Proof. The function receives one complete path. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 29: Shell dollar sign
Situation. An example value contains a dollar sign and is expanded in the shell. Underlying distinction. Shell expansion can change raw input without involvement from defopt. Accurate multilingual support requires attention to input data, parser interpretation and displayed feedback as separate stages.
Repair. Quote or escape for the shell being taught. Proof. The observed argv preserves the intended value. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 30: Unicode filename
Situation. A filename with accents displays correctly but does not open. Underlying distinction. Presentation and actual downstream path identity require separate tests. A translation is only useful if someone can predict which command is valid and what the application will do with its values.
Repair. Use a harmless existing UTF-8 fixture file. Proof. The correct file is selected and no file is modified. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 31: Combining accent
Situation. Two visually identical names behave as distinct inputs. Underlying distinction. Unicode may use composed or decomposed code points. At this boundary, help text is trustworthy only when it describes the installed program rather than the writer’s idealized version of it.
Repair. Choose a domain-level normalization policy if matching requires it. Proof. Both representations have explicit tested outcomes. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 32: RTL command
Situation. Arabic prose visually reorders a Latin long flag. Underlying distinction. Bidirectional display is not a reliable guide to input byte order. The failure is easy to miss in a language-only review: a sentence can be fluent while a copied command is impossible to execute.
Repair. Isolate literal command tokens in code styling. Proof. The copied command works from the published page. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 33: CJK width
Situation. Wide characters shift terminal help columns. Underlying distinction. Display cells are different from code-point counts. Readers need a next action rather than a vague promise; the test makes the difference between explanation and executable fact visible.
Repair. Test local-language help at multiple terminal widths. Proof. Option names remain legible and findable. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 34: Missing locale
Situation. A catalog is unavailable for a requested language. Underlying distinction. defopt does not replace the need for application fallback decisions. Do not silently change application behavior to make a sentence sound natural. If a genuine alias is wanted, version and test that change.
Repair. Provide a readable fallback with valid commands. Proof. Help and errors remain usable without the catalog. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 35: Error categories
Situation. A conversion failure is described as a missing report. Underlying distinction. Parser errors and business-level errors have different causes. Accurate multilingual support requires attention to input data, parser interpretation and displayed feedback as separate stages.
Repair. Translate the precise failure type and a suitable next step. Proof. Both scenarios lead to distinct actionable messages. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 36: Unexpected traceback
Situation. A predictable wrong value produces raw stack traces. Underlying distinction. Application exception boundaries may need separate handling. A translation is only useful if someone can predict which command is valid and what the application will do with its values.
Repair. Handle expected failures without suppressing genuine bugs. Proof. Recoverable errors do not appear as programming failures. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 37: Standard error
Situation. A CI script checks stdout and misses the parser diagnostic. Underlying distinction. Help and errors may be emitted on different streams. At this boundary, help text is trustworthy only when it describes the installed program rather than the writer’s idealized version of it.
Repair. Capture stdout and stderr independently. Proof. The intended failure evidence appears on the expected channel. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 38: Exit status
Situation. A failing command is called successful because it printed localized help. Underlying distinction. The visible message does not establish process success. The failure is easy to miss in a language-only review: a sentence can be fluent while a copied command is impossible to execute.
Repair. Assert process status along with content. Proof. Good and bad cases have explicitly expected results. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 39: Console entry point
Situation. A code example works with python file.py but not the installed command. Underlying distinction. Packaged entry points may change runtime context. Readers need a next action rather than a vague promise; the test makes the difference between explanation and executable fact visible.
Repair. Test the executable name distributed to readers. Proof. Help and valid invocations work outside the source checkout. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 40: Resource packaging
Situation. Translation files vanish when a wheel is installed. Underlying distinction. Non-code resources may be omitted from package configuration. Do not silently change application behavior to make a sentence sound natural. If a genuine alias is wanted, version and test that change.
Repair. Inspect installed files and test a clean virtual environment. Proof. Every claimed locale finds its catalog. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 41: Python version
Situation. A union annotation shown in an article is unsupported by an older Python. Underlying distinction. Annotation syntax and dependency support depend on declared versions. Accurate multilingual support requires attention to input data, parser interpretation and displayed feedback as separate stages.
Repair. Label the tested Python and defopt releases. Proof. The published sample runs on declared versions. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 42: Shell portability
Situation. A copied Bash example fails in PowerShell. Underlying distinction. Quoting syntax and command substitution differ by shell. A translation is only useful if someone can predict which command is valid and what the application will do with its values.
Repair. Offer platform-specific lines where necessary. Proof. Each line is verified in its stated environment. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Investigation 43: Reader trust
Situation. A multilingual help screen looks polished but new users cannot finish a report preview. Underlying distinction. Stylistic fluency and task completion are different evidence. At this boundary, help text is trustworthy only when it describes the installed program rather than the writer’s idealized version of it.
Repair. Use an independent target-language reader with a read-only task. Proof. The reader succeeds and recovers without looking at English source. Carry the complete invocation, locale, Python type or output, and process status in the test note. This makes the advice reproducible for a reader using the packaged command rather than a developer’s working copy.
Frequently asked questions
Does defopt translate its help automatically?
No. It constructs a CLI from functions and their documentation. Applications still need to choose the target-language descriptions, decide on locale fallback and investigate how parser-generated and application-generated diagnostics are presented.
Can a translator rename all command options?
Only when the application actually implements those option names. A label, description and executable token are different things. Preserve working syntax in code examples and require tests for deliberate aliases.
Do Python type hints matter to command-line use?
Yes. defopt uses supported annotations to convert incoming string tokens. Describing an int field as any number, or a choice as free text, can guide users into invalid input. Test the resulting Python types.
Does Optional mean a blank string?
No. An omitted argument, an empty string and an optional typed value are not interchangeable. Explain whichever forms the installed version accepts and do not invent literal None tokens.
Why test union types?
The order in which supported converters are tried can determine whether an ambiguous input becomes a number, string or another value. Use examples that show the resulting Python type and not merely an English paraphrase.
Is the shell part of defopt?
No. The shell processes input before Python receives it. Quoting, expansions and paths need their own documentation when examples are intended for multiple shells.
Why might errors remain in English?
Some wording may originate from the parser, runtime, terminal or application rather than from a docstring. Identify ownership and test each message source instead of assuming one locale choice translates everything.
What proves a release works?
Give the installed artifact to someone unfamiliar with the Python source. Ask them to discover the command, perform a safe preview, deliberately supply a bad value and recover using only the localized help. Record every confusion and repeat after revision.
A four-week implementation and acceptance plan
Week 1 — map signatures and accepted grammar
Install the supported Python and defopt versions in a clean environment. Build a read-only report preview with a required region and optional numeric count. Record the function signature, type hints, docstring style, root and child help where applicable, and actual accepted flag spellings. Capture one correct command, one missing value, one bad integer and one unknown option. This evidence gives translation reviewers an interface they can test rather than merely guess.
Week 2 — write explanations and exercise docstrings
Translate the purpose and parameters into two languages, keeping Sphinx, Google or NumPy markup in the correct form. Review whether the reader can identify a required value, accepted input type and optional default. Render help in a narrow terminal and with a non-Latin script. Ask a reviewer to copy every published command literally. If they replace an option name with a translated synonym, make the instruction clearer or implement a real alias with tests.
Week 3 — test conversion, errors and distribution
Include unions, optional values, choices, Unicode paths, shell quoting and a command-specific error. Capture stdout, stderr and exit status independently. Build a wheel or the relevant distribution format, install it in a fresh virtual environment and check its entry point. Inspect the installed locale files and test fallback when a language catalog is missing. Use exact packages and versions rather than a developer-only editable installation.
Week 4 — observe independent completion
Give a target-language reader a fresh installation and a harmless objective. Ask them to use help, choose a region, set a row count and recover from a wrong type. Observe all failures without coaching, revise the affected explanation and run the same acceptance test again. Assign responsibility for type signatures, message catalogs, examples and packaging, so a subsequent change to one of those layers triggers a full language review.
What success looks like
A defopt command is well localized when the description maps accurately to the Python signature, the documented value converts as promised and a new reader can recover from errors without reading the original source. The guide should remain true for the package as installed. Stable syntax and clear translated meaning work together; neither can replace the other.