Translate Like a Pro | 9610 — Fish Shell argparse Localization, Flag Specs, Functions, Completions, Unicode and Help QA

Fish shell argparse localization means making command-line scripts understandable to international users without changing the options that make them work. A developer looking for fish argparse examples, multilingual help, translated fish shell errors or Unicode-safe shell functions needs more than translated labels: the parser must still identify every flag correctly, preserve arguments and give reliable feedback.

Fish offers an argparse builtin for scripts and functions. An option specification such as h/help or n/name= defines accepted syntax; the command then records parsed information in local _flag_ variables and leaves remaining arguments in $argv. The words a person reads in help, examples and validation responses can change by language, but names used as parser contracts must change only through an intentional compatibility design.

This practical fish shell localization guide follows a small sample command for previewing a public catalogue. It explains option specs, language selection, help text, validation, completion descriptions, boundary cases, error paths and release tests. You can follow the concepts without being a specialist in translation or terminal tooling.

The essentials: what stays stable when a command speaks another language

Preserve every published command token, option type, input value contract and status code unless a new interface is deliberately designed.
Translate complete reader-facing explanations, help messages, examples and recovery instructions, not parser syntax by accident.
Demonstrate the real command before making claims about its localization.
Test both successful execution and missing, invalid, unusual and Unicode input.
Keep human display language distinct from machine-readable output and data schemas.
Use version-specific official documentation and verify a clean installation.
Make a failed command understandable enough that a reader can correct the next attempt.

A working starting point

Begin with a small example rather than an elaborate production system. A tiny, observable command reveals its contract: what a caller types, what the program parses, what is returned and what an error means. The following snippet is deliberately limited to harmless public sample data, so the reader can concentrate on argument handling instead of installing services or handling secrets.

function catalogue-preview
    argparse 'h/help' 'l/locale=' 'n/number=!_validate_int --min 1 --max 50' -- $argv
    or return 2

    if set -q _flag_help
        echo 'Usage: catalogue-preview [--locale CODE] [--number N]'
        return 0
    end

    set -l count 10
    if set -q _flag_number
        set count $_flag_number
    end
    printf 'Previewing %s public items\n' $count
end

The sample deliberately keeps –help, –locale and –number as stable input syntax. The English messages are placeholders for a message-selection layer, not an assertion that fish automatically translates them. Use your real supported locales and treat the count as a number rather than as translated text.

Understand the actual parser and its boundaries

What fish argparse actually parses

The parser reads option specifications before the required — separator, then scans the command arguments. It is not a translation engine; it establishes a contract between a script and its caller.

How to use it. Sketch the contract on paper: accepted short flags, long flags, required values, repeatability and positional arguments. Only after that draw a separate column for visible descriptions and guidance. Begin by asking what a person will actually type, what they expect the command to do, and what evidence they will see. A good explanation answers all three questions in the same order, which makes a technical rule approachable without weakening it.

Where the mistake appears. Translating –locale into an unfamiliar flag silently breaks stored terminal commands and user documentation. A localized sentence must not become an accidental rename of the program interface. In a multilingual guide, a mismatch between a sentence and a runnable command is especially difficult for beginners: they cannot tell whether they misunderstood the language or whether the example is wrong. The guide must remove that uncertainty.

Check it rather than assuming. Call the function with –help and with an unknown flag. Confirm that success, parse failure and remaining positional values follow the parser rather than the natural-language sentence. Record the input, expected behavior, actual output and result status. Repeat the same case with another supported display language. If the underlying behavior changes, investigate the program contract before signing off on the translation. If only the visible explanation changes, judge that explanation for clarity, completeness and cultural appropriateness.

The reader’s final question should be practical: What do I type, what happens if I am right, and how do I recover if I am wrong? A strong international command guide answers that question in a calm sequence. It makes the ordinary case easy to follow, identifies a meaningful edge case and names the evidence that distinguishes a successful run from a plausible-looking mistake.

The mandatory double-dash boundary

In an argparse invocation, the first literal — separates the builtin’s own options and option specifications from the arguments that the script wants to parse.

Try the task. Show readers the exact placement using a copyable example with ‘– $argv’. Explain that a second — supplied by the caller can have its own meaning in the parsed argument stream. Follow the complete path from reading the instruction to entering the invocation. Notice that the translator’s job is to preserve this path, not simply to substitute words while hoping the program understands them.

What to avoid. Removing the first separator because it looks like typographical punctuation makes the invocation ambiguous. It may cause a user’s argument to be interpreted as a parser configuration option. This is why a translated example must be tried with a real interpreter, not approved solely as a polished sentence. Users deserve instructions that produce the promised result in their environment.

Check it rather than assuming. Test empty input, one positional argument, a value beginning with a hyphen and a caller-supplied –. Write expected remaining arguments next to actual results. Record the input, expected behavior, actual output and result status. Repeat the same case with another supported display language. If the underlying behavior changes, investigate the program contract before signing off on the translation. If only the visible explanation changes, judge that explanation for clarity, completeness and cultural appropriateness.

Short and long options are an interface

The h/help form recognizes both -h and –help, and an option specification may have only one of those forms. Users read a description but invoke a literal token.

A practical approach. Explain short forms in a syntax table and keep them next to their long forms. Translate the purpose of the flag, such as showing usage, rather than translating the token. Put the interface rule beside a short example in the target language. Readers should be able to distinguish a literal command token, a replaceable sample value and a helpful description without studying the implementation first.

The failure mode. A description that says a short form exists when the parser accepts only a long form creates an immediately visible usability failure. This is especially damaging in copied tutorials. Even when the original English page is correct, an international reader can be misled by a slightly different implication. Treat that difference as a real bug if it changes the user’s next action.

Check it rather than assuming. Probe each advertised spelling independently and compare the terminal’s response with the help page. Track deliberate aliases as tested interface features. Record the input, expected behavior, actual output and result status. Repeat the same case with another supported display language. If the underlying behavior changes, investigate the program contract before signing off on the translation. If only the visible explanation changes, judge that explanation for clarity, completeness and cultural appropriateness.

Required values and equal signs

The n/name= pattern requires a value. The parser puts the chosen value in the corresponding _flag_ variable; the translation should make the requirement unmistakable.

In a real guide. Write examples for both common invocation forms, including –name followed by a value. Say plainly whether an empty value is allowed by your application. Explain the decision before giving a list of exceptions. A simple operational promise is more useful than a long, vague passage that never tells the reader what will happen.

A common misunderstanding. The reader may translate the metavar NAME as if it were a literal word to type. A sample command then fails while the example appears linguistically polished. The important distinction is between prose that can be adapted and syntax that the program recognizes. Once that distinction is visible, the rest of the localization choices become much easier to review.

Check it rather than assuming. Test a missing argument, a quoted multiword value and a non-Latin value. Verify that help distinguishes a placeholder from a fixed enum. Record the input, expected behavior, actual output and result status. Repeat the same case with another supported display language. If the underlying behavior changes, investigate the program contract before signing off on the translation. If only the visible explanation changes, judge that explanation for clarity, completeness and cultural appropriateness.

Optional values are a different promise

The =? syntax accepts an optional value, but an optional argument normally has to be attached to its option when supplied. The following word may otherwise become positional.

How to use it. Contrast –colour=always with –colour always in a harmless example, explaining exactly which token belongs to the option in the tested fish version. Begin by asking what a person will actually type, what they expect the command to do, and what evidence they will see. A good explanation answers all three questions in the same order, which makes a technical rule approachable without weakening it.

Where the mistake appears. A translated help sentence saying that any following word is used as the optional value overpromises the grammar. It can unexpectedly consume a filename or search term. In a multilingual guide, a mismatch between a sentence and a runnable command is especially difficult for beginners: they cannot tell whether they misunderstood the language or whether the example is wrong. The guide must remove that uncertainty.

Check it rather than assuming. Check the attached and detached forms, a positional word after the option, and a zero-argument invocation. Keep the published example aligned with observed behavior. Record the input, expected behavior, actual output and result status. Repeat the same case with another supported display language. If the underlying behavior changes, investigate the program contract before signing off on the translation. If only the visible explanation changes, judge that explanation for clarity, completeness and cultural appropriateness.

Make the documented interface understandable

Repeated values and ordering

The =+ option specification collects repeated required values. Some other specifications retain only the final occurrence, which changes the meaning of a repeated command.

Try the task. Describe a command taking repeated –tag values, then explain whether order matters for its application. Keep example tags recognizable as sample data, not translated protocol values. Follow the complete path from reading the instruction to entering the invocation. Notice that the translator’s job is to preserve this path, not simply to substitute words while hoping the program understands them.

What to avoid. A careless localization can imply one tag is accepted when several are, or can describe a last-one-wins flag as additive. Those are behavioral errors, not cosmetic issues. This is why a translated example must be tried with a real interpreter, not approved solely as a polished sentence. Users deserve instructions that produce the promised result in their environment.

Check it rather than assuming. Run a command with two values, reverse their order and inspect the resulting _flag_ list. Include repeated flags in regression tests. Record the input, expected behavior, actual output and result status. Repeat the same case with another supported display language. If the underlying behavior changes, investigate the program contract before signing off on the translation. If only the visible explanation changes, judge that explanation for clarity, completeness and cultural appropriateness.

Boolean flags and presence

A flag without a value is a boolean presence signal. In fish, set -q can check whether a _flag_ variable was set by the parser.

A practical approach. Teach the reader to check set -q _flag_help rather than compare it with a translated word such as yes, true or help. The value is not a language preference. Put the interface rule beside a short example in the target language. Readers should be able to distinguish a literal command token, a replaceable sample value and a helpful description without studying the implementation first.

The failure mode. Translating a boolean flag into a text comparison makes the command depend on a string unrelated to the parser’s documented presence semantics. Even when the original English page is correct, an international reader can be misled by a slightly different implication. Treat that difference as a real bug if it changes the user’s next action.

Check it rather than assuming. Check absent and present forms, repeated appearances and long-versus-short aliases. Ensure the output message follows the selected language without changing the branch decision. Record the input, expected behavior, actual output and result status. Repeat the same case with another supported display language. If the underlying behavior changes, investigate the program contract before signing off on the translation. If only the visible explanation changes, judge that explanation for clarity, completeness and cultural appropriateness.

Hyphens become underscores in variables

Fish normalizes characters that are not valid in variable names when constructing _flag_ variables. A long flag like –dry-run is represented by a usable variable name.

In a real guide. Show the written option and the _flag_dry_run variable beside each other, then add a note that documentation must distinguish what callers type from what function authors read. Explain the decision before giving a list of exceptions. A simple operational promise is more useful than a long, vague passage that never tells the reader what will happen.

A common misunderstanding. A guide that tells a caller to type underscores instead of the advertised hyphenized option may be confusing or incorrect even though the script variable uses underscores. The important distinction is between prose that can be adapted and syntax that the program recognizes. Once that distinction is visible, the rest of the localization choices become much easier to review.

Check it rather than assuming. Test the displayed command literally. If the help text and script internals use different spellings, label them as public syntax and implementation variable. Record the input, expected behavior, actual output and result status. Repeat the same case with another supported display language. If the underlying behavior changes, investigate the program contract before signing off on the translation. If only the visible explanation changes, judge that explanation for clarity, completeness and cultural appropriateness.

Mutually exclusive flags

The -x or –exclusive setting can declare combinations that are not allowed together. Translating the explanation must preserve that logical relationship.

How to use it. Give a concrete example such as –json and –table output. Explain that the user chooses exactly one when both output modes conflict, rather than implying they can combine. Begin by asking what a person will actually type, what they expect the command to do, and what evidence they will see. A good explanation answers all three questions in the same order, which makes a technical rule approachable without weakening it.

Where the mistake appears. A softer translation such as ‘prefer one mode’ is unsafe if supplying both is a hard error. Politeness must not erase a constraint the parser enforces. In a multilingual guide, a mismatch between a sentence and a runnable command is especially difficult for beginners: they cannot tell whether they misunderstood the language or whether the example is wrong. The guide must remove that uncertainty.

Check it rather than assuming. Submit each valid flag alone and both together. Record the failure status and verify that the localized guidance states the real resolution. Record the input, expected behavior, actual output and result status. Repeat the same case with another supported display language. If the underlying behavior changes, investigate the program contract before signing off on the translation. If only the visible explanation changes, judge that explanation for clarity, completeness and cultural appropriateness.

Minimum and maximum positional counts

Options for minimum and maximum non-option arguments let the parser check the number of remaining values. Cardinality is part of the interface, not a prose style choice.

Try the task. State whether the command expects zero, one or several path-like arguments. Use numbered examples with ordinary text rather than dense notation when teaching beginners. Follow the complete path from reading the instruction to entering the invocation. Notice that the translator’s job is to preserve this path, not simply to substitute words while hoping the program understands them.

What to avoid. A translator may turn ‘at least one item’ into ‘one item’ and unintentionally describe a stricter command than the shipped code. This is why a translated example must be tried with a real interpreter, not approved solely as a polished sentence. Users deserve instructions that produce the promised result in their environment.

Check it rather than assuming. Test zero, one and multiple positionals and an excess beyond the documented maximum. Messages should identify what the user can do next. Record the input, expected behavior, actual output and result status. Repeat the same case with another supported display language. If the underlying behavior changes, investigate the program contract before signing off on the translation. If only the visible explanation changes, judge that explanation for clarity, completeness and cultural appropriateness.

Handle failure, language and international data

Validating integer flag values

Fish argparse supports validation with an exclamation-mark validator specification; the bundled _validate_int helper can check integers and ranges.

A practical approach. Use a bounded example such as a public preview count of 1 to 50. Translate the explanation, but keep the numeric boundaries and mathematical meaning identical. Put the interface rule beside a short example in the target language. Readers should be able to distinguish a literal command token, a replaceable sample value and a helpful description without studying the implementation first.

The failure mode. Locale-specific digits, commas and signs may be understood differently by humans, while the parser or validator still accepts a particular lexical form. Do not claim universal numeral acceptance. Even when the original English page is correct, an international reader can be misled by a slightly different implication. Treat that difference as a real bug if it changes the user’s next action.

Check it rather than assuming. Try zero, the maximum, one beyond the maximum, negative input, and a non-Latin numeral. State precisely what the supported implementation accepts. Record the input, expected behavior, actual output and result status. Repeat the same case with another supported display language. If the underlying behavior changes, investigate the program contract before signing off on the translation. If only the visible explanation changes, judge that explanation for clarity, completeness and cultural appropriateness.

Validation error output versus stderr

The validation hook expects its own diagnostic text via standard output, while argparse can report a parsing failure on standard error. These are different levels of output.

In a real guide. Document where a validation function should write its explanatory message and where the final command’s failure appears. Keep a simple terminal transcript showing both. Explain the decision before giving a list of exceptions. A simple operational promise is more useful than a long, vague passage that never tells the reader what will happen.

A common misunderstanding. Moving every string to stderr without checking the validator protocol may make diagnostics disappear or produce an awkward wrapper error. The important distinction is between prose that can be adapted and syntax that the program recognizes. Once that distinction is visible, the rest of the localization choices become much easier to review.

Check it rather than assuming. Capture stdout, stderr and exit status separately. Check that the person sees the reason for rejection and not merely a generic failure code. Record the input, expected behavior, actual output and result status. Repeat the same case with another supported display language. If the underlying behavior changes, investigate the program contract before signing off on the translation. If only the visible explanation changes, judge that explanation for clarity, completeness and cultural appropriateness.

Ignored unknown options

The –ignore-unknown mode can leave unrecognized options for later handling. It is useful for wrappers but has limitations around option groups.

How to use it. Use a wrapper-command example where one function handles global flags and another downstream command handles subcommand-specific flags. Explain the boundary explicitly. Begin by asking what a person will actually type, what they expect the command to do, and what evidence they will see. A good explanation answers all three questions in the same order, which makes a technical rule approachable without weakening it.

Where the mistake appears. A translated guide that promises every unknown flag will be safely passed through overstates the behavior of combined short options and value-taking tokens. In a multilingual guide, a mismatch between a sentence and a runnable command is especially difficult for beginners: they cannot tell whether they misunderstood the language or whether the example is wrong. The guide must remove that uncertainty.

Check it rather than assuming. Test an unknown long flag, mixed short-option group and a value attached to an unknown option. Inspect the exact $argv passed forward. Record the input, expected behavior, actual output and result status. Repeat the same case with another supported display language. If the underlying behavior changes, investigate the program contract before signing off on the translation. If only the visible explanation changes, judge that explanation for clarity, completeness and cultural appropriateness.

Stopping at the first non-option

With –stop-nonopt, scanning stops at the first non-option argument. This matters when a command has subcommands with their own flags.

Try the task. Show a two-stage example where the root command parses only its own options and lets a named subcommand parse the remainder. Follow the complete path from reading the instruction to entering the invocation. Notice that the translator’s job is to preserve this path, not simply to substitute words while hoping the program understands them.

What to avoid. A sentence that presents all flags as freely movable may be false when parsing intentionally stops. The consequence is a syntax bug in translated examples. This is why a translated example must be tried with a real interpreter, not approved solely as a polished sentence. Users deserve instructions that produce the promised result in their environment.

Check it rather than assuming. Test a root flag before and after the subcommand name. Document which position the implementation supports. Record the input, expected behavior, actual output and result status. Repeat the same case with another supported display language. If the underlying behavior changes, investigate the program contract before signing off on the translation. If only the visible explanation changes, judge that explanation for clarity, completeness and cultural appropriateness.

Function help and message selection

A fish function can print its own usage text when the –help flag is present. The selected locale should control the words, not the parser’s structural variables.

A practical approach. Store complete messages by stable identifiers or keep a small reviewed language table. Translate full instructions, including what an option changes and what it never changes. Put the interface rule beside a short example in the target language. Readers should be able to distinguish a literal command token, a replaceable sample value and a helpful description without studying the implementation first.

The failure mode. Concatenating fragments can produce broken word order in languages that do not follow English grammar. Translating only a keyword rarely repairs the full message. Even when the original English page is correct, an international reader can be misled by a slightly different implication. Treat that difference as a real bug if it changes the user’s next action.

Check it rather than assuming. Switch between two test locales with the same arguments. Confirm that command behavior remains identical and only reader-facing language changes. Record the input, expected behavior, actual output and result status. Repeat the same case with another supported display language. If the underlying behavior changes, investigate the program contract before signing off on the translation. If only the visible explanation changes, judge that explanation for clarity, completeness and cultural appropriateness.

Test, maintain and release a trustworthy command

Completion descriptions are separate content

Fish’s completion system can show suggestions and descriptions while the user types. A working parser does not guarantee that completion descriptions have been localized.

In a real guide. Audit completion scripts and their explanatory strings as a separate interface surface. Make sure completions never substitute translated prose for actual option tokens. Explain the decision before giving a list of exceptions. A simple operational promise is more useful than a long, vague passage that never tells the reader what will happen.

A common misunderstanding. Users can receive polished –help text but still see untranslated or misleading hints during tab completion. This is a quality gap visible before execution. The important distinction is between prose that can be adapted and syntax that the program recognizes. Once that distinction is visible, the rest of the localization choices become much easier to review.

Check it rather than assuming. Exercise completion in a clean shell session for each supported locale, covering both long options and values with spaces or Unicode characters. Record the input, expected behavior, actual output and result status. Repeat the same case with another supported display language. If the underlying behavior changes, investigate the program contract before signing off on the translation. If only the visible explanation changes, judge that explanation for clarity, completeness and cultural appropriateness.

Unicode paths and arguments

Fish handles strings, but the program called by the shell may have its own encoding constraints. Non-Latin text should travel as data, not be treated as a translated command name.

How to use it. Use safe sample names in several scripts and a filename with spaces. Show quoting and the exact point where the argument is passed to another executable. Begin by asking what a person will actually type, what they expect the command to do, and what evidence they will see. A good explanation answers all three questions in the same order, which makes a technical rule approachable without weakening it.

Where the mistake appears. A sample may look correct when echoed but fail at an external command boundary, a filesystem normalization difference or an unquoted expansion. In a multilingual guide, a mismatch between a sentence and a runnable command is especially difficult for beginners: they cannot tell whether they misunderstood the language or whether the example is wrong. The guide must remove that uncertainty.

Check it rather than assuming. Test actual file handling and round trips, not just display. Compare byte-sensitive identifiers with the received values before declaring success. Record the input, expected behavior, actual output and result status. Repeat the same case with another supported display language. If the underlying behavior changes, investigate the program contract before signing off on the translation. If only the visible explanation changes, judge that explanation for clarity, completeness and cultural appropriateness.

Locale preference and fallback

A user can request a language explicitly or inherit environment preferences, but the program should define a predictable fallback if a catalog entry is missing.

Try the task. Document precedence between –locale, environment settings and a default language. Choose one behavior, state it and verify it rather than promise every fish locale setting is honored automatically. Follow the complete path from reading the instruction to entering the invocation. Notice that the translator’s job is to preserve this path, not simply to substitute words while hoping the program understands them.

What to avoid. An incomplete language pack may produce a mixture of target-language headings and English error details. That is confusing in a crisis or support workflow. This is why a translated example must be tried with a real interpreter, not approved solely as a polished sentence. Users deserve instructions that produce the promised result in their environment.

Check it rather than assuming. Remove one noncritical translation from a test catalog. Check fallback, logging and help visibility without introducing broken command execution. Record the input, expected behavior, actual output and result status. Repeat the same case with another supported display language. If the underlying behavior changes, investigate the program contract before signing off on the translation. If only the visible explanation changes, judge that explanation for clarity, completeness and cultural appropriateness.

Version-specific fish behavior

Builtins evolve. Current fish documentation should be checked against the versions you actually ship, particularly optional values, option specs and argument preservation.

A practical approach. Name the minimum tested version in release notes and run the examples in that version. Treat novel features as version requirements rather than universal facts. Put the interface rule beside a short example in the target language. Readers should be able to distinguish a literal command token, a replaceable sample value and a helpful description without studying the implementation first.

The failure mode. Copying a newer manual’s example into an older installed fish can create a syntax error that looks like a translation bug. Even when the original English page is correct, an international reader can be misled by a slightly different implication. Treat that difference as a real bug if it changes the user’s next action.

Check it rather than assuming. Build a small version matrix and rerun the help, validation and completion suite. Record observed differences with actionable notes. Record the input, expected behavior, actual output and result status. Repeat the same case with another supported display language. If the underlying behavior changes, investigate the program contract before signing off on the translation. If only the visible explanation changes, judge that explanation for clarity, completeness and cultural appropriateness.

Release sign-off for a multilingual function

A successful localization release requires both readable copy and consistent command semantics. Users should not have to discover contradictory rules by trial and error.

In a real guide. Keep test transcripts, a translation review sheet, command contract and a minimal set of runnable examples in the release packet. Review failures with an actual user task. Explain the decision before giving a list of exceptions. A simple operational promise is more useful than a long, vague passage that never tells the reader what will happen.

A common misunderstanding. Approving prose alone misses flag spellings, option cardinality, exit status and shell-specific edge cases. Approving code alone misses instructions nobody can understand. The important distinction is between prose that can be adapted and syntax that the program recognizes. Once that distinction is visible, the rest of the localization choices become much easier to review.

Check it rather than assuming. Install the package fresh, run each documented command, capture terminal output and obtain a bilingual review of the visible language before publishing. Record the input, expected behavior, actual output and result status. Repeat the same case with another supported display language. If the underlying behavior changes, investigate the program contract before signing off on the translation. If only the visible explanation changes, judge that explanation for clarity, completeness and cultural appropriateness.

Walkthrough: a small international release from first draft to sign-off

Stage 1: Define the promise

A volunteer archive team distributes a fish command to preview a list of public records in three languages. They begin with a short functional contract: –help prints instructions, –locale selects a reviewed message set and –number controls a bounded count. They do not promise that fish translates these words automatically. An option table records which inputs are accepted and which strings appear in help.

This stage deserves its own evidence. Keep a runnable example and the exact user-facing message together. Ask someone unfamiliar with the code to explain what they would try next; then compare that answer with the supported behavior. The objective is not to make every term sound technical, but to make the relationship between the words and the command visible. When a reader can predict the result correctly, the documentation is doing its educational job.

Stage 2: Observe a mismatch

The first translation draft is fluent but uses an invented translated flag in its examples. One tester copies the command and receives an unknown-option error. The team fixes the example rather than modifying the parser to match the mistaken copy. This preserves existing shell scripts and makes the correction independently verifiable.

Stage 3: Repair the failure path

Next, the team checks the argument boundary. A preview label contains spaces and non-Latin characters. Rather than test only the echo output, they inspect the value arriving at the sample program. They add a test for both a missing number and a number outside the allowed range and confirm that rejected inputs produce a useful message.

Stage 4: Verify the shipped experience

Finally, reviewers launch a clean fish session with completion enabled, switch between supported locales and compare help, completion hints, validation and exit statuses. The command succeeds only when the same actions work in every supported language. The language may change; the command’s meaning must not.

A four-week practice plan for careful translation and CLI documentation

Week 1 — map the command

Write down command names, flags, positional values, types, defaults, available locales, ordinary output and error statuses. Run the source-language help examples. Keep an evidence column for every claim in the public guide. Prioritize a tiny working demonstration over a complicated setup. A clean contract prevents later discussions about vocabulary from hiding a programming mismatch.

Week 2 — translate the reader’s decisions

Translate full meanings: what the command is for, why a value is required, and how to fix a rejected input. Keep the original executable tokens beside their explanations. Check that numerical boundaries, warnings, exceptions and promises of optional behavior are unchanged. Ask a bilingual reviewer to follow the published example without seeing the source code first.

Week 3 — stress the input boundaries

Try missing values, invalid flags, repeated options where relevant, unusual punctuation, non-Latin data, paths with spaces and conflicting instructions. Capture output channels and status separately. Inspect any machine-readable result rather than relying solely on the way the terminal prints it. Every failing test should lead to a correction in either the software, the example or the explanation.

Week 4 — package, teach and review

Run the full test matrix from a clean installation and the oldest supported runtime. Compare language variants side by side. Fix mixed-language or incomplete fallback messages, then review the guide for a sensible reading order: quick answer, working example, deeper reasoning, troubleshooting and further reading. A successful release leaves both beginners and experts able to verify what it claims.

Questions readers commonly ask

Does fish argparse translate errors for me?

No. argparse handles option parsing and reports parser diagnostics. A script needs an explicit plan for its own help and application messages, and not every builtin diagnostic is under the script author’s control. The reliable way to decide is to compare the documented contract with a test on the version actually distributed. Keep syntax examples copyable, and treat a message that changes the reader’s intended action as a correction priority rather than a stylistic preference.

Should I translate –help?

Usually keep the documented option token stable. You can translate the label explaining what –help does and add aliases only after a deliberate compatibility decision and testing. The reliable way to decide is to compare the documented contract with a test on the version actually distributed. Keep syntax examples copyable, and treat a message that changes the reader’s intended action as a correction priority rather than a stylistic preference.

Why is the first — compulsory?

It separates argparse’s option specifications from the caller’s arguments. Without it the builtin cannot reliably know where its configuration ends. The reliable way to decide is to compare the documented contract with a test on the version actually distributed. Keep syntax examples copyable, and treat a message that changes the reader’s intended action as a correction priority rather than a stylistic preference.

What is _flag_name?

It is a local parser-created variable representing a recognized option. It is not a translated display message and should be treated as part of the program’s implementation contract. The reliable way to decide is to compare the documented contract with a test on the version actually distributed. Keep syntax examples copyable, and treat a message that changes the reader’s intended action as a correction priority rather than a stylistic preference.

Can a single flag be repeated?

It depends on the option specification. Some collect repeated values while others keep one value; document the actual rule before producing examples. The reliable way to decide is to compare the documented contract with a test on the version actually distributed. Keep syntax examples copyable, and treat a message that changes the reader’s intended action as a correction priority rather than a stylistic preference.

How do I test Unicode?

Use real non-Latin input through the complete command, including any external tools, filenames and completion paths. Display-only tests are not sufficient. The reliable way to decide is to compare the documented contract with a test on the version actually distributed. Keep syntax examples copyable, and treat a message that changes the reader’s intended action as a correction priority rather than a stylistic preference.

What belongs in translated completion descriptions?

Human-facing explanations of choices and options. The actual option tokens and machine-readable values should continue to match the parser. The reliable way to decide is to compare the documented contract with a test on the version actually distributed. Keep syntax examples copyable, and treat a message that changes the reader’s intended action as a correction priority rather than a stylistic preference.

What happens if a requested language is missing?

Choose and document a fallback language. Test incomplete catalogs so users see a coherent response rather than an unexplained blank or mixed output. The reliable way to decide is to compare the documented contract with a test on the version actually distributed. Keep syntax examples copyable, and treat a message that changes the reader’s intended action as a correction priority rather than a stylistic preference.

Release checklist: what to verify before calling a translation complete

A first-time reader can understand the command’s purpose in the opening paragraphs.
The help text distinguishes literal syntax from illustrative user data.
Every code example runs without secret accounts or private services.
All advertised options and positionals match the parser, including defaults.
Missing and malformed input produce a recoverable explanation.
The displayed translation does not change program status or machine schemas.
Unicode content survives the complete execution path.
Locale selection and catalog fallback follow documented rules.
The official runtime documentation matches the supported version.
A clean installation produces the shown results, not merely a developer environment.
A bilingual review covers full messages with real sample values.
Human language and parser syntax are never confused.
Screenshots and help examples do not promise unimplemented aliases.
Errors and success are distinguished by observable behavior.
Source references remain available for readers who want more detail.

Where to read next

Readers who want the broader principles of meaning, terminology, audience, accuracy and quality assurance can continue with Master Art of Translation: The Complete System for Moving Meaning Between Languages. The Translate Like a Pro series index connects focused software-localization guides without replacing the larger introduction.

Official documentation

fish argparse documentation — use the reference for exact grammar and version-specific behavior.
fish shell documentation — use the reference for exact grammar and version-specific behavior.

The principle to remember

People should not have to learn a programming language merely to understand a simple command, nor should they have to guess whether a translated sentence has quietly altered its meaning. Good localization makes the tool approachable while leaving its tested contract intact. Begin with an actual use case, keep the runnable example beside the explanation, and end by checking the failure paths as carefully as the happy path. That is how a small multilingual command becomes dependable for a worldwide audience.