Python tyro CLI localization begins with type annotations and human-facing help text. Developers searching for tyro.cli, dataclass command-line arguments, translated Python CLI help, typed subcommands or Unicode terminal tests need to distinguish generated command syntax from the prose that explains it. This guide shows how to make a tyro-based command useful to speakers of different languages without assuming that a translated option name becomes a recognized flag.
Consider a fictional library inventory tool whose operator may enter a Japanese title, choose a language for explanatory messages and inspect a preview before changing records. The tool should accept the same typed input and preserve the same meaning whether the reader follows English, Spanish or Arabic guidance. The quality question is not simply whether a heading sounds fluent: can the reader supply the right value, recognize an invalid argument and predict what happens next?
tyro generates command-line interfaces from typed Python functions and structured types, including dataclasses. The current official documentation describes tyro.cli(), help generation, nested structures and unions used as subcommands. Features and exact generated spellings depend on the installed version and model structure. The examples here explain durable design principles and show where to verify the actual output rather than promising an automatic multilingual catalog that tyro does not document.
Quick answer: what to do first
- Build and inspect help from the exact installed tyro release.
- Keep type annotations, field types and real option names synchronized.
- Translate explanatory text, not invented CLI flag spellings.
- Use dataclass docstrings and field descriptions deliberately.
- Treat locale preference as an explicit application setting.
- Confirm unions of structured types create the expected subcommands.
- Keep help and examples aligned with actual generated names.
- Test quoted Unicode titles as values, not as command identities.
- Preserve integer semantics even when displaying localized numerals.
- Check conversion errors and status codes in addition to happy paths.
- Compare terminal output, redirected output and narrow-width help.
- Document version changes and maintain regression examples.
A safe small example to understand before changing real software
from dataclasses import dataclass
import tyro
@dataclass
class Preview:
"""Preview a fictional reading-list item without saving it."""
title: str
count: int = 1
language: str = "en"
if __name__ == "__main__":
options = tyro.cli(Preview)
print(f"preview: {options.title} ({options.count}) [{options.language}]")
# Try: python preview.py --title "東京の本" --count 2 --language ja
# The example prints a preview; it does not write a file.The example is a teaching fixture. Its important features are visible output, a clear distinction between syntax and human meaning, and data that are safe to discard. Do not mistake a translated sentence for a registered parser alias. Always compare its actual generated help with the executable built from your installed dependencies.
Three promises every translated command must keep
First is the input contract: the executable must recognize the names, order, types and values shown in the instructions. An attractive translation that asks the reader to type nonexistent syntax is not usable. Treat each runnable line as an executable test case rather than as decorative text.
Second is the behavior contract: the operation must perform the action described, and important conditions must remain observable. A preview must not accidentally overwrite a record; a failed validation must not report success. Read-only teaching examples should be isolated from production accounts, files, network calls and credentials.
Third is the message contract: the reader needs enough context to decide, act and recover. Translate sentences and meaningful warnings as complete thoughts. Include a valid example beside a harmless invalid one. Keep the writing simple enough for people who may know the domain but not the original English interface.
How to read this guide
The investigations below follow an observable chain: identify which layer owns a behavior, describe the most tempting wrong assumption, run a safe test and decide what a correct explanation must say. The framework-specific cases come first. General multilingual and accessibility cases follow, because a technically correct parser is still hard to use if its help fails on a reader’s terminal.
Framework-specific investigations with practical checks
1. tyro.cli with a dataclass
Passing a dataclass type to tyro.cli produces a populated configuration object from parsed inputs.
The common misunderstanding is this: A translator may treat the dataclass name as a command the user must type, when the actual CLI is generated from fields.
To check rather than guess: Run the short Preview sample, print –help and inspect the returned Preview instance with a Japanese title.
A useful repair is to translate the explanation of the object, while describing only flags that the generated help really exposes. This distinction should appear beside a complete command and its expected result, so the reader can connect the visible instruction to a tested operation.
2. Function signatures as a second entry point
tyro.cli can also call a type-annotated function and populate its parameters directly.
The common misunderstanding is this: A function-style example copied into a dataclass tutorial may have different defaults or resulting object behavior.
To check rather than guess: Create a harmless function that prints its arguments, then compare help and results with the dataclass form.
A useful repair is to state clearly whether the reader is invoking a function or instantiating a configuration type. This distinction should appear beside a complete command and its expected result, so the reader can connect the visible instruction to a tested operation.
3. Field names and generated switches
Dataclass field names influence generated option spellings, but display names can be configured with the library’s documented mechanisms.
The common misunderstanding is this: A guide that localizes Python identifiers in prose without changing code describes flags the parser does not know.
To check rather than guess: Print the actual help after every field rename and test the previously advertised invocation.
A useful repair is to treat any change to an accepted flag name as an interface migration, not a proofreading edit. This distinction should appear beside a complete command and its expected result, so the reader can connect the visible instruction to a tested operation.
4. Docstrings as source explanations
Type and function documentation can supply help text that tyro surfaces to users.
The common misunderstanding is this: Leaving English docstrings in a multilingual guide can create an uneven interface that seems finished at the top but not inside help.
To check rather than guess: Write a brief original description for each field, inspect the rendered hierarchy and compare wording with the handler.
A useful repair is to use descriptions that say what the value controls and whether it causes a side effect. This distinction should appear beside a complete command and its expected result, so the reader can connect the visible instruction to a tested operation.
5. Required fields and defaults
A dataclass field without a default generally requires user input, while defaults change which flags can be omitted.
The common misunderstanding is this: Translation can turn ‘optional because it has a default’ into ‘optional because the value is ignored’, which is incorrect.
To check rather than guess: Run the same command with the field omitted, empty and explicitly set to the documented default.
A useful repair is to explain the default as actual behavior and show what the tool prints when a value is absent. This distinction should appear beside a complete command and its expected result, so the reader can connect the visible instruction to a tested operation.
6. Types drive conversion
An int, bool or Path annotation carries parsing consequences beyond the English wording beside it.
The common misunderstanding is this: A translated instruction may display locale-specific number typography that the parser does not accept as input.
To check rather than guess: Try supported and unsupported numeric forms and record which type conversion fails before any application logic.
A useful repair is to offer a working ASCII invocation while allowing localized formatting in descriptions and reports. This distinction should appear beside a complete command and its expected result, so the reader can connect the visible instruction to a tested operation.
7. Nested dataclasses
Nested configuration objects can generate grouped or dotted command-line argument structures.
The common misunderstanding is this: Readers may assume a heading is a literal subcommand rather than a group label or dotted option.
To check rather than guess: Add a nested harmless settings object, inspect help and copy an exact nested option from the output.
A useful repair is to show the full invocation for the installed model instead of guessing the separator between field names. This distinction should appear beside a complete command and its expected result, so the reader can connect the visible instruction to a tested operation.
8. Union types become subcommands
tyro’s official examples show unions of structured types used to select distinct configuration branches.
The common misunderstanding is this: Translating a branch label as ordinary prose can leave an invocation pointing at the wrong variant.
To check rather than guess: Create two safe variants with distinct fields and ask the parser which selector it advertises.
A useful repair is to describe the branch selector as software syntax and localize the decision criteria around it. This distinction should appear beside a complete command and its expected result, so the reader can connect the visible instruction to a tested operation.
9. Subcommand ordering
The tyro documentation notes that shared arguments and subcommand-specific arguments can have ordering constraints.
The common misunderstanding is this: A translator who rearranges example phrases into target-language order can accidentally rearrange command tokens.
To check rather than guess: Copy a documented subcommand example exactly, then deliberately move a shared option to see the parser response.
A useful repair is to separate natural-language sentence order from the command’s grammar, and record supported ordering explicitly. This distinction should appear beside a complete command and its expected result, so the reader can connect the visible instruction to a tested operation.
10. tyro.conf.subcommand
The documented subcommand configuration helper supports customizing subcommand presentation beyond basic union annotations.
The common misunderstanding is this: An article may imply every displayed subcommand alias is automatically accepted in every release.
To check rather than guess: Check the installed version’s API reference, print help and test each alias or custom name before teaching it.
A useful repair is to when an alias is not registered, explain it as a translation of meaning rather than runnable syntax. This distinction should appear beside a complete command and its expected result, so the reader can connect the visible instruction to a tested operation.
11. AvoidSubcommands configuration
The documented AvoidSubcommands marker can suppress a union-generated subcommand and use a default branch in certain structures.
The common misunderstanding is this: A simplified help page can hide a choice the user actually expects, reducing access to a valid workflow.
To check rather than guess: Compare help and parsing for the same safe model with and without the documented marker.
A useful repair is to explain which choices are no longer available through the CLI and how the default is selected. This distinction should appear beside a complete command and its expected result, so the reader can connect the visible instruction to a tested operation.
12. CascadeSubcommandArgs
The tyro configuration reference describes cascading arguments to reduce awkward ordering in certain nested subcommand structures.
The common misunderstanding is this: Assuming cascading is universal can make copied invocations break when deployed against a different configuration.
To check rather than guess: Build a test for an option before and after a branch selector under the chosen version and configuration.
A useful repair is to publish the observed accepted order; avoid presenting a library-specific convenience as shell syntax. This distinction should appear beside a complete command and its expected result, so the reader can connect the visible instruction to a tested operation.
13. Boolean switches
Boolean-typed fields often become presence or negation-style options according to configuration and defaults.
The common misunderstanding is this: A natural-language translation of ‘false’ may be mistaken for a literal argument to append after a switch.
To check rather than guess: Test default true, default false and any displayed negated spelling on the installed command.
A useful repair is to use complete examples for both states rather than relying on an English sentence about toggling. This distinction should appear beside a complete command and its expected result, so the reader can connect the visible instruction to a tested operation.
14. Lists and repeated values
A list annotation has different behavior from a scalar string; token count and shell quotation still matter.
The common misunderstanding is this: A guide may collapse several values into a comma-separated phrase even when the parser expects separate tokens.
To check rather than guess: Supply a two-element list with one item containing spaces and verify the resulting Python list.
A useful repair is to describe whether separators, repeated flags or multiple tokens are accepted based on actual help and tests. This distinction should appear beside a complete command and its expected result, so the reader can connect the visible instruction to a tested operation.
15. Literal and enum choices
Type annotations can constrain acceptable values, while localized descriptions may present friendly equivalents.
The common misunderstanding is this: A translated value that sounds right but is not an accepted token leads to a conversion error.
To check rather than guess: Try a recognized choice, a translated choice and an unknown value and compare the messages.
A useful repair is to distinguish user-visible label from canonical input token and register genuine aliases only if supported and tested. This distinction should appear beside a complete command and its expected result, so the reader can connect the visible instruction to a tested operation.
16. Python pathlib paths
Path annotations represent filesystem paths, but cross-platform path rules are not made identical by tyro.
The common misunderstanding is this: An example with Windows backslashes may not behave like its POSIX counterpart; non-Latin names add further ambiguity.
To check rather than guess: Test path handling in a disposable directory on each supported operating system, including spaces and accents.
A useful repair is to label platform-specific path examples and never promise that parsing alone validates existence or permissions. This distinction should appear beside a complete command and its expected result, so the reader can connect the visible instruction to a tested operation.
17. Union ambiguity and defaults
Multiple compatible types or default choices can make a generated interface more complex than the underlying model appears.
The common misunderstanding is this: A translated quick-start example may silently choose a default branch different from the text’s promised operation.
To check rather than guess: Print the chosen object’s type and fields after parsing and compare with the documented scenario.
A useful repair is to explain the selected branch, not just the overall group label, before the reader performs a real action. This distinction should appear beside a complete command and its expected result, so the reader can connect the visible instruction to a tested operation.
18. Dataclass default factories
Mutable or dynamically constructed values should use appropriate Python dataclass patterns, not ad hoc translated literals.
The common misunderstanding is this: A copied example can share mutable state or conceal a dynamically created default as though it were fixed.
To check rather than guess: Initialize two independent configuration instances and compare defaults before involving the CLI.
A useful repair is to document the observed default and keep code concerns distinct from the language catalog. This distinction should appear beside a complete command and its expected result, so the reader can connect the visible instruction to a tested operation.
19. Help headings and groups
Generated help may contain type-derived headings, required sections, option groups and hints.
The common misunderstanding is this: A translator who edits only the opening paragraph may leave the critical choice buried under an English heading.
To check rather than guess: Capture complete help for a model with nested fields and review the headings in reading order.
A useful repair is to decide which text the application controls and which is generated by tyro or its dependencies. This distinction should appear beside a complete command and its expected result, so the reader can connect the visible instruction to a tested operation.
20. Styled help and plain text
Rich-looking help is useful but terminal features, capture modes and versions can affect its presentation.
The common misunderstanding is this: Help that looks aligned in a development terminal may wrap poorly for a user with a screen reader.
To check rather than guess: Compare interactive help, redirected output and narrow terminals with long Japanese and German descriptions.
A useful repair is to treat appearance as progressive enhancement; the plain text instructions must remain complete. This distinction should appear beside a complete command and its expected result, so the reader can connect the visible instruction to a tested operation.
21. Completion scripts
tyro documents shell-completion capabilities for generated commands, depending on the API and version used.
The common misunderstanding is this: A localized guide may promise completion installation steps that do not match the installed release.
To check rather than guess: Follow the version-matched completion documentation and verify the suggestions in a disposable shell profile.
A useful repair is to keep the inserted command tokens stable and localize descriptions only if the mechanism supports it. This distinction should appear beside a complete command and its expected result, so the reader can connect the visible instruction to a tested operation.
22. Validation after parsing
A typed CLI may enforce structural types but still need domain checks such as nonnegative counts.
The common misunderstanding is this: A translated error that says ‘invalid’ without the expected range leaves the operator unable to fix input.
To check rather than guess: Test count zero, negative and an excessive value in a safe handler with explicit validation.
A useful repair is to say precisely which rule belongs to tyro conversion and which rule your application enforces. This distinction should appear beside a complete command and its expected result, so the reader can connect the visible instruction to a tested operation.
23. Output type and side effects
tyro.cli populates data or invokes a function; it does not guarantee translation or read-only behavior.
The common misunderstanding is this: A tutorial might describe a preview while the actual function writes a file as soon as parsing finishes.
To check rather than guess: Run examples with observable no-write handlers and document any real operation before using it in production.
A useful repair is to align the translated verb with the function’s behavior and keep a separate dry-run switch when implemented. This distinction should appear beside a complete command and its expected result, so the reader can connect the visible instruction to a tested operation.
24. Pinned package versions
Generated help, configuration helpers and dependency integration can evolve between tyro releases.
The common misunderstanding is this: An old syntax snippet may compile under one environment and fail under another despite excellent translation.
To check rather than guess: Record Python and tyro versions, and run the published command in the version actually used by readers.
A useful repair is to update version-specific claims in new material rather than rewriting archived articles silently. This distinction should appear beside a complete command and its expected result, so the reader can connect the visible instruction to a tested operation.
Internationalization investigations that apply to this command
25. The difference between language and syntax
A command line mixes words intended for a person with tokens interpreted by software. The second group is an interface contract, even when it resembles English.
Why this creates difficulty for Python tyro: Translating a literal flag as though it were a descriptive sentence produces a helpful-looking example the program may reject. Readers then suspect their language rather than the instructions.
An evidence-based check: Run the localized explanation beside the actual command help and capture the argv values received by a safe example handler.
A reliable reader-facing response: Keep registered commands and flags visibly in code formatting; translate the surrounding purpose, permissible values, prerequisites and recovery steps. The accepted syntax and the human explanation should be reviewed separately before release.
26. Locale selection without guesswork
A CLI may run on a machine whose OS locale differs from the person reading its documentation; environment and application settings may disagree.
Why this creates difficulty for Python tyro: Automatic language guesses can produce mixed-language help, especially in containers, remote terminals and shared classroom machines.
An evidence-based check: Set an explicit sample locale, then unset it and check the documented fallback. Also test a malformed or unsupported locale identifier.
A reliable reader-facing response: Declare a predictable locale precedence and show users how to override it without changing command semantics or saving private preferences. The accepted syntax and the human explanation should be reviewed separately before release.
27. Fallback language and missing catalogue entries
A missing translated message is different from a missing command or a failed parse. The program needs a deliberate fallback instead of an empty instruction.
Why this creates difficulty for Python tyro: Partial catalogs sometimes conceal errors by dropping the very phrase that explains what went wrong with a value.
An evidence-based check: Temporarily remove one noncritical resource in a test copy, invoke the related error and inspect the complete visible message.
A reliable reader-facing response: Use a complete, understandable fallback sentence and record the missing key for maintainers without dumping sensitive user input. The accepted syntax and the human explanation should be reviewed separately before release.
28. Placeholders and grammatical order
Message templates may contain filenames, counts, subcommand names and quotes. Languages differ in the order and grammatical form surrounding those values.
Why this creates difficulty for Python tyro: Concatenating a translated prefix with a filename and English suffix often creates broken grammar or misleading punctuation.
An evidence-based check: Translate complete messages with named placeholders; test strings containing spaces, apostrophes, emoji and brackets.
A reliable reader-facing response: Treat placeholders as typed data. Escape or format them at the display boundary rather than translating their identities. The accepted syntax and the human explanation should be reviewed separately before release.
29. Commands that users can safely copy
A code example is both instructional prose and an executable artifact. Its quoting and path syntax depend on the shell and platform.
Why this creates difficulty for Python tyro: A translated caption may be accurate yet leave readers copying curly quotes, invisible spaces or an unrecognized translated flag.
An evidence-based check: Paste the exact printed command into a disposable test environment; check shell tokenization before inspecting the parser.
A reliable reader-facing response: Put real commands in plain code blocks, label placeholders explicitly and provide separate PowerShell or POSIX variants when needed. The accepted syntax and the human explanation should be reviewed separately before release.
30. Unicode text through the entire journey
Unicode handling includes source text, shell argument encoding, parser values, filesystem names, terminal fonts and captured output.
Why this creates difficulty for Python tyro: A program may accept Japanese text correctly but display replacement characters after output redirection or logging.
An evidence-based check: Use sample values such as café, 東京, Αθήνα and العربية; compare parsed values with their original code points.
A reliable reader-facing response: Diagnose the failing boundary first; do not rewrite a valid user value simply because a terminal cannot render it. The accepted syntax and the human explanation should be reviewed separately before release.
31. Right-to-left help and left-to-right flags
Arabic and Hebrew paragraphs can appear visually reordered when mixed with ASCII options, punctuation and paths.
Why this creates difficulty for Python tyro: A line may look correct in an editor but mislead a reader about which dash or equals sign belongs to a flag.
An evidence-based check: Capture logical string order, copy the command to a shell and examine it under narrow and wide terminal widths.
A reliable reader-facing response: Keep commands on separate lines and use bidirectional isolation for presentation where supported, without inserting control characters into executable snippets. The accepted syntax and the human explanation should be reviewed separately before release.
32. Wide characters and narrow terminals
CJK characters, combining marks, emoji and terminal columns do not always follow one visible-cell-per-code-point assumptions.
Why this creates difficulty for Python tyro: Help tables that align perfectly in English may wrap, truncate or overlap columns in Chinese or Japanese.
An evidence-based check: Render help under several measured terminal widths, with and without ANSI styling, and inspect the plain captured output.
A reliable reader-facing response: Prefer resilient wrapping and independent label lines when a fixed-width description column becomes unreadable. The accepted syntax and the human explanation should be reviewed separately before release.
33. Color, contrast and noninteractive output
Color is optional communication, not a dependable carrier of severity or success. Redirected output may contain escape sequences.
Why this creates difficulty for Python tyro: A green-only success status or red-only warning excludes some readers and can corrupt logs or translated screenshots.
An evidence-based check: Exercise a no-color setting, an ordinary pipe and a screen reader-friendly text capture while forcing a known failure.
A reliable reader-facing response: Include explicit words or machine-readable status, and disable decorations in noninteractive contexts where the application supports it. The accepted syntax and the human explanation should be reviewed separately before release.
34. Human-readable output versus structured output
A person may want a localized explanation, while a script needs stable keys, numeric values and parseable output.
Why this creates difficulty for Python tyro: Translating JSON property names or decimal separators as an unannounced cosmetic change can break integrations.
An evidence-based check: Compare structured output byte structure across two locales and separately compare the human summary for clarity.
A reliable reader-facing response: Version any intentionally changed machine schema; otherwise keep interfaces invariant and localize only display fields intended for people. The accepted syntax and the human explanation should be reviewed separately before release.
35. Helpful errors must still fail
A polite message does not convert invalid input into success. Status codes and failure categories carry operational meaning.
Why this creates difficulty for Python tyro: Some translated wrappers swallow an exception, print a nice sentence and exit zero, making automation report a false success.
An evidence-based check: Trigger an invalid flag, an invalid value and an application-level failure; capture stdout, stderr and exit status for each.
A reliable reader-facing response: Keep failure categories observable while translating recovery instructions into natural language a user can act on. The accepted syntax and the human explanation should be reviewed separately before release.
36. Counts, plurals and locale-sensitive formatting
Many languages use more plural categories than English, and some do not mark plural on nouns in the same way.
Why this creates difficulty for Python tyro: Combining a number with a single translated word for item can sound wrong or obscure whether a limit applies.
An evidence-based check: Run zero, one, two and many cases, plus decimal or negative values where the option permits them.
A reliable reader-facing response: Use plural-aware message selection for prose, but preserve the parser’s documented number syntax for command input. The accepted syntax and the human explanation should be reviewed separately before release.
37. Examples should protect personal information
Translated CLI tutorials often mention file paths, account identifiers, access tokens and host names; realistic examples can accidentally expose secrets.
Why this creates difficulty for Python tyro: Copying a production token into a support ticket or public test transcript is a privacy failure unrelated to translation quality.
An evidence-based check: Run all published examples with fictional data and inspect logs and terminal history for inadvertently echoed credentials.
A reliable reader-facing response: Use synthetic input, redact sensitive tokens and never ask readers to paste secret values into an online demonstration. The accepted syntax and the human explanation should be reviewed separately before release.
38. Shell completion is another interface
Completions suggest command names, flags and choices; their labels and inserted tokens may have separate roles.
Why this creates difficulty for Python tyro: A translated suggestion might be inserted literally as a value that the parser does not accept.
An evidence-based check: Generate completion assets for each supported shell, compare proposed insertions with parser behavior and try Unicode-valued candidates.
A reliable reader-facing response: Localize descriptions if supported; preserve inserted canonical tokens unless a tested alias is genuinely registered. The accepted syntax and the human explanation should be reviewed separately before release.
39. Localization for screen-reader navigation
Help is more accessible when headings, examples, descriptions and errors follow a predictable order instead of relying on columns or colors.
Why this creates difficulty for Python tyro: Decorative icons or dense tables can make a simple option hard to locate in a spoken text rendering.
An evidence-based check: Read a plain text capture sequentially and ask whether a user can identify what action, parameter and recovery step comes next.
A reliable reader-facing response: Place the usable instruction before long rationale; keep labels descriptive and avoid visual-only references such as ‘the green command above’. The accepted syntax and the human explanation should be reviewed separately before release.
40. Release evidence rather than optimistic translation
A successful language review is not proof that the packaged executable, dependency version and shell environment still behave alike.
Why this creates difficulty for Python tyro: Help can change between releases, leaving a translation that describes an older flag or error format.
An evidence-based check: Record the exact package version, generated help, sample invocations, locale, environment, expected status and observed status.
A reliable reader-facing response: Ship only when the evidence agrees; rerun these tests after dependency upgrades rather than relying on an old screenshot. The accepted syntax and the human explanation should be reviewed separately before release.
41. A distinction between translation and product choice
Changing a command from ‘archive’ to ‘delete’ in translation can change the user’s understanding of risk even if the handler is unchanged.
Why this creates difficulty for Python tyro: Words promising to ‘preview’ an action are dangerous if the command actually writes files or sends network requests.
An evidence-based check: Use a disposable fixture to inspect side effects before approving wording for save, replace, overwrite, export and remove.
A reliable reader-facing response: Write messages that match observed behavior, not the friendliest phrase available in the target language. The accepted syntax and the human explanation should be reviewed separately before release.
42. Documentation must show an actual failure
Readers need examples of what happens when things go wrong, not only a beautiful success transcript.
Why this creates difficulty for Python tyro: A guide that skips errors leaves beginners unable to distinguish a typo, unsupported option, invalid path and permissions problem.
An evidence-based check: For every featured command, deliberately cause one harmless failure and show how to recognize the source and correct it.
A reliable reader-facing response: Keep the successful and failed examples together. Explain which correction changes the user’s input and which requires code changes. The accepted syntax and the human explanation should be reviewed separately before release.
Eight deeper lessons: from the first run to a reliable guide
Begin with the smallest model that accurately reflects the job. A translation assignment should not start with forty fields and five nested modes: a reader cannot tell whether an error came from language, the Python type or the CLI design. The fictional Preview example accepts a title, count and language. Print help, run one valid command and record the instance. Only then add a nested object or a union. This isolates the first divergence and makes the explanation honest.
A dataclass is not a language dictionary. Its fields carry typed meanings used by Python code, while descriptions tell the operator how to supply them. Changing a help sentence must not alter the type of count or the stored value of a title. When a release introduces a new field, tests should ask two questions separately: can the parser populate it, and can a non-English reader discover what it means?
Consider a Spanish guide to a program that accepts –count. ‘Cantidad’ may be a perfect section heading, but writing –cantidad inside the example is a claim about the application’s parser. If the source code has not registered this option, the claim is false. Keep the recognizable flag, explain it in Spanish and test the exact copied command. Translating software documentation is not equivalent to translating an application’s accepted command grammar.
Subcommands need especially careful examples. A branch such as checkout or commit can be a literal selector generated from a union; changing its order or replacing it with a translated verb can break parsing. The official examples also show that shared arguments may belong before a selector. An adequate guide gives the actual line, the result type and the chosen branch, then explains the human choice in ordinary language.
When tyro parses Unicode input, that fact says nothing about whether a downstream file operation is safe. A title may reach the handler correctly and still be corrupted by an unrelated encoding, escaping or storage choice. Use a read-only program, inspect the parsed value and then test any storage operation in an isolated fixture. Trace the entire path instead of attributing every failure to a translation.
An excellent error is specific. ‘Wrong parameter’ is rarely enough. Tell the reader whether an integer could not be converted, a required field is missing, a branch selector is unknown or a domain validation rule failed. Then show a complete replacement invocation that is safe to copy. Good localization lowers the cost of recovery, not only the cost of reading the first screen.
Some readers will use type checking, IDE completion and Python dataclasses to maintain scripts across teams. Those developer conveniences do not automatically make a generated interface comprehensible for a student or volunteer. Include one realistic task, a short description of each required value, a correct invocation, the expected harmless output and an explicit non-example. This connects the typed interface to a person’s decision.
Release review is a comparison exercise. Keep a fixture showing the generated help, one successful Unicode command, an invalid typed value, a missing required field and a selected subcommand. Run them in two locales. If the help changes after upgrading tyro, investigate the parser difference before translating fresh words. The reader should receive instructions that match the binary or script they actually execute.
A repeatable international testing routine
Create a disposable directory and keep the same example program for every test locale. Record the executable or script version, dependency lockfile, operating system, shell, language selection, full invocation, parsed input, displayed output, stderr and process status. Keep the test data fictional. A successful English screenshot is not a substitute for a tested Spanish or Japanese command.
Start with one valid argument, one value containing spaces, one non-Latin string and one deliberate error. Compare each locale at the level of behavior rather than surface wording. The order of options, returned values, side effects, JSON keys and exit codes should stay consistent unless a documented product requirement deliberately changes them.
Next test help at a narrow width, under redirection and with color disabled. Check that a user can navigate the text in sequence without relying on columns, symbol shape or background color. An apparently small change in the length of a translated description can move a critical constraint onto another line, so review the actual rendered output instead of relying only on catalog files.
Then ask a reviewer to complete a harmless task using only the target-language guide. Tell them the intended outcome, not the command. Record where they choose the wrong flag, wonder whether a placeholder is literal, misunderstand a default or fail to locate a recovery action. Edit the explanation to answer the missing question, and run the command again.
Finally repeat the tests from the packaged release, not only source code. An installed binary or published script may have different versions, compile-time flags, environment defaults or completion files. The final artifact and its help are the authority. If those disagree with a sentence in the guide, the disagreement must be resolved before that sentence is treated as reliable.
Twelve frequently asked questions
Does tyro translate its generated help automatically?
No multilingual catalog is implied merely by generating help from annotations. Your application still needs a deliberate approach to translated descriptions, custom messages and version-specific generated text.
Can I write a translated flag instead of –count?
Only if the application genuinely registers that spelling. A translation of what –count means is not an alias in the parser.
Why does my subcommand invocation fail after I rearrange arguments?
The generated grammar may impose ordering between shared options and a branch selector. Copy the installed version’s help and test the exact invocation.
What is the safest example for a multilingual guide?
Use a read-only dataclass example that prints parsed values, with a quoted Unicode title, a simple integer and an explicit locale choice.
Will a Japanese title survive a tyro string field?
Python strings support Unicode, but shell, terminal and downstream operations still require testing. Compare the parsed value with the original input.
What belongs in a dataclass field description?
Describe the meaning, allowed form, default and real consequence of supplying a value. Avoid a translated name that suggests an unregistered option.
Are unions and subcommands the same thing?
tyro supports subcommand interfaces built from unions of structured types; exact behavior depends on the annotations, configuration and version.
Does successful parsing prove a path exists?
No. Type conversion and domain validation are different. The application should check permissions and existence when those matter.
Should examples use localized digit separators?
For human reports, local formatting can help. For the command input, show the numeric format that the actual parser accepts.
How do I test right-to-left examples?
Keep flags in isolated code, test copy-and-paste into the intended shell and inspect the logical token order as well as the display.
What should I compare after upgrading tyro?
Generated help, field and branch names, types, defaults, accepted ordering, exit behavior, Unicode inputs and any completion assets.
What is a useful success criterion?
Someone following only the localized guide can complete one harmless task, understand one error and recover without altering program behavior.
Four-week practical learning plan
Week 1: learn the exact executable contract
Install or inspect the chosen version of Python tyro and capture its current help. Identify every command, named option, positional argument and default used by one small read-only task. Compare that list with the draft article line by line. Do not translate a token until you know whether it is a fixed parser symbol or a sentence. By the end of the week, a reader should have one valid command, one invalid command and a clearly described outcome.
Week 2: write complete human explanations
Choose two target locales and write the task description, option meanings, warnings and recovery messages as full sentences. Preserve software identifiers and technical values. Test realistic values including spaces and Unicode. Ask a reviewer to describe what each option does before they run it. If their prediction differs from the result, repair the explanatory wording or the implementation according to the true user requirement, rather than hiding the mismatch.
Week 3: challenge the command
Exercise unknown options, wrong types, missing required values, malformed paths and relevant branch selectors. Capture stdout, stderr, status and side effects. Try narrow terminal displays, no-color text, a pipe and a right-to-left description. For structured output, parse the results rather than judging them by appearance. Keep a short evidence table so that corrections can be distinguished from guesses.
Week 4: verify the release and teach recovery
Build or install the actual release candidate in a clean environment. Repeat the reference invocations in every supported locale. Confirm help matches the available flags, no secrets appear in transcripts and the failure instructions produce a successful correction. A good end-of-month exercise is to hand the guide to someone who has not read the source code. Their ability to complete the safe task and recover from a mistake is the final usability evidence.
A compact release checklist
- The exact dependency and executable versions are recorded.
- Every code example runs safely as published.
- Recognized flags and subcommands match generated help.
- Translated prose describes actual defaults, limits and side effects.
- Invalid input returns an honest error and useful recovery.
- Unicode strings survive input, parsing and output intact.
- RTL examples remain copyable in their logical token order.
- Narrow, redirected and no-color help remains understandable.
- Machine schemas and exit statuses remain stable across locales.
- No real credentials, customer data or production-changing commands appear.
- A reviewer using only the localized text completes the task.
- The packaged release passes the same checks as the teaching fixture.
Further reading and source documentation
tyro official overview · tyro cli API reference · tyro subcommands examples · Master Art of Translation — complete system · Translate Like a Pro — series index
The practical standard is not whether each sentence resembles English, but whether a reader can use Python tyro correctly while retaining the same software contracts. Keep runnable examples, honest failures and tested recovery steps together. Translation is successful when the command works, the message makes sense and the person knows what to do next.