Go flag.FlagSet localization means making Go command-line tools understandable in different languages while retaining the exact names and values their standard-library parser accepts. People looking for Go flag package examples, FlagSet usage, translated help output, error-handling modes, Unicode arguments or multilingual CLI testing need to see where command grammar ends and human explanation begins.
The Go standard library flag package defines typed flags, parses a supplied argument slice and reports remaining arguments. FlagSet lets an application create an independent collection for a command, configure its output and define how parse errors are handled. None of that automatically translates a diagnostic, an option name or a help page. Those messages are an application responsibility, and changes to them should be tested without breaking scripts.
This guide builds a read-only public-index preview and then examines the genuine decisions behind international command-line design: defaults, Boolean syntax, positional boundaries, subcommands, Usage text, status codes, locale selection and safe release checks. It is for Go developers, maintainers, technical writers, translators and beginners who want a command they can actually understand and reproduce.
Fast answer: the contract for a multilingual Go command
- Treat every registered flag name as executable syntax, not as a phrase to translate freely.
- Localize the usage descriptions and human error summaries while leaving types and defaults truthful.
- Remember that the standard flag parser stops at the first non-flag argument.
- Use a FlagSet for each independently parsed command when a tool has subcommands.
- Define how -h, unknown names, missing values and malformed typed values behave.
- Keep stdout stable for data pipelines and send human failures to the right channel.
- Exercise each published command on an installed Go binary in at least two display languages.
A harmless Go FlagSet example
package main
import (
"flag"
"fmt"
"os"
)
func main() {
fs := flag.NewFlagSet("public-preview", flag.ContinueOnError)
locale := fs.String("locale", "en", "display locale (en, fr, ja)")
limit := fs.Int("limit", 3, "number of sample rows (1 to 20)")
if err := fs.Parse(os.Args[1:]); err != nil {
os.Exit(2)
}
if *locale != "en" && *locale != "fr" && *locale != "ja" {
fmt.Fprintln(os.Stderr, "locale must be en, fr or ja")
os.Exit(2)
}
if *limit < 1 || *limit > 20 {
fmt.Fprintln(os.Stderr, "limit must be between 1 and 20")
os.Exit(2)
}
fmt.Printf("Public preview: locale=%s limit=%d\n", *locale, *limit)
}The example illustrates typed flags and explicit application validation. It intentionally prints English because no message catalog is attached; choosing fr or ja only demonstrates a validated input. A real localized release must provide translated messages and a real locale-selection policy. It must also decide whether remaining positional arguments are allowed, because Parse itself is not a substitute for application rules.
The important distinction: typed values are not translated values
The library can store a flag’s integer, Boolean, duration or string value. It cannot infer whether a phrase in a target language accurately expresses the operation behind that value. A translator may improve the usage sentence, but doing so does not change what -limit=5 means. The application must still validate that five records is safe, supported and actually implemented.
Keep an executable invocation adjacent to its translated explanation. Give the reader a reason for each flag, show one harmless success and then deliberately show a failure. That sequence moves from understanding to evidence. It is more trustworthy than a collection of attractive help screenshots with no test of what happens after the user presses Enter.
Practical lessons for the Go standard-library flag package
NewFlagSet establishes a separate scope
flag.NewFlagSet creates a named parser with an error-handling policy. It is useful when a program has separate commands that should not share every option.
A translated help page may show an option under the wrong subcommand if documentation was assembled from a global list. The parser and the page then disagree about scope.
Keep one clear FlagSet per separately parsed command, and explain which flags are local to it. Global options, if any, need an explicit design rather than a translated promise.
Run each subcommand with its own help and with an option belonging to another command. Confirm that the expected boundary is enforced.
The name of a FlagSet
A FlagSet name is used for diagnostics and description. It does not automatically create a command dispatcher or register an executable name.
A guide can make a name appear to be a subcommand that the program never routes to. This encourages users to copy commands that fail before parsing.
Separate the program’s dispatch logic from the name supplied to NewFlagSet. Describe both layers when teaching an international audience.
Start from os.Args and trace how the chosen command reaches its own Parse call, then execute every published example.
String flags versus typed flags
String and StringVar return a string even when the text resembles a number. Int, Bool, Duration and other constructors parse their supported value types.
A translator may suggest a localized number format that the actual typed flag rejects, such as a comma decimal separator or a spelled-out number.
State the accepted literal grammar beside each flag and use runnable examples. Add localized display formatting after parsing, not in place of syntax.
Test one valid ASCII value, one culturally familiar but unsupported format and one malformed input, comparing output and status.
Pointer-based definitions
Calling fs.String returns a pointer to the flag value that is populated by Parse. Before parsing, the pointer references the registered default.
New developers sometimes read or display the value before parsing and assume the user’s chosen locale or limit has already been applied.
Define all flags, call Parse once on the intended argument slice and only then inspect user choices. Keep instructions in the same order.
Demonstrate a flag overriding its default, and confirm the printed value reflects the invocation rather than a compile-time setting.
StringVar and application state
StringVar binds an existing variable to a registered flag instead of returning a new pointer. The parser still owns option recognition, not validation of semantic choices.
A field with the name locale may look intrinsically international, but StringVar does not validate BCP 47 tags or select translation resources.
Choose between pointer and bound-variable styles for program clarity, then implement explicit supported-language checks and catalog selection.
Compare omitted and explicit locale flags, asserting the precise stored value and a separate successful catalog lookup.
Flag names are compatibility tokens
Names such as locale and limit become part of the interface. Automation, tutorials and completion examples can depend on their exact spelling.
Translating -limit to a localized word in documentation creates an unusable command unless the binary registers that new name as a flag.
Keep tokens literally in code and translate surrounding descriptions. Treat adding a genuine translated alias as a versioned feature with collision rules.
Paste commands from every translated page into an unchanged binary. Failure shows an executable mismatch, not simply an editorial typo.
Single and double hyphens
The standard flag package recognizes flag names written with one or two leading hyphens, unlike assumptions imported from some other parsers.
Technical writers may describe short and long option aliases that are not actually registered, especially when they see -locale and –locale in examples.
Explain the parser’s accepted spelling without implying automatic one-letter aliases. A separate -l works only if it is defined.
Test -locale=fr, –locale=fr and -l fr on the actual binary. Document the third only if registration exists.
Equals-style values
A text flag may be written as -locale=fr, and a separate value is generally possible for non-Boolean flags. Precise copying matters.
A line wrap or localized punctuation can turn the ASCII equals sign into another character, or separate a flag from its value incorrectly.
Use code formatting, monospace text and explicit examples. Avoid changing punctuation inside executable snippets for typographic appearance.
Copy the command from the published webpage, not from source notes, and verify that the parser receives the intended value.
Boolean flag syntax
A Boolean flag can be activated without an explicit value and may accept an attached =false or =true representation.
A common beginner expectation is that -verbose false means false. In standard flag parsing the bare Boolean can complete before the next argument, changing what follows.
Teach -verbose=false when disabling explicitly, and explain the difference between a flag and a positional word.
Compare -verbose=false and -verbose false, then inspect both the Boolean result and Args() to catch the stray positional.
Parsing stops at a positional
The standard flag parser stops processing flags when it reaches the first non-flag argument. It does not generally permute later flags around positionals.
A translated quick-start might put an input filename before -locale, implying that the later flag will still be recognized by this parser.
Place flags before positionals and state the ordering rule. If interspersed options are a requirement, choose or implement behavior consciously.
Run both orders with the same fixture and record whether -locale is a parsed option or a remaining argument.
The double-dash separator
Two hyphens on their own end flag interpretation in conventional Go flag parsing. This helps handle positional values beginning with a hyphen.
A reader may need to work with a filename like -sample.csv and assume that quoting alone prevents it being read as a flag.
Show the separator before such data when your command accepts positionals. Make the grammar visible rather than relying on unexplained punctuation.
Invoke the sample with — followed by -sample.csv and verify the name appears in Args() instead of producing an unknown-flag error.
os.Args is not a FlagSet output
os.Args includes the program name at index zero. FlagSet.Parse expects the arguments to parse, usually os.Args[1:] for a simple command.
Passing the entire slice may treat the executable path as a positional and stop option parsing prematurely, producing confusing symptoms across languages.
Explain which arguments reach Parse and how a subcommand dispatcher slices them. Keep example code consistent with the described invocation.
Print a temporary diagnostic of the received slice, run a harmless example and then remove private values from permanent logs.
ContinueOnError policy
flag.ContinueOnError returns parsing errors to the caller. The application decides whether and how to exit, and can add context.
A translated error may be printed on top of an English parser diagnostic, causing duplication or inconsistent instructions if the output path is not planned.
Choose an explicit error policy and document how a caller receives invalid-usage status. Separate parser output from application guidance.
Cause an unknown flag and inspect stderr, the returned error and the final process status, including whether the same message appears twice.
ExitOnError policy
flag.ExitOnError causes the parser to exit for failures under its documented behavior. That is convenient for small programs but limits localization control.
An application that needs to translate a technical error may never regain control to replace or contextualize the parser’s own wording.
Prefer ContinueOnError when your design requires tailored error presentation, and test all exit paths instead of assuming one mode suits every audience.
Deliberately invoke an invalid typed value and note whether code after Parse executes under the chosen policy.
PanicOnError policy
flag.PanicOnError panics on parse failures. It is an explicit programmer choice, not a user-friendly localization mechanism.
A terminal traceback can leak implementation detail and overwhelm a reader who merely mistyped an option, especially in translated support material.
Avoid this policy for ordinary public-facing recovery unless your application has a justified and tested reason. Provide actionable errors instead.
Run a synthetic invalid-option case in a development fixture and compare the result with the user experience the documentation promises.
ErrHelp and -h
A request for -h or -help can produce flag.ErrHelp if the special name is not explicitly defined, according to the standard package behavior.
A translation may promise that -h is an operational flag or a localized alias, while the parser treats it as a help request.
Define a consistent help convention; consider custom Usage output and the appropriate exit behavior. Explain if application-specific -h has been registered.
Run -h and –help with no other arguments, and inspect whether they display correct help without executing the normal task.
FlagSet.Usage customization
A FlagSet has a Usage function that can print application-specific instructions. The default usage output is not a full translated tutorial.
Changing a prose heading in the README does not change the text produced by the installed program. Users may find conflicting descriptions.
Implement a small localized Usage function based on a selected catalog. State the syntax, defaults and one runnable example in a predictable order.
Invoke help in every supported locale and compare the actual terminal output against the published help examples.
SetOutput directs diagnostics
SetOutput changes the writer used for FlagSet usage and diagnostic output. That helps a program manage what reaches stderr or a captured test buffer.
Silencing the parser without providing replacement guidance can leave an international user with a nonzero exit and no understandable explanation.
Use an explicit writer policy, then emit reviewed messages from the appropriate component. Never hide parse failures merely to make screenshots tidy.
Capture output in tests and verify that intentional failures remain visible while machine-readable stdout is not contaminated.
PrintDefaults and automatic help
PrintDefaults formats registered flags with usage strings and defaults. It saves repetitive documentation work but reflects the messages used when flags were defined.
If you translate the README but register every usage description in English, automatic help remains English despite a locale switch elsewhere.
Select translated usage strings before constructing the FlagSet, or build a deliberate localized help renderer. Keep typed defaults accurate.
Run PrintDefaults or -help after selecting each supported language and review widths, defaults, wording and terminal behavior.
Message selection before registration
In many small designs, user-facing usage text is passed to the flag constructor. The locale must therefore be known before constructing those descriptions.
Attempting to parse –locale using a FlagSet whose descriptions were already fixed in English creates a bootstrap problem for translated help.
Choose a documented bootstrap policy such as an environment setting or an early restricted locale scan, with explicit rules for conflicting values.
Request help under two locales and verify that the help text changes while the registered executable names remain identical.
Environment and command precedence
Applications may support a LANG-like environment setting as well as an explicit -locale flag. Neither source automatically wins without a clear policy.
Readers in shared terminals can receive an unexpected language if locale precedence is undocumented or if a stale environment variable is left behind.
Define a simple order such as explicit flag, supported environment preference, then safe fallback. Show the same rule in every translation.
Run a matrix with environment only, flag only, both conflicting and neither, and assert which language is selected.
Typed error strings
The standard parser can produce errors for unknown flags and malformed numeric values. Some text is produced inside the library rather than in your catalog.
A designer may promise complete localization when the underlying parser still emits English diagnostics first. Such mixed output is a product behavior, not a translator’s mistake.
Be explicit about what your code can localize. Consider handling returned errors, supplying a localized recovery sentence and preserving technical detail where useful.
Try a misspelled name and an invalid integer, then review the entire stderr output with a target-language reader.
Unexpected arguments
A successful Parse does not mean every remaining positional argument is valid. FlagSet.Args returns unconsumed strings that application code must evaluate.
A CLI that silently ignores an extra filename can give the impression that it processed more data than it did. Language-specific help can intensify that misunderstanding.
Check NArg or Args after parsing. Reject, accept or document remaining positionals based on an explicit contract.
Run with zero, one and three extra arguments. Confirm the result and the message identify exactly which values were used.
Arg and Args accessors
Args returns the remaining argument slice and Arg(i) accesses an individual remaining argument. The program must still assign meaning and validate bounds.
A translated example may reorder two positional values to match natural sentence structure, while the program continues interpreting the first as an input and second as output.
Show each positional in a named description and do not rearrange executable order in localized examples.
Invoke an example with two visibly different harmless values and compare the values the program actually receives.
Visit and VisitAll
Visit iterates flags actually set, whereas VisitAll covers registered flags. That difference is useful when distinguishing user choice from default behavior.
A diagnostic or translated configuration summary can incorrectly claim that a user explicitly requested the default simply because the flag exists.
Use Visit for audit statements about supplied flags, and VisitAll for documentation or comprehensive configuration inspection. State the distinction to readers.
Run with defaults and one explicit flag, then verify that a displayed user-choice summary does not fabricate a choice.
NFlag and missing values
NFlag reports how many flags were set; it is not a count of meaningful tasks performed, nor proof that an input file exists.
Translating an interface count as number of processed records can turn a parser statistic into a false completion claim.
Use exact language such as options supplied when displaying parser counts. Report processing outcomes from the application layer.
Compare the flag count with real synthetic processing results and ensure the two remain separate across languages.
Custom flag.Value types
The flag.Value interface allows an application to parse domain-specific values. That power also adds error cases beyond built-in strings and integers.
A custom date, duration or list parser may reject language-specific punctuation even though localized help suggests it accepts that format.
Define a documented canonical grammar, return descriptive errors and add localization only around an intentional supported input policy.
Test a valid value, a culturally familiar alternate form and an ambiguous input. Document which forms are accepted, not merely understood by a reviewer.
Duration values
Duration flags parse duration expressions using Go’s duration syntax rather than a phrase such as five minutes in arbitrary languages.
A translation that replaces 5m with a localized abbreviation may make the command invalid even though the prose is more natural.
Keep the actual duration token in code and explain it in full text. If localized duration input is required, implement a separate validated conversion.
Compare -timeout=5m with a translated word expression and verify the intended behavior in a clean build.
Subcommand dispatch
The standard flag package does not automatically create a full subcommand router. A program typically inspects a command token and invokes the matching FlagSet.
A translated guide may imply that subcommand names vary by locale, while the dispatcher only recognizes one exact spelling.
Document registered subcommand tokens and localized meanings separately. Choose whether aliases are needed as an intentional design decision.
Invoke every translated example for each command and test an unsupported subcommand to check that help points to real choices.
Command-specific help
A program with multiple FlagSets may offer distinct options for list, preview or verify. Users need help for the specific command they are using.
A single global list can accidentally imply that flags from one command work with another, particularly after translation and restructuring.
Generate or maintain help per command, including accepted positional arguments, defaults and realistic examples.
Compare list -help, preview -help and an unknown command. Ensure each message points to the correct executable route.
Aliases and collisions
Registering two flag names for one variable can create aliases, but conflicts need rules when both forms are supplied with different values.
A translated alias might collide with an existing short name or another localized name, creating silent precedence confusion.
Adopt a stable primary name and an explicit alias policy. Avoid multiplying language-specific executable tokens merely to make captions sound familiar.
Test both aliases alone and together in reverse orders. Confirm the documented conflict behavior.
Locale codes as data
A locale flag supplies a string that must be validated against supported resources. It does not translate an interface simply by changing the value.
A screenshot showing -locale=ja followed by English text can mislead readers into believing that the command is defective, rather than deliberately illustrative.
Make demonstration limitations explicit and show the catalog lookup separately. Use proper language identifiers rather than translated names as parser inputs.
Request supported, unsupported and malformed locale values and compare actual catalog loading with the expected fallback path.
Fallback and incomplete messages
International message resources can be incomplete. A fallback policy is a useful safety net but should not hide missing critical instructions.
An untranslated error after a destructive failure may be harder to understand than an untranslated nonessential heading, even if both are missing strings.
Prioritize safety and recovery messages. Report missing message identifiers during tests, and choose one consistent fallback that does not change behavior.
Remove one benign translation from a test resource and check the resulting message, status and event log without using private data.
String interpolation and escaping
Dynamic error details may contain paths, user-supplied names or quoted arguments. Translation templates must preserve the value without turning it into trusted prose.
A raw filename containing line breaks or control sequences can make a diagnostic appear to include a second command or fabricated success notice.
Use controlled formatting, visibly separate data from instruction and escape output as appropriate for terminal or HTML targets.
Test harmless names containing spaces, accents, quotes and control-like characters. Check the actual output medium for ambiguity.
Machine output stays stable
Downstream tools may parse JSON field names, CSV columns or numeric status codes. Translation of a caption must not silently change those machine contracts.
A Japanese help setting that renames the JSON key result can break an English-language script consuming it, despite every displayed word appearing fluent.
Separate a human mode from a structured output mode and version any intentional schema change. Keep automated output predictable.
Parse output from both locales using the same consumer, then compare structure and record values for identical synthetic inputs.
Unicode filenames and arguments
The invoking terminal, operating system and Go process form an end-to-end argument path. Strings can represent Unicode, but display and filesystem behavior still vary.
A web tutorial may show a correctly rendered Arabic or CJK filename while a particular terminal or filesystem cannot reproduce the operation.
Use real fixtures in supported operating environments and keep clear guidance about quoting and normalization expectations.
Exercise filenames with spaces, accented letters, combining characters and CJK symbols, recording exact arguments and file operations.
Bidirectional readability
Right-to-left help can place Latin hyphenated tokens next to Arabic or Hebrew text, causing surprising visual order in some terminals.
A reviewer may approve the translation in a browser, but a terminal may place the hyphen or equals sign where readers cannot confidently copy it.
Keep commands in isolated code blocks and check the rendering and copying behavior in the actual supported terminal.
Compare copied bytes with the registered flag name, and verify both narrow and wide terminal presentation.
Help wrapping and width
Help descriptions often grow when translated. Tabular alignment that looks neat in English may wrap poorly in French, German or CJK text.
If an option description wraps underneath the wrong flag, a beginner can assign the wrong meaning to an executable parameter.
Favor legible paragraphs and conservative alignment. Test a text-only fallback so color and spacing do not carry essential meaning.
Review help at narrow widths and with color disabled; ask a reader to identify which description belongs to which option.
Exit behavior and error honesty
A command can print a translated error and still accidentally exit with zero. Scripts and monitoring systems use exit status, not prose, to decide success.
A comforting sentence that says completed after a parse failure can mislead both humans and automated systems.
Define stable exit categories and never report successful work unless the corresponding application operation succeeded.
Capture status, stderr and stdout for help, invalid flags, missing files and good input in all supported languages.
Testing published examples
Documentation examples are an interface surface: people will copy them literally. A successful development test does not ensure the installed release matches.
A translation can keep an option that was renamed in a previous software version, making the problem appear to be the reader’s language knowledge.
Run copyable examples against clean, packaged binaries on each supported platform, not only an editor’s test harness.
Store a transcript with exact invocation, locale, expected output and return code. Rerun after any change to registered flags.
Choosing between flag and richer parsers
The standard library is practical for simple typed options and modest command trees. Rich completion systems or interspersed flags need additional design.
A long article should not imply that FlagSet magically supplies shell completions, localization catalogs or framework-wide command discovery.
Describe what the standard package really does, and compare alternative libraries only when the application’s requirements justify another dependency.
Write compatibility tests for existing names, positional order and output before migrating parsers, particularly when several languages are already documented.
Error categories for support
A usable support ticket separates parsing errors from application failures, permission denials and external service timeouts. Each category requires different next steps.
A generic translated failure message can hide which action occurred and which action never started, making troubleshooting slow and potentially unsafe.
Ask for a redacted invocation, Go version, operating system, locale, stderr and status. Do not encourage sharing credentials or private paths.
Create synthetic cases for unknown flag, invalid integer and missing input; ensure support can diagnose them without private data.
Maintaining translations after flag changes
When engineers rename or remove a flag, documentation, help catalogs and examples must change together. A multilingual site has more places to become stale.
A legacy translated screenshot can keep a removed option alive in readers’ expectations, causing avoidable support incidents.
Keep a versioned flag inventory and check every locale during release. Make deprecated names explicit when an alias still works.
Compare the release binary’s registered flags with catalog usage strings and translated examples before each publication.
A practical test matrix for a worldwide Go CLI
Build the sample command in a clean environment and record its supported Go version. Run a default invocation, one with -locale=fr, one with -limit=5 and one with both flags. For each case, observe the parsed values and the output. Because this teaching sample does not load translations, do not claim that a language code proves localization. Use a second build with actual catalogs when testing readable messages.
Add failure paths: -limit=banana, -limit=-1, an unsupported -locale, an unknown option and an unexpected positional argument. Observe the default parser’s diagnostics and any application-level response. Capture stderr separately from stdout and check process status. Try -h and -help to understand the selected error-handling mode, and verify that help never performs the application task.
Then build a Unicode matrix: a Latin accented record name, a CJK filename, a combining-mark example and a bidirectional script example. Test the terminal you actually support, including a narrow window. A screenshot of translated help is not enough; the copied command and its resulting program behavior must agree.
Frequently asked questions
Is flag.FlagSet a localization package?
No. It is a standard command-line parser; localization needs a separate source of translated descriptions and application messages.
Does the Go parser accept flags after a filename?
The standard flag package stops at the first non-flag argument, so document and test the ordering rule.
Are -locale and –locale different aliases?
The standard parser accepts one- and two-hyphen spellings of names, but a separate one-letter alias such as -l must be registered.
How do I write a Boolean false value?
Use an explicit attached form such as -verbose=false rather than assuming a following word false will be consumed.
Can I translate the name of a flag?
Only by registering and testing an alias or a changed public interface. Translating prose does not alter the parser.
What does ContinueOnError do?
It returns parse errors so the application can decide how to explain and exit; it does not provide translated messages automatically.
Does PrintDefaults generate a complete manual?
No. It formats registered flags, their usage descriptions and defaults. A full task guide still needs examples and recovery instructions.
How can I check localized output reliably?
Compare copyable commands, parsed values, stdout, stderr and exit status under at least two implemented locales in clean installations.
Official documentation and further reading
- Go standard library: flag package
- Official Go documentation
- Master Art of Translation — broader meaning principles
- Translate Like a Pro — chapter index
A trustworthy multilingual Go command is one that a person can run without guessing. The parser decides whether an invocation fits its published syntax; the application decides whether the request is valid; the language resources explain both outcomes clearly. Protect those boundaries, and international usability becomes a measurable feature rather than a marketing promise.