Clojure babashka.cli localization is the practical task of making command-line scripts understandable across languages while keeping their option specifications and dispatch rules accurate. People searching for babashka.cli parse-opts examples, Clojure CLI option specs, translated command help, :coerce and :validate errors, subcommand dispatch or Unicode terminal testing need an explanation that separates program behavior from human-facing wording. This guide teaches that separation and shows how to verify what users actually type.
Consider an international library that uses a small Clojure script to inspect catalogue files in several languages. A librarian may receive a Japanese filename, choose an EDN or JSON output and need a help message in Spanish. The same invocation passes through the shell, the babashka runtime, the library’s parser and the script’s own work. Good instructions tell a reader which layer is responsible for each choice and what happens if the choice is wrong.
The official babashka.cli README and API reference document options expressed as a :spec map, coercion, aliases, validation, defaults, formatting and longest-match command dispatch. None of these features means every visible string is automatically translated. The examples below are educational and read-only; whenever a particular installation or version matters, verify against its actual build. The goal is not to memorize keywords but to make technical instructions accurate enough to follow.
Quick answer: option keys are not translation strings
- Identify the exact :spec and any nested :cmd dispatch table.
- Treat :desc and similar explanation fields as translatable text, not new option names.
- Keep aliases, coercions, validation and required options consistent with examples.
- Test valid inputs, missing options, invalid values and unknown names.
- Inspect leftover arguments and dispatch route, not just a help screenshot.
- Translate recovery instructions using structured error causes.
- Test non-Latin strings and right-to-left terminal output separately.
- Ship multilingual examples only after a target-language reader completes a safe task.
Small read-only example: parse the option spec before adding an application
(require '[babashka.cli :as cli])
(def spec
{:language {:coerce :string :default "en" :alias :l
:desc "Language tag for messages"}
:preview {:coerce :boolean
:desc "Print a preview without modifying files"}
:format {:coerce :keyword :default :edn
:desc "Output format keyword"}})
(prn (cli/parse-opts ["--language" "ja" "--preview" "--format" "edn"]
{:spec spec}))
;; A parsing demonstration only: no translation catalog, files or network.The result of parsing contains values for language, preview and format, but the demonstration does not actually load a language catalog, convert a file or save data. That difference matters. If a tutorial implies that the presence of :language automatically activates translations, it teaches a false connection. The application must separately validate supported language identifiers and select appropriate resources. A useful first exercise is to change a value, print the returned map and compare it with the documented outcome.
How the command travels from a terminal to a real action
The shell first divides the command into arguments. The bb launcher or JVM process then exposes those strings to the script, commonly through *command-line-args*. The library interprets the argument list according to a spec or dispatch table. The handler finally decides whether to preview, convert, save or reject the request. Translating the visible words is only one part of this chain. A broken command example may fail before the library sees it, while a valid parsed map may still fail a business rule.
Readers benefit from a stable order of explanation: the task, the exact command, the meaning of its parameters, its expected result and its recoverable errors. An expert API reference and a beginner guide serve different moments. This article links those moments so a learner can start with one safe command and then investigate the exceptions when needed.
Forty technical checkpoints for multilingual babashka.cli
1. The library’s role
babashka.cli parses option maps and can dispatch commands; translation is supplied by the application around those facilities. A multilingual data-preservation script can parse Japanese paths but still need its own Japanese diagnostics. The useful distinction is between what a string means to the human reader and what the runtime treats as data. A translation should improve the former without silently changing the latter.
A translator can wrongly treat a spec description as an automatically translated user interface. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Compare the CLI namespace API with the visible messages of your particular script. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
Keep a separate catalog of natural-language strings and leave functional option keys predictable. A verified example is more persuasive than a broad claim of language support. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
2. The execution environment
babashka is a fast Clojure scripting runtime, while babashka.cli is the CLI library also usable in Clojure contexts. Readers need to know whether they are running a script or a library function from a REPL. Imagine a colleague copying the example from a phone screen into a terminal. An overlooked punctuation or spacing difference could change the program’s interpretation.
Some examples assume bb invocation while others run under a JVM project with different dependency arrangements. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Run bb –version and inspect the project’s dependencies before teaching installation. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
State the exact invocation environment and how its shell forwards arguments. Make the instruction resilient to copying, narrow displays and unfamiliar terminology. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
3. parse-opts versus parse-args
parse-opts returns parsed option values, while parse-args offers richer argument information and metadata. A task that needs leftover operands must not pretend they are ordinary option keys. This issue usually becomes visible when something goes wrong, not when the happy path succeeds. Therefore the investigation needs at least one controlled failure.
An explanation may refer to a returned map shape that belongs to the other function. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Run both APIs with the same synthetic argv and examine the documented return structures. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
Use the function name alongside the shape of its result in every worked example. The repair must identify the mistaken assumption and the next valid action. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
4. Option spec maps
A :spec map names accepted options and carries settings including :coerce, :alias and :desc. A developer can offer French help while maintaining –format as the canonical token. Ask whether the library, the application or the shell owns the behavior. That question often locates the cause before any translated text is changed.
A translated option description does not change the accepted option keyword. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Test –format edn against the actual map declaration rather than the translated page title. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
Keep stable programmatic keys and translate only visible explanation unless implementing a designed migration. A precise boundary avoids promising that every runtime behaves in exactly the same way. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
5. The :desc field
The :desc string explains a particular option when rendering formatted help. The reader should know whether –preview only prints or actually writes a report. Documentation is a testable part of the interface. A command shown in an article should behave like the application described beside it.
A description saying delete may misrepresent a flag that only previews a deletion plan. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Compare displayed text with the action reached by the parsed value. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
Use an action verb, expected input, side effect and boundary where relevant. If reality and prose disagree, repair both together and repeat the test. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
6. The :ref field
The :ref marker labels a value in generated option descriptions. A beginner should not type angle brackets around a placeholder unless the tool truly expects them. The useful distinction is between what a string means to the human reader and what the runtime treats as data. A translation should improve the former without silently changing the latter.
A translated marker can look like literal syntax when its placeholder role is unclear. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Show –format edn beside –format <format> in an explicitly annotated example. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
Choose a short placeholder and explain accepted choices in a sentence. A verified example is more persuasive than a broad claim of language support. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
7. Short aliases
An option may declare an alias such as :alias :l for –language. A one-letter shortcut is not a word to translate automatically. Imagine a colleague copying the example from a phone screen into a terminal. An overlooked punctuation or spacing difference could change the program’s interpretation.
Translators sometimes invent a letter corresponding to a translated noun without registering it. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Run the short and long spelling and compare the parsed map. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
Treat the alias as an interface decision reviewed for collisions and stability. Make the instruction resilient to copying, narrow displays and unfamiliar terminology. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
8. Coercion to integers
The :coerce setting can turn command-line text into numeric types such as :long. Users should know whether 1,000 means a thousands separator or produces a failure. This issue usually becomes visible when something goes wrong, not when the happy path succeeds. Therefore the investigation needs at least one controlled failure.
A message may display a local decimal representation that the coercer does not accept. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Test a valid integer, a negative integer and an invalid mixed string. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
Distinguish accepted input syntax from locale-specific display of numbers. The repair must identify the mistaken assumption and the next valid action. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
9. Coercion to keywords
Using :coerce :keyword changes strings into Clojure keywords. The international label for a format need not equal the stable machine-readable format code. Ask whether the library, the application or the shell owns the behavior. That question often locates the cause before any translated text is changed.
A guide that shows localized values as bare text may hide that downstream code compares keyword identities. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Print the actual parsed representation for values such as json and edn. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
Explain the accepted values as data, not translated prose. A precise boundary avoids promising that every runtime behaves in exactly the same way. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
10. Collection coercion
A vector, set or list coercion form can collect multiple supplied values. Archive selection can involve several filenames without silently inventing splitting rules. Documentation is a testable part of the interface. A command shown in an article should behave like the application described beside it.
A translated sample may imply a single comma-separated argument while the spec gathers repeated values. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Compare repeated –path entries with one comma-separated string. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
Explain multiplicity and ordering; show what the resulting collection contains. If reality and prose disagree, repair both together and repeat the test. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
11. Boolean defaults
Boolean flag behavior deserves a separate example from string-valued options. A flag describes a switch in behavior, not a sentence that takes a translated yes. The useful distinction is between what a string means to the human reader and what the runtime treats as data. A translation should improve the former without silently changing the latter.
Adding true as the next token may create an unrelated argument instead of setting the flag. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Test presence and absence of –preview with the configured spec. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
Use a plain-language explanation of the enabled and disabled outcomes. A verified example is more persuasive than a broad claim of language support. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
12. Default values
The :default field can supply a value absent from the command line. Readers should know why they saw a French preview without typing –language fr. Imagine a colleague copying the example from a phone screen into a terminal. An overlooked punctuation or spacing difference could change the program’s interpretation.
A tutorial may claim the default is English while the deployed spec chooses another locale. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Call parse-opts with an empty vector and inspect the returned values. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
Document the real fallback and any configuration precedence. Make the instruction resilient to copying, narrow displays and unfamiliar terminology. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
13. Default descriptions
The :default-desc field can explain defaults in help output. An inaccurate default may cause a user to choose the wrong report format. This issue usually becomes visible when something goes wrong, not when the happy path succeeds. Therefore the investigation needs at least one controlled failure.
The human description can drift from the actual :default setting. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Compare generated help text and empty-argv parsing in one test. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
Update visible default wording alongside the executable default and verify both. The repair must identify the mistaken assumption and the next valid action. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
14. Required options
The :require facility lets an application reject missing required inputs. A person under deadline needs a next action, not merely a red error line. Ask whether the library, the application or the shell owns the behavior. That question often locates the cause before any translated text is changed.
An error can be translated so vaguely that readers do not know which argument was absent. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Test zero arguments and read error details, including the offending option. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
Name the missing option and show one safe command that supplies it. A precise boundary avoids promising that every runtime behaves in exactly the same way. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
15. Validation functions
The :validate setting can check semantic constraints after coercion. A port number or page limit has a range constraint distinct from being an integer. Documentation is a testable part of the interface. A command shown in an article should behave like the application described beside it.
A valid number can still be outside an accepted range, but an imprecise translation calls it nonnumeric. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Test wrong type and out-of-range values separately. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
Explain whether a value failed conversion, validation or business rules. If reality and prose disagree, repair both together and repeat the test. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
16. Restriction of unknowns
The :restrict behavior determines how unknown options are treated. For destructive workflows, an unknown flag ignored silently can be hazardous. The useful distinction is between what a string means to the human reader and what the runtime treats as data. A translation should improve the former without silently changing the latter.
Loose parsing can silently accept a misspelled translated flag. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Run –langauge by mistake under both restricted and unrestricted scenarios. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
Decide whether strict rejection suits the tool and document that policy. A verified example is more persuasive than a broad claim of language support. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
17. Error callbacks
An :error-fn callback can receive structured information about failures. Missing file and invalid format should not collapse into the same message. Imagine a colleague copying the example from a phone screen into a terminal. An overlooked punctuation or spacing difference could change the program’s interpretation.
A translated error handler can discard the cause and lose useful diagnostics. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Simulate :coerce, :require, :validate and :restrict problems. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
Branch on the structured cause, then provide an accurate human recovery. Make the instruction resilient to copying, narrow displays and unfamiliar terminology. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
18. Help formatting
format-opts and related functions can print option information from a spec. Help is a functional interface; spacing can change comprehension. This issue usually becomes visible when something goes wrong, not when the happy path succeeds. Therefore the investigation needs at least one controlled failure.
A formatted table may be technically correct yet unreadable with longer translations. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Generate two locales and compare alignment in a narrow terminal. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
Shorten headings carefully or move longer explanations below the summary. The repair must identify the mistaken assumption and the next valid action. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
19. Command dispatch
dispatch can match a command table and call the associated function. A tool may say cache clean in several languages while executing the same two tokens. Ask whether the library, the application or the shell owns the behavior. That question often locates the cause before any translated text is changed.
Translation of the displayed command name does not change the dispatch table’s registered :cmds. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Test every documented command sequence against the table. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
Show stable command tokens with translated descriptions, or register aliases deliberately. A precise boundary avoids promising that every runtime behaves in exactly the same way. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
20. Longest command match
The dispatcher selects the longest matching command entry in its table. Users should not guess whether a command acts on all records or just a subset. Documentation is a testable part of the interface. A command shown in an article should behave like the application described beside it.
An abbreviated documentation example can activate a general handler instead of the intended subcommand. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Compare a root command with nested alternatives in a read-only fixture. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
Give full paths for complex actions and state which handler should be reached. If reality and prose disagree, repair both together and repeat the test. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
21. Table-driven routing
A dispatch table stores entries with :cmds and :fn, plus optional parsing settings. A language flag on a root command may not be accepted after every subcommand. The useful distinction is between what a string means to the human reader and what the runtime treats as data. A translation should improve the former without silently changing the latter.
A reader may assume option specs are globally shared when they belong to individual entries. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Run sibling subcommands with the same option spelling and compare results. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
Document option scope and where it becomes meaningful. A verified example is more persuasive than a broad claim of language support. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
22. Tree-shaped routing
The library also supports tree-shaped command descriptions with nested :cmd nodes. Readers benefit when common tasks remain easy to find in translated command menus. Imagine a colleague copying the example from a phone screen into a terminal. An overlooked punctuation or spacing difference could change the program’s interpretation.
The ordering of nested help entries may surprise writers who rely on unspecified map iteration order. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Render help after adding more than eight child keys and inspect the intended order. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
Use documented ordering controls when sequence matters in the interface. Make the instruction resilient to copying, narrow displays and unfamiliar terminology. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
23. Global and local options
A root command and child commands can have different specs or overrides. A clear map of option scope prevents misleading copy-paste examples. This issue usually becomes visible when something goes wrong, not when the happy path succeeds. Therefore the investigation needs at least one controlled failure.
One general sentence can conceal that –output works for export but not inspect. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Test options before and after relevant subcommands with the actual dispatcher. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
Separate global requirements from command-specific choices. The repair must identify the mistaken assumption and the next valid action. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
24. Positional arguments
Unparsed arguments may be returned through metadata rather than ordinary option fields. Filename examples should not be confused with command names. Ask whether the library, the application or the shell owns the behavior. That question often locates the cause before any translated text is changed.
A translator may say an input path is a named option when it is positional data. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Inspect the result metadata for leftover operands on a safe call. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
Explain order, allowed count and how extra operands are handled. A precise boundary avoids promising that every runtime behaves in exactly the same way. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
25. Option ordering
The placement of named options relative to arguments can affect routing and interpretation. Consistency lowers the mental effort for multilingual readers. Documentation is a testable part of the interface. A command shown in an article should behave like the application described beside it.
Examples transplanted from another parser may rely on a different order policy. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Test an option before and after the subcommand and a free path. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
Publish a preferred canonical order and describe the accepted alternatives. If reality and prose disagree, repair both together and repeat the test. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
26. The end-of-options marker
The conventional — separator can distinguish later file names from flags. Do not confuse bb runtime arguments with script arguments. The useful distinction is between what a string means to the human reader and what the runtime treats as data. A translation should improve the former without silently changing the latter.
A path beginning with a dash can accidentally look like a command option. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Test a harmless -notes.edn filename with delimiter handling in the deployed parser. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
Show when a double dash is needed and which layer receives it. A verified example is more persuasive than a broad claim of language support. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
27. Shell and script boundaries
The shell and bb process arguments before the Clojure code calls babashka.cli. People should not have to debug the shell by reading a parser-only description. Imagine a colleague copying the example from a phone screen into a terminal. An overlooked punctuation or spacing difference could change the program’s interpretation.
A copied example may contain whitespace or quoting that changes the argv vector. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Print *command-line-args* before parsing in a diagnostic fixture. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
Supply shell-specific copyable examples, especially when filenames contain spaces. Make the instruction resilient to copying, narrow displays and unfamiliar terminology. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
28. Unicode files and paths
The parser may receive strings with Japanese, Arabic or accented Latin characters. Translating an archive title is different from preserving the exact title supplied. This issue usually becomes visible when something goes wrong, not when the happy path succeeds. Therefore the investigation needs at least one controlled failure.
A display problem can be mistaken for a failed parser or a damaged file. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Compare the original argv text, returned map and filesystem resolution separately. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
Keep user-owned paths as opaque data and test output encoding. The repair must identify the mistaken assumption and the next valid action. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
29. Right-to-left labels
Bi-directional scripts can rearrange the visual position of ASCII flags and punctuation. Reader safety depends on the copied command, not only its appearance. Ask whether the library, the application or the shell owns the behavior. That question often locates the cause before any translated text is changed.
An Arabic sentence may visually seem to contain a different order than its stored bytes. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Copy examples from rendered help into a shell and compare the token sequence. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
Isolate executable fragments and verify plain-text readability. A precise boundary avoids promising that every runtime behaves in exactly the same way. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
30. Plural messages
Error and success messages can have language-specific grammar for counts. A count is data, while its natural-language rendering belongs to localization. Documentation is a testable part of the interface. A command shown in an article should behave like the application described beside it.
String substitution into an English singular template fails in some languages. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Test zero, one and multiple files with the application’s message formatter. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
Use a locale-capable message catalog; keep that grammar outside the parser spec. If reality and prose disagree, repair both together and repeat the test. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
31. Locale tags
BCP 47 language tags are common application conventions but not a parser feature. Accepting –lang zh does not prove a Chinese translation exists. The useful distinction is between what a string means to the human reader and what the runtime treats as data. A translation should improve the former without silently changing the latter.
A guide may claim support for a locale whose resources were never shipped. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Compare supported locale identifiers with catalog files and fallback rules. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
Validate user input and explain default language behavior honestly. A verified example is more persuasive than a broad claim of language support. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
32. Configuration precedence
CLI values may override defaults or environment configuration in application logic. International users need predictable behavior when inherited settings differ. Imagine a colleague copying the example from a phone screen into a terminal. An overlooked punctuation or spacing difference could change the program’s interpretation.
Documentation may conflate precedence rules with the behavior of parse-opts. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Run tests with conflicting default, environment and explicit values. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
Describe who wins and which layer implements the rule. Make the instruction resilient to copying, narrow displays and unfamiliar terminology. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
33. Exit codes and diagnostics
Parser exceptions must become clear process outcomes for shell automation. A translated diagnostic serves both readers and automation. This issue usually becomes visible when something goes wrong, not when the happy path succeeds. Therefore the investigation needs at least one controlled failure.
Printing a nice translated error while returning success can mislead build scripts. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Capture stdout, stderr and exit code on each invalid command. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
Exit nonzero for failure and keep ordinary help distinct from errors. The repair must identify the mistaken assumption and the next valid action. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
34. Dry-run safety
A read-only preview mode is useful for teaching command meaning without modifying files. An educational article should make its safe boundary obvious. Ask whether the library, the application or the shell owns the behavior. That question often locates the cause before any translated text is changed.
A translated tutorial that includes a real cleanup command can cause accidental data loss. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Exercise all examples against disposable fixture paths. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
State which samples are read-only and which are hypothetical. A precise boundary avoids promising that every runtime behaves in exactly the same way. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
35. Formatting line width
Longer option descriptions can wrap badly in monospaced output. Good CLI localization includes layout, not merely strings. Documentation is a testable part of the interface. A command shown in an article should behave like the application described beside it.
Readers may attach a description to the wrong short alias when columns shift. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Capture help in an 80-column and a narrower terminal. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
Move detailed qualifications into paragraphs rather than truncating meaning. If reality and prose disagree, repair both together and repeat the test. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
36. Completion and help
Command completion and help may derive from related but not identical metadata. The terminal should not advertise a nonexistent localized alias. The useful distinction is between what a string means to the human reader and what the runtime treats as data. A translation should improve the former without silently changing the latter.
A translated completion label can suggest a command that dispatch does not recognize. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Check actual completion suggestions and then execute representative suggestions. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
Keep descriptions, completion results and dispatch names aligned. A verified example is more persuasive than a broad claim of language support. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
37. Data-driven examples
Example invocations should use harmless internationally understandable scenarios. A good guide can be tested by anyone without compromising their information. Imagine a colleague copying the example from a phone screen into a terminal. An overlooked punctuation or spacing difference could change the program’s interpretation.
A locale demonstration with real user data or secret tokens violates trust. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Use synthetic archive labels and fake filenames with no network dependencies. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
Redact credentials, choose read-only actions and explain expected output. Make the instruction resilient to copying, narrow displays and unfamiliar terminology. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
38. Version-specific behavior
The library and babashka runtime may evolve independently. Maintenance is part of making a guide world-facing. This issue usually becomes visible when something goes wrong, not when the happy path succeeds. Therefore the investigation needs at least one controlled failure.
A snippet written for an old API can mislead people using a newer release. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Pin versions in reproducible examples and consult official current API docs. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
Date version-sensitive claims and avoid unsupported compatibility promises. The repair must identify the mistaken assumption and the next valid action. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
39. Release regression
Option specs, command tables and translations can drift in different branches. A reader-oriented quality gate catches integration failures that unit tests miss. Ask whether the library, the application or the shell owns the behavior. That question often locates the cause before any translated text is changed.
A change to :alias can break a translated quick start without breaking unrelated tests. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Automate copy-paste examples as executable fixtures after every relevant code change. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
Require one valid and one invalid path per command family. A precise boundary avoids promising that every runtime behaves in exactly the same way. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
40. Reader comprehension
An expert translator can miss confusion experienced by a first-time CLI user. The purpose is informed action, not the appearance of sophistication. Documentation is a testable part of the interface. A command shown in an article should behave like the application described beside it.
A polished help screen may not reveal which action is safe or required. That mismatch can make a translated article appear fluent while leaving readers unable to predict which command works. It also creates avoidable support requests when a harmless example is mistaken for a production operation.
Have a new reader locate a command, invoke it and recover from a deliberate error. Note the exact argument vector, parsed map, selected handler, visible message and process status wherever relevant. Then ask whether a reader using the translated instructions could have predicted the result.
Revise according to observed behavior, not just word choice. If reality and prose disagree, repair both together and repeat the test. Preserve a tested fixture for future changes so a translation update cannot quietly alter the executable contract.
Worked case: a multilingual catalogue conversion request
Suppose the script accepts a format choice, a path and a preview flag. A Portuguese-speaking librarian receives an Arabic-titled file and wishes to see a JSON preview. A useful guide first defines the goal, then shows a literal command with proper quoting, followed by the expected parsed values. It separately states that preview does not modify the input. If JSON output is implemented only in the handler, it should be described as a handler capability rather than an automatic effect of babashka.cli.
Now deliberately misspell the format option. With a strict specification, the script can reject it and explain which spelling is valid. With permissive parsing, an unknown key may enter the result or be ignored, depending on configuration. Neither situation should be hidden behind a reassuring translation. The author should test the actual parser settings and choose copy that helps the reader recover. The source of confidence is observed behavior.
Worked case: confusing a translated subcommand with an alias
A French help page might explain a clean command as nettoyer. Unless the dispatch table registers nettoyer as a command, the displayed French verb is an explanation, not an executable synonym. In a teaching guide, separate the stable token from its translated purpose. If a product deliberately introduces multilingual command aliases, document how they are registered, what happens when language settings change and whether automation should continue using canonical commands.
The same care applies to nested routes, option scopes and command order. A child command can have different validation or format defaults from its parent. A command table that changes over time can make shortcuts unreliable. A short, complete invocation is more educational than an attractive incomplete one because readers can identify exactly which handler will run.
How to run a responsible four-stage release test
First inventory the command tables, option specs and business rules. Confirm the installed babashka CLI and runtime versions, and capture current help plus an argv printout. Name the purpose of every option before translating its label. This prevents assumptions borrowed from similar parsers from contaminating the guide.
Next write direct task-oriented paragraphs. Start with what the reader gains and a harmless working example. State every default, required option, accepted data type, validation condition and real side effect. Use a consistent way to distinguish a literal key from a translated explanation. Verify the first three paragraphs answer the primary search intent immediately.
Then test commands with Unicode filenames, spaces, unknown options, missing requirements, invalid coercion, nested dispatch and right-to-left help. Run at least one command through a narrow terminal and a redirected plain-text log. Include exit codes and synthetic example data. Do not use private directories or actual credentials.
Finally ask a target-language reader to perform a safe task without seeing the original English notes. Observe the questions asked and where the reader hesitates. Repair misleading text or examples, rerun the test and only publish after the packaged script and documentation match. Retest whenever specs, aliases or dependencies change.
Frequently asked questions
Does babashka.cli localize messages for me?
No. It provides option parsing, formatting and dispatch facilities. An application decides how to select language resources, translate descriptions and respond to user actions. Pair the answer with a verified example using the same configuration as the released program, because one real observation is more reliable than a generic promise.
What is a :spec map?
It is the library’s description of accepted options and their behavior, including coercion, aliases, requirements and human-facing descriptions. Pair the answer with a verified example using the same configuration as the released program, because one real observation is more reliable than a generic promise.
Why use :desc rather than rewriting an option key?
The description is for readers; the option key participates in parsing. Changing one does not automatically change the other. Pair the answer with a verified example using the same configuration as the released program, because one real observation is more reliable than a generic promise.
What is the difference between :coerce and :validate?
Coercion converts incoming text to a type or representation; validation checks whether an already interpreted value meets a rule. Error messages should reflect that difference. Pair the answer with a verified example using the same configuration as the released program, because one real observation is more reliable than a generic promise.
Can translated command names work?
They can be designed and registered as accepted command names or aliases, but documentation alone cannot make them work. Pair the answer with a verified example using the same configuration as the released program, because one real observation is more reliable than a generic promise.
Why does my JSON sample not change the file?
Parsing an option named format simply produces a value. A separate handler must implement conversion and output. Pair the answer with a verified example using the same configuration as the released program, because one real observation is more reliable than a generic promise.
How can I prevent an unknown flag from going unnoticed?
Use the documented restriction and error-handling facilities appropriate to the app, then exercise deliberate misspellings in tests. Pair the answer with a verified example using the same configuration as the released program, because one real observation is more reliable than a generic promise.
What should a translated help screen include?
A succinct task summary, literal command syntax, clear option purpose and requirements, a safe example and a useful recovery path for mistakes. Pair the answer with a verified example using the same configuration as the released program, because one real observation is more reliable than a generic promise.
What makes this guide internationally usable?
Its commands are tested; user text survives Unicode processing; locale-specific grammar is handled outside parser syntax; and shell or version limitations are stated plainly. Pair the answer with a verified example using the same configuration as the released program, because one real observation is more reliable than a generic promise.
Primary documentation and next reading
Read the babashka.cli official documentation, babashka.cli API reference and Babashka book. Continue with Master Art of Translation and the Translate Like a Pro index. This chapter specifically covers babashka.cli command interfaces rather than general literary translation or other command frameworks.
The point of localization is not to decorate a command with words from more languages. It is to help people act correctly with software they may never have seen before. Babashka.cli offers clear spec and dispatch boundaries. Writers can use those boundaries to explain exactly what the command accepts, why a failure occurred and how to continue safely.