Translate Like a Pro | 8790 — Ada GNAT.Command_Line Localization, Getopt, Define_Switch, Display_Help and Unicode QA

Ada GNAT.Command_Line localization means making an Ada program’s command-line help, switch explanations, diagnostics and examples understandable in another language while preserving the switch grammar that GNAT.Command_Line actually parses. Readers searching for Ada Getopt translation, Define_Switch help, Display_Help, long switches, Invalid_Switch, Invalid_Parameter and Unicode command-line testing need a practical distinction between a human explanation and a machine-recognized token.

Imagine a small, read-only inspection program called ledgercheck. An engineer runs ledgercheck -v –report input.txt on a working terminal, while a colleague in another country needs Spanish or Japanese guidance. The option names, executable spelling and file arguments are not interchangeable with natural language. Translate why an option exists and what to do after a failure; do not quietly change -v or –report in copied commands unless a new compatible alias is actually implemented.

The reliable approach starts with GNAT.Command_Line’s two patterns: direct Getopt scanning and configured switches using Command_Line_Configuration, Define_Switch and Display_Help. Then it adds a message catalogue, a clear distinction between syntax and prose, controlled handling of exceptions, tests across target platforms and a release checklist. The sections below move from first principles to diagnostic cases and finished-user verification.

Parser syntax stays literal; human explanations can be localized.
Choose a documented Getopt or Command_Line_Configuration approach.
Review error classes, paths, display encoding and release evidence separately.
Test published examples against the built program.

Chapter 1 — Understand the Ada command-line contract

What the package does and does not do

GNAT.Command_Line is an Ada-specific facility for parsing switches and arguments. It is not a general translation engine. In a simple Getopt loop, a switch specification declares what the parser accepts; the program then handles the returned character, Full_Switch and any Parameter. When using a Command_Line_Configuration, definitions can connect declared switches to help content and, in several overloads, to application variables. Neither arrangement automatically translates the application’s own explanations, output records or business rules. That boundary is the foundation of a dependable localized command-line program.

A grammar is a contract, not a sentence

Consider an invocation such as ledgercheck -v –report input.txt. The binary name, -v, –report and the positional file have defined parser roles. A translator may write a natural-language description of the report, but a help example must still show a command that the shipped program accepts. If the product intentionally adds alternate long switch spellings, treat them as API changes, document them explicitly and test both old and new forms. Do not let a revised manual become the only place where an unimplemented option appears.

Two useful starting models

The direct Getopt model suits small programs whose scanning and switch dispatch fit in a short loop. The configuration model supports Define_Switch, optional long aliases, help strings, sections, typed storage and Display_Help. These are not magic substitutes for product design. Choose one arrangement that the team can maintain and map its exact syntax to a small translation inventory. Keep the public usage sentence, the labels for arguments and the diagnostic messages together so a reviewer can trace them to actual code.

Treat help as an interface

A useful help page answers four questions in sequence: what the program does, which command is valid, what each option changes and how to recover from common mistakes. Ada users may see Display_Help output defined from a Command_Line_Configuration, or an application-specific hand-written help renderer. Either way, a reader should discover defaults, whether an argument is mandatory and what a sample invocation would actually do. A literal translation that hides those details is less useful than a clear revision that preserves semantics.

Chapter 2 — A bounded Ada example and its limits

The following teaching fragment demonstrates the direct scanning idea. It is intentionally small, has no filesystem side effects and prints state only. It omits positional-argument processing, a full multilingual message catalogue, output-stream policy and a sophisticated exit-code model. It is therefore a learning artifact rather than a production-ready template. The exact GNAT.Command_Line specification supplied with your compiler remains authoritative for signatures and options.

-- Schematic Ada pattern for understanding switch dispatch.
-- Confirm exact signatures against the GNAT runtime in use.
with Ada.Text_IO;           use Ada.Text_IO;
with GNAT.Command_Line;     use GNAT.Command_Line;
with ASCII;

procedure Ledgercheck is
begin
   loop
      case Getopt ("v o:") is
         when ASCII.NUL => exit;
         when 'v' => Put_Line ("Verbose mode selected");
         when 'o' => Put_Line ("Output path: " & Parameter);
         when others => null;
      end case;
   end loop;
exception
   when Invalid_Switch =>
      Put_Line ("Unrecognized option; check --help");
   when Invalid_Parameter =>
      Put_Line ("An option requires a value; check --help");
end Ledgercheck;

The simple pattern illustrates a valuable separation: the declaration tells Getopt what is legal; Put_Line text explains what happened. In a multilingual program, a catalogue can supply such explanations without changing Getopt’s accepted characters. To produce configured help rather than a hand-written message, use Command_Line_Configuration, appropriate Define_Switch overloads and Display_Help after verifying them against your GNAT distribution. Keep the switches and any command examples synchronized with that configuration.

Chapter 3 — Help, defaults, errors and Unicode as one user journey

Keep error sources separate

An Invalid_Switch exception points to a switch that the parser did not accept; Invalid_Parameter is associated with an option’s missing or malformed argument under the applicable parsing form. An application can also reject a perfectly parsed file path because the requested file does not exist, or a value because it violates a domain rule. Those are different errors and deserve different recovery advice. The translator should not invent claims about which layer failed. A diagnostic contract can identify source, safe user input and one next step.

Unicode is a runtime issue too

A Unicode-friendly message catalogue does not guarantee that a terminal will display every character correctly or that filenames will round-trip through a particular operating system and compiler runtime. Ada.Strings.Unbounded, UTF-8 byte strings, environment encoding and platform path APIs must be considered according to the build. Avoid assuming every Ada String is automatically a Unicode scalar sequence. Test the actual binary with filenames containing accents, spaces and characters outside ASCII, and describe any supported limitations accurately.

Documentation sources and maintenance

The GNAT.Command_Line package specification is the best place to confirm the overloads and exceptions supported by the compiler distribution being used. The GNAT Reference Manual explains the environment, but an older online source file might not match a newer toolchain exactly. Record a compiler and runtime version in reproducible tests. If a switch definition changes, revisit its translated help, examples, validation logic, automated tests and accessibility notes together rather than updating a sentence in isolation.

A small example before translation

A reader can reason about the basic loop without building a production utility. Declare a Getopt switch pattern that accepts -v without a value and -o with a required value. Handle the returned code and read Parameter only for -o. Later, a configuration can define the equivalent public switches and their help messages. The crucial learning point is that the parser understands the pattern while the human needs a properly explained action, including where the output goes and how to recover from omitted values.

Chapter 4 — Twenty-six investigations that reveal real translation failures

The investigations below are deliberately practical. Each starts with an observable symptom, explains the relevant parser or interface boundary, offers a bounded repair and gives an acceptance test. The cases are not claims that GNAT automatically performs every operation mentioned. They are a method for verifying the exact application and runtime being documented. A professional translation should survive a real user following its steps without relying on hidden expert knowledge.

1. The translated short switch fails

A Spanish instruction replaces -v with an invented localized letter, but Getopt still accepts only the switch pattern compiled into the binary. The reader encounters an invalid switch before the intended action even begins.

Keep -v verbatim in the executable example and translate its meaning beside the code. If a localized alias is genuinely required, implement it and decide how both spellings coexist in a versioned interface.

Test the English and translated documents using the same executable; both sample commands must reach the same branch. Record Invalid_Switch only for tokens that are truly unsupported.

Reader exercise: explain the difference between the text a person should understand in this the translated short switch fails case and the exact arguments the program must recognize. Try the accepted form first, then reproduce the failure intentionally in a disposable environment. Keep the command, visible outcome and corrected wording together so another reviewer can validate the explanation independently.

2. A long switch looks plausible but does not exist

A help paragraph shows –verbose because many programs support that spelling, while the simple Getopt pattern recognizes only -v. Readers reasonably trust the documentation and run a failing command.

Inspect the shipped switch definition instead of inferring common conventions. Add a long alias through the configuration APIs if supported and intended, or remove it from the public example.

Compare every code-formatted option on the page with the accepted switch inventory. Run each example as a smoke test and fail the documentation build on an unknown option.

Reader exercise: explain the difference between the text a person should understand in this a long switch looks plausible but does not exist case and the exact arguments the program must recognize. Try the accepted form first, then reproduce the failure intentionally in a disposable environment. Keep the command, visible outcome and corrected wording together so another reviewer can validate the explanation independently.

3. Required value disappears during translation

The option -o expects a value, but a translation says only ‘choose output’ and shows -o without a filename. The parser then raises a parameter error, making the language look misleading.

Explain that -o requires an output path and give a safe local example such as -o result.txt. Keep the distinction between the switch itself and its parameter visible in the sentence.

Exercise both -o result.txt and -o with no value. The first must parse, and the second must lead to a relevant, translated recovery instruction without exposing implementation internals.

Reader exercise: explain the difference between the text a person should understand in this required value disappears during translation case and the exact arguments the program must recognize. Try the accepted form first, then reproduce the failure intentionally in a disposable environment. Keep the command, visible outcome and corrected wording together so another reviewer can validate the explanation independently.

4. Optional arguments are misread as mandatory

GNAT switch syntax can describe optional parameters, but an ordinary-language rewrite changes ‘if supplied’ into ‘must supply’. This can make a valid invocation appear forbidden, especially in quick-start examples.

Document the actual optional-argument rule and any default that applies when a user supplies a switch but not its value. Avoid translating punctuation used in the option specification.

Test the switch absent, present without its optional value and present with a value. Put all three observed outcomes in reviewer notes so the translated guidance matches runtime behavior.

Reader exercise: explain the difference between the text a person should understand in this optional arguments are misread as mandatory case and the exact arguments the program must recognize. Try the accepted form first, then reproduce the failure intentionally in a disposable environment. Keep the command, visible outcome and corrected wording together so another reviewer can validate the explanation independently.

5. Grouped short switches are described incorrectly

A program may accept certain grouped switches, yet the page says every character after a dash is one independent option. In GNAT, grouping rules and argument-taking switches require care.

Give a concrete supported combination only after inspecting the relevant parser configuration. Explain the limitation when a switch consumes a parameter, and avoid suggesting arbitrary bundles.

Run the exact grouped expression and its separate equivalent; compare the parsed values and failure cases. Document any order dependence instead of assuming conventional POSIX behavior.

Reader exercise: explain the difference between the text a person should understand in this grouped short switches are described incorrectly case and the exact arguments the program must recognize. Try the accepted form first, then reproduce the failure intentionally in a disposable environment. Keep the command, visible outcome and corrected wording together so another reviewer can validate the explanation independently.

6. A description accidentally becomes a parser key

An editor translates a Define_Switch declaration’s Switch or Long_Switch strings as though they were help copy. The resulting application now changes its public interface and breaks existing scripts.

Treat Switch and Long_Switch as reviewed compatibility data, while Help and Argument are candidates for reader-facing localization. Changes to identifiers require separate feature approval.

Use a before-and-after command corpus to confirm legacy invocations remain accepted. Inspect built help to see that descriptions changed while recognized names did not.

Reader exercise: explain the difference between the text a person should understand in this a description accidentally becomes a parser key case and the exact arguments the program must recognize. Try the accepted form first, then reproduce the failure intentionally in a disposable environment. Keep the command, visible outcome and corrected wording together so another reviewer can validate the explanation independently.

7. Display_Help mixes languages

A configuration contains a translated Help field for one option and English defaults for others. Display_Help prints a visibly mixed page that makes the product seem unfinished.

Inventory every option description, usage sentence, general help field and argument label. Set up a complete catalogue or localized configuration rather than editing whichever string happened to be most visible.

Capture complete help output per locale and search for unintended source-language fragments. Preserve necessary technical tokens, but review all human prose as one reading experience.

Reader exercise: explain the difference between the text a person should understand in this display_help mixes languages case and the exact arguments the program must recognize. Try the accepted form first, then reproduce the failure intentionally in a disposable environment. Keep the command, visible outcome and corrected wording together so another reviewer can validate the explanation independently.

8. An argument placeholder is translated ambiguously

An output flag uses a generic placeholder such as ARG, and the translation renders it as a sentence fragment. Readers cannot tell whether the next token should be a path, count or choice.

Choose concise placeholders that name a value category and keep syntax markers distinct. If a placeholder is displayed in uppercase by the formatter, account for that before choosing a readable label.

Have a new user identify which text must be typed literally and which text represents a replaceable value. Test a real command made from their interpretation.

Reader exercise: explain the difference between the text a person should understand in this an argument placeholder is translated ambiguously case and the exact arguments the program must recognize. Try the accepted form first, then reproduce the failure intentionally in a disposable environment. Keep the command, visible outcome and corrected wording together so another reviewer can validate the explanation independently.

9. A Boolean switch gets an invented value

A documentation sample says -v yes although the configured Boolean switch takes no parameter. The next positional argument changes and an unexpected failure appears later.

Explain a flag as a presence/absence switch and reserve value examples for switches explicitly declared to accept them. Do not borrow the formatting of an unrelated CLI toolkit.

Run the flag alone and with a trailing yes. Check whether the extra token remains positional; the article must not claim the parser consumes it when it does not.

Reader exercise: explain the difference between the text a person should understand in this a boolean switch gets an invented value case and the exact arguments the program must recognize. Try the accepted form first, then reproduce the failure intentionally in a disposable environment. Keep the command, visible outcome and corrected wording together so another reviewer can validate the explanation independently.

10. Integer values are localized as numerals with separators

A team rewrites -O 1000 as -O 1,000 to look natural in English, or uses a locale-specific separator elsewhere. The integer parser may reject or misread that token.

Keep CLI numeric syntax in the format accepted by GNAT’s integer switch handler. Explain quantities in the surrounding prose if needed, but leave example arguments machine-valid.

Test zero, negative values if allowed, maximum supported values, malformed text and separator-bearing values. Confirm the user-facing guidance distinguishes syntax from units.

Reader exercise: explain the difference between the text a person should understand in this integer values are localized as numerals with separators case and the exact arguments the program must recognize. Try the accepted form first, then reproduce the failure intentionally in a disposable environment. Keep the command, visible outcome and corrected wording together so another reviewer can validate the explanation independently.

11. A default value is falsely advertised

The translated help states that verbosity starts enabled, but the configured Boolean variable begins false. A novice thinks the command should print diagnostic output and distrusts the tool.

Read actual initialization behavior and document the default condition, not the translator’s expectation. Where overloads set Initial and Default values, distinguish absent-switch behavior from optional-value behavior.

Run with no switches and capture the resulting state through a harmless demonstration. Verify the written default matches the observed result on every supported build.

Reader exercise: explain the difference between the text a person should understand in this a default value is falsely advertised case and the exact arguments the program must recognize. Try the accepted form first, then reproduce the failure intentionally in a disposable environment. Keep the command, visible outcome and corrected wording together so another reviewer can validate the explanation independently.

12. String access storage is mishandled

A configuration writes a switch parameter through GNAT.Strings.String_Access, but sample code assumes the referenced storage has an unlimited lifetime. Locale text then obscures a memory problem.

Keep pointer ownership and freeing decisions in engineering review, separate from wording. Explain to documentation readers which value is an output path while testing implementation safety against the package specification.

Use repeated invocations or controlled test harnesses where applicable. Inspect for leaks and stale pointers; never market translated help as a substitute for correct Ada memory management.

Reader exercise: explain the difference between the text a person should understand in this string access storage is mishandled case and the exact arguments the program must recognize. Try the accepted form first, then reproduce the failure intentionally in a disposable environment. Keep the command, visible outcome and corrected wording together so another reviewer can validate the explanation independently.

13. Positional files are treated as switches

A filename starts with a dash, and the command parser mistakes it for another option. The translated guide merely says ‘enter any filename’, hiding an important boundary.

Where supported, document an end-of-options separator or a safe path form. The exact behavior should be checked against the selected scanning mode rather than assumed from another parser.

Test a file called -notes.txt, a path containing spaces and a normal path. Publish only command forms that parse correctly on the supported target.

Reader exercise: explain the difference between the text a person should understand in this positional files are treated as switches case and the exact arguments the program must recognize. Try the accepted form first, then reproduce the failure intentionally in a disposable environment. Keep the command, visible outcome and corrected wording together so another reviewer can validate the explanation independently.

14. Get_Argument is forgotten

The article spends pages on options but never explains what happens to the positional path. A reader supplies a valid switch and still cannot tell why the program demands another token.

Show that option scanning and collection of remaining arguments are separate steps. Explain whether the program accepts one path, several paths or standard input, as designed.

Run no-path, one-path and extra-path cases and verify the text describes the actual acceptance policy. Provide a useful error instead of a generic failed command.

Reader exercise: explain the difference between the text a person should understand in this get_argument is forgotten case and the exact arguments the program must recognize. Try the accepted form first, then reproduce the failure intentionally in a disposable environment. Keep the command, visible outcome and corrected wording together so another reviewer can validate the explanation independently.

15. Wildcard expansion changes the files selected

An example uses a wildcard while Get_Argument is called with expansion behavior enabled. Depending on runtime and platform, the files the program sees may differ from the writer’s mental model.

Explain whether the application expands wildcards itself, delegates expansion to the shell, or avoids it. Do not promise identical expansion across operating systems without testing.

Use fixtures with two similarly named files and a literal asterisk. Compare observed arguments in each supported shell; update instructions to show what users can expect.

Reader exercise: explain the difference between the text a person should understand in this wildcard expansion changes the files selected case and the exact arguments the program must recognize. Try the accepted form first, then reproduce the failure intentionally in a disposable environment. Keep the command, visible outcome and corrected wording together so another reviewer can validate the explanation independently.

16. Sections are collapsed into one global list

A GNAT program delegates options to different tool phases using section delimiters, but the translation presents every option as valid everywhere. Users receive confusing failures in later phases.

Explain section boundaries and indicate which subsystem consumes each switch. If the configuration defines separate sections, retain those divisions in both help and examples.

Test a switch inside its intended section and again in the wrong section. The page should teach why one invocation works and the other is rejected.

Reader exercise: explain the difference between the text a person should understand in this sections are collapsed into one global list case and the exact arguments the program must recognize. Try the accepted form first, then reproduce the failure intentionally in a disposable environment. Keep the command, visible outcome and corrected wording together so another reviewer can validate the explanation independently.

17. An error is translated as permission denial

Invalid_Switch is converted into a statement about file permissions, because an old translation was copied from another error table. The reader then changes file access unnecessarily.

Associate each message key with the specific exception or validation state that triggers it. Write plain advice to check spelling or supported switches rather than guessing at external causes.

Trigger the error using an intentionally unknown switch. Verify it does not recommend changing permissions or files; reserve those instructions for a genuine access error.

Reader exercise: explain the difference between the text a person should understand in this an error is translated as permission denial case and the exact arguments the program must recognize. Try the accepted form first, then reproduce the failure intentionally in a disposable environment. Keep the command, visible outcome and corrected wording together so another reviewer can validate the explanation independently.

18. A missing parameter is blamed on encoding

The program expects a value following -o but the translated error says the file path contains unsupported characters. This introduces a new, false diagnosis.

Keep Invalid_Parameter handling close to the actual failure and distinguish ‘missing’ from ‘not well formed’ when the runtime can do so. Display a safe usage form.

Test an empty invocation, a missing value and an invalid numeric value separately. Ensure each explanation is accurate at the level the program can really observe.

Reader exercise: explain the difference between the text a person should understand in this a missing parameter is blamed on encoding case and the exact arguments the program must recognize. Try the accepted form first, then reproduce the failure intentionally in a disposable environment. Keep the command, visible outcome and corrected wording together so another reviewer can validate the explanation independently.

19. A translated error loses its offending token

An error says only ‘incorrect option’, removing the safe switch token that would help a reader recognize the typo. They repeat the mistake because there is no useful evidence.

Include a bounded, sanitized option token when appropriate, quoted clearly as user input. Do not echo passwords, large untrusted text or other sensitive argument values indiscriminately.

Try -verbsoe and compare the message with expected help. Check that a user can identify the typo while no unrelated or secret input is disclosed.

Reader exercise: explain the difference between the text a person should understand in this a translated error loses its offending token case and the exact arguments the program must recognize. Try the accepted form first, then reproduce the failure intentionally in a disposable environment. Keep the command, visible outcome and corrected wording together so another reviewer can validate the explanation independently.

20. Terminal output becomes unreadable

The program emits valid UTF-8 explanation bytes, but the chosen console or font displays replacement glyphs. A reviewer approves the translated text from a browser screenshot alone.

Test through the actual command runner and supported terminals. Document locale and output encoding requirements where necessary, and use simple fallback wording for environments that cannot render the target script.

Capture both raw output bytes and a terminal screenshot in the test environment. A passing text comparison is not enough when the visible glyphs are unusable.

Reader exercise: explain the difference between the text a person should understand in this terminal output becomes unreadable case and the exact arguments the program must recognize. Try the accepted form first, then reproduce the failure intentionally in a disposable environment. Keep the command, visible outcome and corrected wording together so another reviewer can validate the explanation independently.

21. A Unicode path is silently altered

The user provides a path containing combining marks or characters outside ASCII; a demo program handles it as a byte string and cannot open the intended resource. Help translation alone cannot repair it.

Separate display text testing from filesystem-path behavior. Investigate the compiler runtime’s path handling on each supported operating system and retain an exact round-trip test fixture.

Create a disposable file with the representative name, pass it as an argument, and verify the application identifies the same file. Avoid claiming full Unicode support when only the help text works.

Reader exercise: explain the difference between the text a person should understand in this a unicode path is silently altered case and the exact arguments the program must recognize. Try the accepted form first, then reproduce the failure intentionally in a disposable environment. Keep the command, visible outcome and corrected wording together so another reviewer can validate the explanation independently.

22. Help examples contain unsafe operations

An article copies a real maintenance command that deletes files merely to demonstrate a flag. Even when translated correctly, the example exposes learners to avoidable loss.

Use a read-only or mocked example with fictional data. State side effects plainly and show a dry run if the real product supports one; never invent a dry-run option.

Have an independent reader follow the example in a disposable directory. Confirm no deletion, external transmission or irreversible change occurs during the tutorial.

Reader exercise: explain the difference between the text a person should understand in this help examples contain unsafe operations case and the exact arguments the program must recognize. Try the accepted form first, then reproduce the failure intentionally in a disposable environment. Keep the command, visible outcome and corrected wording together so another reviewer can validate the explanation independently.

23. Line wrapping hides option descriptions

Long translated strings push the Display_Help columns past a typical terminal width, causing misleading visual alignment or clipped text. The source-language version did not reveal this issue.

Shorten descriptions without dropping conditions, and use detailed explanatory sections for complex concepts. If help formatting is configurable, test its actual layout rather than assuming characters equal display columns.

Capture help at narrow and ordinary widths with Latin and wide-script content. Verify every option remains associated with the right description.

Reader exercise: explain the difference between the text a person should understand in this line wrapping hides option descriptions case and the exact arguments the program must recognize. Try the accepted form first, then reproduce the failure intentionally in a disposable environment. Keep the command, visible outcome and corrected wording together so another reviewer can validate the explanation independently.

24. Help and stderr are confused

A failed invocation writes a usage message to stdout, while the product’s script runner expects errors on stderr. A translation-only edit can accidentally obscure this interface contract.

Decide separately where successful help, warnings and failures belong. Preserve exit status conventions and ensure localized wording does not change output routing by surprise.

Redirect stdout and stderr to separate files for both –help and an invalid switch. Verify documented status and stream behavior for each outcome.

Reader exercise: explain the difference between the text a person should understand in this help and stderr are confused case and the exact arguments the program must recognize. Try the accepted form first, then reproduce the failure intentionally in a disposable environment. Keep the command, visible outcome and corrected wording together so another reviewer can validate the explanation independently.

25. Automation reads human prose as data

A script consumes a line of translated output and stops working when an English heading becomes Japanese. The program had accidentally made a localized sentence an integration contract.

Separate machine-readable output from human-facing help. Keep keys, delimiters and documented structured formats stable; translate explanatory lines intended for people.

Run the same automation under at least two locales and compare the parsed records. The localized help may differ, but machine-contract output must remain compatible.

Reader exercise: explain the difference between the text a person should understand in this automation reads human prose as data case and the exact arguments the program must recognize. Try the accepted form first, then reproduce the failure intentionally in a disposable environment. Keep the command, visible outcome and corrected wording together so another reviewer can validate the explanation independently.

26. A release passes in only one locale

A team tests the Ada command in English and approves every translated locale because the same binary is used. That misses broken examples, missing catalogue keys and path issues.

Make the supported locale list explicit. Exercise help, one success case and each major failure category per locale, then add targeted Unicode and platform checks.

Store a versioned matrix showing environment, invocation, expected output and reviewer. If a locale or operating system is untested, mark it honestly instead of implying universal support.

Reader exercise: explain the difference between the text a person should understand in this a release passes in only one locale case and the exact arguments the program must recognize. Try the accepted form first, then reproduce the failure intentionally in a disposable environment. Keep the command, visible outcome and corrected wording together so another reviewer can validate the explanation independently.

Chapter 5 — Six controlled exercises for translating a working program

Lab A — A switch inventory

Write down each accepted option, alias, required value, default, sample use and source location. Compare the inventory with the published help. If an item exists only in documentation, resolve it before translation.

Make the exercise auditable: record the invocation, relevant environment, expected behavior, observed behavior and any unresolved limitation. The result should answer what a reader can safely do next, not merely whether a translation sounds fluent. When evidence disagrees with a polished sentence, correct the sentence and recheck the tool.

Lab B — A diagnostic matrix

Prepare four small invocations: one success, one unknown switch, one missing value and one path error. Classify the origin of each failure before writing the message. Avoid attributing a parser problem to the filesystem.

Lab C — A safe language review

Give a proficient target-language reviewer the compiled program and only the translated guide. Ask them to run a harmless inspection, locate a help option and recover from one typo. Observe their actions rather than telling them the answer.

Lab D — A cross-platform path check

Use a disposable directory containing a file with spaces and one with accented or non-Latin characters. Record the operating system, compiler/runtime version, locale environment and exact invocation. Do not generalize beyond the combinations tested.

Lab E — Layout and accessibility

View help at widths representative of a typical and narrow terminal. Check line wrapping, punctuation, directionality where relevant, color independence and whether a screen-reader user can follow the order of options.

Lab F — Release evidence

Keep a sample output file or terminal transcript for every target locale and documented command. Include what was tested and when, the version, and a link to the source specification. Readers should be able to reproduce the claims.

Chapter 6 — Frequently asked questions

Does GNAT.Command_Line translate errors automatically?

No. The package parses options and can help display configured descriptions; complete localization of application messages and recovery instructions is an application responsibility. Even parser exceptions need an appropriate user-facing boundary.

A useful answer also preserves the distinction between application-controlled help text and executable syntax. Verify uncertain details against the installed GNAT package and a real invocation. That is particularly important when examples travel between languages, platforms and compiler versions.

Should we translate -v or –verbose?

Usually not in an existing executable interface. Keep the actual option names intact in examples. New localized aliases require deliberate implementation, compatibility review and testing rather than editorial substitution.

What is the difference between Getopt and Define_Switch?

Getopt is a scanning interface driven by a switch specification. Define_Switch populates a configuration that can support help generation and typed values. Compare the overloads available in the installed GNAT distribution.

Can Display_Help be a complete manual?

It is useful immediate help, not a substitute for workflow examples, safety context and validation guidance. Keep the short help accurate and provide deeper explanations in accessible documentation.

Why can an apparently correct Unicode filename fail?

Filesystem APIs, terminal encoding and runtime representations differ. Test real file round trips for the operating systems supported; do not infer filename support from correctly displayed text.

Is translated error text allowed to contain option names?

Yes. Keep machine-recognized names literal, quote them clearly and translate only the explanatory sentence. Remove or redact sensitive values from diagnostics where necessary.

Should example commands use the target language everywhere?

Translate surrounding explanation. Preserve executable tokens unless deliberately supported by the program. A working command is more helpful than a fully translated string that the parser rejects.

How should reviewers handle outdated sample code?

Compare against the currently installed package specification and a small compiled test. Mark illustrative pseudocode as such, and avoid implying that an untested fragment is production-ready.

What should a minimal acceptance test include?

Capture help, a valid command, an unknown switch, a missing required value and a Unicode filename test. Include stdout, stderr and exit status so the result can be evaluated, not guessed.

Can one translation be reused for multiple switches?

Only when the switches genuinely mean the same thing in context. Similar-sounding terms may differ in defaults, side effects or required values; maintain enough context for a reader to choose correctly.

How does this differ from language translation in a textbook?

Software help includes formal syntax and runtime consequences. Success means a user understands the message and can execute a valid, safe task with the shipped program.

What triggers a new review?

Any change to switch declarations, compiled aliases, exception handling, usage rendering, output format, supported locale, compiler runtime or platform support should reopen the relevant examples and tests.

Chapter 7 — A four-week implementation and review plan

Week one: map behavior

Read the installed GNAT.Command_Line specification and list accepted short and long switches, required and optional values, default states and positional arguments. Run the current program in one reference locale and save examples of each class of success or failure. Agree which tokens are protocol-like and which messages may be freely expressed in another language. Inventory help shown by Display_Help separately from errors written by the application. Avoid translating an unknown or undocumented option.

Week two: translate for tasks

Draft short, descriptive option help that tells a new user what action will occur, not merely what a noun means. Add a valid, safe sample beside difficult switches, and explain defaults and constraints in full sentences. Review terminology with someone who understands Ada and someone proficient in the target language. Keep parameter labels distinct from literal syntax, and prefer a short direct recovery instruction to generic apologies. Compile a test build to expose mismatches early.

Week three: test edge conditions

Exercise every localized example plus deliberate mistakes: absent parameters, unsupported switches, grouped options where supported, section boundaries, negative integers, option-like filenames and Unicode paths. Capture stdout, stderr, exit codes and terminal rendering. Test in supported shells and platforms; check that machine-readable output remains stable. Record limitations explicitly. A locale that passes text review but fails the CLI task is not finished.

Week four: release with evidence

Give an unfamiliar reader a clean environment and the localized documentation. Ask them to find help, complete a harmless task and recover from one invalid invocation without external coaching. Amend confusing text, then run regression checks on the final build and page. Archive version, tested platforms, sample invocations and known limitations. Trigger renewed review after parser, compiler, output or catalogue changes; translation quality is maintained through verified behavior, not a once-only proofreading exercise.

Chapter 8 — What reliable proficiency looks like

An Ada command-line interface is successful in another language when the reader can see a trustworthy relationship between what the page says and what the executable accepts. GNAT.Command_Line can organize switch scanning, definitions and generated help, but the software team remains responsible for meaningful messages, safe workflows, accurate defaults and reproducible Unicode behavior. Preserve the command grammar, write the human explanation in clear language, and treat error recovery as part of the lesson.

The best translation is not the one with the most translated tokens. It is the one in which an unfamiliar reader can form a correct expectation, run a valid command, understand a failure and complete the intended task without guessing. That standard is measurable, teachable and portable to other command-line tools.