Translate Like a Pro | 8800 — Vala GLib OptionContext Localization, OptionEntry, Gettext Help, Filename Encoding and QA

Vala GLib OptionContext localization is the work of translating generated command-line help, option descriptions, argument placeholders and readable failures without confusing those human-facing strings with the switches accepted by GLib.OptionEntry. Anyone searching for Vala OptionContext translation, add_main_entries, gettext, OptionError, Unicode filenames or multilingual –help testing needs to know where the option parser stops and the application’s user experience begins.

Consider a small Vala utility called archiveview that inspects a local manifest. Its English help says –output=FILE and -v, while a French user needs clear instructions for a destination path and a German user wants to know whether verbose mode changes the result. The parser’s long_name, short_name and value type are executable details. The description and arg_description explain their meaning. A good localized manual leaves the working invocation intact and removes uncertainty about what it does.

A practical solution begins by reading GLib.OptionContext and GLib.OptionEntry together, adding main entries, assigning a translation domain, and reviewing automatically generated help as actual terminal output. It then checks OptionError boundaries, strict POSIX behavior, option groups, unknown-option policy, filenames versus ordinary strings, UTF-8 and supported locale setups. This guide develops each decision through small examples, real diagnostic patterns, questions and a reproducible four-week quality plan.

Keep GLib option identifiers stable and translate human explanations.
Use a verified gettext domain for generated help and any option groups.
Differentiate filename encoding from ordinary UTF-8 strings.
Validate help, errors and real terminal behavior in every supported locale.

Chapter 1 — The GLib OptionContext model in plain language

How Vala reaches the GLib parser

Vala exposes GLib.OptionContext, a language binding to GLib’s GOptionContext mechanism. A context knows which options are accepted and can generate a help page. Entries describe long names, optional short aliases, argument kinds and human-facing descriptions. An important design advantage is that help and parsing can share one declaration. An important limitation is that this does not localize application-specific output, validation errors, command examples or configuration formats. Authors must decide separately which texts belong in translation catalogues and which tokens are stable input or output interfaces.

An OptionEntry has several roles

The OptionEntry.long_name is the accepted form after two hyphens; short_name provides a one-character alias where specified. OptionArg selects the type, such as NONE, STRING, FILENAME or integer variants. The description field tells people what the option does; arg_description names a value placeholder displayed in help. Do not translate an executable long name simply because it is readable English. Translate the description and placeholder through the configured catalogue, then verify that the resulting help is accurate for the registered type.

Generated help is not just a string

OptionContext can render a usage line, a summary, a description and groups of options. It recognizes standard help forms unless help generation has been disabled. An application may also retrieve help programmatically with get_help, and may set summary or description fields for different levels of context. A reviewer should inspect the full output rather than translating an isolated OptionEntry row. In particular, a long translated description can change wrapping and the relation between a value placeholder and its option.

Gettext and translation domains

GLib provides methods for assigning translation domains and custom translation functions to option contexts and groups. Vala’s add_main_entries accepts a domain parameter, so the main group’s descriptions can be associated with the intended catalogue. That does not eliminate the need for installation of catalogue files, a correct environment or message extraction. Use one documented translation path, test whether the targeted strings are found under real locale settings and never infer correctness from the existence of a .po file alone.

Chapter 2 — A safe Vala example with explicit limits

This compact example illustrates a Boolean flag, a filename argument, a translation domain attached through add_main_entries and the catching of OptionError. It intentionally only prints a Boolean status. It does not write a file, install gettext catalogues or guarantee a particular encoding across operating systems. The example should be compiled against the Vala and GLib versions actually supported by the application, and every demonstration invocation should be tested against that build.

// Illustrative Vala option setup. Catalogue deployment is separate.
public class ArchiveView : Object {
    private static bool verbose = false;
    private static string? output_file = null;
    private const OptionEntry[] entries = {
        { "verbose", 'v', OptionFlags.NONE, OptionArg.NONE,
          ref verbose, "Show additional details", null },
        { "output", 'o', OptionFlags.NONE, OptionArg.FILENAME,
          ref output_file, "Write a report to FILE", "FILE" },
        { null }
    };

    public static int main (string[] args) {
        var context = new OptionContext ("- inspect a local manifest");
        context.add_main_entries (entries, "archiveview");
        try {
            context.parse (ref args);
        } catch (OptionError e) {
            stderr.printf ("Option error: %s\n", e.message);
            return 2;
        }
        stdout.printf ("verbose=%s\n", verbose ? "true" : "false");
        return 0;
    }
}

In this teaching fragment, –output and -o remain literal options; ‘Write a report to FILE’ and FILE are candidates for translated display via the configured domain. If the actual application writes files, it must validate output destinations and side effects separately. To test localization, start with a known compiled catalogue and request help in two supported locales. The absence of a translated sentence should be treated as an integration signal, not as a reason to change the parser keys.

Chapter 3 — Build the reader’s pathway from help to action

Strings and filenames are different kinds of arguments

GLib distinguishes G_OPTION_ARG_STRING from G_OPTION_ARG_FILENAME. Its documentation says string values are returned in UTF-8 while filenames use the GLib filename encoding, subject to platform and locale behavior. This is a functional distinction. A translated tutorial should not advise developers to pass every filename through a generic UTF-8 string conversion. Validate the field’s OptionArg, the actual platform and the file open operation, not only whether the text looks correct on screen.

OptionError is a boundary, not a story

A malformed invocation can raise GLib.OptionError in Vala. The application should catch it near parsing and decide on a stable exit status, safe stderr message and next action, such as viewing help. It should not claim that all errors are caused by a bad translation. After parsing, application logic may still fail on permissions, missing files or invalid domain data. Distinguish these layers in both source code and reader-facing explanations. More precise diagnoses make users safer and reduce support effort.

Automatic options and grouped options

The context can include groups supplied by libraries and supports help forms such as –help-all and group-specific help. This helps complex programs but expands the translation surface. An application may have stable option names defined by a dependency, while human descriptions come from the group’s translation domain. Audit each group’s help separately, especially when a plugin or library updates. Do not promise that translating the main group covers every line produced by the full program.

What a publishable example should show

A useful code sample names the option types, shows a safe invocation and makes the failure case understandable. Avoid copying a complex production application merely to illustrate gettext behavior. A small read-only inspection scenario can demonstrate a Boolean verbose flag and a filename-valued option. It should state that real catalogue setup, secure path handling and a supported UTF-8 terminal remain separate tasks. Make code-formatted commands pasteable and avoid inventing flags or shell conventions.

Testing is part of the translation

A help file can be perfectly grammatical and still be unusable: the text may wrap badly, required parameters may be unclear, –help may exit unexpectedly, or non-ASCII filenames may fail in a locale with different encoding. Build a matrix of supported Vala, GLib, operating system and locale combinations. Confirm the same executable tokens work across languages and that human-facing descriptions are appropriate. Store expected outputs as observations from a build rather than aspirational text.

Version awareness and upstream sources

Read the GLib API reference and Vala binding documentation for the versions supported by your program. The official descriptions of GOptionContext, GOptionEntry and the command-line parser explain which behavior is guaranteed. Avoid attributing a modern method to an older release just because an online page shows it. A documented version floor and test environment make the translation guide useful internationally, where readers may use distributions with different GLib packages.

Chapter 4 — Twenty-seven practical investigations and verification methods

Each problem below is specific enough to be observed. For every failure, diagnose whether it belongs to a parser declaration, a translation catalogue, the terminal environment or the application itself. The acceptance check is as important as the proposed wording: it prevents a polished but incorrect guide from going live.

1. Long option name translated instead of its label

The French translation changes OptionEntry.long_name from output to sortie, but documentation and scripts continue to use –output. The result is a compatibility break rather than a successful help translation.

Keep the long name as a stable parser identifier and translate the description that explains it. If the product deliberately introduces aliases, maintain both forms and document the version in which the new name exists.

Run the old –output path form after changing the catalogue. It must still parse. Compare captured –help output to confirm that human descriptions change while option spellings do not.

Practical review exercise: start with the real option declaration associated with long option name translated instead of its label. Mark which characters are parser syntax, which sentence is explanatory text and which behavior must be observed rather than assumed. Have a target-language reader follow a safe example, then compare the resulting invocation and displayed help with the accepted command contract.

2. Short aliases collide after a language rewrite

An editor decides -v should become -d for a German word, but another registered option already uses -d. A human-language preference has created a parser conflict.

Keep the existing alias unless there is an explicit versioned interface change. Inventory all short options, including those from library option groups, before proposing any new shortcut.

Capture help for the main group and –help-all. Verify each alias maps unambiguously to the documented behavior and that old scripts still run.

Practical review exercise: start with the real option declaration associated with short aliases collide after a language rewrite. Mark which characters are parser syntax, which sentence is explanatory text and which behavior must be observed rather than assumed. Have a target-language reader follow a safe example, then compare the resulting invocation and displayed help with the accepted command contract.

3. An OptionArg.NONE flag is shown with a value

A help example says –verbose=true while the entry is declared with OptionArg.NONE. The reader assumes an ordinary Boolean option accepts a separate textual value.

Describe the flag as a switch enabled by presence, unless the application’s actual option declaration provides another syntax. Keep values and placeholders only on options that accept them.

Run –verbose by itself and the documented value-bearing form. Observe parser behavior and correct every published example that suggests unsupported syntax.

Practical review exercise: start with the real option declaration associated with an optionarg.none flag is shown with a value. Mark which characters are parser syntax, which sentence is explanatory text and which behavior must be observed rather than assumed. Have a target-language reader follow a safe example, then compare the resulting invocation and displayed help with the accepted command contract.

4. Filename argument is declared as STRING

A program accepts –output with OptionArg.STRING even though the value is later used as a filesystem path. It appears fine for ASCII test files and fails in another locale.

Choose FILENAME when the argument is a file path and validate the entire path-processing chain according to GLib’s documented encoding behavior. Do not treat display bytes as filesystem identity.

Create a disposable file with a non-ASCII name and verify the exact file can be opened. Test on each supported operating system rather than relying on a single locale.

Practical review exercise: start with the real option declaration associated with filename argument is declared as string. Mark which characters are parser syntax, which sentence is explanatory text and which behavior must be observed rather than assumed. Have a target-language reader follow a safe example, then compare the resulting invocation and displayed help with the accepted command contract.

5. Translatable placeholder is not understandable

A help row shows –output=ARG after the team removes the explanatory word FILE. The localized description says ‘choose destination’ but the reader does not know whether ARG is a directory, base name or report file.

Use arg_description to present a concise type or role such as FILE. Translate that human placeholder where the group’s catalogue allows, while keeping the accepted –output spelling intact.

Give the page to an unfamiliar reader and ask them to construct a valid command. Their interpretation should produce a destination path and not a literal file named ARG.

Practical review exercise: start with the real option declaration associated with translatable placeholder is not understandable. Mark which characters are parser syntax, which sentence is explanatory text and which behavior must be observed rather than assumed. Have a target-language reader follow a safe example, then compare the resulting invocation and displayed help with the accepted command contract.

6. Translation domain omitted from the main group

The code adds main entries with no domain, and a translated catalogue exists but generated help remains English. The team mistakenly blames the translator’s word choices.

Confirm the call to add_main_entries and the relevant context or group translation domain, catalogue installation and locale initialization. Keep the domain name consistent across build and packaging.

Run the binary with a supported non-English locale and capture full help. Search for a known translated phrase; compare with a reference locale to prove the catalogue is actually being loaded.

Practical review exercise: start with the real option declaration associated with translation domain omitted from the main group. Mark which characters are parser syntax, which sentence is explanatory text and which behavior must be observed rather than assumed. Have a target-language reader follow a safe example, then compare the resulting invocation and displayed help with the accepted command contract.

7. A .po file is present but no installed .mo is found

The project repository contains translated messages, yet deployed users get English help. The source material and the runtime packaging no longer match.

Test the production package layout and gettext domain discovery path instead of assuming a repository file is installed. Include package-management steps only when they match the platform.

Install into a clean environment, set the supported locale and request –help. Passing requires the installed binary, catalogues and declared domain to work together.

Practical review exercise: start with the real option declaration associated with a .po file is present but no installed .mo is found. Mark which characters are parser syntax, which sentence is explanatory text and which behavior must be observed rather than assumed. Have a target-language reader follow a safe example, then compare the resulting invocation and displayed help with the accepted command contract.

8. Summary and description are swapped

A long translated paragraph is placed in the short summary position, while the concise product purpose appears after options. The generated help now hides the immediate decision.

Use summary for the quick purpose and description for secondary context, following the documented OptionContext presentation. Translate them with attention to location and reader intent.

Read complete help at a realistic terminal width and ask a novice to locate the program’s purpose in a few seconds. Adjust wording, not executable options.

Practical review exercise: start with the real option declaration associated with summary and description are swapped. Mark which characters are parser syntax, which sentence is explanatory text and which behavior must be observed rather than assumed. Have a target-language reader follow a safe example, then compare the resulting invocation and displayed help with the accepted command contract.

9. Unknown option policy is changed casually

To make localized examples seem forgiving, code enables ignore_unknown_options. Typos may then pass through to later logic instead of producing a clear parser error.

Preserve the application’s intended validation policy. Use ignore_unknown_options only when another component truly needs to parse remaining arguments and the flow is tested.

Run a mistyped flag such as –outpt. Confirm whether the program rejects it or legitimately hands it to a delegated parser; explain that behavior accurately.

Practical review exercise: start with the real option declaration associated with unknown option policy is changed casually. Mark which characters are parser syntax, which sentence is explanatory text and which behavior must be observed rather than assumed. Have a target-language reader follow a safe example, then compare the resulting invocation and displayed help with the accepted command contract.

10. Strict POSIX assumptions alter invocation order

A tutorial shows flags after positional arguments without checking strict_posix handling. Different parser settings make the example unreliable across builds.

Test the application’s chosen strict POSIX mode and document order-sensitive syntax. Do not borrow command layouts from a different library and assume they apply to GLib.

Try options before and after a positional input under the actual mode. Save the observed remaining argv and ensure the tutorial’s command matches the supported behavior.

Practical review exercise: start with the real option declaration associated with strict posix assumptions alter invocation order. Mark which characters are parser syntax, which sentence is explanatory text and which behavior must be observed rather than assumed. Have a target-language reader follow a safe example, then compare the resulting invocation and displayed help with the accepted command contract.

11. A group-specific help page is forgotten

A program combines application options with a library’s option group. Translators review only –help and miss additional messages under –help-all or group-specific help.

Inventory main and dependency-supplied option groups. Ask owners of each group to provide translation context and confirmed option meanings rather than copying a neighboring product’s descriptions.

Capture –help, –help-all and an applicable –help-groupname form. Review every sentence a user might encounter, including placeholders and the library’s summary.

Practical review exercise: start with the real option declaration associated with a group-specific help page is forgotten. Mark which characters are parser syntax, which sentence is explanatory text and which behavior must be observed rather than assumed. Have a target-language reader follow a safe example, then compare the resulting invocation and displayed help with the accepted command contract.

12. The help flag is manually redefined without reason

A developer registers an application option named help while GLib’s automatic help machinery remains enabled. The collision creates confusing behavior or inconsistent exit handling.

Understand set_help_enabled before adding custom help handling. Use generated help when sufficient; if disabling it, take responsibility for all access paths and maintain an explicit test.

Run -h, –help and help-related invalid forms. Confirm that the displayed instructions, stream and exit status match the product’s documented policy.

Practical review exercise: start with the real option declaration associated with the help flag is manually redefined without reason. Mark which characters are parser syntax, which sentence is explanatory text and which behavior must be observed rather than assumed. Have a target-language reader follow a safe example, then compare the resulting invocation and displayed help with the accepted command contract.

13. An integer parameter is formatted like a locale-specific number

The translated guide shows –count=1,000 while OptionArg.INT expects a numeric argument. Natural typography has accidentally changed a machine-readable value.

Keep the CLI token in the format the parser accepts and place a localized quantity description in prose. Document the allowed range and any application-level constraint separately.

Test valid integer, missing integer, excessive value and a number with a separator. The published example must match the actual parser result.

Practical review exercise: start with the real option declaration associated with an integer parameter is formatted like a locale-specific number. Mark which characters are parser syntax, which sentence is explanatory text and which behavior must be observed rather than assumed. Have a target-language reader follow a safe example, then compare the resulting invocation and displayed help with the accepted command contract.

14. The string-array option is documented as single-use

An entry uses OptionArg.STRING_ARRAY, but translated help tells readers to supply exactly one package name. They cannot discover an intended repeated option.

Explain whether repeated –include values accumulate and show an example if the application supports it. Make the distinction between a list argument and repeated individual options explicit.

Supply two values in separate occurrences and inspect the collected array. A reader should be able to predict the number and order of elements.

Practical review exercise: start with the real option declaration associated with the string-array option is documented as single-use. Mark which characters are parser syntax, which sentence is explanatory text and which behavior must be observed rather than assumed. Have a target-language reader follow a safe example, then compare the resulting invocation and displayed help with the accepted command contract.

15. A translated option error hides the offending switch

The catch block displays only a vague sentence, such as ‘Something went wrong’. The user has no clue whether the issue was spelling, a value type or argument order.

Retain GLib.OptionError information when safe and add a clear next step such as –help. Avoid indiscriminate echoing of secrets or unbounded user-supplied text.

Trigger an unknown option and a missing argument. Confirm the message offers enough information for a new user to correct each failure without revealing sensitive data.

Practical review exercise: start with the real option declaration associated with a translated option error hides the offending switch. Mark which characters are parser syntax, which sentence is explanatory text and which behavior must be observed rather than assumed. Have a target-language reader follow a safe example, then compare the resulting invocation and displayed help with the accepted command contract.

16. A parse error is mistaken for an application validation error

A typed integer failure is translated as ‘report not found’, even though the program has not reached any filesystem operation. This sends users to investigate the wrong problem.

Map parser errors separately from business-rule errors. Differentiate an invalid option type, a missing path, a nonexistent file and a permission failure in the message catalogue.

Use one fixture for each error source and compare exit status and stderr. A support reader must be able to identify the layer without inspecting source code.

Practical review exercise: start with the real option declaration associated with a parse error is mistaken for an application validation error. Mark which characters are parser syntax, which sentence is explanatory text and which behavior must be observed rather than assumed. Have a target-language reader follow a safe example, then compare the resulting invocation and displayed help with the accepted command contract.

17. Help returns the wrong exit status

A localized build prints a perfectly understandable help page but exits as though an error occurred, breaking shell scripts that check -h or –help.

Specify and test help success separately from failed parsing. A translation change should not accidentally alter program control flow or the behavior of automatic generated help.

Capture exit status, stdout and stderr from –help and –bad-option. They should follow distinct documented policies that remain stable across locales.

Practical review exercise: start with the real option declaration associated with help returns the wrong exit status. Mark which characters are parser syntax, which sentence is explanatory text and which behavior must be observed rather than assumed. Have a target-language reader follow a safe example, then compare the resulting invocation and displayed help with the accepted command contract.

18. Leftover arguments are silently ignored

OptionContext.parse changes the argument vector to contain remaining positional values, but the translated tutorial says any extra token will be rejected automatically.

Implement and document the application’s actual positional-argument count and semantics. Do not claim OptionContext enforces a rule that belongs to the program’s own validation.

Try no input, one input and two inputs. Confirm that the program reacts as documented after parsing and that a failure gives one useful recovery step.

Practical review exercise: start with the real option declaration associated with leftover arguments are silently ignored. Mark which characters are parser syntax, which sentence is explanatory text and which behavior must be observed rather than assumed. Have a target-language reader follow a safe example, then compare the resulting invocation and displayed help with the accepted command contract.

19. The — separator is omitted from a path example

A reader wants to inspect a file whose name begins with a dash. A localized example passes it as though it were a flag, causing the parser to reject it.

Explain the end-of-options marker where the supported parser accepts it. If the product uses other path conventions, show a tested alternative that distinguishes data from options.

Use a disposable file named -memo.txt and paste-test the documented invocation in the target shell. Confirm the file is treated as a positional argument.

Practical review exercise: start with the real option declaration associated with the — separator is omitted from a path example. Mark which characters are parser syntax, which sentence is explanatory text and which behavior must be observed rather than assumed. Have a target-language reader follow a safe example, then compare the resulting invocation and displayed help with the accepted command contract.

20. A literal dash is mistaken for standard input

A human-language guide says ‘-‘ means ‘nothing’, while the application actually treats it as a filename or as standard input depending on its own conventions.

Document the program’s decision, not a generic Unix custom. Distinguish OptionContext’s parsing of the token from application-specific handling after parsing.

Try ‘-‘ with empty standard input and a local file fixture. Validate the intended behavior and avoid suggesting standard input unless the executable truly supports it.

Practical review exercise: start with the real option declaration associated with a literal dash is mistaken for standard input. Mark which characters are parser syntax, which sentence is explanatory text and which behavior must be observed rather than assumed. Have a target-language reader follow a safe example, then compare the resulting invocation and displayed help with the accepted command contract.

21. Right-to-left punctuation hides the command structure

Arabic or Hebrew prose surrounds a left-to-right CLI example, making the option name and equals sign visually confusing. The code bytes may be correct while their displayed order misleads.

Keep commands in isolated code blocks with an explicit readable direction where the publishing environment supports it. Do not transpose hyphens or translate punctuation inside commands.

Ask a target-language reviewer to copy the command into a shell and explain which token is the option and which is its value. Verify rendered order and copied bytes.

Practical review exercise: start with the real option declaration associated with right-to-left punctuation hides the command structure. Mark which characters are parser syntax, which sentence is explanatory text and which behavior must be observed rather than assumed. Have a target-language reader follow a safe example, then compare the resulting invocation and displayed help with the accepted command contract.

22. Help columns wrap poorly under wide-script text

A Chinese or Japanese description takes more display cells than its apparent character count. A long column pushes the next option off a narrow terminal.

Use short help phrases that preserve necessary conditions, and move extended explanation into paragraphs. Test the actual GLib help output rather than relying on a browser preview.

Capture terminal output at narrow and conventional widths using representative fonts. Confirm every flag is paired with its correct description after wrapping.

Practical review exercise: start with the real option declaration associated with help columns wrap poorly under wide-script text. Mark which characters are parser syntax, which sentence is explanatory text and which behavior must be observed rather than assumed. Have a target-language reader follow a safe example, then compare the resulting invocation and displayed help with the accepted command contract.

23. Terminal encoding is mistaken for bad translation

The .mo catalogue contains valid characters but the terminal displays squares or replacement glyphs. Editing the translation repeatedly cannot fix a locale or font mismatch.

Test encoding, locale initialization and display capability separately. Record the supported terminal environment and provide fallback guidance rather than promising impossible universality.

Save raw output bytes and visible terminal evidence. Only approve the locale when the intended user can actually read the help screen.

Practical review exercise: start with the real option declaration associated with terminal encoding is mistaken for bad translation. Mark which characters are parser syntax, which sentence is explanatory text and which behavior must be observed rather than assumed. Have a target-language reader follow a safe example, then compare the resulting invocation and displayed help with the accepted command contract.

24. Filename encoding is confused with output text encoding

A Vala developer sees that OptionArg.FILENAME produced a path and assumes it can be copied without conversion into a UTF-8 JSON field. The result may be wrong on some platforms.

Keep the GLib filename-encoding boundary distinct from ordinary translated text and from serialized machine data. Use supported conversion paths where required, with error handling.

Round-trip a non-ASCII filename through the application and its machine output. Compare identities rather than visual approximations; check the operating systems that matter.

Practical review exercise: start with the real option declaration associated with filename encoding is confused with output text encoding. Mark which characters are parser syntax, which sentence is explanatory text and which behavior must be observed rather than assumed. Have a target-language reader follow a safe example, then compare the resulting invocation and displayed help with the accepted command contract.

25. A program starts performing writes in documentation examples

An educational example uses –output pointing at a real user file, potentially overwriting it. The translation reads well but the workflow is unsafe to copy.

Prefer a fresh disposable directory, a fictional filename and a read-only operation for introductory teaching. Explain side effects and overwrite behavior before instructing users to run a real write.

Have a reviewer execute the commands in an empty test directory and inspect the resulting files. No unintended changes should occur.

Practical review exercise: start with the real option declaration associated with a program starts performing writes in documentation examples. Mark which characters are parser syntax, which sentence is explanatory text and which behavior must be observed rather than assumed. Have a target-language reader follow a safe example, then compare the resulting invocation and displayed help with the accepted command contract.

26. A newer GLib feature is shown as universally available

A guide uses set_strict_posix or parse_strv without noting the GLib version on which a method is available. Readers with older distributions see compilation or API errors.

Check method availability against the supported GLib version floor and Vala binding package. Annotate examples where a feature needs newer libraries, or use an older supported path.

Build with the oldest and newest supported dependencies. Record precise versions and correct documentation before release rather than relying only on the latest hosted API page.

Practical review exercise: start with the real option declaration associated with a newer glib feature is shown as universally available. Mark which characters are parser syntax, which sentence is explanatory text and which behavior must be observed rather than assumed. Have a target-language reader follow a safe example, then compare the resulting invocation and displayed help with the accepted command contract.

27. An integration script breaks when human output is localized

The CLI prints a translated heading before a JSON record and a downstream script reads the first line as machine data. A user-interface improvement has damaged an automation path.

Separate translated help and diagnostics from stable machine-readable output. Define which fields, exit codes and streams automation may rely upon, and test the contract in each locale.

Run a downstream parser with English and another language; compare the structured records. Human messages can differ, but promised machine keys must remain unchanged.

Practical review exercise: start with the real option declaration associated with an integration script breaks when human output is localized. Mark which characters are parser syntax, which sentence is explanatory text and which behavior must be observed rather than assumed. Have a target-language reader follow a safe example, then compare the resulting invocation and displayed help with the accepted command contract.

Chapter 5 — Six guided labs for responsible localization

Discover the accepted grammar

Collect every OptionEntry and group, including inherited library options. Record long and short names, argument type, placeholder, default, required application validations and associated translation domain. This is the contract against which all translated examples must be checked.

Record the exact binary and library versions, the locale and shell, the user action, expected behavior and observed behavior. A technical reviewer checks parser fidelity; a language reviewer checks comprehensibility. Both views matter, especially when encoding or layout makes a valid command difficult to use.

Verify catalogue reachability

Choose a visible message and translate it into a test locale. Build and install the actual package with its compiled catalogue, invoke –help under that locale and record the resulting output. A source file in the repository alone is not proof of a working translation.

Build an error-origin table

Trigger an unknown option, a missing value, a malformed number and a missing file. Label which errors originate in OptionContext and which arise in later application logic. Draft precise repairs rather than recycling one generic failure sentence.

Exercise filenames responsibly

Use disposable paths with spaces, accents and non-Latin characters. Compare OptionArg.FILENAME behavior with the supported runtime and actual file opening, then test how the path is displayed in diagnostics. Avoid sharing private filenames in published samples.

Review help in several widths

Capture –help and –help-all at narrow and normal terminal dimensions. Inspect word wrapping, long placeholders, grouped options and translated wide-script text. Keep a human reader in the review, not just a string-diff tool.

Preserve downstream output

Have a test process consume the CLI’s promised machine format under at least two locales. Compare keys, values, separators and exit conventions. Any intentional format change deserves a separate migration plan rather than an unnoticed translation edit.

Chapter 6 — Frequently asked questions

Does GLib translate –help automatically?

OptionContext can generate help and can use a translation function or domain for human-facing strings. A working multilingual build still requires catalogues, domain setup, locale initialization and real output testing.

The fastest reliable answer is often a direct experiment with the installed binary and a representative locale. Check the accepted syntax, inspect the complete help output and confirm the visible result before changing prose or promising cross-platform support.

Which OptionEntry fields should translators edit?

Generally descriptions and argument placeholders are reader-facing. long_name, short_name and OptionArg determine accepted syntax and types; changing them is an application-interface decision.

Why use FILENAME rather than STRING for paths?

GLib documents different treatment of filename arguments and ordinary strings. That distinction matters for encoding and platform behavior; use the type matching the actual input.

Does add_main_entries translate every plugin’s options?

No. Additional option groups may have their own translation functions and domains. Check –help-all and group-specific help where those groups are exposed.

What if –help is printed in English under a non-English locale?

Verify runtime locale, translation domain, installed catalogue and the exact strings marked for translation. Do not presume the .po source file is being loaded.

Can we rename –output in a translated manual?

Not without implementing the renamed switch in the program. The safer standard is to preserve literal syntax and translate explanations around it.

What is the purpose of OptionError?

It reports parsing failures at the parser boundary. Application-specific errors such as nonexistent reports or access-denied paths need their own handling and explanations.

Does Unicode help text prove Unicode filename support?

No. Terminal rendering, GLib argument conversions, operating system path rules and application file handling are separate tests.

Should we localize numeric values in copyable commands?

Preserve what the parser accepts. Localized display of quantities belongs in prose; commas or other separators may produce invalid arguments.

When is custom help better than generated help?

Only when the application has a clear unmet reader need and can maintain correctness and tests. Generated help is often a reliable source for basic option syntax.

How do we review right-to-left languages?

Separate left-to-right executable snippets from right-to-left prose in the rendered page, and test copy/paste as well as human readability.

What is a sensible release gate?

Check a valid invocation, generated help, one or more parser errors, positional paths, relevant option groups, terminal layout, Unicode filenames and downstream output compatibility.

Chapter 7 — A four-week plan from first reading to release

Week one — inventory the parser

Examine OptionContext and every OptionEntry as used in the shipped application, including dependency groups. Separate identifiers, value types, defaults and positional rules from descriptions, placeholders and help summaries. Record the existing behavior of –help, –help-all, unknown options and a valid invocation. Choose a small number of supported locales for the initial test. Write down the GLib and Vala versions to avoid demonstrating an API that an older supported build does not have.

Week two — connect the language system

Prepare translations for option descriptions, argument labels, summaries and application-owned errors. Link catalogues to the correct domain and ensure the deployed build can find them. Review terminology with a target-language reader and an engineer who knows the option semantics. Keep commands pasteable and use fictional, safe file paths in examples. Inspect the complete generated output because concise entries can become unreadable when several longer translated phrases appear together.

Week three — test the uncomfortable cases

Try bad values, unknown options, repeated arguments, grouped help, a filename beginning with a dash, a path containing spaces and a Unicode filename. Confirm which failures arise from OptionContext and which originate in the app. Capture stdout, stderr and exit status. Test terminal display in scripts with different writing systems and, when relevant, right-to-left prose. Run any machine-output consumer under two locales to confirm the data contract stays intact.

Week four — validate with new readers

Give a new reader only the localized page and a clean test installation. Ask them to locate a flag, run a harmless command and recover from a predictable mistake. If they cannot identify the next action, revise the explanation before release. Archive screenshots, command transcripts, catalogue version and tested platform combinations. Add a maintenance trigger for changes to OptionEntry declarations, GLib, gettext packaging or expected output. A translation is useful only as long as its examples remain true.

Chapter 8 — A command-line interface that travels well

The strongest multilingual Vala CLI is one in which GLib.OptionContext still recognizes stable commands while readers understand those commands in their own language. Generated help, gettext domains, OptionEntry types and filename encoding each solve a different part of the problem. None cancels the need for honest examples, safe defaults, readable errors and terminal-level tests.

Treat translation as a task-completion discipline. A reader should discover the operation, distinguish a literal flag from a placeholder, predict the result and recover safely from a mistake. That outcome matters more than matching individual English phrases. Document the actual supported build and its limitations so the guidance remains trustworthy across locations and languages.