Translate Like a Pro | 8720 — GNU Guile getopt-long Localization, Option Grammar, Predicates, Errors and Unicode CLI QA

GNU Guile getopt-long localization is the practical work of translating the instructions, help, diagnostics and examples of a Scheme command-line program without corrupting the option grammar that getopt-long parses. The Guile procedure accepts a command-line string list and an option specification describing long names, optional short equivalents, required values and optional predicates. The parser provides structured results and reports invalid invocations; your application must still decide how readers request help, which language to show and how to explain a safe correction.

Imagine a read-only Guile program called AtlasRecords that counts records in a named file. Someone in Brazil wants Portuguese help, someone in Turkey has a path with a dotted capital letter, and someone using an Arabic terminal needs to copy a command containing --input and --limit. The executable option names must remain stable even when the supporting prose changes. People searching for GNU Guile getopt-long help localization, option grammar, multilingual Scheme CLI examples or translated argument errors need clear examples that can actually run.

The essential rules are to retain long and short option tokens, preserve which options require values, distinguish a parser predicate failure from business validation, localize complete user-facing messages rather than code, and test Unicode filenames across shells and terminals. Start with a small program, capture valid and invalid input, review translation with native speakers and test each documented repair. This guide explains that sequence from the underlying parser contract to robust multilingual release quality.

Know the option grammar before localizing descriptions.
Keep --option and -o stable unless real aliases exist.
Test required options, value-bearing flags, predicates, Unicode paths, and two-stage parsing.
Validate translated instructions by copying their commands into a real terminal.

Chapter 1 — The Guile parser and the reader’s mental model

1. A parser for options, not a full translation framework

The documented getopt-long procedure consumes args and grammar. Its input list includes the program name, which the parser skips. Each grammar entry names a long option as a Scheme symbol and may attach properties such as single-char, required?, value or predicate. The returned option structure can be queried by application code. That is the machine-facing model. Choosing a locale, preparing a help page and explaining a file error are independent design responsibilities.

A useful way to verify this distinction is to write down the exact token Guile accepts, the sentence that describes its meaning and the visible outcome of one valid and one invalid invocation. When those three pieces are consistent, readers gain a method rather than a fragile memorized example. When they disagree, find which layer is responsible before changing the translation. A correction to the message cannot make an undeclared option valid; a correction to grammar can break scripts even if the documentation still looks fluent.

2. The grammar should be inspected before any sentence is translated

A Guile definition such as ((input (single-char #\i) (value #t)) (limit (value #t)) (verbose (single-char #\v))) expresses a particular interface. Input and limit accept values; verbose is a switch. Translating the natural-language label “input file” does not grant permission to rename the symbol input, the command token --input or the short alias -i. If aliases are introduced, test them as a software feature and document them as real options, not as editorial synonyms.

3. Three different meanings of required

An option may be mandatory in the declared grammar through required?. Another option may require a value when used through value #t, while still being optional overall. Finally, the application may require a file to exist only after parsing succeeds. A multilingual guide that mixes these meanings sends readers to the wrong fix. The word ‘required’ must always answer ‘required to do what?’ and ‘checked by which part of the program?’.

4. Predicates validate strings, not natural language

For options that take values, a grammar predicate can reject an argument when its procedure returns false. For instance, the application may use a predicate to accept only a defined set of machine-readable modes. A translated description can name these modes in the reader’s language, but the accepted values remain exactly those tested by the program. Do not suggest that a locale-dependent synonym is accepted unless the predicate or later conversion layer explicitly handles it.

5. The first command argument is special

Because getopt-long expects a list resembling (command-line), including the executable name, the parser ignores the first element. A custom test that passes only the options can accidentally lose the first option. This is a subtle but important educational point: when testing the parser directly, supply a synthetic program-name element. A translated guide must not present a broken unit test as proof that an alias is valid or invalid.

6. When option processing stops

Guile’s #:stop-at-first-non-option parameter changes parsing when a non-option word is encountered. It matters for two-level command designs with global flags and a subcommand whose options belong to the subcommand. Translation does not change that behavior. A reader should understand which layer owns --help, when a word is interpreted as a command and when a string is a value. Test the exact split rather than making assumptions based on a familiar CLI from another language.

7. Help text belongs to the program

The parser can reject unknown options, omitted values and failing predicates. It is not a complete internationalization solution for the application’s own help. Write explicit help messages, label literal tokens consistently, separate standard output from errors and choose a documented language policy. The language choice itself should not depend on translated parsing grammar unless the implementation deliberately supplies real aliases. This protects existing scripts and allows readers to follow the same commands regardless of their spoken language.

8. What to record in a release baseline

Save the Guile version, the option grammar, valid commands, invalid commands, stdout, stderr and exit status. Use harmless fixtures so documentation tests cannot modify user files. For Unicode verification create a real file named with accented letters or non-Latin characters and prove that the value reaches application code unchanged. The baseline gives translators and developers a shared set of facts when a sentence appears natural but the program behaves differently.

Chapter 2 — A minimal parser that reveals its values

(use-modules (ice-9 getopt-long))
(define grammar
  '((input (single-char #\i) (value #t))
    (limit (value #t))
    (verbose (single-char #\v))))
(define options (getopt-long (command-line) grammar))
(display (option-ref options 'input "none"))
(newline)
(display (option-ref options 'limit "20"))
(newline)
(display (option-ref options 'verbose #f))
(newline)

;; Example: guile atlas-records.scm --input "café.csv" --limit 5

This minimal script is a diagnostic rather than a completed file-processing tool. It prints what the parser returns and does not open the supplied file. That makes it ideal for separating the command grammar from later behavior. Confirm syntax and actual output on your supported Guile release before repurposing the example. A production application should still validate file existence, value ranges and permitted operations after a successful parse, with clear translated failure messages for those later checks.

Try the script with an ordinary ASCII path, then a Unicode filename, an unknown option and a missing option value. Do not rely on only one terminal or one visual screenshot. Record exactly what Guile receives, what the selected shell passed in and whether the failure originated in the parser or the application. The same truth table can guide review for Japanese, French, Arabic or any other supported language.

Chapter 3 — Thirty investigations that expose real translation failures

Investigation 1: A help page invents a translated long option

The writer replaces --input with a word that means input in another language, even though the grammar contains only the input symbol. The translated example is now invalid.

Keep executable tokens exact and translate the surrounding description. If aliases are wanted, add them with a compatibility policy rather than disguising them as documentation.

Paste the guide’s example in the supported shell and check that the returned input value is correct.

For this case, keep the translation review tied to a reproducible invocation. Record the exact Guile version, input vector, option grammar, chosen locale, outcome and any difference from the documented intention. Then ask a fluent reader to decide what action to take without seeing an English original. If their decision would fail, improve the explanatory sentence or the underlying software behavior at the layer that is actually responsible. Do not trade accurate recovery advice for a shorter phrase that merely looks more polished.

Investigation 2: An option requires a value but the example omits it

The grammar says (value #t) for limit. A guide shows --limit alone and describes the option as enabling a mode.

Say explicitly that a value follows the flag, and include a complete numeric example. Avoid implying that a flag with a required argument is Boolean.

Run missing-value and valid-value cases; verify the error identifies the absent argument, not a missing entire option.

Investigation 3: Required option and required argument are confused

(required? #t) means the option itself must occur. That is different from (value #t), which means an option requires a value when present.

Separate those concepts in prose and draw two miniature command forms so readers can see omission versus an incomplete value.

Test a missing mandatory option, a present option without its value, and a complete invocation separately.

Investigation 4: A short option alias is mistranscribed

The Scheme grammar uses (single-char #\i), but the public guide prints a visually similar non-ASCII character or an uppercase I.

Treat the alias as a literal, case-sensitive token. Use monospace styling and check visually confusable characters with a code-point inspection.

Run -i with a harmless fixture and compare it against the suspicious glyph that appeared in review.

Investigation 5: The first argument disappears in a unit test

An engineer passes the list ("--input" "x.csv") directly to getopt-long. Guile treats the first element as the program name and begins parsing at the second.

Show test inputs with a synthetic program name and explain why (command-line) already includes it during a normal launch.

Repeat the test with ("atlas-records" "--input" "x.csv") and compare the returned option values.

Investigation 6: An unknown option is described as a file error

The user types --inpt, which is absent from the grammar. A localized error says that the specified file could not be opened.

Classify parse failures before running application file logic; explain that the option spelling was not recognized and show the supported form.

Test a misspelled flag and a real nonexistent filename. Their diagnoses must point to different repairs.

Investigation 7: A predicate error is mistaken for a number format error

The option value is a string that a predicate rejects because the mode is unsupported. The translated text wrongly claims the text cannot be converted to a number.

Name the allowed set of machine-readable values and say the requested value is outside that set, without implying a conversion that did not occur.

Provide one accepted mode and one rejected mode, then verify exactly which predicate or application check fails.

Investigation 8: Optional values are treated as universally portable

Guile supports an optional value setting in its grammar, but users assume every position and spelling works like a required value.

Document the tested invocation form and avoid transferring behavior from GNU C getopt or a different Scheme implementation.

Exercise the optional-value flag with no value, an explicit value and an adjacent positional, recording observed parsing.

Investigation 9: A first non-option changes which grammar applies

With #:stop-at-first-non-option #t, the parser stops at a subcommand word. The localized guide incorrectly claims that later global options are still handled by the first pass.

Teach global and subcommand options as separate stages with a clear example of the boundary and the next parser invocation.

Trace the words left for the second stage and compare correct, misplaced and unknown flags.

Investigation 10: The double-dash marker is explained incorrectly

A reader uses -- to stop option interpretation, but the article says the marker is passed as an ordinary filename.

Explain the separator’s documented effect and distinguish the marker from following positional strings, especially filenames starting with a dash.

Run a fixture beginning with a hyphen and verify what the application receives after the separator.

Investigation 11: The help sentence is shorter but misleading

A translator omits a condition such as ‘only before a subcommand’ to make a long sentence elegant. The resulting claim is false for a two-stage parser.

Restore the condition even when the target language needs an extra sentence. Favor accurate instructions over a compact but incomplete label.

Ask a reviewer to decide whether a global flag after a subcommand will work using only the localized text.

Investigation 12: A filename containing spaces becomes two arguments

The guide demonstrates final report.csv without shell quoting. The shell splits it before Guile can interpret it as a value.

Document correct quoting for the supported shell and preserve the real filename as user-supplied data.

Pass one quoted path and one unquoted path, and record the argument list visible to Guile.

Investigation 13: A multilingual path fails at the filesystem boundary

The parser correctly accepts a Unicode string, but the application cannot find a file on disk because of differing normalization or an earlier encoding conversion.

Separate successful parsing from file opening. Show a real fixture, compare the received characters with the path stored on disk and avoid automatically translating filenames.

Test accented and CJK filenames with one existing and one deliberately absent file.

Investigation 14: Right-to-left punctuation appears reordered

An Arabic paragraph combines --input=files/تقرير.csv with prose. The visual line order becomes confusing although the string may remain intact.

Present the command in a dedicated code block and validate both copy order and rendered display in an actual right-to-left environment.

Observe the characters pasted into the terminal and compare them to the expected byte sequence.

Investigation 15: A shell wildcard expands before parsing

An example uses an unquoted glob for many files, yet the guide says getopt-long performs the filename selection.

Explain the shell’s expansion layer and what arguments remain for the Guile program; show a deterministic fixture when teaching parsing.

Test with one and several matching files and inspect the argument list the program actually receives.

Investigation 16: A zero-length value looks like omission

The invocation supplies --input=. The parser may receive a value, but application logic should reject an empty path with a more precise explanation.

Distinguish absence, empty string and nonexistent file. Localize each recovery step independently.

Run all three conditions, checking that the suggested corrective action matches what the user supplied.

Investigation 17: A boolean switch is presented with an invented value

The grammar declares verbose with no value property, but the guide shows --verbose=true as though a string value were expected.

Show the flag alone and explicitly describe its effect. If a value-bearing switch is wanted, implement and test a different grammar.

Compare omitted and present verbose, and deliberately pass an attached value to verify error behavior.

Investigation 18: A short-option cluster is assumed to work

A tutorial claims that combining short flags always behaves the same way as a familiar shell utility. Different parsers and value-bearing options can change the interpretation.

Use the Guile documentation and a tested example rather than importing assumptions from another CLI framework.

Try two independent short flags and a short option requiring a value; document only the successful combinations.

Investigation 19: The translated diagnostic leaks private paths

An example support transcript repeats a real user’s home directory and confidential report filename. The information is irrelevant to the parsing lesson.

Use fictitious fixture paths in public text and redact sensitive details from bug reports without suppressing the error category.

Review terminal transcripts and screenshots for names, home directories and secret options before publication.

Investigation 20: A non-English digit is assumed to pass a predicate

The reader supplies a visually numeric value using a local numeral system, but the application predicate expects a particular string or a downstream conversion format.

State the accepted input representation rather than promising universal numeral recognition. If broader input is required, design and test its normalization intentionally.

Test ASCII digits, the target locale’s digits and a malformed value as separate inputs.

Investigation 21: Option descriptions become stale after a code change

A developer changes the grammar so an option is no longer mandatory, while translated help still says it is required.

Review the live grammar alongside each language’s help strings whenever properties change. Make the requirement visible in both tests and editorial review.

Test omission against the new release and record whether the program rejects or accepts it.

Investigation 22: An example with a semicolon behaves differently across shells

The documentation includes shell metacharacters in unquoted illustrative text. The command is split or interpreted before Guile receives the intended value.

Keep examples simple and quote shell-sensitive values when necessary, explaining that the parser only sees arguments delivered by the shell.

Paste into each supported shell and record the exact list passed to getopt-long.

Investigation 23: Pluralization is handled by a string suffix

The application reports one record and many records, but translation adds an English-style final letter to a fixed message.

Use full target-language messages selected by number category and keep counts intact as data. A label alone is insufficient for some languages.

Check zero, one, two and several records and review the final sentence in context.

Investigation 24: The same option has two conflicting descriptions

One chapter says --limit caps displayed records while a translated error says it caps imported records. The contradiction changes user expectations.

Write one unambiguous semantic definition and make code, help and recovery messages use it consistently.

Compare the actual program result at limit one and limit ten, then review every sentence that names the option.

Investigation 25: The locale fallback is undocumented

A program has Portuguese help but leaves low-frequency parser errors in English. The guide promises that all messages are translated.

Tell readers which messages the application controls and which may originate in Guile; define and test a fallback policy instead of claiming full coverage.

Force an unsupported locale and trigger a parser error to inspect exactly what users see.

Investigation 26: The program accidentally writes results during a help test

A help verification invokes a command that also performs an output operation because tests reuse production paths.

Use read-only fixtures or a dry-run execution layer during translation QA and confirm no side effects occur before inspecting text.

Run the fixture in a temporary directory and verify that only expected files and streams change.

Investigation 27: The translated example is not copyable

Typographic quotes, nonbreaking spaces and visually similar dashes enter the final article after a web editor formats the command.

Protect code snippets and test commands extracted from the rendered publication, not only the original draft.

Copy the code from the published page into the documented terminal and confirm that the Guile program accepts it.

Investigation 28: A bug report lacks grammar and version context

A report merely says ‘French Guile help is wrong’. It omits the Guile version, defined option grammar, shell, failing input and actual output.

Provide a compact reproduction containing those details, plus expected message intent and observed stream or exit behavior.

Ask a second engineer to reproduce the defect without access to the first person’s development environment.

Investigation 29: An error message changes exit status expectations

A translated paragraph describes a fatal parse failure as a normal warning, while automated callers depend on unsuccessful invocations being detectable.

Align prose with application behavior and deliberately set or preserve appropriate nonzero exit status when catching failures.

Capture output and status with both a valid command and an invalid predicate value; make the distinction visible to readers.

Investigation 30: A two-stage tool confuses the subcommand owner

The first parser handles global options and the second handles subcommand-specific ones, but a localized page mixes their flags into one undifferentiated example.

Draw the command as program, global options, subcommand and subcommand options, and identify which grammar validates each part.

Execute the sample through both stages and verify that an option cannot silently migrate to the wrong owner.

Chapter 4 — Three complete applied scenarios

An international data-science lab

A research lab uses the same Guile utility to inspect nonconfidential tabular samples in several countries. Analysts type a stable --input flag, while the meaning and examples are explained in their own languages. In the Portuguese documentation, a value-bearing option should not look like a Boolean switch. In the Japanese documentation, a UTF-8 filename should not be silently romanized. In the Arabic documentation, a copied command must preserve option order despite right-to-left typography. Test one successful and one rejected invocation per locale, then ask each analyst to explain what the rejection means.

End the case study with evidence: the exact command, the resulting parsed values, the error status where relevant and a note about the reader’s interpretation. A strong localized article supports a decision the reader can verify, not merely a good-sounding explanation. Keep data paths invented in publication examples, and keep both success and failure captures available to future maintainers.

A two-level command with subcommands

A tool accepts global configuration followed by a word such as inspect and then subcommand-specific flags. The first getopt-long call uses #:stop-at-first-non-option #t; the application selects the subcommand and hands the remaining tokens to a second parser. The guide must make this boundary visible because even perfect translation cannot rescue a flag parsed at the wrong level. Prepare a diagram of the argument sequence, show one valid command and one misplaced option, and ensure that error messages name the layer that rejected the input.

A support report after an invalid mode

A user chooses a machine-readable mode that is absent from the allowed set. The parser or a later predicate rejects it, yet the interface should not imply that the file is missing or corrupted. The translated failure should state that the requested value is unsupported, display the accepted values exactly as the program understands them and suggest a safe retry. Support logs should include the parser version and option grammar but redact private filenames. Reproduce the failure on a clean machine and ask a native-language reviewer to carry out the retry independently.

Chapter 5 — Frequent questions from Guile CLI maintainers

What does `getopt-long` translate for me?

Nothing automatically. It parses declared command-line options. You implement reader-facing help and localization behavior around the resulting values and failures.

Apply this guidance to the concrete grammar and runtime version of the tool in question. Test the documented invocation rather than assuming another programming language’s option parser follows the same conventions.

Does `(value #t)` mean the option must always appear?

No. It means that an option, when used, takes a value. (required? #t) is a separate declaration concerning whether that option must be supplied.

Why must my test include the program name?

The documented args list contains the program name first, and getopt-long skips it. A manually constructed list without that element can be parsed incorrectly.

Can I translate short and long options?

Only if your program really implements those aliases. A translated explanatory label is not an executable alias.

How do I handle subcommands?

A two-stage parser can stop at the first non-option, then parse the subcommand’s remaining arguments with a separate grammar. Test the boundary.

What if Guile emits an error outside my message catalog?

Document the actual error source and supported fallback. Do not claim an internal parser diagnostic is translated unless the application catches and correctly presents it.

Should user filenames be translated?

No. Treat filenames and paths as data supplied by the user. Translate instructions about where to provide them, not the names themselves.

What proves quality?

A reader follows the target-language page, uses a valid command, recognizes an invalid one and recovers without needing English-only undocumented knowledge.

Chapter 6 — Four weeks from first inspection to reliable localized help

Week 1

Week one is about truth rather than prose. Inventory option names, short aliases, predicates, required flags, options requiring values, positional arguments and subcommand boundaries. Build a harmless parser fixture and record valid and rejected inputs. Decide which text belongs to Guile and which is written by the application. Keep the real published command tokens unchanged.

The exit requirement is a demonstrated reader action: a correctly executed invocation, a correctly interpreted rejection and no ambiguity between a program token and translated explanatory words. Keep the evidence with the release so the next maintainer can verify it without reconstructing private conversations.

Week 2

Week two is for the language layer. Choose one additional locale, write complete descriptions, helpful recovery instructions and one copyable command for each important task. Have a reviewer explain what action they believe the sentence instructs. Pay special attention to required versus optional, to numeric values and to terminology for parse failure versus file-processing failure.

Week 3

Week three is for hostile but realistic input. Run Unicode paths, spaces, empty values, unknown aliases, conflicting flags, failing predicates and subcommand split points. Capture standard output and standard error separately, verify status codes and inspect narrow or right-to-left terminal layouts. File each disagreement between words and behavior as a reproducible bug.

Week 4

Week four is for external readers and maintenance. Ask someone unfamiliar with the English documentation to complete one normal task and recover from two failures. Paste-test every example from the published page, freeze the tested Guile version and record the glossary and fallback behavior. When the application grammar changes, rerun the entire command and message suite instead of updating just the headline.

Chapter 7 — Meaning and executable identity can coexist

The aim of GNU Guile getopt-long localization is not to produce a different command grammar for every market. It is to make one coherent grammar intelligible to more people. The most important decisions are mundane but powerful: preserve the token the parser recognizes, explain when a value is required, separate a predicate rejection from a missing file and show the exact action that repairs the problem. Readers should be able to trust the translated message because an actual invocation proves its claims.

Technical translation succeeds when a new reader can act independently. Test the release with people who do not already know the software. Let their confusion guide the next improvement, and keep the documentation synchronized with the option grammar as the program grows. A clear line between machine syntax and human explanation protects both accessibility and backward compatibility.