Julia Comonicon localization means producing reliable multilingual help, command examples and diagnostic guidance for a Julia command-line application built with Comonicon.@main, @cast and documented command definitions. A reader searching for Julia Comonicon translated help, CLI docstrings, # Args, # Options, # Flags, subcommands or Unicode terminal testing needs to understand how generated usage is related to Julia function signatures. This guide follows that connection from a small example to practical multilingual quality checks.
Imagine a university research group sharing a lightweight Julia tool called plotnote that summarizes a local measurement file without changing it. Researchers in Brazil, Germany and Japan need clear explanations of a positional file path and a --format option, while scripts written by the original team still need to run. The human explanation can change with language; a Julia keyword argument, the literal CLI option and a documented accepted value cannot be silently renamed in a translation editor without potentially changing behavior.
The sound approach is to distinguish command metadata, docstring prose and executable identifiers; keep @main or @cast declarations aligned with their documented arguments; test generated help rather than guessing its layout; and validate translated examples against the actual runtime. This article covers authoring, command hierarchies, help generation, Unicode paths, error recovery, accessibility, release checks and a practical learning sequence.
@mainand@castdescribe command entry points; translated prose must not quietly alter their executable structure.- Comonicon uses docstrings and sections such as
# Args,# Optionsand# Flagsto generate help. - Julia function arguments and keyword arguments influence accepted command-line input.
- Test generated usage, values, Unicode filenames, errors and build artifacts on the deployed version.
Chapter 1 — From framework behavior to a useful multilingual interface
Comonicon is a Julia command-line generator that maps Julia definitions into a command interface. Its documentation presents @main for a command entry point and @cast for commands and modules, including nested structures. Positional inputs correspond to ordinary function arguments, options to keyword arguments and Boolean flags to particular keyword patterns. This closeness to Julia syntax is convenient, but it makes documentation drift consequential: a translated option example is incorrect if it no longer matches the function’s accepted interface.
Comonicon’s documented help generation relies on Julia docstrings. It recognizes section headings such as # Args or # Arguments, # Options and # Flags, with descriptions beneath them. These headings are conventions used to organize command metadata, not arbitrary presentation labels that a reviewer should change without testing. A translator’s safe surface is primarily the human explanation inside the documentation, while the definition of an option, its alias and its relationship to a keyword argument must remain consistent with the code.
Julia’s Unicode string support helps applications handle multilingual content, but it is not proof that any console, filesystem path or deployment package behaves identically across systems. The full journey includes a shell constructing arguments, a Julia executable receiving them, Comonicon interpreting them, the program opening any file and output channels displaying messages. A guide should say which stage has been tested instead of calling every visible non-ASCII success complete internationalization.
Generated help can be convenient for developers and frustrating for readers when it is treated as a substitute for editorial review. A short function description may be adequate for a developer who wrote the code, yet insufficient for a first-time analyst who needs to choose a valid option or recover from a wrong value. Teach the real user task at the top, use the generated usage as a reference and add a tested step-by-step example for any choice whose meaning is not obvious.
Whether a Comonicon application is run as a Julia script, installed as a package entry point or produced through code generation, the documentation needs to match the executable distributed to its readers. In particular, do not assume that editing a source docstring updates every previously built artifact. Version the test fixture, inspect actual generated help and check the installation route that users follow. A good multilingual release makes the connection between source, artifact and published guide visible.
Chapter 2 — One harmless example, examined carefully
The following simplified Julia code illustrates the documented approach of declaring a command and describing its arguments. The function prints selected values and does not modify files. The prose inside the docstring is the place for carefully reviewed human explanations; path, format and quiet remain executable identifiers unless the application deliberately changes its command API.
using Comonicon
"""
Inspect a local note without changing the file.
# Args
- `path`: local input filename
# Options
- `--format=<str>`: choose text or json output
# Flags
- `-q, --quiet`: suppress routine progress messages
"""
@main function plotnote(path; format::String="text", quiet::Bool=false)
println("path=", path, " format=", format, " quiet=", quiet)
endUse the example as a starting point, not a claim that every installed version handles every Markdown nuance identically. Run its generated help and test both a valid invocation and a rejected value. Notice that the function body shown here does not itself validate the format name; production code must do so if only text and json are intended. Any localized explanation should preserve that distinction.
Chapter 3 — Practical investigations with observable acceptance tests
The following 29 cases are organized around problems a real reader or maintainer can encounter. Each one separates the visible symptom from the framework mechanism, a bounded repair and a test. The aim is to learn how the command actually behaves. A good translation becomes reliable when the user can predict and verify that behavior, rather than when a phrase merely sounds like an English original.
1. Docstring heading renamed
An editor translates # Options into an unfamiliar heading inside the structured docstring and the generated help loses option metadata. Comonicon recognizes documented section conventions, so headings used as a parseable format are not ordinary free prose.
The lesson for multilingual documentation is to keep command grammar and reader-facing explanation in separate places. Preserve recognized section names and translate the explanatory lines that appear beneath them. Explain the accepted form with a small ordinary task, not with a slogan about localization. If the correction implies a software change, it belongs in an engineering review rather than a translator’s untracked edit.
Verify the result with evidence: Regenerate help from the same Julia definition before and after editing the descriptions. Preserve the invocation and its observed output so the check can be repeated after an upgrade. A passing outcome in one locale is not proof of behavior in every operating system.
2. Function argument and usage mismatch
A common reader journey starts here: The function expects path, yet a localized guide labels the positional argument file and readers assume the program accepts a different keyword. The underlying mechanism matters because Julia argument names, CLI metadata and descriptive labels are related but not interchangeable concepts.
Use one canonical reference example and distinguish display placeholders from executable identifiers. Describe the difference between what is typed and what is explained. Show a valid example and one intentional failure that the reader can safely reproduce without modifying valuable files.
A useful acceptance check is this: Run the published invocation and compare its parsed arguments with the function signature. If the translated guide does not enable the reader to interpret the result, improve its recovery explanation before treating the passage as complete.
3. Option renamed in translation
The source command accepts --format, but a translator publishes a local-language alternative without implementing an alias. The visible words are only part of the problem. An executable option is derived from command metadata, not automatically translated with surrounding sentences.
A maintainable correction begins with the actual contract. Retain the stable spelling and explain its meaning naturally, adding aliases only through an explicit API migration. Keep the test small so that a failure can be traced to a command token, a value conversion, an application rule or display formatting. These are different defects and often require different owners.
Reproduce and review: Run the original flag under every target locale and confirm it still works. Save both positive and negative outcomes. Ask a language reviewer to explain which input is accepted and why; an accurate answer is more valuable than a superficially fluent screenshot.
4. Boolean flag given a string value
Consider the boundary between the executable and its explanation. A reader supplies --quiet=true even though the documented flag is Boolean presence. Comonicon’s documented flag pattern maps certain Boolean keyword arguments to switches without independent string values.
Show the exact supported flag form and its default state; test other forms instead of inventing them. Write the example using literal accepted tokens, then translate the prose about their purpose. Avoid claiming that the framework provides a feature merely because the surrounding application could implement it.
The release gate should include this check: Compare command behavior with the flag absent and present under the installed release. Document any dependence on versions, shells or terminal settings rather than generalizing a local result to every reader.
5. Short alias not declared
The translated help recommends -f for --format because its initial letter seems obvious. Short aliases are command metadata and can require an explicit docstring form.
The lesson for multilingual documentation is to keep command grammar and reader-facing explanation in separate places. Document only aliases that the installed generated help actually exposes. Explain the accepted form with a small ordinary task, not with a slogan about localization. If the correction implies a software change, it belongs in an engineering review rather than a translator’s untracked edit.
Verify the result with evidence: Invoke the long and short forms and compare the values received by the command. Preserve the invocation and its observed output so the check can be repeated after an upgrade. A passing outcome in one locale is not proof of behavior in every operating system.
6. Short alias collision
A common reader journey starts here: Two option descriptions appear to suggest the same one-letter shortcut after localization. The underlying mechanism matters because Aliases must be unambiguous within the command and should not follow local-language initials automatically.
Maintain a stable alias register and block collisions during code review. Describe the difference between what is typed and what is explained. Show a valid example and one intentional failure that the reader can safely reproduce without modifying valuable files.
A useful acceptance check is this: Enumerate help flags in a test and check each unique short spelling. If the translated guide does not enable the reader to interpret the result, improve its recovery explanation before treating the passage as complete.
7. Docstring signature drift
An option is removed from a Julia function but the localized article still includes it in an example. The visible words are only part of the problem. Documentation generated from live definitions can diverge from manually maintained external pages.
A maintainable correction begins with the actual contract. Derive acceptance fixtures from the current command and rewrite stale examples when signatures change. Keep the test small so that a failure can be traced to a command token, a value conversion, an application rule or display formatting. These are different defects and often require different owners.
Reproduce and review: Run every documented command in a clean project environment. Save both positive and negative outcomes. Ask a language reviewer to explain which input is accepted and why; an accurate answer is more valuable than a superficially fluent screenshot.
8. Generated help too terse
Consider the boundary between the executable and its explanation. A novice sees an accurate list of arguments but cannot decide when to choose text instead of json. Automatic generation represents declared metadata; it does not supply unstated educational context.
Add a task-driven explanation and output example alongside the generated reference. Write the example using literal accepted tokens, then translate the prose about their purpose. Avoid claiming that the framework provides a feature merely because the surrounding application could implement it.
The release gate should include this check: Ask a reader to select the right format without using the English documentation. Document any dependence on versions, shells or terminal settings rather than generalizing a local result to every reader.
9. Variadic positional data
A command accepts several filenames, while the translation says there is exactly one required path. A variadic Julia function definition affects the command’s positional input expectations.
The lesson for multilingual documentation is to keep command grammar and reader-facing explanation in separate places. Describe whether multiple paths are allowed and what happens for zero input paths. Explain the accepted form with a small ordinary task, not with a slogan about localization. If the correction implies a software change, it belongs in an engineering review rather than a translator’s untracked edit.
Verify the result with evidence: Test one, two and no input values with harmless temporary files. Preserve the invocation and its observed output so the check can be repeated after an upgrade. A passing outcome in one locale is not proof of behavior in every operating system.
10. Nested command not discoverable
A common reader journey starts here: A Comonicon application uses @cast modules but the localized page describes only its top-level command. The underlying mechanism matters because Command hierarchies can be generated from modules as well as individual functions.
Explain parent commands and subcommands in a navigation-oriented structure. Describe the difference between what is typed and what is explained. Show a valid example and one intentional failure that the reader can safely reproduce without modifying valuable files.
A useful acceptance check is this: Request top-level help and subcommand help and verify the path to each task. If the translated guide does not enable the reader to interpret the result, improve its recovery explanation before treating the passage as complete.
11. Module name mistaken for a sentence
A command or module identifier is translated as though it were an English noun. The visible words are only part of the problem. Command dispatch can depend on generated names connected to Julia declarations.
A maintainable correction begins with the actual contract. Use stable command tokens in code lines and translate only their explanations. Keep the test small so that a failure can be traced to a command token, a value conversion, an application rule or display formatting. These are different defects and often require different owners.
Reproduce and review: Run the exact dispatch name shown on the localized page. Save both positive and negative outcomes. Ask a language reviewer to explain which input is accepted and why; an accurate answer is more valuable than a superficially fluent screenshot.
12. Markdown backticks corrupted
Consider the boundary between the executable and its explanation. A web editor modifies the docstring example’s inline code and readers copy punctuation into CLI flags. Docstrings, Markdown rendering and terminal syntax form separate layers.
Use tested source snippets and ensure code formatting preserves literal option characters. Write the example using literal accepted tokens, then translate the prose about their purpose. Avoid claiming that the framework provides a feature merely because the surrounding application could implement it.
The release gate should include this check: Paste an option sample from the published page and compare argument bytes. Document any dependence on versions, shells or terminal settings rather than generalizing a local result to every reader.
13. Help output from stale build
The documentation is updated, but a packaged script still prints the previous language or old descriptions. Generated artifacts may not update merely because the source file changed.
The lesson for multilingual documentation is to keep command grammar and reader-facing explanation in separate places. Rebuild and reinstall through the documented path before accepting help screenshots. Explain the accepted form with a small ordinary task, not with a slogan about localization. If the correction implies a software change, it belongs in an engineering review rather than a translator’s untracked edit.
Verify the result with evidence: Compare help from the source environment and the distribution artifact. Preserve the invocation and its observed output so the check can be repeated after an upgrade. A passing outcome in one locale is not proof of behavior in every operating system.
14. Locale selection undocumented
A common reader journey starts here: The tool has two sets of messages but does not explain how users select a language. The underlying mechanism matters because The CLI generator does not by itself define every application’s localization policy.
Specify how locale selection works in application code and document any fallback. Describe the difference between what is typed and what is explained. Show a valid example and one intentional failure that the reader can safely reproduce without modifying valuable files.
A useful acceptance check is this: Run the same task with each supported locale and check the expected help language. If the translated guide does not enable the reader to interpret the result, improve its recovery explanation before treating the passage as complete.
15. Unexpected English validation
French help looks complete, but --format=other triggers an English application error. The visible words are only part of the problem. Parser-generated help and application-owned validation messages can have different sources.
A maintainable correction begins with the actual contract. Centralize error resources and cover actual validation branches in language review. Keep the test small so that a failure can be traced to a command token, a value conversion, an application rule or display formatting. These are different defects and often require different owners.
Reproduce and review: Run a known invalid value and inspect the complete diagnostic. Save both positive and negative outcomes. Ask a language reviewer to explain which input is accepted and why; an accurate answer is more valuable than a superficially fluent screenshot.
16. Type name translated as a value
Consider the boundary between the executable and its explanation. A help description translates String or a placeholder into a word that the program treats as an allowed literal format. Type information and accepted option values are not interchangeable.
Show literal accepted tokens separately from readable type explanations. Write the example using literal accepted tokens, then translate the prose about their purpose. Avoid claiming that the framework provides a feature merely because the surrounding application could implement it.
The release gate should include this check: Try the displayed choices and verify each corresponds to a valid conversion. Document any dependence on versions, shells or terminal settings rather than generalizing a local result to every reader.
17. Floating-point punctuation changed
A translated numerical example uses a comma decimal although the application’s conversion expects a dot. Julia numeric conversion behavior must be checked for the actual argument parsing route.
The lesson for multilingual documentation is to keep command grammar and reader-facing explanation in separate places. Preserve machine-readable syntax and explain regional display conventions separately. Explain the accepted form with a small ordinary task, not with a slogan about localization. If the correction implies a software change, it belongs in an engineering review rather than a translator’s untracked edit.
Verify the result with evidence: Test both representations and record the accepted one. Preserve the invocation and its observed output so the check can be repeated after an upgrade. A passing outcome in one locale is not proof of behavior in every operating system.
18. Negative value looks like flag
A common reader journey starts here: A positional negative number is interpreted as a flag-like token in a command. The underlying mechanism matters because Command grammar and shell argument boundaries determine what enters numeric conversion.
Show a tested separator or positional form and document numeric range constraints. Describe the difference between what is typed and what is explained. Show a valid example and one intentional failure that the reader can safely reproduce without modifying valuable files.
A useful acceptance check is this: Run both a positive and negative fixture under the exact installed command. If the translated guide does not enable the reader to interpret the result, improve its recovery explanation before treating the passage as complete.
19. Unicode path only prints
The Julia function echoes a Japanese path successfully, but does not actually open the named file. The visible words are only part of the problem. Displaying a string and performing filesystem I/O are different claims.
A maintainable correction begins with the actual contract. Test real but harmless path operations before saying Unicode filenames work. Keep the test small so that a failure can be traced to a command token, a value conversion, an application rule or display formatting. These are different defects and often require different owners.
Reproduce and review: Open a temporary non-Latin file from the packaged executable. Save both positive and negative outcomes. Ask a language reviewer to explain which input is accepted and why; an accurate answer is more valuable than a superficially fluent screenshot.
20. Combining accents alter lookup
Consider the boundary between the executable and its explanation. A visually identical accented filename arrives with a different normalization form and the path cannot be resolved. Unicode normalization and filesystem matching differ across deployments.
Avoid silently normalizing file identifiers and describe tested path behavior. Write the example using literal accepted tokens, then translate the prose about their purpose. Avoid claiming that the framework provides a feature merely because the surrounding application could implement it.
The release gate should include this check: Compare composed and decomposed path fixtures where the system supports them. Document any dependence on versions, shells or terminal settings rather than generalizing a local result to every reader.
21. Right-to-left help confuses copy
An Arabic explanation includes ASCII flags whose visual order is ambiguous in a paragraph. Bidirectional rendering can change appearance without changing the underlying command token order.
The lesson for multilingual documentation is to keep command grammar and reader-facing explanation in separate places. Show commands as isolated code lines and check pasted input in the target terminal. Explain the accepted form with a small ordinary task, not with a slogan about localization. If the correction implies a software change, it belongs in an engineering review rather than a translator’s untracked edit.
Verify the result with evidence: Review the page with a fluent reader and execute the copied sample. Preserve the invocation and its observed output so the check can be repeated after an upgrade. A passing outcome in one locale is not proof of behavior in every operating system.
22. Narrow terminal wrapping
A common reader journey starts here: Long German explanations make a generated help table hard to scan at forty columns. The underlying mechanism matters because Terminal width and glyph width affect text layout independently from semantic translation.
Break complex guidance into short sentences and test narrow output. Describe the difference between what is typed and what is explained. Show a valid example and one intentional failure that the reader can safely reproduce without modifying valuable files.
A useful acceptance check is this: Capture narrow and wide help and verify no flag is obscured. If the translated guide does not enable the reader to interpret the result, improve its recovery explanation before treating the passage as complete.
23. Colored message lacks text
An error is indicated only with color, so redirected logs and assistive tools do not explain the failure. The visible words are only part of the problem. Presentation styling is not a substitute for a meaningful diagnostic.
A maintainable correction begins with the actual contract. Add a textual error category and an actionable correction. Keep the test small so that a failure can be traced to a command token, a value conversion, an application rule or display formatting. These are different defects and often require different owners.
Reproduce and review: Redirect output to plain text and verify it retains the full explanation. Save both positive and negative outcomes. Ask a language reviewer to explain which input is accepted and why; an accurate answer is more valuable than a superficially fluent screenshot.
24. Secret argument echoed
Consider the boundary between the executable and its explanation. A failed invocation prints a whole command line containing credentials in the generated or application error. User arguments are untrusted and potentially sensitive regardless of language.
Redact secrets and avoid reproducing private values in tutorial examples. Write the example using literal accepted tokens, then translate the prose about their purpose. Avoid claiming that the framework provides a feature merely because the surrounding application could implement it.
The release gate should include this check: Use a dummy token fixture and verify no full value enters logs. Document any dependence on versions, shells or terminal settings rather than generalizing a local result to every reader.
25. JSON key localized
A machine reader stops working because a translated CLI mode changes structured field names. A locale-sensitive display is different from a stable machine-data interface.
The lesson for multilingual documentation is to keep command grammar and reader-facing explanation in separate places. Keep declared JSON keys fixed and translate surrounding guidance instead. Explain the accepted form with a small ordinary task, not with a slogan about localization. If the correction implies a software change, it belongs in an engineering review rather than a translator’s untracked edit.
Verify the result with evidence: Parse output in two locales against the same schema. Preserve the invocation and its observed output so the check can be repeated after an upgrade. A passing outcome in one locale is not proof of behavior in every operating system.
26. Exit status misleading
A common reader journey starts here: A type or validation failure prints a clear translated message but still returns a success status. The underlying mechanism matters because An exit code is part of the CLI contract and must be handled by the application.
Use consistent nonzero failures and test them separately from language quality. Describe the difference between what is typed and what is explained. Show a valid example and one intentional failure that the reader can safely reproduce without modifying valuable files.
A useful acceptance check is this: Run a valid and invalid command and compare status codes under both locales. If the translated guide does not enable the reader to interpret the result, improve its recovery explanation before treating the passage as complete.
27. Terminal startup variation
The first Julia invocation takes much longer than later invocations and a translated guide implies the program has failed. The visible words are only part of the problem. Runtime startup and package compilation can affect observed responsiveness independently from localization.
A maintainable correction begins with the actual contract. Describe expected launch behavior conservatively and do not invent fixed performance promises. Keep the test small so that a failure can be traced to a command token, a value conversion, an application rule or display formatting. These are different defects and often require different owners.
Reproduce and review: Compare fresh and warmed invocations while checking that help eventually appears. Save both positive and negative outcomes. Ask a language reviewer to explain which input is accepted and why; an accurate answer is more valuable than a superficially fluent screenshot.
28. Documentation from wrong Comonicon version
Consider the boundary between the executable and its explanation. A code sample is copied from a different package release and a supported macro convention differs. Documentation and generated CLI behavior can evolve with releases.
Pin the reference version and regenerate examples under the deployed environment. Write the example using literal accepted tokens, then translate the prose about their purpose. Avoid claiming that the framework provides a feature merely because the surrounding application could implement it.
The release gate should include this check: Compare the installed version and the published snippet before release. Document any dependence on versions, shells or terminal settings rather than generalizing a local result to every reader.
29. Misleading cross-platform claim
One machine displays Unicode help correctly and the article asserts every operating system will do the same. Shells, terminals, fonts and filesystems are outside Julia’s simple string semantics.
The lesson for multilingual documentation is to keep command grammar and reader-facing explanation in separate places. Report the actual tested setup and keep unsupported claims out of the guide. Explain the accepted form with a small ordinary task, not with a slogan about localization. If the correction implies a software change, it belongs in an engineering review rather than a translator’s untracked edit.
Verify the result with evidence: Repeat the Unicode fixture on supported operating systems and retain the result. Preserve the invocation and its observed output so the check can be repeated after an upgrade. A passing outcome in one locale is not proof of behavior in every operating system.
Chapter 4 — Quality gates that make localization dependable
1. Choose a measurable reader task
An international command-line guide should begin with an outcome that makes sense outside the development team. A reader may want to inspect a file, request a summary or list available commands. Identify that task, give the smallest safe invocation, and explain the result. A translation that merely reproduces an API reference without helping the reader act is not sufficient. Record what a successful run looks like before choosing terminology, because the expected result determines which details deserve the clearest wording.
For Comonicon, begin with the result of plotnote report.txt, not a lecture on Julia macros. Show the one-line command and the output a reader can expect, then explain the role of the path argument. Developers can follow the macro reference afterward. This ordering lets both novices and Julia programmers find what they need.
2. Classify the text before translating it
Make a three-way distinction between literal syntax, user data and translatable content. Literal syntax includes established command names, flags, placeholders when interpreted by a parser and configuration keys promised as stable. User data includes filenames, project identifiers and values supplied by the reader. Human-facing explanations, headings and recovery instructions are the main translation surface. This classification prevents a well-meaning language edit from creating an incompatible executable command.
The # Args, # Options and # Flags docstring conventions deserve a separate grammar map. The translator may improve the surrounding prose but should not replace a section marker or alias with a natural-language lookalike without checking the generated help. Put command metadata and language resources under different review responsibilities.
3. Keep a single source of truth for examples
A code sample should be tested in the same shell and software version named by the documentation. Store the command beside a known expected result and rerun it after releases. If the example is displayed through a publishing system, paste-test the rendered version as well; quotation marks, dashes, code fences and whitespace are easily corrupted. Use imaginary local paths and harmless operations rather than live credentials, production services or private information.
Comonicon examples need a known Julia project environment and version. Use a harmless local file, not a public research repository, and show the julia invocation separately from code inside a module. This prevents a reader from pasting Julia source into a shell or misinterpreting a shell command as a docstring.
4. Explain accepted values, not just option labels
A label such as ‘format’ is useful only when the reader knows which values it accepts. Distinguish machine tokens such as text and json from translated descriptions of those tokens. State defaults, whether case matters, whether the value may be omitted and how invalid values are handled. If a number is expected, document the actually accepted numeric syntax rather than silently replacing a decimal point with a culturally familiar separator.
The generated usage screen does not know which research workflow brought a user to the tool. Add task-level explanation: a command for inspection, its accepted output format and the common reason for a rejection. Then let the API reference supply the full option list. The path from goal to action should remain visible.
5. Connect discovery, execution and recovery
Help has more than one job. It must allow a user to discover what exists, understand enough to choose the right option, execute a reasonable command, and correct mistakes without escalating to an expert. Test all four stages. If the first three work but the error remains a cryptic source-language exception, the reader still lacks an independent path to completion. A concise, concrete repair instruction can have more value than many translated lines of reference material.
If plotnote emits JSON, keep keys such as path or format stable for consuming scripts while translating explanatory headings and interactive diagnostics. A locale change should not quietly alter serialized structures. A dedicated machine-readable mode can reduce this risk if the application’s contract is documented.
6. Protect automation when localizing output
The same executable may serve a person and a scheduled job. Human-readable help, progress and errors can vary with locale; machine-readable keys, numeric fields and exit statuses should follow their documented stable contracts. If users pipe output into another program, changing a JSON key or adding decorative banners may break workflows. Separate interactive presentation from data output explicitly and test each as a different interface.
A Julia type annotation for a keyword argument influences accepted values and coercion, but a translated label is not a type conversion rule. Explain whether the option takes a string, number or Boolean, and ensure application-specific enums are checked explicitly. A decimal point must not be replaced simply because a language convention differs.
7. Check Unicode input and output separately
A visually correct non-Latin command in a web article does not prove that a terminal receives the same bytes or that a file can be opened. Test shell argument construction, runtime string handling, path operations, error formatting and terminal or redirected output as separate stages. Include decomposed accents and mixed-direction text where relevant. Report what was actually tested and avoid claiming uniform behavior across all systems from one machine.
Testing a string containing Japanese or accented characters inside Julia is helpful, but actual file I/O is a separate check. Create a disposable local file and open it from the built command. Include the full shell-to-runtime path and the tested OS when claiming Unicode filename support.
8. Design for narrow terminals and plain text
Not every reader uses an eighty-column desktop terminal with color support. Test long descriptions at narrow widths, copy them into plain text and verify that each flag remains associated with its explanation. When color is stripped, errors should still be identifiable by wording and stable codes. Avoid using whitespace alignment as a substitute for good sentences. A readable fallback is more inclusive than a beautiful table that collapses under translation.
Markdown documentation that looks elegant in an editor can wrap badly in generated terminal help. Review the installed program at narrow widths, compare redirection to a text file and check that code terms retain exact spelling. Avoid relying only on screenshots of an English help screen.
9. Use error messages to teach valid recovery
An error should identify the offending choice where safe, state the actual accepted form and show a harmless corrective example. Do not dump secret values or raw environment configurations. Keep error categories stable even when prose is localized, so support teams can diagnose the same problem in different languages. A practical acceptance test is to give a user an incorrect command and see whether they can repair it using the displayed message alone.
When an invalid --format value is accepted as a string and rejected by the program, that rejection is application behavior, not necessarily Comonicon’s parser. Keep localizable validation messages in a centralized place and give one valid example. Treat source-language fallbacks as defects if the product promises a target locale.
10. Store release evidence with the translation
Translate documentation against a tested version, not against a remembered version. Keep the source text, locale resources, executable examples, observed results and responsible reviewer linked to the release. Parser or framework upgrades should trigger renewed testing of help, errors, Unicode and compatibility. When something remains unverified, say so. Accurate limitations increase trust and make it easier to decide what to test next.
Record the Julia and Comonicon versions for tested examples. A macro change, command hierarchy update or regenerated installation script can affect generated usage. Save the output from a clean build and compare it with the public page before every release.
Chapter 5 — Common implementation questions
Does Comonicon translate help text automatically?
Its documented role is generating a CLI and help from Julia definitions and docstrings. Multilingual prose, localized error selection and quality review still require deliberate application design. Treat any locale mechanism as something to verify in the installed version.
Can I translate the `# Args` heading in a docstring?
Do not assume so. It is part of the documented structure used by the generator. Keep recognized headings stable unless you have verified a supported alternative, then translate the descriptions underneath.
What does `@main` do compared with `@cast`?
The documentation uses @main to mark an entry point and @cast to expose functions or modules as commands. This distinction matters for command hierarchies. Test the generated help rather than inferring command names only from source text.
Should a keyword argument name be translated?
Not casually. A keyword argument and its CLI representation can be part of executable compatibility. Use translated explanatory language beside the literal accepted option. Any new aliases require engineering and tests.
Can Julia handle Unicode filenames?
Julia supports Unicode strings, but correct end-to-end filename handling also depends on argument acquisition, filesystem behavior and the target deployment environment. Open an actual harmless fixture and report what was tested.
How should a team test generated help?
Build the distributed artifact, request help from it, test the published invocations and compare the displayed option set with live declarations. Repeat at narrow widths and when locale resources change.
Does a type annotation check all business rules?
No. Even when arguments are converted to a type, application-specific constraints such as allowed output formats, ranges or incompatible options still require explicit validation. Localize their recovery messages too.
What is the best first translation milestone?
Choose one complete user task: discover the command, run a safe example, interpret its output and repair an intentional error. Once that works in a target language, expand to more commands and regression fixtures.
Chapter 6 — Four weeks from first example to maintainable documentation
Week one — audit the executable contract
List the literal flags, command names, aliases, value types, defaults and errors for Julia Comonicon. Build one harmless test command and one deliberately incorrect command. Use the official reference for the installed framework version and note where the application supplies custom behavior. By the end of this week, a reviewer should distinguish syntax from translatable explanation, and the team should have an observable baseline against which future documentation can be checked.
Week two — translate a complete task
Select one user goal and translate its help entry, example, expected result and error recovery together. Ask a technical reviewer and a proficient target-language reader to attempt that task independently. The technical reviewer verifies Julia Comonicon behavior; the language reviewer verifies that instructions are understandable without referring to the source-language article. Disagreements about command spelling are resolved against the accepted grammar, not by preference for a familiar word.
Week three — test international edge cases
Expand the matrix to include a missing value, a wrong value, one unknown option, Unicode paths, a filename with spaces, redirected output and narrow terminal display. Add any framework-specific cases in the preceding investigations that match the actual product. Test the supported versions and operating systems; do not advertise untested behavior. Keep the fixtures small, fictional and free from credentials. Preserve both the test invocation and the observed result.
Week four — publish and establish a revision trigger
Give a new reader the finished localized page and a clean environment. They should be able to discover help, run the simplest valid command, interpret the output and recover from a predictable failure. Paste-test the rendered code samples in the target shell. Archive the result and record a trigger for changes to Julia Comonicon, command signatures, help generation, recognized options or expected output. Every such change deserves a new documentation check, not an assumption that the old translation remains correct.
Chapter 7 — What proficiency looks like
Comonicon makes it easy to connect Julia declarations to command-line usage, which is precisely why localization must respect the code’s structure. A good guide teaches what a command does, which names are executable, which values are accepted and how a reader can recover from mistakes. The macros and docstring conventions deserve technical accuracy; the explanations deserve natural language. Review them together, test generated help from the distributed artifact and preserve evidence for the next update.
The long-term measure is not the number of translated sentences. It is whether a reader using another language can perform the intended task, understand the consequences of their choices and recover safely when something goes wrong. Keep executable syntax stable unless deliberately versioned, keep ordinary explanations clear, preserve machine contracts and test the published examples. That is the practical work of translating command-line software like a professional.