Translate Like a Pro | 8630 — Elixir Optimus CLI Localization, Subcommands, Options, Flags, Parser Errors and Release QA

Elixir Optimus localization is the process of translating a command-line application’s help, option descriptions, subcommand explanations and recovery messages without changing how Optimus parses the command. This practical guide explains the parser’s args, options, flags, nested commands and error results for multilingual Elixir CLI software. The main promise is not simply fluent translated text: it is a tool whose instructions are correct, whose runnable examples remain valid and whose operators can tell whether a command succeeded.

Imagine HarborManifest, a small application that inspects shipping manifest files before an operations team files a report. An English-speaking maintainer can run harbormanifest inspect shipments.csv –dry-run, but an operator reading French, Japanese or Arabic help must understand the same permitted action. If the text translates –dry-run as a different literal switch, a well-intentioned reader receives an unknown-option error. If the text says that a preview creates no output, the test suite must prove that promise.

Start with this rule: preserve stable command tokens, typed parser values and exit behavior; localize prose that explains those tokens; then verify real outputs and failure paths under every supported locale. Optimus v0.6.1 documents specification fields such as :args, :flags, :options, :subcommands, :help and :value_name, along with new, parse and help functions. These fields provide a useful boundary between human-facing guidance and executable grammar, but they do not by themselves establish a complete application translation system.

Quick answer — how to localize Elixir Optimus safely

Keep the subcommand path, option names, flag aliases, parsed argument atoms, custom parser return types and result shape exact in runnable examples and program behavior.
Translate the :name, :description, :about and :help strings, human-oriented :value_name labels, application-owned explanations and contextual error guidance in a controlled language layer.
Distinguish library-generated text from messages owned by the application.
Pin and inspect the installed Elixir dependencies before relying on a public example.
Test valid commands, missing values, invalid options and unsafe side-effect claims.
Capture real stdout, stderr and exit status; compare typed outputs instead of translated strings.
Test Unicode filenames, narrow terminals, right-to-left explanations and copied commands.
Record a supported-language fallback and ask native speakers to complete a real task.

Chapter 1 — What the command-line interface actually does

A command-line interface is a compact language. It combines a program name, selected action, options and data supplied by the reader. In Elixir Optimus, Optimus.new/1 and new!/1 construct specifications; Optimus.parse/2 returns structured success or error variants; Optimus.help/1 produces a help string; the specification distinguishes positional :args, value-taking :options, boolean :flags and nested :subcommands. This arrangement is valuable because the program can recognize the intended operation without interpreting an entire natural-language sentence. It is also why careless translation is risky: replacing a recognized command with a fluent but unimplemented synonym is equivalent to changing the program, not improving its documentation.

Begin with a task the reader already understands: HarborManifest, an illustrative shipping-manifest checker that reads a local CSV export without contacting a production service. The example task is harbormanifest inspect shipments.csv –dry-run. Before translating anything, identify the input file, the executable tokens, the expected result and possible side effects. A professional guide is useful when it answers what will change, what will not change, how to confirm success, and what happens if a step fails. Those four questions are more important than showing every optional switch on the first screen.

Chapter 2 — Separate executable identity from language

The simplest reliable distinction is between a machine token and a human description. the subcommand path, option names, flag aliases, parsed argument atoms, custom parser return types and result shape belong to the interface contract. the :name, :description, :about and :help strings, human-oriented :value_name labels, application-owned explanations and contextual error guidance are candidates for localization, provided the chosen software architecture can display the translated text. A filename or number is usually data, which needs its own validation and formatting policy. The fact that all three may appear in one help line does not make them interchangeable.

Create a small inventory with columns for the visible string, where it originates, who owns it, whether users must type it and what tests protect it. For example, a translated phrase can sit beside –help, while –help itself remains literal. Reconfirm where the string is actually rendered: command help, validation error, progress output, a manual page, a generated completion script or a copied example. A change to a help paragraph should not need to rewire parsing.

Chapter 3 — A small version-aware technical example

The following Elixir excerpt is a compact illustration of the code boundary. It is not an invitation to run unreviewed operations against real records. Put equivalent code in a disposable project, pin the library version and test with sample inputs. If your installed package differs from the cited documentation, inspect its public API first. Some applications wrap libraries with their own helper layers, so a team’s production command may accept different options from this educational example.

Read the example in two directions. First, follow the value typed by a user through the parser and into the program’s action. Second, find which strings describe that process to the reader. Translation belongs primarily in the second path, while validation and successful execution belong in the first. If the input path or option set changes when only the description language changes, that is evidence of a behavioral regression.

spec = [
  name: "harbormanifest",
  description: "Inspect local shipping manifests",
  args: [source: [value_name: "SOURCE", help: "Input CSV path", required: true]],
  flags: [dry_run: [long: "dry-run", short: "n", help: "Do not write changes"]]
]
{:ok, cli} = Optimus.new(spec)
case Optimus.parse(cli, ["shipments.csv", "--dry-run"]) do
  {:ok, result} -> IO.inspect(result)
  {:error, errors} -> IO.inspect(errors, label: "parse errors")
  other -> IO.inspect(other, label: "other parser result")
end

Chapter 4 — Help must form a useful path, not a dictionary

A good help page begins with purpose, then a minimum safe invocation, then common arguments, then the next action after success or failure. It should not force a novice to decode a complete reference table before trying a single harmless example. Show a real path format, state whether it refers to a file or folder, identify default behavior, and explain what the command will write. Use short option descriptions for scanning, followed by detailed discussion for ambiguous or risky actions.

For HarborManifest, an illustrative shipping-manifest checker that reads a local CSV export without contacting a production service, start with a local fixture and a clear observation such as a row count, a checked schema, or a summarized warning. Present a command in code formatting and keep its spelling stable. The surrounding explanation can adapt to local grammar, but the command cannot change unless the program really supports another syntax. Think of translated help as a trustworthy user journey rather than a list of words that happen to be equivalent.

Chapter 5 — Choose a locale without changing the task

A multilingual application needs to determine the language before it constructs human-facing output. Depending on the application’s design, a documented flag, environment variable or configuration setting may be appropriate. Use predictable fallbacks and support an explicit list of locale tags. A user who requests Japanese help should not accidentally run a different operation, write to a different directory or grant broader permissions. Locale selection is a presentation decision until the application explicitly documents a different contract.

Avoid assuming that a low-level parser library supplies a ready-made translation catalog. The technical reference may document description strings without providing message extraction, fallback or plural handling. A practical architecture keeps a catalog keyed by stable identifiers and lets application code choose complete sentences. The key is never itself a command flag. Record which messages still come from Elixir Optimus so readers and maintainers do not confuse a partial translation with total support.

Chapter 6 — Make errors actionable, accurate and safe

An error message should answer what failed, where the user can look and which next action is safe. Missing arguments, unknown switches, unsupported values, unreadable files and malformed contents are different failures. Some are rejected by the parser before the application starts; others occur later. Translating them into one generic ‘operation failed’ sentence removes critical information. Where messages are controlled by a dependency and lack a documented translation hook, a localized application explanation can be safer than brittle rewriting of raw dependency output.

Never print a successful-completion message after a command that failed. Compare exit status and side effects as well as displayed wording. When errors mention sensitive paths, identifiers or internal details, avoid exposing secrets in the guise of helpful localization. Show enough context for recovery without turning a CLI diagnostic into a data leak. The correct reader-facing wording often includes a valid minimal invocation and a pointer to a local log reference.

Chapter 7 — Treat Unicode and typography as engineering issues

Translation changes the shape of text. French descriptions may be longer, Japanese glyphs may occupy multiple terminal display columns, Arabic paragraphs may mix right-to-left text with left-to-right options, and filenames can contain combining marks or spaces. A string that looks fine in a browser may be unreadable or uncopyable in a shell. The program’s data representation, stdout encoding, terminal font and renderer are separate boundaries worth checking.

Keep executable tokens in code formatting, preserve ASCII punctuation where it has syntax meaning, and test copied commands as bytes. Check a narrow terminal and a normal terminal, stdout piped into a file and errors written to stderr. A correct translation should help a reader act, not merely look attractive in the translator’s editor. Confirm the supported environments rather than claiming universal Unicode behavior from the language runtime alone.

Chapter 8 — Check real outcomes, not just translated snapshots

A screenshot proves that text appeared. It does not prove that an operator selected the correct input, that the parser produced the intended value or that a command avoided an unpromised write. Build fixtures for a valid invocation, missing required input, malformed value, unknown option, Unicode path and a permissions failure. Compare parsed outputs, exit code and file effects across languages. The content of the sentence may change, but the operational result should stay consistent.

Native-language testing adds a different kind of evidence. Ask a reader to explain what the command will do before executing it, which part of the example is a placeholder, and what the next step is after a failure. A reviewer who can translate every word but selects the wrong operation has found a usability defect. Use that observation to fix help ordering, not just vocabulary.

Chapter 9 — Elixir Optimus design decisions that change translation quality

1. The specification is a contract

An Optimus specification combines description strings with parser identity. The :name field identifies the program, while :description and :about explain it. Nested :subcommands carry their own options and purpose. Do not rewrite a working program’s supported command tree just because a localized paragraph sounds more natural. Inventory the actual parse combinations first, including aliases, hidden flags and default values.

To make this decision useful for a real reader, first identify which part of harbormanifest inspect shipments.csv –dry-run is a typed token, which part is an input value, and which part is merely explanatory. Record the behavior before revising the wording. When a localized page makes a promise, turn that promise into a fixture: invoke a valid sample command, inspect the structured result and check that side effects match the guide.

For HarborManifest, an illustrative shipping-manifest checker that reads a local CSV export without contacting a production service, the acceptance test is concrete: the operator must be able to follow harbormanifest inspect shipments.csv –dry-run, tell which output is a preview or final result, and recover from an invalid invocation. The reviewer should record the exact Elixir runtime and dependency versions used. This turns the topic from an abstract translation preference into a verifiable instruction that can be maintained through future releases.

2. Positional argument names are not values

The :args list defines positional input. A value_name such as SOURCE is a display placeholder, not the filename typed by an operator; translating SOURCE may improve the help page while a source path itself remains untouched. A required input is still required in every language. Test absent positional arguments separately from nonexistent files, because one is a parse failure and the other is an application validation failure.

This issue usually appears when source code, an English help screen and a translator’s draft are reviewed separately. Put them side by side. Ask the maintainer to show what Elixir Optimus actually accepts, ask the language reviewer to describe the intended operation without consulting English, and let the test suite arbitrate differences. A good edit survives both kinds of review.

3. Value-taking options need types

An Optimus :option can carry :parser, :default, :required and :multiple metadata. When a user passes –limit 20, the translated description may explain units and the allowed range, but the flag and value must still be recognized as configured. A custom parser can return {:ok, value} or {:error, message}; the application should treat a bad value as a failure even when an explanatory translation is available.

A small example is better than a sweeping claim. Build a disposable input, run it once successfully and then change only the display language. If the parsed values or selected files differ, the localization boundary has moved too far. If behavior matches but the reader cannot explain what happened, the prose is still not adequate. Both outcomes deserve independent fixes.

4. Flags are switches, not sentences

Optimus distinguishes flags from value-taking options. A Boolean dry-run flag changes program behavior without asking for another value. The short spelling -n and long spelling –dry-run are exact executable strings if defined that way. Never turn a localized phrase such as ‘without saving’ into an undocumented –without-saving option. Put that phrase next to the actual switch in prose.

Keep a note of ownership and version. If the wording comes from library help generation, check the installed public API. If the wording comes from the application, change it with a catalog key and a semantic test. Never translate an internal identifier simply because it looks English, and never leave a user without an explanation because a technical token must remain stable.

5. Subcommand paths need a separate map

Optimus supports :subcommands with named specifications. A nested command can have a different positional argument sequence and valid flags from the top-level command. Map root help, inspect help and export help independently. A translation that describes export as available from the root when it actually lives under a subcommand misdirects readers; a path test must catch it.

6. Parser return shapes must remain intelligible

The documented parse signature includes successes with or without subcommand paths, errors with or without paths and a version result. Do not assume that every return is a two-element tuple. Build error handling that distinguishes help or version behavior from genuine invalid input and from success. A localized wrapper should be added only after the parser’s actual result shapes have been tested.

7. Error localization requires ownership

Error text from Optimus may be produced by the dependency, while invalid-file and permission errors may come from application code. Keep the ownership boundary visible. If a dependency diagnostic cannot be replaced safely through a documented extension, the application can add a localized next-step explanation rather than claiming the parser itself supports a particular locale. Avoid fragile string substitution of upstream error paragraphs.

8. Custom parsers preserve meaning

A custom parser is a function from an input string to a typed success or error result. It may check a date, decimal, enumerated status or manifest identifier. Translation cannot repair a parser that accepts unsafe inputs. Check the documented data format, whether decimal separators are accepted, and the output type. Then localize only its human-facing explanation, testing both valid and malformed samples.

9. Global options affect all subcommands

The :global option attribute matters when a setting such as –locale should be recognized across nested commands. Its exact scope must be tested, not inferred from placement in an examples table. If –locale is allowed only before a subcommand, explain the correct order. Verify that choosing a language for output does not silently alter argument grammar or load an unrelated configuration file.

10. Hidden flags and support instructions

The :hide attribute can suppress a command from ordinary help. This may be reasonable for experimental or internal switches; it does not make the switch safe to change casually. Translation teams should not surface hidden maintenance flags in public examples without an explicit product decision. Help content should guide readers toward supported workflows and declare when a task needs privileged access.

11. Unknown arguments are a deliberate policy

The specification includes :allow_unknown_args and :parse_double_dash options. Those controls can affect how inputs are interpreted. A reader may reasonably believe that text after — is a filename even when the configured parser differs. Write examples that reflect the actual settings, and test both unknown flags and the — separator without changing acceptance rules during localization.

12. Versioned technical accuracy

The documented surface was checked against Optimus v0.6.1, whose Hex package listing was updated in February 2026. An application may pin a different version, so its lockfile and tests outrank a tutorial’s example. When a translation changes after a dependency upgrade, compare generated help, parse failures and subcommand handling before declaring the release compatible.

13. Locale selection must happen before help rendering

If the application’s selected language comes from an environment variable, configuration file or safe explicit option, choose and validate the locale before assembling descriptions. Set a predictable fallback for unsupported tags. Never let display language select a new manifest file, change execution permissions or rewrite a parsed option’s meaning; a locale is a presentation preference, not a hidden business-rule toggle.

14. The shipping-file example has real stakes

A manifest checker may warn about missing shipment IDs, duplicate rows or invalid dates. Translate the difference between ‘not found’, ‘not valid’ and ‘not authorized’; these are separate repairs. Illustrative commands should operate on clearly labelled sample files, and reports should say whether they are previews. For each locale, validate that the same row count, error list and no-write behavior are obtained.

Chapter 10 — Eighteen realistic troubleshooting investigations

The cases below describe different ways a Elixir Optimus translation can be polished but wrong. Each has a symptom, a repair and a verification step. They are examples for training and testing, not claims about defects in the library itself. Use fictitious data, preserve any real system’s access controls and rerun relevant checks when the underlying package is upgraded.

Investigation 1: Translated option spelling

What the operator encounters: A German reviewer replaces the literal –dry-run in a copyable code block with a German synonym. The resulting command is rejected or treated differently. This matters because help text and a working parser can disagree even when each looks coherent in isolation. A human may follow instructions correctly and still make the wrong call, which is a documentation defect as much as an implementation problem.

A safe correction is specific: Restore –dry-run as a command token, then add a translated explanation directly below the example. Keep the change limited to the right layer. Do not alter the subcommand path, option names, flag aliases, parsed argument atoms, custom parser return types and result shape in response to a purely linguistic problem, and do not hide actual application defects beneath nicer wording.

Proof before release: Run the published command under German and English display preferences; compare parsed flags and the filesystem. Then repeat the attempt under the default language and at least one translated locale. Compare the result class, stderr and exit status, and inspect whether any output file, report or cache was changed. Mark a test as passing only when the technical result and the reader’s understanding agree.

Investigation 2: Misleading SOURCE placeholder

What the operator encounters: A Japanese translator treats SOURCE as a required literal word rather than a placeholder for shipments.csv. This matters because help text and a working parser can disagree even when each looks coherent in isolation. A human may follow instructions correctly and still make the wrong call, which is a documentation defect as much as an implementation problem.

A safe correction is specific: Identify SOURCE as a filename placeholder and show one concrete safe value with a note that filenames may contain spaces. Keep the change limited to the right layer. Do not alter the subcommand path, option names, flag aliases, parsed argument atoms, custom parser return types and result shape in response to a purely linguistic problem, and do not hide actual application defects beneath nicer wording.

Proof before release: Use a sample named 出荷一覧.csv and confirm that the shell quoting and input selection work. Then repeat the attempt under the default language and at least one translated locale. Compare the result class, stderr and exit status, and inspect whether any output file, report or cache was changed. Mark a test as passing only when the technical result and the reader’s understanding agree.

Investigation 3: Integer parser message

What the operator encounters: A French error says ‘missing limit’ when a user supplied –limit banana; the real problem is a type conversion. This matters because help text and a working parser can disagree even when each looks coherent in isolation. A human may follow instructions correctly and still make the wrong call, which is a documentation defect as much as an implementation problem.

A safe correction is specific: Distinguish a missing option, an invalid integer and an out-of-range integer in separate recovery wording. Keep the change limited to the right layer. Do not alter the subcommand path, option names, flag aliases, parsed argument atoms, custom parser return types and result shape in response to a purely linguistic problem, and do not hide actual application defects beneath nicer wording.

Proof before release: Exercise all three failure fixtures and compare error state, exit code and recovery instructions. Then repeat the attempt under the default language and at least one translated locale. Compare the result class, stderr and exit status, and inspect whether any output file, report or cache was changed. Mark a test as passing only when the technical result and the reader’s understanding agree.

Investigation 4: Inherited global locale

What the operator encounters: The root command accepts –locale but a nested inspect command does not where the guide says it will. This matters because help text and a working parser can disagree even when each looks coherent in isolation. A human may follow instructions correctly and still make the wrong call, which is a documentation defect as much as an implementation problem.

A safe correction is specific: Reproduce the installed parser’s valid order and document the exact placement instead of promising unspecified inheritance. Keep the change limited to the right layer. Do not alter the subcommand path, option names, flag aliases, parsed argument atoms, custom parser return types and result shape in response to a purely linguistic problem, and do not hide actual application defects beneath nicer wording.

Proof before release: Try locale before and after inspect, record which forms the application actually accepts. Then repeat the attempt under the default language and at least one translated locale. Compare the result class, stderr and exit status, and inspect whether any output file, report or cache was changed. Mark a test as passing only when the technical result and the reader’s understanding agree.

Investigation 5: Untranslated version output

What the operator encounters: The application prints a version string regardless of locale and a reviewer marks it as unfinished translation. This matters because help text and a working parser can disagree even when each looks coherent in isolation. A human may follow instructions correctly and still make the wrong call, which is a documentation defect as much as an implementation problem.

A safe correction is specific: Keep semantic version, build hash and library versions unchanged while explaining their purpose in the user’s language. Keep the change limited to the right layer. Do not alter the subcommand path, option names, flag aliases, parsed argument atoms, custom parser return types and result shape in response to a purely linguistic problem, and do not hide actual application defects beneath nicer wording.

Proof before release: Compare version bytes across locales and verify that a version request has no side effects. Then repeat the attempt under the default language and at least one translated locale. Compare the result class, stderr and exit status, and inspect whether any output file, report or cache was changed. Mark a test as passing only when the technical result and the reader’s understanding agree.

Investigation 6: Help and parse paths confused

What the operator encounters: An operator sees a translated help heading and assumes that displaying help means the manifest was checked. This matters because help text and a working parser can disagree even when each looks coherent in isolation. A human may follow instructions correctly and still make the wrong call, which is a documentation defect as much as an implementation problem.

A safe correction is specific: Give help output its own non-action status. Explain that a command listing usage does not validate source content. Keep the change limited to the right layer. Do not alter the subcommand path, option names, flag aliases, parsed argument atoms, custom parser return types and result shape in response to a purely linguistic problem, and do not hide actual application defects beneath nicer wording.

Proof before release: Check that help mode never opens production files and that a successful parse alone does not claim a completed audit. Then repeat the attempt under the default language and at least one translated locale. Compare the result class, stderr and exit status, and inspect whether any output file, report or cache was changed. Mark a test as passing only when the technical result and the reader’s understanding agree.

Investigation 7: Colon and path confusion

What the operator encounters: An Arabic layout embeds a Windows drive path inside right-to-left prose and reverses the visual order of punctuation. This matters because help text and a working parser can disagree even when each looks coherent in isolation. A human may follow instructions correctly and still make the wrong call, which is a documentation defect as much as an implementation problem.

A safe correction is specific: Display runnable paths in a code span with direction-aware presentation, keeping their underlying bytes unchanged. Keep the change limited to the right layer. Do not alter the subcommand path, option names, flag aliases, parsed argument atoms, custom parser return types and result shape in response to a purely linguistic problem, and do not hide actual application defects beneath nicer wording.

Proof before release: Copy a path containing a drive letter from the localized page and compare it byte-for-byte. Then repeat the attempt under the default language and at least one translated locale. Compare the result class, stderr and exit status, and inspect whether any output file, report or cache was changed. Mark a test as passing only when the technical result and the reader’s understanding agree.

Investigation 8: Duplicate flag interpretation

What the operator encounters: A flag marked :multiple changes intended results, but translated documentation implies duplicates are ignored. This matters because help text and a working parser can disagree even when each looks coherent in isolation. A human may follow instructions correctly and still make the wrong call, which is a documentation defect as much as an implementation problem.

A safe correction is specific: Clarify how repeated switches are represented in the actual parser result and avoid guessing at deduplication semantics. Keep the change limited to the right layer. Do not alter the subcommand path, option names, flag aliases, parsed argument atoms, custom parser return types and result shape in response to a purely linguistic problem, and do not hide actual application defects beneath nicer wording.

Proof before release: Pass the flag twice and inspect the structured result under both languages. Then repeat the attempt under the default language and at least one translated locale. Compare the result class, stderr and exit status, and inspect whether any output file, report or cache was changed. Mark a test as passing only when the technical result and the reader’s understanding agree.

Investigation 9: Unknown switches permitted

What the operator encounters: A maintenance command enables unknown args, but the translation says unknown switches are rejected. This matters because help text and a working parser can disagree even when each looks coherent in isolation. A human may follow instructions correctly and still make the wrong call, which is a documentation defect as much as an implementation problem.

A safe correction is specific: Describe what the current tool accepts and where unrecognized items are forwarded, if anywhere; do not suggest safety from mere parsing. Keep the change limited to the right layer. Do not alter the subcommand path, option names, flag aliases, parsed argument atoms, custom parser return types and result shape in response to a purely linguistic problem, and do not hide actual application defects beneath nicer wording.

Proof before release: Inject a harmless unexpected switch and assert the exact application behavior. Then repeat the attempt under the default language and at least one translated locale. Compare the result class, stderr and exit status, and inspect whether any output file, report or cache was changed. Mark a test as passing only when the technical result and the reader’s understanding agree.

Investigation 10: Double dash misunderstood

What the operator encounters: A file beginning with a hyphen is mistaken for a switch; someone translates the — separator into punctuation. This matters because help text and a working parser can disagree even when each looks coherent in isolation. A human may follow instructions correctly and still make the wrong call, which is a documentation defect as much as an implementation problem.

A safe correction is specific: Explain the separator as an exact terminal token and test its configured handling in Optimus. Keep the change limited to the right layer. Do not alter the subcommand path, option names, flag aliases, parsed argument atoms, custom parser return types and result shape in response to a purely linguistic problem, and do not hide actual application defects beneath nicer wording.

Proof before release: Use a disposable file called -incoming.csv and record whether the parser reads it as data. Then repeat the attempt under the default language and at least one translated locale. Compare the result class, stderr and exit status, and inspect whether any output file, report or cache was changed. Mark a test as passing only when the technical result and the reader’s understanding agree.

Investigation 11: No-write promise untested

What the operator encounters: A translated preview label says ‘nothing is saved’ even though the surrounding application writes a cache. This matters because help text and a working parser can disagree even when each looks coherent in isolation. A human may follow instructions correctly and still make the wrong call, which is a documentation defect as much as an implementation problem.

A safe correction is specific: Audit every side effect, including logs, generated reports and temporary files, before approving that label. Keep the change limited to the right layer. Do not alter the subcommand path, option names, flag aliases, parsed argument atoms, custom parser return types and result shape in response to a purely linguistic problem, and do not hide actual application defects beneath nicer wording.

Proof before release: Hash test directories before and after dry-run and reconcile intentional logs separately. Then repeat the attempt under the default language and at least one translated locale. Compare the result class, stderr and exit status, and inspect whether any output file, report or cache was changed. Mark a test as passing only when the technical result and the reader’s understanding agree.

Investigation 12: Encoding on remote terminals

What the operator encounters: Help displays correctly in an editor but becomes unreadable when piped through an older terminal locale. This matters because help text and a working parser can disagree even when each looks coherent in isolation. A human may follow instructions correctly and still make the wrong call, which is a documentation defect as much as an implementation problem.

A safe correction is specific: Keep UTF-8 content, test the effective locale, encoding and fonts, and provide a plain-text fallback only where needed. Keep the change limited to the right layer. Do not alter the subcommand path, option names, flag aliases, parsed argument atoms, custom parser return types and result shape in response to a purely linguistic problem, and do not hide actual application defects beneath nicer wording.

Proof before release: Capture stdout and stderr bytes independently on Linux, macOS and Windows terminals. Then repeat the attempt under the default language and at least one translated locale. Compare the result class, stderr and exit status, and inspect whether any output file, report or cache was changed. Mark a test as passing only when the technical result and the reader’s understanding agree.

Investigation 13: Custom date ambiguity

What the operator encounters: A custom date parser accepts ISO dates, while an example translates 2026-11-06 into 06/11/2026 without parser support. This matters because help text and a working parser can disagree even when each looks coherent in isolation. A human may follow instructions correctly and still make the wrong call, which is a documentation defect as much as an implementation problem.

A safe correction is specific: Keep the required machine date format and explain it using a readable localized sentence, not an altered argument. Keep the change limited to the right layer. Do not alter the subcommand path, option names, flag aliases, parsed argument atoms, custom parser return types and result shape in response to a purely linguistic problem, and do not hide actual application defects beneath nicer wording.

Proof before release: Test an unambiguous ISO date, an invalid calendar date and a culturally ambiguous date. Then repeat the attempt under the default language and at least one translated locale. Compare the result class, stderr and exit status, and inspect whether any output file, report or cache was changed. Mark a test as passing only when the technical result and the reader’s understanding agree.

Investigation 14: Exception wording exposed

What the operator encounters: A custom application parser raises a raw stack trace when a user passes malformed input; localization staff translate the trace. This matters because help text and a working parser can disagree even when each looks coherent in isolation. A human may follow instructions correctly and still make the wrong call, which is a documentation defect as much as an implementation problem.

A safe correction is specific: Handle the expected failure in application code, display a concise safe message and retain technical details in protected logs. Keep the change limited to the right layer. Do not alter the subcommand path, option names, flag aliases, parsed argument atoms, custom parser return types and result shape in response to a purely linguistic problem, and do not hide actual application defects beneath nicer wording.

Proof before release: Confirm that normal invalid inputs do not print stack traces and still yield failure status. Then repeat the attempt under the default language and at least one translated locale. Compare the result class, stderr and exit status, and inspect whether any output file, report or cache was changed. Mark a test as passing only when the technical result and the reader’s understanding agree.

Investigation 15: Incorrect source directory

What the operator encounters: The translation says –source points to a folder even though the CLI expects a single CSV file. This matters because help text and a working parser can disagree even when each looks coherent in isolation. A human may follow instructions correctly and still make the wrong call, which is a documentation defect as much as an implementation problem.

A safe correction is specific: State the accepted file type and distinguish a directory from a regular file before running a demonstration. Keep the change limited to the right layer. Do not alter the subcommand path, option names, flag aliases, parsed argument atoms, custom parser return types and result shape in response to a purely linguistic problem, and do not hide actual application defects beneath nicer wording.

Proof before release: Test existing file, directory path, missing path and unreadable path with distinct messages. Then repeat the attempt under the default language and at least one translated locale. Compare the result class, stderr and exit status, and inspect whether any output file, report or cache was changed. Mark a test as passing only when the technical result and the reader’s understanding agree.

Investigation 16: Subcommand name translated

What the operator encounters: A translated table renames inspect into a natural-language verb while the command registry still recognizes inspect. This matters because help text and a working parser can disagree even when each looks coherent in isolation. A human may follow instructions correctly and still make the wrong call, which is a documentation defect as much as an implementation problem.

A safe correction is specific: Keep inspect in command examples and move the translated action description to its adjacent help text. Keep the change limited to the right layer. Do not alter the subcommand path, option names, flag aliases, parsed argument atoms, custom parser return types and result shape in response to a purely linguistic problem, and do not hide actual application defects beneath nicer wording.

Proof before release: Check root help, command-specific help and actual invocation with the same command name. Then repeat the attempt under the default language and at least one translated locale. Compare the result class, stderr and exit status, and inspect whether any output file, report or cache was changed. Mark a test as passing only when the technical result and the reader’s understanding agree.

Investigation 17: Status code concealed

What the operator encounters: The translated app says ‘finished’ after a parser error because the wrapper always prints a success footer. This matters because help text and a working parser can disagree even when each looks coherent in isolation. A human may follow instructions correctly and still make the wrong call, which is a documentation defect as much as an implementation problem.

A safe correction is specific: Make the footer conditional on real successful completion; parse error and application error must not share success wording. Keep the change limited to the right layer. Do not alter the subcommand path, option names, flag aliases, parsed argument atoms, custom parser return types and result shape in response to a purely linguistic problem, and do not hide actual application defects beneath nicer wording.

Proof before release: Assert exit codes, output file existence and success banner for one valid and two invalid invocations. Then repeat the attempt under the default language and at least one translated locale. Compare the result class, stderr and exit status, and inspect whether any output file, report or cache was changed. Mark a test as passing only when the technical result and the reader’s understanding agree.

Investigation 18: Documentation version drifts

What the operator encounters: The article example uses a newer :global behavior but the deployed tool pins an older Optimus dependency. This matters because help text and a working parser can disagree even when each looks coherent in isolation. A human may follow instructions correctly and still make the wrong call, which is a documentation defect as much as an implementation problem.

A safe correction is specific: Tie examples to tested library and application versions, and annotate differences rather than changing commands blindly. Keep the change limited to the right layer. Do not alter the subcommand path, option names, flag aliases, parsed argument atoms, custom parser return types and result shape in response to a purely linguistic problem, and do not hide actual application defects beneath nicer wording.

Proof before release: Run the same fixtures on the released lockfile and on a separate upgrade branch. Then repeat the attempt under the default language and at least one translated locale. Compare the result class, stderr and exit status, and inspect whether any output file, report or cache was changed. Mark a test as passing only when the technical result and the reader’s understanding agree.

Chapter 11 — A multilingual acceptance matrix

English baseline: Use it to establish actual flags, commands, defaults, success behavior, and known error variants. Record this as a reference trace, not as the one correct grammatical form for every locale.
French: Look for long descriptions, distinction between a command and a suggestion, correct treatment of filenames and quantities, and errors that say whether a file is absent or invalid.
German: Check compound nouns, table widths, longer help lines and precise distinction between validation and execution. Confirm that examples still contain exact option names.
Japanese: Check CJK terminal cell widths, natural task explanations, non-Latin filenames, copied quotes and an unambiguous explanation of values versus placeholders.
Arabic: Check right-to-left prose beside left-to-right program tokens, numerals and paths. Verify that copied commands preserve byte order and the underlying command has not been visually rearranged.
Hindi and Tamil: Test complex-script rendering, longer instructional sentences, font availability and clear presentation of syntax fragments. Do not use romanization as a substitute for genuine localized guidance without product justification.
Spanish and Portuguese: Check regional variations, units, number formatting and whether translated verbs imply a read-only check or a write. Numeric argument syntax must remain what the program actually parses.

The matrix is a set of test questions, not evidence that these locales already ship with Elixir Optimus. The application owner must say which languages are supported, how they are selected, who reviews them and which environments are in scope. It is better to support a few languages accurately than to advertise many through untranslated dependency errors and untested scripts.

Chapter 12 — Twelve reader-focused practical exercises

Exercise 1: The specification is a contract

The purpose of this exercise is to make the specification is a contract understandable to someone who has not studied the library source. First, have a learner predict the effect of a safe invocation before executing it; write down the predicted input, output and any possible side effects. Then change the display language, not the command, and have a second learner repeat the prediction without reading the first answer. In HarborManifest, an illustrative shipping-manifest checker that reads a local CSV export without contacting a production service, the worked example is harbormanifest inspect shipments.csv –dry-run. Use sample inputs only, and keep a record of the version, locale, expected result, actual result and the exact sentence that caused confusion.

The decision at stake is this: An Optimus specification combines description strings with parser identity. The :name field identifies the program, while :description and :about explain it. Nested :subcommands carry their own options and purpose. Do not rewrite a working program’s supported command tree just because a localized paragraph sounds more natural. Inventory the actual parse combinations first, including aliases, hidden flags and default values. A reviewer should be able to explain why a misleading translation changes the operator’s decision, not merely say that two sentences sound different. If testing reveals an implementation bug, fix that separately and rerun the language review. A completed exercise leaves a small reproducible proof that the documentation matches the product.

Exercise 2: Positional argument names are not values

The purpose of this exercise is to make positional argument names are not values understandable to someone who has not studied the library source. Use an intentionally invalid command to examine recovery guidance. Preserve the typed tokens in the report, identify the exact rejection stage, and ask the learner to choose the next permitted action rather than merely translate the displayed error. In HarborManifest, an illustrative shipping-manifest checker that reads a local CSV export without contacting a production service, the worked example is harbormanifest inspect shipments.csv –dry-run. Use sample inputs only, and keep a record of the version, locale, expected result, actual result and the exact sentence that caused confusion.

The decision at stake is this: The :args list defines positional input. A value_name such as SOURCE is a display placeholder, not the filename typed by an operator; translating SOURCE may improve the help page while a source path itself remains untouched. A required input is still required in every language. Test absent positional arguments separately from nonexistent files, because one is a parse failure and the other is an application validation failure. A reviewer should be able to explain why a misleading translation changes the operator’s decision, not merely say that two sentences sound different. If testing reveals an implementation bug, fix that separately and rerun the language review. A completed exercise leaves a small reproducible proof that the documentation matches the product.

Exercise 3: Value-taking options need types

The purpose of this exercise is to make value-taking options need types understandable to someone who has not studied the library source. Create two local fixtures: one valid and one that violates the condition under discussion. Test each in the base language and a translated language, comparing the parser result and real files, not just the text on screen. In HarborManifest, an illustrative shipping-manifest checker that reads a local CSV export without contacting a production service, the worked example is harbormanifest inspect shipments.csv –dry-run. Use sample inputs only, and keep a record of the version, locale, expected result, actual result and the exact sentence that caused confusion.

The decision at stake is this: An Optimus :option can carry :parser, :default, :required and :multiple metadata. When a user passes –limit 20, the translated description may explain units and the allowed range, but the flag and value must still be recognized as configured. A custom parser can return {:ok, value} or {:error, message}; the application should treat a bad value as a failure even when an explanatory translation is available. A reviewer should be able to explain why a misleading translation changes the operator’s decision, not merely say that two sentences sound different. If testing reveals an implementation bug, fix that separately and rerun the language review. A completed exercise leaves a small reproducible proof that the documentation matches the product.

Exercise 4: Flags are switches, not sentences

The purpose of this exercise is to make flags are switches, not sentences understandable to someone who has not studied the library source. Review a narrow-terminal rendering and a copied command. Ask the learner to identify which components are executable grammar, which are placeholders and which describe behavior. Then paste the command into a disposable environment and verify the claim. In HarborManifest, an illustrative shipping-manifest checker that reads a local CSV export without contacting a production service, the worked example is harbormanifest inspect shipments.csv –dry-run. Use sample inputs only, and keep a record of the version, locale, expected result, actual result and the exact sentence that caused confusion.

The decision at stake is this: Optimus distinguishes flags from value-taking options. A Boolean dry-run flag changes program behavior without asking for another value. The short spelling -n and long spelling –dry-run are exact executable strings if defined that way. Never turn a localized phrase such as ‘without saving’ into an undocumented –without-saving option. Put that phrase next to the actual switch in prose. A reviewer should be able to explain why a misleading translation changes the operator’s decision, not merely say that two sentences sound different. If testing reveals an implementation bug, fix that separately and rerun the language review. A completed exercise leaves a small reproducible proof that the documentation matches the product.

Exercise 5: Subcommand paths need a separate map

The purpose of this exercise is to make subcommand paths need a separate map understandable to someone who has not studied the library source. First, have a learner predict the effect of a safe invocation before executing it; write down the predicted input, output and any possible side effects. Then change the display language, not the command, and have a second learner repeat the prediction without reading the first answer. In HarborManifest, an illustrative shipping-manifest checker that reads a local CSV export without contacting a production service, the worked example is harbormanifest inspect shipments.csv –dry-run. Use sample inputs only, and keep a record of the version, locale, expected result, actual result and the exact sentence that caused confusion.

The decision at stake is this: Optimus supports :subcommands with named specifications. A nested command can have a different positional argument sequence and valid flags from the top-level command. Map root help, inspect help and export help independently. A translation that describes export as available from the root when it actually lives under a subcommand misdirects readers; a path test must catch it. A reviewer should be able to explain why a misleading translation changes the operator’s decision, not merely say that two sentences sound different. If testing reveals an implementation bug, fix that separately and rerun the language review. A completed exercise leaves a small reproducible proof that the documentation matches the product.

Exercise 6: Parser return shapes must remain intelligible

The purpose of this exercise is to make parser return shapes must remain intelligible understandable to someone who has not studied the library source. Use an intentionally invalid command to examine recovery guidance. Preserve the typed tokens in the report, identify the exact rejection stage, and ask the learner to choose the next permitted action rather than merely translate the displayed error. In HarborManifest, an illustrative shipping-manifest checker that reads a local CSV export without contacting a production service, the worked example is harbormanifest inspect shipments.csv –dry-run. Use sample inputs only, and keep a record of the version, locale, expected result, actual result and the exact sentence that caused confusion.

The decision at stake is this: The documented parse signature includes successes with or without subcommand paths, errors with or without paths and a version result. Do not assume that every return is a two-element tuple. Build error handling that distinguishes help or version behavior from genuine invalid input and from success. A localized wrapper should be added only after the parser’s actual result shapes have been tested. A reviewer should be able to explain why a misleading translation changes the operator’s decision, not merely say that two sentences sound different. If testing reveals an implementation bug, fix that separately and rerun the language review. A completed exercise leaves a small reproducible proof that the documentation matches the product.

Exercise 7: Error localization requires ownership

The purpose of this exercise is to make error localization requires ownership understandable to someone who has not studied the library source. Create two local fixtures: one valid and one that violates the condition under discussion. Test each in the base language and a translated language, comparing the parser result and real files, not just the text on screen. In HarborManifest, an illustrative shipping-manifest checker that reads a local CSV export without contacting a production service, the worked example is harbormanifest inspect shipments.csv –dry-run. Use sample inputs only, and keep a record of the version, locale, expected result, actual result and the exact sentence that caused confusion.

The decision at stake is this: Error text from Optimus may be produced by the dependency, while invalid-file and permission errors may come from application code. Keep the ownership boundary visible. If a dependency diagnostic cannot be replaced safely through a documented extension, the application can add a localized next-step explanation rather than claiming the parser itself supports a particular locale. Avoid fragile string substitution of upstream error paragraphs. A reviewer should be able to explain why a misleading translation changes the operator’s decision, not merely say that two sentences sound different. If testing reveals an implementation bug, fix that separately and rerun the language review. A completed exercise leaves a small reproducible proof that the documentation matches the product.

Exercise 8: Custom parsers preserve meaning

The purpose of this exercise is to make custom parsers preserve meaning understandable to someone who has not studied the library source. Review a narrow-terminal rendering and a copied command. Ask the learner to identify which components are executable grammar, which are placeholders and which describe behavior. Then paste the command into a disposable environment and verify the claim. In HarborManifest, an illustrative shipping-manifest checker that reads a local CSV export without contacting a production service, the worked example is harbormanifest inspect shipments.csv –dry-run. Use sample inputs only, and keep a record of the version, locale, expected result, actual result and the exact sentence that caused confusion.

The decision at stake is this: A custom parser is a function from an input string to a typed success or error result. It may check a date, decimal, enumerated status or manifest identifier. Translation cannot repair a parser that accepts unsafe inputs. Check the documented data format, whether decimal separators are accepted, and the output type. Then localize only its human-facing explanation, testing both valid and malformed samples. A reviewer should be able to explain why a misleading translation changes the operator’s decision, not merely say that two sentences sound different. If testing reveals an implementation bug, fix that separately and rerun the language review. A completed exercise leaves a small reproducible proof that the documentation matches the product.

Exercise 9: Global options affect all subcommands

The purpose of this exercise is to make global options affect all subcommands understandable to someone who has not studied the library source. First, have a learner predict the effect of a safe invocation before executing it; write down the predicted input, output and any possible side effects. Then change the display language, not the command, and have a second learner repeat the prediction without reading the first answer. In HarborManifest, an illustrative shipping-manifest checker that reads a local CSV export without contacting a production service, the worked example is harbormanifest inspect shipments.csv –dry-run. Use sample inputs only, and keep a record of the version, locale, expected result, actual result and the exact sentence that caused confusion.

The decision at stake is this: The :global option attribute matters when a setting such as –locale should be recognized across nested commands. Its exact scope must be tested, not inferred from placement in an examples table. If –locale is allowed only before a subcommand, explain the correct order. Verify that choosing a language for output does not silently alter argument grammar or load an unrelated configuration file. A reviewer should be able to explain why a misleading translation changes the operator’s decision, not merely say that two sentences sound different. If testing reveals an implementation bug, fix that separately and rerun the language review. A completed exercise leaves a small reproducible proof that the documentation matches the product.

Exercise 10: Hidden flags and support instructions

The purpose of this exercise is to make hidden flags and support instructions understandable to someone who has not studied the library source. Use an intentionally invalid command to examine recovery guidance. Preserve the typed tokens in the report, identify the exact rejection stage, and ask the learner to choose the next permitted action rather than merely translate the displayed error. In HarborManifest, an illustrative shipping-manifest checker that reads a local CSV export without contacting a production service, the worked example is harbormanifest inspect shipments.csv –dry-run. Use sample inputs only, and keep a record of the version, locale, expected result, actual result and the exact sentence that caused confusion.

The decision at stake is this: The :hide attribute can suppress a command from ordinary help. This may be reasonable for experimental or internal switches; it does not make the switch safe to change casually. Translation teams should not surface hidden maintenance flags in public examples without an explicit product decision. Help content should guide readers toward supported workflows and declare when a task needs privileged access. A reviewer should be able to explain why a misleading translation changes the operator’s decision, not merely say that two sentences sound different. If testing reveals an implementation bug, fix that separately and rerun the language review. A completed exercise leaves a small reproducible proof that the documentation matches the product.

Exercise 11: Unknown arguments are a deliberate policy

The purpose of this exercise is to make unknown arguments are a deliberate policy understandable to someone who has not studied the library source. Create two local fixtures: one valid and one that violates the condition under discussion. Test each in the base language and a translated language, comparing the parser result and real files, not just the text on screen. In HarborManifest, an illustrative shipping-manifest checker that reads a local CSV export without contacting a production service, the worked example is harbormanifest inspect shipments.csv –dry-run. Use sample inputs only, and keep a record of the version, locale, expected result, actual result and the exact sentence that caused confusion.

The decision at stake is this: The specification includes :allow_unknown_args and :parse_double_dash options. Those controls can affect how inputs are interpreted. A reader may reasonably believe that text after — is a filename even when the configured parser differs. Write examples that reflect the actual settings, and test both unknown flags and the — separator without changing acceptance rules during localization. A reviewer should be able to explain why a misleading translation changes the operator’s decision, not merely say that two sentences sound different. If testing reveals an implementation bug, fix that separately and rerun the language review. A completed exercise leaves a small reproducible proof that the documentation matches the product.

Exercise 12: Versioned technical accuracy

The purpose of this exercise is to make versioned technical accuracy understandable to someone who has not studied the library source. Review a narrow-terminal rendering and a copied command. Ask the learner to identify which components are executable grammar, which are placeholders and which describe behavior. Then paste the command into a disposable environment and verify the claim. In HarborManifest, an illustrative shipping-manifest checker that reads a local CSV export without contacting a production service, the worked example is harbormanifest inspect shipments.csv –dry-run. Use sample inputs only, and keep a record of the version, locale, expected result, actual result and the exact sentence that caused confusion.

The decision at stake is this: The documented surface was checked against Optimus v0.6.1, whose Hex package listing was updated in February 2026. An application may pin a different version, so its lockfile and tests outrank a tutorial’s example. When a translation changes after a dependency upgrade, compare generated help, parse failures and subcommand handling before declaring the release compatible. A reviewer should be able to explain why a misleading translation changes the operator’s decision, not merely say that two sentences sound different. If testing reveals an implementation bug, fix that separately and rerun the language review. A completed exercise leaves a small reproducible proof that the documentation matches the product.

Chapter 13 — Frequently asked questions

Does Optimus translate all its own error messages?

Do not assume that it does. The documented parser exposes structured results and human-facing specification strings. Where dependency-owned errors lack a documented locale override, add clearly marked application guidance rather than an invented translation hook.

For HarborManifest, an illustrative shipping-manifest checker that reads a local CSV export without contacting a production service, settle this with a real command and a controlled fixture rather than intuition. A helpful answer names the stable part of the subcommand path, option names, flag aliases, parsed argument atoms, custom parser return types and result shape, identifies the reader-facing explanation, and shows how to verify the outcome without production data. Where support depends on package version, test the installed release rather than assuming universal behavior.

Should command names change in each language?

Usually not for an existing command-line interface: changing command names affects scripts and documentation. A deliberate alias strategy is possible only after engineering implements and tests it, and then every translated example must say which names are genuinely accepted.

Can a locale option change decimal syntax?

Only if a documented and tested application parser intentionally supports that behavior. Display conventions and accepted input grammar are separate. For shipping quantities, silently accepting culturally ambiguous numbers can create a material reconciliation error.

Is a translated value_name a new argument?

No. A value_name in help is a display label. The caller supplies a value such as a path, an integer or a date. Explain the difference with a valid example and check that an operator will not literally type the placeholder.

What if a translation is longer than the help column?

Use width tests and sensible wrapping without truncating a safety warning. Terminal widths differ, and an RTL or CJK rendering can break alignment even where the Unicode string itself is correct.

How should errors be compared across languages?

Compare error category and recovery action, not the literal sentence. The same invalid command should fail in each locale with consistent exit behavior, leaving files unchanged and producing an understandable next step.

Why test subcommands separately?

Because flags, positional arguments, defaults and error paths may differ by branch. Root-level help can look perfect while a nested command accepts the wrong input, or explains a flag that is not available at that level.

What belongs in a release checklist?

Record the pinned dependency, supported locale list, fallback policy, valid and invalid fixtures, terminal captures, native-language review, behavior assertions and an owner responsible for correcting regressions.

Chapter 14 — A four-week implementation and review plan

Week 1: inventory the interface

Capture root help, nested help, sample invocations and errors from the released application. Map every visible message to its owner, list supported commands, record exact dependency and runtime versions, and classify input values separately from strings meant for translation. Choose two real reader tasks. A good result for this week is a short baseline document with no uncertainty about what the program actually accepts.

Applied to Elixir Optimus, this week’s exit condition must be checked in both code and language. Use harbormanifest inspect shipments.csv –dry-run with a disposable fixture, retain the original command spellings and compare the intended operation with the observed result. Do not advance merely because the text sounds polished; advance when a learner can predict and verify what the tool will do.

Week 2: draft and integrate language support

Choose supported locales and a fallback policy. Translate complete tasks, warnings and recovery instructions instead of isolated words, preserving fixed tokens. Connect application-owned strings to catalog keys or another version-appropriate system, and leave library-owned text identified where override support is unavailable. Ask developers to review every promise about writes, permissions, defaults, file formats and errors.

Week 3: behavior and comprehension testing

Run successful and invalid input fixtures under each chosen locale. Compare parsed values, stdout/stderr channels, exit statuses and output effects; also test non-ASCII paths, terminal width and copied code snippets. Ask native-language reviewers to complete the two original tasks without English guidance and record where decisions fail. Correct both functional and wording faults; re-run the baseline tests.

Week 4: publish, monitor and maintain

Finalize a short quick-start, supported-version note, option reference, troubleshooting guide and fallback disclosure. Publish only tested examples, with a release checklist signed by engineering and language reviewers. Keep the command contract versioned, record known limitations and add regression fixtures for defects found during real support requests. A translation is complete when a reader can finish the task safely, not when the catalog has no empty cells.

Chapter 15 — Professional standard and next step

The best multilingual command-line documentation is boring in the most useful sense: the examples execute as written, the parser behaves consistently, the outputs say what happened and the reader knows how to repair a failure. With Elixir Optimus, translation quality depends on respecting how the framework defines commands and values while giving humans accurate descriptions of those same structures.

Start from one small task in HarborManifest, an illustrative shipping-manifest checker that reads a local CSV export without contacting a production service, verify it in the default language, translate its complete explanation and test the same action again. Expand to errors, more commands and additional locales only when earlier behavior stays stable. That sequence makes multilingual support maintainable for new contributors, reviewers and users who cannot ask the original developer what a sentence was supposed to mean.