Java Airline CLI localization means making Airline command help, options, examples, errors and terminal output understandable for people working in multiple languages without breaking the commands themselves. This practical guide is for engineers, technical writers, translators and operators searching for Java CLI internationalization, multilingual parser help, Unicode terminal testing, command-line error localization and reliable release QA. Airline uses Java annotations such as @Command, @Cli, @Option and @Arguments to define Git-style command structures and then generates help from metadata. Translating descriptions without changing parser identifiers is a practical engineering challenge, especially when the same metadata feeds terminal help and documentation generators.
Imagine HarborLink, a fictional port records utility whose Java commands inspect shipment metadata for teams working across different countries. A real user in this setting is a port supervisor who needs to inspect vessel manifests while an automated job relies on exact flags and subcommand paths. A helpful localized interface explains the task clearly while keeping registered command names, aliases, argument arity, option names, command hierarchy and numeric status codes reliable. It should support someone who is reading instructions for the first time and someone whose work depends on an established automated workflow. Translation that only changes visible words, without observing the executable effect of those words, is not yet a complete implementation.
This chapter starts with a quick decision guide, explains @Command, @Cli, @Option, @Arguments, @Parser, HelpOption, Help.class, help hints, restrictions and generator formats, then follows real tasks through help generation, validation, values, scripts, errors, accessibility and release testing. It distinguishes annotation descriptions, authored help sections, explanations of restrictions, examples, friendly diagnostics and human-facing document headings from registered command names, aliases, argument arity, option names, command hierarchy and numeric status codes. You will find a worked example, a practical failure-and-recovery library, a test matrix, a four-week implementation plan and clear answers to frequent questions. Annotation descriptions are static Java metadata. A locale-sensitive dynamic help strategy may require constructing or adapting help metadata; do not claim annotations automatically read ResourceBundle translations.
Quick answer: what changes and what must remain compatible
- Translate human explanations: annotation descriptions, authored help sections, explanations of restrictions, examples, friendly diagnostics and human-facing document headings.
- Preserve public machine-facing syntax: registered command names, aliases, argument arity, option names, command hierarchy and numeric status codes.
- Document the exact library version, platform and language-selection method.
- Test successful commands and failures, not only screenshots or translation catalogs.
- Treat copied code, file paths, data fields and status codes as operational contracts.
- Ship with a readable fallback and a tested rollback process.
Start by taking three captures from a real installed build: the root –help screen, the help for one important subcommand and an error produced by a deliberately invalid invocation. Record the arguments, process exit status, output stream and files touched in each case. A translator should know what happened before trying to rewrite the words. The owner of the CLI should know exactly which strings the parser constructs and which the application creates. This small baseline prevents a common failure: everyone agrees that a translation sounds fluent, but nobody can explain whether it still describes the software.
Understanding Airline before translating
The useful mental model is a three-layer interface. The first layer is the human explanation: the description of an action, an example sentence, a warning or a help heading. The second layer is the executable grammar: registered command names, aliases, argument arity, option names, command hierarchy and numeric status codes. The third layer is the result contract: structured records, side effects, logs, process status and any saved output. Translating the first layer is usually desirable; changing the second or third requires a separate compatibility decision. This distinction is easier to remember when it is tied to an ordinary task. In HarborLink, a fictional port records utility whose Java commands inspect shipment metadata for teams working across different countries, the analyst must understand what a region or report means, while a downstream program must still recognize its exact identifiers.
The principal vocabulary here includes @Command, @Cli, @Option, @Arguments, @Parser, HelpOption, Help.class, help hints, restrictions and generator formats. These names are not presented as a complete API catalog. They are the library-specific places where reader-facing language and parsing meet. Reference documentation should be checked against your installed version before using an example in production. A localized interface may be assembled by application code, metadata, a resource catalog, a customized formatter or a build-time method. Those approaches do not automatically have the same fallback behavior or compatibility guarantees. Annotation descriptions are static Java metadata. A locale-sensitive dynamic help strategy may require constructing or adapting help metadata; do not claim annotations automatically read ResourceBundle translations.
A practical string inventory should therefore record a source string, where it appears, its meaning, the related command route, any variables or punctuation constraints, the responsible code owner and a tested screenshot or command invocation. A statement such as "choose one" also needs to identify the exact choices and whether the parser enforces exclusivity. A word such as "export" needs to be labeled either a command token or ordinary explanatory prose. Without that distinction, reviewers are asked to guess which characters matter and which can change freely.
A small working example and how to reason about it
@Command(name = "inspect", description = "Inspect a shipment manifest")
public class InspectCommand implements Runnable {
@Option(name = {"--format"}, description = "Output format")
public String format = "text";
@Arguments(description = "Manifest files")
public java.util.List<String> files;
@Override public void run() {
// Validate input and produce a result.
}
}This example is deliberately small: it shows where metadata is declared and where parsing or execution begins, not a full translation subsystem. The description communicates intent; the registered command, option and argument names communicate executable syntax. The localized design should leave a stable invocation usable while supplying reader-friendly descriptions from a controlled source. The implementation may need explicit locale lookup and help customization outside the snippet, especially when the framework itself supplies fixed default strings. Do not infer that replacing a source comment translates every generated message.
Before adapting an example, verify the dependency version and the actual output. Copy the invocation into a clean project; record stdout and stderr separately; then try a missing value and an invalid value. Note whether generated help uses annotation text, docstrings, defaults or an internal formatter. If a particular internationalization feature is not documented, present the required integration as application work rather than an existing built-in switch. This approach is slower than blindly replacing English strings but faster than repairing a release that confused users or broke automation.
Detailed decisions and practical investigations
01. The name in @Command is executable syntax
A writer rewrites inspect as a local-language verb in an annotation and the deployed command route no longer matches automation. Picture the operator at a terminal with a real deadline. They are not comparing dictionaries; they are trying to complete a task without losing work. The wording needs to tell them what kind of input is expected, which part of the command to retain literally and what result to expect. The important question is not merely whether the sentence is grammatical. It is whether the reader can safely predict the next action from that sentence while the software still interprets the exact same bytes. In a multilingual release, the precise risk can remain hidden when reviewers inspect text outside the program.
Keep @Command(name) under compatibility control and localize @Command(description) or an equivalent help representation separately. For Airline, begin from the actual declarations and help generator, not from an imagined interface. Write a bilingual specification that shows the original technical token, the new human-facing explanation and a complete example in a safe test workspace. Mark anything connected to registered command names, aliases, argument arity, option names, command hierarchy and numeric status codes as requiring an explicit compatibility review. That discipline lets the translation team improve clarity without inadvertently becoming the owner of parser semantics.
Run the pre-existing inspect invocation after the translation work; confirm it reaches the original handler with equivalent parsed input. Capture the command, the resulting output and any files it creates. Ask a new reader to predict the effect from the translated help before running it, then compare their prediction with what happened. If the result differs, fix the description or the implementation deliberately; do not hide the discrepancy under a more attractive heading. Finally record the exact version and locale so the same case can be reproduced after packaging.
02. @Cli provides a navigational hierarchy
Nested groups expose a route of names, while translated headings might imply a command sits under a different group. This seems like a small wording detail until an operator copies the example or a colleague depends on the old behavior. The challenge is to distinguish the surface where a person reads a sentence from the surface where Airline interprets input. A fluent translation can still create a false expectation if it implies a different flag, accepted value, argument order or side effect. Begin the diagnosis by identifying the actual field or metadata entry that produced the visible wording.
Create a route map before translation and mark command groups as navigation contracts, not interchangeable prose headings. An editor should ask three questions: What is the user trying to do? What literal syntax does the parser accept? What evidence would show that the instruction is accurate? Put the answers beside the translation in the reviewer packet. Preserve any stable technical values and make the human explanation concrete: identify the operation, describe boundaries and show an example that can be executed. If the code cannot express the promised behavior, revise the promise rather than silently inventing a new feature.
List all root and nested help screens and compare routes with the parser’s registered metadata. A useful quality check combines language review with runtime review. Run a valid invocation first, then a nearby wrong one, and compare the resulting values with the same tests in the original language. Check the exit code and whether an error reaches stderr when appropriate. Reviewers should see that a reader can recognize both successful completion and a safe correction. The published article and built application should agree about what the command does.
03. @Option descriptions explain accepted flags
An operator reads a translated statement describing –format but the literal flag has been replaced in a code example. The place to begin is a real workflow, not a list of terms. Someone encountering this situation must decide what to type next, and that decision may involve a command name, a value, a path, a default or a potentially irreversible action. When translation obscures that choice, the interface becomes harder even if every sentence is idiomatic. The test of useful prose is therefore whether it supports the correct decision under ordinary working conditions.
Localize the description but retain the hyphens, option spellings, type and arity defined by @Option. Build a small contract table for the affected feature: reader-facing label, stable parser token, accepted values, default behavior, invalid-input behavior and output. The table is an editorial check, not a proposal to translate technical tokens by force. Give translators full example commands and expected results so they can make sentences natural while keeping registered command names, aliases, argument arity, option names, command hierarchy and numeric status codes stable. Any needed behavior change belongs in a versioned product decision, not a hidden catalog revision.
Test every documented form, including short aliases if configured, and verify both text and machine output types. Reproduce the good case and the failure case in the target locale. Validate that the right handler runs, the reported next step matches the actual parser and the downstream data still has its promised structure. Test a narrow terminal and at least one language whose text is visibly longer than English; these conditions reveal contradictions that a code review can miss. Record the observation as a release criterion, not an anecdote.
04. @Arguments are positional even in translation
A translation changes the apparent order of two positional values because the prose sounds more natural that way. Picture the operator at a terminal with a real deadline. They are not comparing dictionaries; they are trying to complete a task without losing work. The wording needs to tell them what kind of input is expected, which part of the command to retain literally and what result to expect. The smallest useful test begins with an actual command line and a measurable outcome. A translated snapshot alone cannot prove that the correct handler ran or that the exported data stayed intact. In a multilingual release, the precise risk can remain hidden when reviewers inspect text outside the program.
Rewrite the explanatory sentence for natural reading without changing the actual positional binding or example invocation order. For Airline, begin from the actual declarations and help generator, not from an imagined interface. Write a bilingual specification that shows the original technical token, the new human-facing explanation and a complete example in a safe test workspace. Mark anything connected to registered command names, aliases, argument arity, option names, command hierarchy and numeric status codes as requiring an explicit compatibility review. That discipline lets the translation team improve clarity without inadvertently becoming the owner of parser semantics.
Give two distinguishable input paths in a test and verify which field receives each one. Capture the command, the resulting output and any files it creates. Ask a new reader to predict the effect from the translated help before running it, then compare their prediction with what happened. If the result differs, fix the description or the implementation deliberately; do not hide the discrepancy under a more attractive heading. Finally record the exact version and locale so the same case can be reproduced after packaging.
05. A default command should be explicit
The CLI runs a default command but the translated top-level help merely says choose a command. This seems like a small wording detail until an operator copies the example or a colleague depends on the old behavior. The challenge is to distinguish the surface where a person reads a sentence from the surface where Airline interprets input. A fluent translation can still create a false expectation if it implies a different flag, accepted value, argument order or side effect. Begin the diagnosis by identifying the actual field or metadata entry that produced the visible wording.
Describe the default path and its consequences in language users can understand before they invoke it accidentally. An editor should ask three questions: What is the user trying to do? What literal syntax does the parser accept? What evidence would show that the instruction is accurate? Put the answers beside the translation in the reviewer packet. Preserve any stable technical values and make the human explanation concrete: identify the operation, describe boundaries and show an example that can be executed. If the code cannot express the promised behavior, revise the promise rather than silently inventing a new feature.
Run the program with no explicit subcommand; compare actions and exit code with the published documentation. A useful quality check combines language review with runtime review. Run a valid invocation first, then a nearby wrong one, and compare the resulting values with the same tests in the original language. Check the exit code and whether an error reaches stderr when appropriate. Reviewers should see that a reader can recognize both successful completion and a safe correction. The published article and built application should agree about what the command does.
06. HelpOption can alter workflow
The –help option is available, but a command executes before help has been handled and causes an unintended operation. The place to begin is a real workflow, not a list of terms. Someone encountering this situation must decide what to type next, and that decision may involve a command name, a value, a path, a default or a potentially irreversible action. When translation obscures that choice, the interface becomes harder even if every sentence is idiomatic. The test of useful prose is therefore whether it supports the correct decision under ordinary working conditions.
Use the library’s documented HelpOption path when configured, and ensure help processing occurs before side-effecting work. Build a small contract table for the affected feature: reader-facing label, stable parser token, accepted values, default behavior, invalid-input behavior and output. The table is an editorial check, not a proposal to translate technical tokens by force. Give translators full example commands and expected results so they can make sentences natural while keeping registered command names, aliases, argument arity, option names, command hierarchy and numeric status codes stable. Any needed behavior change belongs in a versioned product decision, not a hidden catalog revision.
Request help in a clean workspace and assert no files, network calls or shipment records were changed. Reproduce the good case and the failure case in the target locale. Validate that the right handler runs, the reported next step matches the actual parser and the downstream data still has its promised structure. Test a narrow terminal and at least one language whose text is visibly longer than English; these conditions reveal contradictions that a code review can miss. Record the observation as a release criterion, not an anecdote.
07. Help.class is not a translation engine
A generic help command shows English-only descriptions even though application status messages are localized. Picture the operator at a terminal with a real deadline. They are not comparing dictionaries; they are trying to complete a task without losing work. The wording needs to tell them what kind of input is expected, which part of the command to retain literally and what result to expect. Localized terminals can differ in font coverage, character widths and bidirectional layout. These display details matter, but they must never become a reason to change a stable parser token accidentally. In a multilingual release, the precise risk can remain hidden when reviewers inspect text outside the program.
Treat Help.class as a display route that requires appropriately localized underlying help content; test its actual output. For Airline, begin from the actual declarations and help generator, not from an imagined interface. Write a bilingual specification that shows the original technical token, the new human-facing explanation and a complete example in a safe test workspace. Mark anything connected to registered command names, aliases, argument arity, option names, command hierarchy and numeric status codes as requiring an explicit compatibility review. That discipline lets the translation team improve clarity without inadvertently becoming the owner of parser semantics.
Invoke help at root and at least two nested routes in every supported locale rather than trusting only application messages. Capture the command, the resulting output and any files it creates. Ask a new reader to predict the effect from the translated help before running it, then compare their prediction with what happened. If the result differs, fix the description or the implementation deliberately; do not hide the discrepancy under a more attractive heading. Finally record the exact version and locale so the same case can be reproduced after packaging.
08. Generated help has more than one target
The terminal display looks acceptable, while generated Markdown for an intranet mangles language headings and punctuation. This seems like a small wording detail until an operator copies the example or a colleague depends on the old behavior. The challenge is to distinguish the surface where a person reads a sentence from the surface where Airline interprets input. A fluent translation can still create a false expectation if it implies a different flag, accepted value, argument order or side effect. Begin the diagnosis by identifying the actual field or metadata entry that produced the visible wording.
Define separate acceptance criteria for text help, Markdown documentation, HTML or man output when those generators are used. An editor should ask three questions: What is the user trying to do? What literal syntax does the parser accept? What evidence would show that the instruction is accurate? Put the answers beside the translation in the reviewer packet. Preserve any stable technical values and make the human explanation concrete: identify the operation, describe boundaries and show an example that can be executed. If the code cannot express the promised behavior, revise the promise rather than silently inventing a new feature.
Generate each selected output from the same release and compare literal command syntax, headings, links and widths. A useful quality check combines language review with runtime review. Run a valid invocation first, then a nearby wrong one, and compare the resulting values with the same tests in the original language. Check the exit code and whether an error reaches stderr when appropriate. Reviewers should see that a reader can recognize both successful completion and a safe correction. The published article and built application should agree about what the command does.
09. Restriction hints must remain truthful
A help hint says a value is required, but a translation weakens it to recommended and users attempt invalid commands. The place to begin is a real workflow, not a list of terms. Someone encountering this situation must decide what to type next, and that decision may involve a command name, a value, a path, a default or a potentially irreversible action. When translation obscures that choice, the interface becomes harder even if every sentence is idiomatic. The test of useful prose is therefore whether it supports the correct decision under ordinary working conditions.
Translate the force of a restriction accurately, preserving mandatory, optional, exclusive and repeatable distinctions. Build a small contract table for the affected feature: reader-facing label, stable parser token, accepted values, default behavior, invalid-input behavior and output. The table is an editorial check, not a proposal to translate technical tokens by force. Give translators full example commands and expected results so they can make sentences natural while keeping registered command names, aliases, argument arity, option names, command hierarchy and numeric status codes stable. Any needed behavior change belongs in a versioned product decision, not a hidden catalog revision.
Trigger both a valid and invalid value, then compare the restriction hint with actual parser behavior. Reproduce the good case and the failure case in the target locale. Validate that the right handler runs, the reported next step matches the actual parser and the downstream data still has its promised structure. Test a narrow terminal and at least one language whose text is visibly longer than English; these conditions reveal contradictions that a code review can miss. Record the observation as a release criterion, not an anecdote.
10. Help sections need editorial ownership
An @Examples section is translated by one team while @Discussion remains outdated and contradicts the new behavior. Picture the operator at a terminal with a real deadline. They are not comparing dictionaries; they are trying to complete a task without losing work. The wording needs to tell them what kind of input is expected, which part of the command to retain literally and what result to expect. Nothing here requires choosing English for all users. It requires knowing which part of the interface belongs to the person and which part belongs to a machine-readable agreement. In a multilingual release, the precise risk can remain hidden when reviewers inspect text outside the program.
Inventory @Examples, @Discussion, @ExitCodes and other sections as separate content units with release owners. For Airline, begin from the actual declarations and help generator, not from an imagined interface. Write a bilingual specification that shows the original technical token, the new human-facing explanation and a complete example in a safe test workspace. Mark anything connected to registered command names, aliases, argument arity, option names, command hierarchy and numeric status codes as requiring an explicit compatibility review. That discipline lets the translation team improve clarity without inadvertently becoming the owner of parser semantics.
Review a full generated help document and trace every example to an executable test. Capture the command, the resulting output and any files it creates. Ask a new reader to predict the effect from the translated help before running it, then compare their prediction with what happened. If the result differs, fix the description or the implementation deliberately; do not hide the discrepancy under a more attractive heading. Finally record the exact version and locale so the same case can be reproduced after packaging.
11. Externally stored prose must be packaged
An ExternalDiscussion or ExternalExamples resource works from the source tree but disappears from a packaged JAR. This seems like a small wording detail until an operator copies the example or a colleague depends on the old behavior. The challenge is to distinguish the surface where a person reads a sentence from the surface where Airline interprets input. A fluent translation can still create a false expectation if it implies a different flag, accepted value, argument order or side effect. Begin the diagnosis by identifying the actual field or metadata entry that produced the visible wording.
Treat resource loading and the build’s inclusion rules as first-class localization requirements. An editor should ask three questions: What is the user trying to do? What literal syntax does the parser accept? What evidence would show that the instruction is accurate? Put the answers beside the translation in the reviewer packet. Preserve any stable technical values and make the human explanation concrete: identify the operation, describe boundaries and show an example that can be executed. If the code cannot express the promised behavior, revise the promise rather than silently inventing a new feature.
Run a JAR from a directory without project sources and verify every localized section loads or falls back coherently. A useful quality check combines language review with runtime review. Run a valid invocation first, then a nearby wrong one, and compare the resulting values with the same tests in the original language. Check the exit code and whether an error reaches stderr when appropriate. Reviewers should see that a reader can recognize both successful completion and a safe correction. The published article and built application should agree about what the command does.
12. Parser abbreviations are not universally safe
A locale-specific command word suggests a short prefix that becomes ambiguous with a second command. The place to begin is a real workflow, not a list of terms. Someone encountering this situation must decide what to type next, and that decision may involve a command name, a value, a path, a default or a potentially irreversible action. When translation obscures that choice, the interface becomes harder even if every sentence is idiomatic. The test of useful prose is therefore whether it supports the correct decision under ordinary working conditions.
Only enable command or option abbreviation deliberately; record unambiguous behavior in the exact parser configuration. Build a small contract table for the affected feature: reader-facing label, stable parser token, accepted values, default behavior, invalid-input behavior and output. The table is an editorial check, not a proposal to translate technical tokens by force. Give translators full example commands and expected results so they can make sentences natural while keeping registered command names, aliases, argument arity, option names, command hierarchy and numeric status codes stable. Any needed behavior change belongs in a versioned product decision, not a hidden catalog revision.
Try a shared prefix of two commands, a unique prefix and the full names; reject unexpected resolution. Reproduce the good case and the failure case in the target locale. Validate that the right handler runs, the reported next step matches the actual parser and the downstream data still has its promised structure. Test a narrow terminal and at least one language whose text is visibly longer than English; these conditions reveal contradictions that a code review can miss. Record the observation as a release criterion, not an anecdote.
13. Negated flags must retain polarity
A configurable –no- prefix is paired with a description whose translation reverses the meaning. Picture the operator at a terminal with a real deadline. They are not comparing dictionaries; they are trying to complete a task without losing work. The wording needs to tell them what kind of input is expected, which part of the command to retain literally and what result to expect. Help text is executable guidance in a practical sense: people copy commands from it. Every example should therefore be treated as a tested instruction rather than decorative copy. In a multilingual release, the precise risk can remain hidden when reviewers inspect text outside the program.
Keep the Boolean parser setting and literal negation prefix stable, and translate the effect of true and false correctly. For Airline, begin from the actual declarations and help generator, not from an imagined interface. Write a bilingual specification that shows the original technical token, the new human-facing explanation and a complete example in a safe test workspace. Mark anything connected to registered command names, aliases, argument arity, option names, command hierarchy and numeric status codes as requiring an explicit compatibility review. That discipline lets the translation team improve clarity without inadvertently becoming the owner of parser semantics.
Run both enabled and disabled flags with defaults visible; inspect resulting booleans and user-facing confirmation. Capture the command, the resulting output and any files it creates. Ask a new reader to predict the effect from the translated help before running it, then compare their prediction with what happened. If the result differs, fix the description or the implementation deliberately; do not hide the discrepancy under a more attractive heading. Finally record the exact version and locale so the same case can be reproduced after packaging.
14. Option arity is not a linguistic choice
A translated description implies –count takes no following number, although the parser expects one. This seems like a small wording detail until an operator copies the example or a colleague depends on the old behavior. The challenge is to distinguish the surface where a person reads a sentence from the surface where Airline interprets input. A fluent translation can still create a false expectation if it implies a different flag, accepted value, argument order or side effect. Begin the diagnosis by identifying the actual field or metadata entry that produced the visible wording.
Explain arity with concrete examples and retain the number of supplied values the Option expects. An editor should ask three questions: What is the user trying to do? What literal syntax does the parser accept? What evidence would show that the instruction is accurate? Put the answers beside the translation in the reviewer packet. Preserve any stable technical values and make the human explanation concrete: identify the operation, describe boundaries and show an example that can be executed. If the code cannot express the promised behavior, revise the promise rather than silently inventing a new feature.
Test zero, one and excessive values and verify diagnostics identify the flag and expected count. A useful quality check combines language review with runtime review. Run a valid invocation first, then a nearby wrong one, and compare the resulting values with the same tests in the original language. Check the exit code and whether an error reaches stderr when appropriate. Reviewers should see that a reader can recognize both successful completion and a safe correction. The published article and built application should agree about what the command does.
15. Command aliases can become permanent promises
A convenience alias is introduced for one locale and later removed, breaking scripts that copied a help example. The place to begin is a real workflow, not a list of terms. Someone encountering this situation must decide what to type next, and that decision may involve a command name, a value, a path, a default or a potentially irreversible action. When translation obscures that choice, the interface becomes harder even if every sentence is idiomatic. The test of useful prose is therefore whether it supports the correct decision under ordinary working conditions.
Version aliases like public syntax and avoid proliferating locale-specific executable tokens without a migration policy. Build a small contract table for the affected feature: reader-facing label, stable parser token, accepted values, default behavior, invalid-input behavior and output. The table is an editorial check, not a proposal to translate technical tokens by force. Give translators full example commands and expected results so they can make sentences natural while keeping registered command names, aliases, argument arity, option names, command hierarchy and numeric status codes stable. Any needed behavior change belongs in a versioned product decision, not a hidden catalog revision.
Execute every published alias in two locales and preserve a deprecation path when one is retired. Reproduce the good case and the failure case in the target locale. Validate that the right handler runs, the reported next step matches the actual parser and the downstream data still has its promised structure. Test a narrow terminal and at least one language whose text is visibly longer than English; these conditions reveal contradictions that a code review can miss. Record the observation as a release criterion, not an anecdote.
16. Custom converters need clear domain rules
An option receives a time, currency or measurement value whose local written form is not accepted by the converter. Picture the operator at a terminal with a real deadline. They are not comparing dictionaries; they are trying to complete a task without losing work. The wording needs to tell them what kind of input is expected, which part of the command to retain literally and what result to expect. A translator needs the same screen that the operator sees, not only a spreadsheet of isolated strings. Context exposes the difference between a friendly explanation, a sample value, a required token and a destructive action. In a multilingual release, the precise risk can remain hidden when reviewers inspect text outside the program.
Separate localized display labels from accepted input grammar; add localized parsing only with explicit round-trip tests. For Airline, begin from the actual declarations and help generator, not from an imagined interface. Write a bilingual specification that shows the original technical token, the new human-facing explanation and a complete example in a safe test workspace. Mark anything connected to registered command names, aliases, argument arity, option names, command hierarchy and numeric status codes as requiring an explicit compatibility review. That discipline lets the translation team improve clarity without inadvertently becoming the owner of parser semantics.
Feed representative comma decimals, ISO dates and invalid units; confirm meaning and rejected input are unambiguous. Capture the command, the resulting output and any files it creates. Ask a new reader to predict the effect from the translated help before running it, then compare their prediction with what happened. If the result differs, fix the description or the implementation deliberately; do not hide the discrepancy under a more attractive heading. Finally record the exact version and locale so the same case can be reproduced after packaging.
17. Friendly errors should not bury the original cause
A technical exception reaches a port worker as a stack trace rather than a safe correction message. This seems like a small wording detail until an operator copies the example or a colleague depends on the old behavior. The challenge is to distinguish the surface where a person reads a sentence from the surface where Airline interprets input. A fluent translation can still create a false expectation if it implies a different flag, accepted value, argument order or side effect. Begin the diagnosis by identifying the actual field or metadata entry that produced the visible wording.
Provide a plain statement of the field, expected shape and next step; keep detailed logs available to engineers without leaking identifiers. An editor should ask three questions: What is the user trying to do? What literal syntax does the parser accept? What evidence would show that the instruction is accurate? Put the answers beside the translation in the reviewer packet. Preserve any stable technical values and make the human explanation concrete: identify the operation, describe boundaries and show an example that can be executed. If the code cannot express the promised behavior, revise the promise rather than silently inventing a new feature.
Exercise missing files, forbidden paths and malformed data, checking safe error output and nonzero exit status. A useful quality check combines language review with runtime review. Run a valid invocation first, then a nearby wrong one, and compare the resulting values with the same tests in the original language. Check the exit code and whether an error reaches stderr when appropriate. Reviewers should see that a reader can recognize both successful completion and a safe correction. The published article and built application should agree about what the command does.
18. Exit codes matter across languages
The new translation changes an error path so an automation job treats the command as successful despite a failure message. The place to begin is a real workflow, not a list of terms. Someone encountering this situation must decide what to type next, and that decision may involve a command name, a value, a path, a default or a potentially irreversible action. When translation obscures that choice, the interface becomes harder even if every sentence is idiomatic. The test of useful prose is therefore whether it supports the correct decision under ordinary working conditions.
Keep exit codes tied to outcome, not the language of the message; distinguish warnings from failed tasks. Build a small contract table for the affected feature: reader-facing label, stable parser token, accepted values, default behavior, invalid-input behavior and output. The table is an editorial check, not a proposal to translate technical tokens by force. Give translators full example commands and expected results so they can make sentences natural while keeping registered command names, aliases, argument arity, option names, command hierarchy and numeric status codes stable. Any needed behavior change belongs in a versioned product decision, not a hidden catalog revision.
Compare error and success codes in English and another locale while forcing the same condition. Reproduce the good case and the failure case in the target locale. Validate that the right handler runs, the reported next step matches the actual parser and the downstream data still has its promised structure. Test a narrow terminal and at least one language whose text is visibly longer than English; these conditions reveal contradictions that a code review can miss. Record the observation as a release criterion, not an anecdote.
19. Terminal and documentation width differ
A long translated command description wraps over a table column and makes help hard to scan. Picture the operator at a terminal with a real deadline. They are not comparing dictionaries; they are trying to complete a task without losing work. The wording needs to tell them what kind of input is expected, which part of the command to retain literally and what result to expect. An error is a particularly good test of translation quality because the reader needs to recover while uncertain. A good explanation names the problem, preserves relevant syntax and offers a reliable next move. In a multilingual release, the precise risk can remain hidden when reviewers inspect text outside the program.
Test width-aware formatting, simpler wording and accessible plain-text help rather than truncating essential meaning. For Airline, begin from the actual declarations and help generator, not from an imagined interface. Write a bilingual specification that shows the original technical token, the new human-facing explanation and a complete example in a safe test workspace. Mark anything connected to registered command names, aliases, argument arity, option names, command hierarchy and numeric status codes as requiring an explicit compatibility review. That discipline lets the translation team improve clarity without inadvertently becoming the owner of parser semantics.
Capture help at multiple terminal widths and inspect the same content in generated HTML and Markdown. Capture the command, the resulting output and any files it creates. Ask a new reader to predict the effect from the translated help before running it, then compare their prediction with what happened. If the result differs, fix the description or the implementation deliberately; do not hide the discrepancy under a more attractive heading. Finally record the exact version and locale so the same case can be reproduced after packaging.
20. Unicode and bidirectional text need semantic checking
Arabic prose encloses a file path and the visual order makes a slash seem attached to the wrong token. This seems like a small wording detail until an operator copies the example or a colleague depends on the old behavior. The challenge is to distinguish the surface where a person reads a sentence from the surface where Airline interprets input. A fluent translation can still create a false expectation if it implies a different flag, accepted value, argument order or side effect. Begin the diagnosis by identifying the actual field or metadata entry that produced the visible wording.
Isolate code examples, preserve actual path bytes and request review from someone fluent in the target language. An editor should ask three questions: What is the user trying to do? What literal syntax does the parser accept? What evidence would show that the instruction is accurate? Put the answers beside the translation in the reviewer packet. Preserve any stable technical values and make the human explanation concrete: identify the operation, describe boundaries and show an example that can be executed. If the code cannot express the promised behavior, revise the promise rather than silently inventing a new feature.
Have a reviewer reproduce a copied command from rendered documentation and compare input bytes. A useful quality check combines language review with runtime review. Run a valid invocation first, then a nearby wrong one, and compare the resulting values with the same tests in the original language. Check the exit code and whether an error reaches stderr when appropriate. Reviewers should see that a reader can recognize both successful completion and a safe correction. The published article and built application should agree about what the command does.
21. Version-specific metadata requires evidence
A tutorial for a different Airline version names an annotation feature absent from the application. The place to begin is a real workflow, not a list of terms. Someone encountering this situation must decide what to type next, and that decision may involve a command name, a value, a path, a default or a potentially irreversible action. When translation obscures that choice, the interface becomes harder even if every sentence is idiomatic. The test of useful prose is therefore whether it supports the correct decision under ordinary working conditions.
Bind examples and build dependencies to the installed release and use official version-matched API documentation. Build a small contract table for the affected feature: reader-facing label, stable parser token, accepted values, default behavior, invalid-input behavior and output. The table is an editorial check, not a proposal to translate technical tokens by force. Give translators full example commands and expected results so they can make sentences natural while keeping registered command names, aliases, argument arity, option names, command hierarchy and numeric status codes stable. Any needed behavior change belongs in a versioned product decision, not a hidden catalog revision.
Compile and run examples in a minimal project before inclusion in the translated guide. Reproduce the good case and the failure case in the target locale. Validate that the right handler runs, the reported next step matches the actual parser and the downstream data still has its promised structure. Test a narrow terminal and at least one language whose text is visibly longer than English; these conditions reveal contradictions that a code review can miss. Record the observation as a release criterion, not an anecdote.
22. Help is a safety interface
The port tool can perform an irreversible import but translated help describes it only as a routine inspection. Picture the operator at a terminal with a real deadline. They are not comparing dictionaries; they are trying to complete a task without losing work. The wording needs to tell them what kind of input is expected, which part of the command to retain literally and what result to expect. The important question is not merely whether the sentence is grammatical. It is whether the reader can safely predict the next action from that sentence while the software still interprets the exact same bytes. In a multilingual release, the precise risk can remain hidden when reviewers inspect text outside the program.
Describe effects, prerequisites and rollback limitations in help, and require confirmation for destructive actions if the application supports it. For Airline, begin from the actual declarations and help generator, not from an imagined interface. Write a bilingual specification that shows the original technical token, the new human-facing explanation and a complete example in a safe test workspace. Mark anything connected to registered command names, aliases, argument arity, option names, command hierarchy and numeric status codes as requiring an explicit compatibility review. That discipline lets the translation team improve clarity without inadvertently becoming the owner of parser semantics.
Run –help and the safe dry-run route; verify no irreversible action is triggered and consequences are accurately stated. Capture the command, the resulting output and any files it creates. Ask a new reader to predict the effect from the translated help before running it, then compare their prediction with what happened. If the result differs, fix the description or the implementation deliberately; do not hide the discrepancy under a more attractive heading. Finally record the exact version and locale so the same case can be reproduced after packaging.
Five complete workflows for a multilingual release
Onboarding a first-time user
Give a new operator a specific goal in HarborLink, a fictional port records utility whose Java commands inspect shipment metadata for teams working across different countries and no private developer notes. Provide the translated overview, one complete command and one explanation of the output. Observe whether they understand the purpose, distinguish placeholders from real values, and know what to do when a value is missing. The acceptance record should name the user goal, a full invocation, the observed effect, the reviewer and any unresolved limitation. Annotation descriptions are static Java metadata. A locale-sensitive dynamic help strategy may require constructing or adapting help metadata; do not claim annotations automatically read ResourceBundle translations.
Diagnosing an invalid command
Choose a realistic mistake such as an unknown option, missing required input or malformed value. The failure message should explain the accepted shape and identify a safe correction while retaining meaningful technical tokens. Capture the actual process status and all output channels. The acceptance record should name the user goal, a full invocation, the observed effect, the reviewer and any unresolved limitation. Annotation descriptions are static Java metadata. A locale-sensitive dynamic help strategy may require constructing or adapting help metadata; do not claim annotations automatically read ResourceBundle translations.
Keeping an automation script stable
Run an existing script with the new language selected. Compare filenames, JSON keys, values, return status and side effects with the original binary. It is not enough that a human sees the same general result; automation depends on exact machine contracts. The acceptance record should name the user goal, a full invocation, the observed effect, the reviewer and any unresolved limitation. Annotation descriptions are static Java metadata. A locale-sensitive dynamic help strategy may require constructing or adapting help metadata; do not claim annotations automatically read ResourceBundle translations.
Reviewing a right-to-left help screen
Render an Arabic explanation next to a command line with hyphens and paths. Place the literal command in an isolated code block, ask a fluent reader what it does, and test their copied invocation. Note visual ambiguity separately from accepted bytes. The acceptance record should name the user goal, a full invocation, the observed effect, the reviewer and any unresolved limitation. Annotation descriptions are static Java metadata. A locale-sensitive dynamic help strategy may require constructing or adapting help metadata; do not claim annotations automatically read ResourceBundle translations.
Packaging for someone else
Build the release artifact, install it outside the development checkout and repeat the previous four tasks. Record how locale is selected, which language is the fallback and where support documentation lives. A translation that works only in a contributor’s workspace is not a shipped feature. The acceptance record should name the user goal, a full invocation, the observed effect, the reviewer and any unresolved limitation. Annotation descriptions are static Java metadata. A locale-sensitive dynamic help strategy may require constructing or adapting help metadata; do not claim annotations automatically read ResourceBundle translations.
Testing matrix: what to run before launch
- English baseline and every officially supported target language, with an intentionally missing translation entry.
- Root help, nested help, one successful command, one invalid option, one invalid value and one missing required argument.
- Standard 80-column terminal, narrow 40-column terminal, no-color or redirected output, and a non-interactive execution.
- Unicode filenames, spaces and quotes; selected CJK and right-to-left text for display and copying.
- Default settings, all supported choices, true and false flags, repeated values, and a safe failure.
- stdout and stderr separately, with exit status and structured output compared byte-for-byte where promised.
- A packaged install in a clean environment without source checkout or developer-only resource paths.
- A regression against the previous release so any deliberate parser change is clearly identified.
A good matrix is modest enough to run repeatedly but broad enough to expose the differences that matter. At minimum, retain one command per documented user journey and one wrong-input case per parser feature with a human-facing message. Keep expected output structured: parsed arguments, destination paths, exit codes and stable record keys. Review the wording separately with human readers. A snapshot test alone can certify that a string has not changed; it cannot certify that it is natural, polite, complete or accurate for the task.
When an item fails, distinguish four kinds of defect. A language defect makes a sentence difficult or misleading. A parser defect changes which bytes are accepted. A rendering defect makes help unreadable at the user’s terminal. A release defect means the right resource or code was not shipped. These categories lead to different owners and different fixes. They also prevent a team from treating every issue as a request to rewrite a translation, when the failure may be in resource discovery, terminal layout or package construction.
A realistic four-week implementation plan
Week 1 — inventory and baseline
List the current commands, parser metadata, help surfaces, error paths and output agreements for Airline. Build a golden set of invocations and capture their effects. Confirm which audiences use the tool and what locales they actually need. Finish with a visible artifact: a reviewed inventory, a tested translation, a clean release candidate or a supported rollout decision. This is more useful than a claim that a percentage of isolated strings has been translated.
Week 2 — editorial design
Create the term list and translator context packets, prioritize important workflows and define fallback language. Draft localized help, examples and common errors, checking each sentence against its executable contract. Have a bilingual reviewer verify safety-critical wording. Finish with a visible artifact: a reviewed inventory, a tested translation, a clean release candidate or a supported rollout decision. This is more useful than a claim that a percentage of isolated strings has been translated.
Week 3 — integration and testing
Connect the localized wording to the application’s help and message construction. Run parser-regression tests, generated-help snapshots, keyboard and Unicode tests, non-TTY checks and packaging checks. Fix missing catalogs and code-example errors before widening the rollout. Finish with a visible artifact: a reviewed inventory, a tested translation, a clean release candidate or a supported rollout decision. This is more useful than a claim that a percentage of isolated strings has been translated.
Week 4 — pilot, release and recovery
Let a small group of real operators complete tasks using the built artifact. Record where they hesitate, correct confusing instructions and confirm the rollback approach. Publish versioned release notes that say exactly what changed and what did not. Finish with a visible artifact: a reviewed inventory, a tested translation, a clean release candidate or a supported rollout decision. This is more useful than a claim that a percentage of isolated strings has been translated.
Frequently asked questions
Can the visible command itself be translated?
Sometimes an application can deliberately register aliases, but changing registered command names, aliases, argument arity, option names, command hierarchy and numeric status codes without a compatibility plan may break copied documentation, shell history and automation. Translate explanatory text first; add executable aliases only as a tested feature with support and deprecation rules.
Does the library automatically translate all errors?
Do not assume so. Annotation descriptions are static Java metadata. A locale-sensitive dynamic help strategy may require constructing or adapting help metadata; do not claim annotations automatically read ResourceBundle translations. Inventory strings produced by the framework and strings created by the application, then test the built program under each selected locale.
Should JSON output and log keys be localized?
Usually not when another system reads them. Localized human summaries can sit beside stable structured output. If a report is exclusively human-readable, its headings may be translated, but document that distinction explicitly.
What about Unicode and right-to-left languages?
Use proper Unicode encoding and test font coverage, width, copying and directionality. Keep command tokens inside clearly delimited code examples. Have a fluent reviewer validate meaning; a screenshot without a runnable command is incomplete evidence.
What is the fastest useful first step?
Run –help, one valid command and one invalid command from a clean installation. Annotate every human string and every machine token. This small inventory gives translators context and developers a baseline to protect.
Is a translation ready when every string has a target-language entry?
No. Completeness of a catalog is only one condition. A release also needs correct parser behavior, task comprehension, readable terminal layouts, a fallback when a resource is missing and evidence that downstream consumers still receive stable values.
How should a translation dispute be settled?
Ask which user task the sentence supports, which parser behavior it describes and what concrete invocation tests the claim. When two wordings are equally natural, prefer the one that helps an operator predict the right result and recover safely from an error.
How does this chapter relate to the other translation guides?
This article focuses on Airline and @Command, @Cli, @Option, @Arguments, @Parser, HelpOption, Help.class, help hints, restrictions and generator formats. The broader translation master explains the general movement of meaning between languages; the series index leads to other framework-specific situations. These are complementary tasks rather than interchangeable tutorials.
Final checklist and further reading
The main test is simple: can a reader of the translated interface understand the task, run the intended command, interpret a failure and trust the result? With Airline, that means localizing annotation descriptions, authored help sections, explanations of restrictions, examples, friendly diagnostics and human-facing document headings, protecting registered command names, aliases, argument arity, option names, command hierarchy and numeric status codes, respecting version limitations and testing both human comprehension and executable behavior. Do not turn every English-looking token into a translated word; do not leave essential guidance in English merely because the parser itself uses stable identifiers. A well-engineered international interface makes these two responsibilities compatible.
For implementation details, consult the official technical references for the specific installed version. Cross-check examples, packaging and help behavior because libraries evolve and some documentation reflects older releases. For the larger discipline, return to the translation master; for neighboring framework chapters, use the series index. This chapter is a focused educational reference, not a substitute for compiled tests, a translator’s native-language review or a security assessment of the released program.