C++ argh localization is the work of giving international users accurate command-line instructions for programs built with the minimalist, header-only adishavit/argh argument parser. If you are searching for C++ argh::parser translation, custom CLI help, flags versus parameters, Unicode filenames or multilingual terminal errors, begin with one important limit: argh does not provide a complete automatic usage-generation and strict-validation framework. The application author has to make many of those decisions explicitly.
Imagine a museum digitization project that lets visitors preview a public catalog without changing any records. The C++ program accepts –catalog=items.json and a –verbose flag. A French guide can explain the catalog in natural French, but it must not replace –catalog with an invented executable word. A Japanese guide needs examples that display well in terminals with narrow columns and local filenames. If a user mistypes an unknown option, the manual must not promise automatic diagnostics that the application never implemented.
This guide examines argh’s parameter registration, bracket and parenthesis accessors, equals-sign splitting, parser modes, typed extraction, application-level help and errors, Unicode path behavior, shell quoting and cross-platform testing. It uses a read-only fixture, explains exactly where the parser stops and application policy begins, and shows how to write understandable educational nonfiction for readers worldwide without teaching invalid command lines.
Quick answer: how argh localization should work
- Keep the real argh-recognized flag and parameter names literal in copyable commands.
- Translate human-facing descriptions, custom help and recovery steps as full natural sentences.
- Do not promise automatic syntax validation or usage generation that argh explicitly does not provide.
- Test missing and empty parameter values in the application, not only in a parser demonstration.
- Test Unicode paths, shell quoting, output status and terminal layout on supported systems.
Understand why argh differs from larger CLI frameworks
The library is deliberately small. It parses arguments into positional values, Boolean-style flags and named parameters, and leaves many higher-level policies to the application. The developer decides which names are legitimate, how missing required data should be handled and what –help should print. A translation should be equally clear about those responsibilities. If the guide claims that argh automatically rejects unknown switches or generates extensive usage text, its polished language will be factually wrong.
Command-line syntax and natural-language explanation are distinct. In archive-check –catalog=items.json –verbose, the catalog option and verbosity flag are intended fixed executable controls, while items.json is an example of a value a reader may replace. A translation can explain where to find the catalog and what verbose output means, but it cannot make another option spelling work simply by using a different noun. The parser and its callers see bytes and argument boundaries, not the writer’s intentions.
When problems appear, identify the responsible layer. The shell can split an unquoted filename with spaces before C++ receives it. The parser can interpret a string as a flag rather than a parameter. The application can refuse an empty filename, fail to open a file or reject an unsupported data format. The terminal can wrap translated help awkwardly while the command still succeeds. Each diagnosis requires different advice. A world-facing guide teaches that reasoning in plain language.
A small read-only program for learning
#include <iostream>
#include <string>
#include "argh.h"
int main(int argc, char* argv[]) {
argh::parser cmdl({"--catalog"});
cmdl.parse(argc, argv);
const bool verbose = cmdl[{"-v", "--verbose"}];
const std::string catalog = cmdl("catalog").str();
if (catalog.empty()) {
std::cerr << "Provide --catalog=FILE\n";
return 2;
}
std::cout << "Catalog: " << catalog << "\n";
if (verbose) std::cout << "Verbose preview enabled\n";
return 0;
}The program is intentionally modest: it demonstrates extracting a value and a flag and printing a preview. It does not open or alter a real archive. The missing-catalog rule and the resulting status code are application decisions, not proof of automatic argh validation. A working invocation is archive-check –catalog=items.json –verbose. To exercise the error branch, run archive-check –catalog= and examine the diagnostic. Use your actual compiled executable name and the compiler settings for the installed library revision.
The distinction between [] and () matters in both code and explanation. The bracket form can look up flags; the parenthesis form retrieves a parameter stream or string. Users do not need to memorize the implementation to follow the command, but they do need examples showing when an option is a presence/absence choice and when a value follows a name. In an international manual, mark which substrings remain literal and which file names can be replaced.
The argh field guide: 34 decisions that affect real users
1. Minimalist parser philosophy
The adishavit/argh library treats argument parsing as a compact task and leaves many application policies to the author. Put the reader’s immediate task before the technical name: what can be entered, what will the program interpret, and what visible result should follow? When the choice involves a command token, show it literally; when it involves a filename or quantity, mark the value as replaceable. A natural translation is useful only if it still teaches executable truth.
A translation guide that promises comprehensive syntax validation misrepresents the parser’s design. This problem cannot be solved solely by swapping English words for equivalents. Confirm the actual parsing mode and the behavior of any application-level checks, then explain that behavior in a complete local-language sentence. Do not describe a feature as automatic merely because another C++ argument parser implements it.
Run an empty invocation and an unknown switch before describing supported error handling. Compare the accepted case with a deliberately rejected or unusual one and record the observed output and process status. A newcomer should be able to follow the translated guide, identify which characters to type and explain the outcome without reading the C++ code. If the command works only on a developer’s machine, qualify the example rather than overstating portability.
2. Header-only integration
argh is designed as a single-header C++ library without extensive external runtime dependencies. Put the reader’s immediate task before the technical name: what can be entered, what will the program interpret, and what visible result should follow? When the choice involves a command token, show it literally; when it involves a filename or quantity, mark the value as replaceable. A natural translation is useful only if it still teaches executable truth.
A guide can confuse readers by pretending a separate localization service is built into the header. This problem cannot be solved solely by swapping English words for equivalents. Confirm the actual parsing mode and the behavior of any application-level checks, then explain that behavior in a complete local-language sentence. Do not describe a feature as automatic merely because another C++ argument parser implements it.
Build a small test program using the project’s supported compiler and recorded library revision. Compare the accepted case with a deliberately rejected or unusual one and record the observed output and process status. A newcomer should be able to follow the translated guide, identify which characters to type and explain the outcome without reading the C++ code. If the command works only on a developer’s machine, qualify the example rather than overstating portability.
3. Flag lookup with brackets
The [] interface tests flags, often using a literal name or a group of accepted spellings. Put the reader’s immediate task before the technical name: what can be entered, what will the program interpret, and what visible result should follow? When the choice involves a command token, show it literally; when it involves a filename or quantity, mark the value as replaceable. A natural translation is useful only if it still teaches executable truth.
A translated name is not automatically a recognized C++ option. This problem cannot be solved solely by swapping English words for equivalents. Confirm the actual parsing mode and the behavior of any application-level checks, then explain that behavior in a complete local-language sentence. Do not describe a feature as automatic merely because another C++ argument parser implements it.
Inspect and test the same spellings documented in help. Compare the accepted case with a deliberately rejected or unusual one and record the observed output and process status. A newcomer should be able to follow the translated guide, identify which characters to type and explain the outcome without reading the C++ code. If the command works only on a developer’s machine, qualify the example rather than overstating portability.
4. Named parameter lookup
The () interface provides access to parameters whose values are supplied with a name. Put the reader’s immediate task before the technical name: what can be entered, what will the program interpret, and what visible result should follow? When the choice involves a command token, show it literally; when it involves a filename or quantity, mark the value as replaceable. A natural translation is useful only if it still teaches executable truth.
A guide may mix up flag presence with a value-bearing option. This problem cannot be solved solely by swapping English words for equivalents. Confirm the actual parsing mode and the behavior of any application-level checks, then explain that behavior in a complete local-language sentence. Do not describe a feature as automatic merely because another C++ argument parser implements it.
Show –catalog=FILE separately from –verbose and print the returned value. Compare the accepted case with a deliberately rejected or unusual one and record the observed output and process status. A newcomer should be able to follow the translated guide, identify which characters to type and explain the outcome without reading the C++ code. If the command works only on a developer’s machine, qualify the example rather than overstating portability.
5. Parameter registration
Some space-separated named parameters must be designated as value-bearing before parsing. Put the reader’s immediate task before the technical name: what can be entered, what will the program interpret, and what visible result should follow? When the choice involves a command token, show it literally; when it involves a filename or quantity, mark the value as replaceable. A natural translation is useful only if it still teaches executable truth.
Without the intended declaration, a value can be interpreted as a positional argument. This problem cannot be solved solely by swapping English words for equivalents. Confirm the actual parsing mode and the behavior of any application-level checks, then explain that behavior in a complete local-language sentence. Do not describe a feature as automatic merely because another C++ argument parser implements it.
Test both supported equals and space-separated forms using the exact parser construction. Compare the accepted case with a deliberately rejected or unusual one and record the observed output and process status. A newcomer should be able to follow the translated guide, identify which characters to type and explain the outcome without reading the C++ code. If the command works only on a developer’s machine, qualify the example rather than overstating portability.
6. Equals-sign splitting
Default handling may recognize –name=value unless an alternate parsing mode changes it. Put the reader’s immediate task before the technical name: what can be entered, what will the program interpret, and what visible result should follow? When the choice involves a command token, show it literally; when it involves a filename or quantity, mark the value as replaceable. A natural translation is useful only if it still teaches executable truth.
A writer may insert spaces around equals for readability and thereby change the tokens. This problem cannot be solved solely by swapping English words for equivalents. Confirm the actual parsing mode and the behavior of any application-level checks, then explain that behavior in a complete local-language sentence. Do not describe a feature as automatic merely because another C++ argument parser implements it.
Copy the command exactly and compare extracted values. Compare the accepted case with a deliberately rejected or unusual one and record the observed output and process status. A newcomer should be able to follow the translated guide, identify which characters to type and explain the outcome without reading the C++ code. If the command works only on a developer’s machine, qualify the example rather than overstating portability.
7. NO_SPLIT_ON_EQUALSIGN
This parsing mode disables the ordinary equals-sign split behavior. Put the reader’s immediate task before the technical name: what can be entered, what will the program interpret, and what visible result should follow? When the choice involves a command token, show it literally; when it involves a filename or quantity, mark the value as replaceable. A natural translation is useful only if it still teaches executable truth.
An example that assumes equals splitting works in every mode will fail after a mode change. This problem cannot be solved solely by swapping English words for equivalents. Confirm the actual parsing mode and the behavior of any application-level checks, then explain that behavior in a complete local-language sentence. Do not describe a feature as automatic merely because another C++ argument parser implements it.
Record the parse mode and test –catalog=FILE under that mode. Compare the accepted case with a deliberately rejected or unusual one and record the observed output and process status. A newcomer should be able to follow the translated guide, identify which characters to type and explain the outcome without reading the C++ code. If the command works only on a developer’s machine, qualify the example rather than overstating portability.
8. SINGLE_DASH_IS_MULTIFLAG
The compound-short-flags mode can treat -abc as several one-letter switches. Put the reader’s immediate task before the technical name: what can be entered, what will the program interpret, and what visible result should follow? When the choice involves a command token, show it literally; when it involves a filename or quantity, mark the value as replaceable. A natural translation is useful only if it still teaches executable truth.
Some readers assume all C++ parsers understand bundled flags automatically. This problem cannot be solved solely by swapping English words for equivalents. Confirm the actual parsing mode and the behavior of any application-level checks, then explain that behavior in a complete local-language sentence. Do not describe a feature as automatic merely because another C++ argument parser implements it.
Test the bundled and separated forms in the shipped build. Compare the accepted case with a deliberately rejected or unusual one and record the observed output and process status. A newcomer should be able to follow the translated guide, identify which characters to type and explain the outcome without reading the C++ code. If the command works only on a developer’s machine, qualify the example rather than overstating portability.
9. Positional tokens
The parser provides indexed access to positional arguments, including program-related position conventions. Put the reader’s immediate task before the technical name: what can be entered, what will the program interpret, and what visible result should follow? When the choice involves a command token, show it literally; when it involves a filename or quantity, mark the value as replaceable. A natural translation is useful only if it still teaches executable truth.
Calling a position the first file without checking indexing can produce off-by-one mistakes. This problem cannot be solved solely by swapping English words for equivalents. Confirm the actual parsing mode and the behavior of any application-level checks, then explain that behavior in a complete local-language sentence. Do not describe a feature as automatic merely because another C++ argument parser implements it.
Print an indexed list in a read-only demonstration and label each position. Compare the accepted case with a deliberately rejected or unusual one and record the observed output and process status. A newcomer should be able to follow the translated guide, identify which characters to type and explain the outcome without reading the C++ code. If the command works only on a developer’s machine, qualify the example rather than overstating portability.
10. Unknown switches
argh deliberately avoids strict automatic command syntax validation. Put the reader’s immediate task before the technical name: what can be entered, what will the program interpret, and what visible result should follow? When the choice involves a command token, show it literally; when it involves a filename or quantity, mark the value as replaceable. A natural translation is useful only if it still teaches executable truth.
A manual claiming an unknown flag always raises a specific exception is unreliable. This problem cannot be solved solely by swapping English words for equivalents. Confirm the actual parsing mode and the behavior of any application-level checks, then explain that behavior in a complete local-language sentence. Do not describe a feature as automatic merely because another C++ argument parser implements it.
Add application-level checking where the product needs strict supported-option enforcement. Compare the accepted case with a deliberately rejected or unusual one and record the observed output and process status. A newcomer should be able to follow the translated guide, identify which characters to type and explain the outcome without reading the C++ code. If the command works only on a developer’s machine, qualify the example rather than overstating portability.
11. Custom help
The library does not automatically produce a comprehensive usage page. Put the reader’s immediate task before the technical name: what can be entered, what will the program interpret, and what visible result should follow? When the choice involves a command token, show it literally; when it involves a filename or quantity, mark the value as replaceable. A natural translation is useful only if it still teaches executable truth.
Translating imaginary generated help means the text will not match any real command. This problem cannot be solved solely by swapping English words for equivalents. Confirm the actual parsing mode and the behavior of any application-level checks, then explain that behavior in a complete local-language sentence. Do not describe a feature as automatic merely because another C++ argument parser implements it.
Write a simple usage string in the application and test its –help route. Compare the accepted case with a deliberately rejected or unusual one and record the observed output and process status. A newcomer should be able to follow the translated guide, identify which characters to type and explain the outcome without reading the C++ code. If the command works only on a developer’s machine, qualify the example rather than overstating portability.
12. Required options
A required catalog path is an application rule that needs an explicit check. Put the reader’s immediate task before the technical name: what can be entered, what will the program interpret, and what visible result should follow? When the choice involves a command token, show it literally; when it involves a filename or quantity, mark the value as replaceable. A natural translation is useful only if it still teaches executable truth.
Saying catalog is required in prose does not cause an empty invocation to fail. This problem cannot be solved solely by swapping English words for equivalents. Confirm the actual parsing mode and the behavior of any application-level checks, then explain that behavior in a complete local-language sentence. Do not describe a feature as automatic merely because another C++ argument parser implements it.
Test absent, empty and normal values and verify appropriate exit statuses. Compare the accepted case with a deliberately rejected or unusual one and record the observed output and process status. A newcomer should be able to follow the translated guide, identify which characters to type and explain the outcome without reading the C++ code. If the command works only on a developer’s machine, qualify the example rather than overstating portability.
13. Stream conversion
Parameters may be read through stream-style conversion into typed variables. Put the reader’s immediate task before the technical name: what can be entered, what will the program interpret, and what visible result should follow? When the choice involves a command token, show it literally; when it involves a filename or quantity, mark the value as replaceable. A natural translation is useful only if it still teaches executable truth.
A localized decimal notation may not match the input stream’s grammar. This problem cannot be solved solely by swapping English words for equivalents. Confirm the actual parsing mode and the behavior of any application-level checks, then explain that behavior in a complete local-language sentence. Do not describe a feature as automatic merely because another C++ argument parser implements it.
Test a valid number, an invalid word and the applicable locale settings. Compare the accepted case with a deliberately rejected or unusual one and record the observed output and process status. A newcomer should be able to follow the translated guide, identify which characters to type and explain the outcome without reading the C++ code. If the command works only on a developer’s machine, qualify the example rather than overstating portability.
14. String retrieval
The .str() form can preserve whitespace in a parameter value better than tokenizing extraction. Put the reader’s immediate task before the technical name: what can be entered, what will the program interpret, and what visible result should follow? When the choice involves a command token, show it literally; when it involves a filename or quantity, mark the value as replaceable. A natural translation is useful only if it still teaches executable truth.
A sample filename with spaces may be truncated when extracted as one token. This problem cannot be solved solely by swapping English words for equivalents. Confirm the actual parsing mode and the behavior of any application-level checks, then explain that behavior in a complete local-language sentence. Do not describe a feature as automatic merely because another C++ argument parser implements it.
Compare string retrieval with typed stream extraction using a harmless path containing spaces. Compare the accepted case with a deliberately rejected or unusual one and record the observed output and process status. A newcomer should be able to follow the translated guide, identify which characters to type and explain the outcome without reading the C++ code. If the command works only on a developer’s machine, qualify the example rather than overstating portability.
15. Empty parameter values
A supplied key with an empty value may be different from a wholly absent parameter. Put the reader’s immediate task before the technical name: what can be entered, what will the program interpret, and what visible result should follow? When the choice involves a command token, show it literally; when it involves a filename or quantity, mark the value as replaceable. A natural translation is useful only if it still teaches executable truth.
A mere presence check can accept a meaningless file name. This problem cannot be solved solely by swapping English words for equivalents. Confirm the actual parsing mode and the behavior of any application-level checks, then explain that behavior in a complete local-language sentence. Do not describe a feature as automatic merely because another C++ argument parser implements it.
Test missing, –catalog= and –catalog=sample.json separately. Compare the accepted case with a deliberately rejected or unusual one and record the observed output and process status. A newcomer should be able to follow the translated guide, identify which characters to type and explain the outcome without reading the C++ code. If the command works only on a developer’s machine, qualify the example rather than overstating portability.
16. Negative numbers
Values beginning with a dash can interact with option tokenization. Put the reader’s immediate task before the technical name: what can be entered, what will the program interpret, and what visible result should follow? When the choice involves a command token, show it literally; when it involves a filename or quantity, mark the value as replaceable. A natural translation is useful only if it still teaches executable truth.
An arithmetic example such as -5 should not be assumed to parse identically to 5. This problem cannot be solved solely by swapping English words for equivalents. Confirm the actual parsing mode and the behavior of any application-level checks, then explain that behavior in a complete local-language sentence. Do not describe a feature as automatic merely because another C++ argument parser implements it.
Test negative bounds through the exact supported syntax. Compare the accepted case with a deliberately rejected or unusual one and record the observed output and process status. A newcomer should be able to follow the translated guide, identify which characters to type and explain the outcome without reading the C++ code. If the command works only on a developer’s machine, qualify the example rather than overstating portability.
17. Defaults
The application may apply its own value when no parameter appears. Put the reader’s immediate task before the technical name: what can be entered, what will the program interpret, and what visible result should follow? When the choice involves a command token, show it literally; when it involves a filename or quantity, mark the value as replaceable. A natural translation is useful only if it still teaches executable truth.
Translating a default as though it were entered by the user can obscure reproducibility. This problem cannot be solved solely by swapping English words for equivalents. Confirm the actual parsing mode and the behavior of any application-level checks, then explain that behavior in a complete local-language sentence. Do not describe a feature as automatic merely because another C++ argument parser implements it.
Run with the option omitted and compare with an explicit equivalent. Compare the accepted case with a deliberately rejected or unusual one and record the observed output and process status. A newcomer should be able to follow the translated guide, identify which characters to type and explain the outcome without reading the C++ code. If the command works only on a developer’s machine, qualify the example rather than overstating portability.
18. Conflicting flags
Two individually acceptable flags may express contradictory user intent. Put the reader’s immediate task before the technical name: what can be entered, what will the program interpret, and what visible result should follow? When the choice involves a command token, show it literally; when it involves a filename or quantity, mark the value as replaceable. A natural translation is useful only if it still teaches executable truth.
argh does not infer that –quiet and –verbose must be exclusive. This problem cannot be solved solely by swapping English words for equivalents. Confirm the actual parsing mode and the behavior of any application-level checks, then explain that behavior in a complete local-language sentence. Do not describe a feature as automatic merely because another C++ argument parser implements it.
Define the relationship in application code and test the conflict case. Compare the accepted case with a deliberately rejected or unusual one and record the observed output and process status. A newcomer should be able to follow the translated guide, identify which characters to type and explain the outcome without reading the C++ code. If the command works only on a developer’s machine, qualify the example rather than overstating portability.
19. Aliases
The application can check short and long names for the same logical flag. Put the reader’s immediate task before the technical name: what can be entered, what will the program interpret, and what visible result should follow? When the choice involves a command token, show it literally; when it involves a filename or quantity, mark the value as replaceable. A natural translation is useful only if it still teaches executable truth.
A translated paragraph can look like another accepted alias even when it is not. This problem cannot be solved solely by swapping English words for equivalents. Confirm the actual parsing mode and the behavior of any application-level checks, then explain that behavior in a complete local-language sentence. Do not describe a feature as automatic merely because another C++ argument parser implements it.
List only spellings tested against the parser. Compare the accepted case with a deliberately rejected or unusual one and record the observed output and process status. A newcomer should be able to follow the translated guide, identify which characters to type and explain the outcome without reading the C++ code. If the command works only on a developer’s machine, qualify the example rather than overstating portability.
20. Dash handling
The parser can be more permissive about leading dashes than some CLI toolkits. Put the reader’s immediate task before the technical name: what can be entered, what will the program interpret, and what visible result should follow? When the choice involves a command token, show it literally; when it involves a filename or quantity, mark the value as replaceable. A natural translation is useful only if it still teaches executable truth.
Assuming universal POSIX behavior may result in misleading examples. This problem cannot be solved solely by swapping English words for equivalents. Confirm the actual parsing mode and the behavior of any application-level checks, then explain that behavior in a complete local-language sentence. Do not describe a feature as automatic merely because another C++ argument parser implements it.
Prefer one canonical spelling and verify any additional forms before advertising them. Compare the accepted case with a deliberately rejected or unusual one and record the observed output and process status. A newcomer should be able to follow the translated guide, identify which characters to type and explain the outcome without reading the C++ code. If the command works only on a developer’s machine, qualify the example rather than overstating portability.
21. Environmental configuration
An application may read environment variables separately from parsed arguments. Put the reader’s immediate task before the technical name: what can be entered, what will the program interpret, and what visible result should follow? When the choice involves a command token, show it literally; when it involves a filename or quantity, mark the value as replaceable. A natural translation is useful only if it still teaches executable truth.
A manual might assume an environment value silently overrides the command line. This problem cannot be solved solely by swapping English words for equivalents. Confirm the actual parsing mode and the behavior of any application-level checks, then explain that behavior in a complete local-language sentence. Do not describe a feature as automatic merely because another C++ argument parser implements it.
Document the application’s actual precedence and test a conflicting setting. Compare the accepted case with a deliberately rejected or unusual one and record the observed output and process status. A newcomer should be able to follow the translated guide, identify which characters to type and explain the outcome without reading the C++ code. If the command works only on a developer’s machine, qualify the example rather than overstating portability.
22. Config files
The parser may return a path while the application later reads the named file. Put the reader’s immediate task before the technical name: what can be entered, what will the program interpret, and what visible result should follow? When the choice involves a command token, show it literally; when it involves a filename or quantity, mark the value as replaceable. A natural translation is useful only if it still teaches executable truth.
A valid –config argument does not prove the file contents are well formed. This problem cannot be solved solely by swapping English words for equivalents. Confirm the actual parsing mode and the behavior of any application-level checks, then explain that behavior in a complete local-language sentence. Do not describe a feature as automatic merely because another C++ argument parser implements it.
Keep path parsing, file access and schema validation distinct in recovery advice. Compare the accepted case with a deliberately rejected or unusual one and record the observed output and process status. A newcomer should be able to follow the translated guide, identify which characters to type and explain the outcome without reading the C++ code. If the command works only on a developer’s machine, qualify the example rather than overstating portability.
23. Unicode normalization
Non-ASCII names may have different normalization forms while appearing similar. Put the reader’s immediate task before the technical name: what can be entered, what will the program interpret, and what visible result should follow? When the choice involves a command token, show it literally; when it involves a filename or quantity, mark the value as replaceable. A natural translation is useful only if it still teaches executable truth.
Calling normalization automatic can conceal identity errors in archive records. This problem cannot be solved solely by swapping English words for equivalents. Confirm the actual parsing mode and the behavior of any application-level checks, then explain that behavior in a complete local-language sentence. Do not describe a feature as automatic merely because another C++ argument parser implements it.
Test composed and decomposed sample filenames under a documented policy. Compare the accepted case with a deliberately rejected or unusual one and record the observed output and process status. A newcomer should be able to follow the translated guide, identify which characters to type and explain the outcome without reading the C++ code. If the command works only on a developer’s machine, qualify the example rather than overstating portability.
24. Windows arguments
Windows argument encoding and conversion may differ from POSIX char* conventions. Put the reader’s immediate task before the technical name: what can be entered, what will the program interpret, and what visible result should follow? When the choice involves a command token, show it literally; when it involves a filename or quantity, mark the value as replaceable. A natural translation is useful only if it still teaches executable truth.
Promising UTF-8 support everywhere without tests is unsafe. This problem cannot be solved solely by swapping English words for equivalents. Confirm the actual parsing mode and the behavior of any application-level checks, then explain that behavior in a complete local-language sentence. Do not describe a feature as automatic merely because another C++ argument parser implements it.
Use non-ASCII path fixtures on the supported Windows compiler and runtime. Compare the accepted case with a deliberately rejected or unusual one and record the observed output and process status. A newcomer should be able to follow the translated guide, identify which characters to type and explain the outcome without reading the C++ code. If the command works only on a developer’s machine, qualify the example rather than overstating portability.
25. Shell quoting
A shell divides input into arguments before argh receives them. Put the reader’s immediate task before the technical name: what can be entered, what will the program interpret, and what visible result should follow? When the choice involves a command token, show it literally; when it involves a filename or quantity, mark the value as replaceable. A natural translation is useful only if it still teaches executable truth.
Using typographic quotation marks can fail to preserve filenames with spaces. This problem cannot be solved solely by swapping English words for equivalents. Confirm the actual parsing mode and the behavior of any application-level checks, then explain that behavior in a complete local-language sentence. Do not describe a feature as automatic merely because another C++ argument parser implements it.
Paste examples into each documented shell and inspect the actual received arguments. Compare the accepted case with a deliberately rejected or unusual one and record the observed output and process status. A newcomer should be able to follow the translated guide, identify which characters to type and explain the outcome without reading the C++ code. If the command works only on a developer’s machine, qualify the example rather than overstating portability.
26. CJK line widths
Custom help has to be formatted with display columns, not simply source string length. Put the reader’s immediate task before the technical name: what can be entered, what will the program interpret, and what visible result should follow? When the choice involves a command token, show it literally; when it involves a filename or quantity, mark the value as replaceable. A natural translation is useful only if it still teaches executable truth.
A long Japanese help label may misalign a value placeholder. This problem cannot be solved solely by swapping English words for equivalents. Confirm the actual parsing mode and the behavior of any application-level checks, then explain that behavior in a complete local-language sentence. Do not describe a feature as automatic merely because another C++ argument parser implements it.
Review help at 50 and 80 columns with actual Japanese text. Compare the accepted case with a deliberately rejected or unusual one and record the observed output and process status. A newcomer should be able to follow the translated guide, identify which characters to type and explain the outcome without reading the C++ code. If the command works only on a developer’s machine, qualify the example rather than overstating portability.
27. Right-to-left labels
Arabic or Hebrew explanations beside –flags need visual inspection. Put the reader’s immediate task before the technical name: what can be entered, what will the program interpret, and what visible result should follow? When the choice involves a command token, show it literally; when it involves a filename or quantity, mark the value as replaceable. A natural translation is useful only if it still teaches executable truth.
The rendered order can mislead copying even when logical Unicode strings are correct. This problem cannot be solved solely by swapping English words for equivalents. Confirm the actual parsing mode and the behavior of any application-level checks, then explain that behavior in a complete local-language sentence. Do not describe a feature as automatic merely because another C++ argument parser implements it.
Ask a fluent user to copy and run the command from a terminal capture. Compare the accepted case with a deliberately rejected or unusual one and record the observed output and process status. A newcomer should be able to follow the translated guide, identify which characters to type and explain the outcome without reading the C++ code. If the command works only on a developer’s machine, qualify the example rather than overstating portability.
28. Error statuses
The application chooses diagnostics and process status for many error cases. Put the reader’s immediate task before the technical name: what can be entered, what will the program interpret, and what visible result should follow? When the choice involves a command token, show it literally; when it involves a filename or quantity, mark the value as replaceable. A natural translation is useful only if it still teaches executable truth.
Printing a translated warning while returning success can fool scripts. This problem cannot be solved solely by swapping English words for equivalents. Confirm the actual parsing mode and the behavior of any application-level checks, then explain that behavior in a complete local-language sentence. Do not describe a feature as automatic merely because another C++ argument parser implements it.
Assert nonzero status for deliberately invalid invocations. Compare the accepted case with a deliberately rejected or unusual one and record the observed output and process status. A newcomer should be able to follow the translated guide, identify which characters to type and explain the outcome without reading the C++ code. If the command works only on a developer’s machine, qualify the example rather than overstating portability.
29. Stdout versus stderr
Structured data and human errors can require different output channels. Put the reader’s immediate task before the technical name: what can be entered, what will the program interpret, and what visible result should follow? When the choice involves a command token, show it literally; when it involves a filename or quantity, mark the value as replaceable. A natural translation is useful only if it still teaches executable truth.
Injecting a translation banner before JSON can break consumers. This problem cannot be solved solely by swapping English words for equivalents. Confirm the actual parsing mode and the behavior of any application-level checks, then explain that behavior in a complete local-language sentence. Do not describe a feature as automatic merely because another C++ argument parser implements it.
Redirect both streams and test machine parsing independently. Compare the accepted case with a deliberately rejected or unusual one and record the observed output and process status. A newcomer should be able to follow the translated guide, identify which characters to type and explain the outcome without reading the C++ code. If the command works only on a developer’s machine, qualify the example rather than overstating portability.
30. Subcommand dispatch
A complex application may interpret a positional value as a command route. Put the reader’s immediate task before the technical name: what can be entered, what will the program interpret, and what visible result should follow? When the choice involves a command token, show it literally; when it involves a filename or quantity, mark the value as replaceable. A natural translation is useful only if it still teaches executable truth.
The minimalist parser does not by itself implement a complete internationalized subcommand system. This problem cannot be solved solely by swapping English words for equivalents. Confirm the actual parsing mode and the behavior of any application-level checks, then explain that behavior in a complete local-language sentence. Do not describe a feature as automatic merely because another C++ argument parser implements it.
Document application dispatch decisions without attributing them to argh. Compare the accepted case with a deliberately rejected or unusual one and record the observed output and process status. A newcomer should be able to follow the translated guide, identify which characters to type and explain the outcome without reading the C++ code. If the command works only on a developer’s machine, qualify the example rather than overstating portability.
31. Locale catalogs
An application can choose resources for help and recovery messages. Put the reader’s immediate task before the technical name: what can be entered, what will the program interpret, and what visible result should follow? When the choice involves a command token, show it literally; when it involves a filename or quantity, mark the value as replaceable. A natural translation is useful only if it still teaches executable truth.
Translating a resource key does not register a new switch. This problem cannot be solved solely by swapping English words for equivalents. Confirm the actual parsing mode and the behavior of any application-level checks, then explain that behavior in a complete local-language sentence. Do not describe a feature as automatic merely because another C++ argument parser implements it.
Vary a catalog string and confirm parsing behavior remains stable. Compare the accepted case with a deliberately rejected or unusual one and record the observed output and process status. A newcomer should be able to follow the translated guide, identify which characters to type and explain the outcome without reading the C++ code. If the command works only on a developer’s machine, qualify the example rather than overstating portability.
32. Safe examples
Parser lessons need no deletion, upload or modification of production data. Put the reader’s immediate task before the technical name: what can be entered, what will the program interpret, and what visible result should follow? When the choice involves a command token, show it literally; when it involves a filename or quantity, mark the value as replaceable. A natural translation is useful only if it still teaches executable truth.
A tutorial that runs destructive commands creates unnecessary hazards for beginners. This problem cannot be solved solely by swapping English words for equivalents. Confirm the actual parsing mode and the behavior of any application-level checks, then explain that behavior in a complete local-language sentence. Do not describe a feature as automatic merely because another C++ argument parser implements it.
Use a read-only file preview with temporary public samples. Compare the accepted case with a deliberately rejected or unusual one and record the observed output and process status. A newcomer should be able to follow the translated guide, identify which characters to type and explain the outcome without reading the C++ code. If the command works only on a developer’s machine, qualify the example rather than overstating portability.
33. Cross-platform regression
Compiler, shell, locale and parser-mode differences can change behavior after releases. Put the reader’s immediate task before the technical name: what can be entered, what will the program interpret, and what visible result should follow? When the choice involves a command token, show it literally; when it involves a filename or quantity, mark the value as replaceable. A natural translation is useful only if it still teaches executable truth.
Compilation success alone does not guarantee all translated commands still work. This problem cannot be solved solely by swapping English words for equivalents. Confirm the actual parsing mode and the behavior of any application-level checks, then explain that behavior in a complete local-language sentence. Do not describe a feature as automatic merely because another C++ argument parser implements it.
Automate valid, invalid and help paths across supported platforms. Compare the accepted case with a deliberately rejected or unusual one and record the observed output and process status. A newcomer should be able to follow the translated guide, identify which characters to type and explain the outcome without reading the C++ code. If the command works only on a developer’s machine, qualify the example rather than overstating portability.
34. Future option changes
An additional option can make old help and examples incomplete. Put the reader’s immediate task before the technical name: what can be entered, what will the program interpret, and what visible result should follow? When the choice involves a command token, show it literally; when it involves a filename or quantity, mark the value as replaceable. A natural translation is useful only if it still teaches executable truth.
Collective copy that says exactly two formats becomes false when a third appears. This problem cannot be solved solely by swapping English words for equivalents. Confirm the actual parsing mode and the behavior of any application-level checks, then explain that behavior in a complete local-language sentence. Do not describe a feature as automatic merely because another C++ argument parser implements it.
Reconcile translated descriptions against the registered supported options every release. Compare the accepted case with a deliberately rejected or unusual one and record the observed output and process status. A newcomer should be able to follow the translated guide, identify which characters to type and explain the outcome without reading the C++ code. If the command works only on a developer’s machine, qualify the example rather than overstating portability.
Extended case studies for international C++ tools
Case study 1: A museum catalog preview
A museum provides a read-only catalog listing command to external conservation volunteers. The developer uses argh for –catalog and –verbose, and writes explicit help and missing-file checks in the application. A Polish translator explains the task, but keeps the literal switches stable. Volunteers test local filenames and one intentionally empty catalog value. The resulting guide is useful because it tells them exactly what to type and why a rejected command was rejected.
The independent-reader test is straightforward. Give someone a safe file and the translated guide, ask them to run the preview, replace one value and recover from one intentional mistake. Observe whether they reach for a correct flag or guess an unregistered translation. Improve the wording where they hesitate and repeat the task on a clean build. That is stronger evidence than an attractive help screenshot.
Case study 2: A scientific lab’s threshold input
An environmental physics lab accepts –threshold=NUMBER and prints a preview of a configured analysis threshold. One translated handout shows a comma decimal separator although the C++ extraction routine expects another format. A reviewer tests the exact stream conversion, then explains the accepted numeric syntax without implying it automatically follows the reader’s spreadsheet settings. This prevents a value-grammar mistake from masquerading as a language problem.
The independent-reader test is straightforward. Give someone a safe file and the translated guide, ask them to run the preview, replace one value and recover from one intentional mistake. Observe whether they reach for a correct flag or guess an unregistered translation. Improve the wording where they hesitate and repeat the task on a clean build. That is stronger evidence than an attractive help screenshot.
Case study 3: An international heritage archive on Windows and Linux
A cross-platform volunteer tool accepts paths with spaces and non-ASCII names. An initial guide uses curly quotation marks copied from a document editor; a Windows test also reveals different argument conversion behavior. The team checks each real shell, the program’s encoding policy and the actual command received by the parser. The final documentation states supported paths clearly instead of promising universal UTF-8 handling without proof.
The independent-reader test is straightforward. Give someone a safe file and the translated guide, ask them to run the preview, replace one value and recover from one intentional mistake. Observe whether they reach for a correct flag or guess an unregistered translation. Improve the wording where they hesitate and repeat the task on a clean build. That is stronger evidence than an attractive help screenshot.
A multilingual acceptance test that protects the command
Parser and application rules
List which requirements argh implements and which the application checks. Test missing, empty and malformed values rather than assuming the parser refuses them. For each test, write the literal invocation, input fixture, expected result and actual result. A localization review is complete only when the translated instruction works in the environment and the recovery advice matches the observed failure.
Platform and shell
Run the same sample in the documented shell environments with a path containing spaces, one accented filename and one CJK filename. Capture the argv outcome where possible. For each test, write the literal invocation, input fixture, expected result and actual result. A localization review is complete only when the translated instruction works in the environment and the recovery advice matches the observed failure.
Terminal and direction
Review 50- and 80-column help, Arabic text beside left-to-right flags and plain output for assistive readers. Confirm copied commands remain correct. For each test, write the literal invocation, input fixture, expected result and actual result. A localization review is complete only when the translated instruction works in the environment and the recovery advice matches the observed failure.
Machine compatibility
Keep structured output and exit statuses stable. Redirect stdout and stderr separately and test both a read-only success path and an intentional rejection. For each test, write the literal invocation, input fixture, expected result and actual result. A localization review is complete only when the translated instruction works in the environment and the recovery advice matches the observed failure.
Build reproducibility
Record compiler, library revision, parse mode, source code and executable version. Confirm examples after rebuilding in a clean environment. For each test, write the literal invocation, input fixture, expected result and actual result. A localization review is complete only when the translated instruction works in the environment and the recovery advice matches the observed failure.
Native-language task completion
Give a reviewer the real localized help, not an English explanation of it. Check whether the reader completes a safe task and accurately diagnoses an error. For each test, write the literal invocation, input fixture, expected result and actual result. A localization review is complete only when the translated instruction works in the environment and the recovery advice matches the observed failure.
Frequently asked questions about argh
Does argh generate –help in other languages?
No. The upstream design does not include automatic comprehensive usage generation. The application must write and localize its own help. The reader should also be given one concrete command to test the answer. If behavior varies by build or parsing mode, state that condition clearly rather than treating it as a rule that applies everywhere.
Are [] and () the same?
No. Use the documented lookup semantics: [] is associated with flags and positional indexing, while () accesses named parameter values. The reader should also be given one concrete command to test the answer. If behavior varies by build or parsing mode, state that condition clearly rather than treating it as a rule that applies everywhere.
Can I translate a switch?
Only if application code actually recognizes the new spelling. A translation of its explanation does not register an alias. The reader should also be given one concrete command to test the answer. If behavior varies by build or parsing mode, state that condition clearly rather than treating it as a rule that applies everywhere.
Will argh reject every unknown option?
Do not assume it will. The library is intentionally permissive; the application needs its own supported-option rules when strict validation matters. The reader should also be given one concrete command to test the answer. If behavior varies by build or parsing mode, state that condition clearly rather than treating it as a rule that applies everywhere.
Why does a filename with spaces fail?
Check shell quoting and string extraction before blaming argh or language. The argument boundary may have changed before parsing. The reader should also be given one concrete command to test the answer. If behavior varies by build or parsing mode, state that condition clearly rather than treating it as a rule that applies everywhere.
Does char* argv always contain UTF-8 on Windows?
No universal promise is safe. Test the supported Windows runtime’s argument encoding and application conversion policy. The reader should also be given one concrete command to test the answer. If behavior varies by build or parsing mode, state that condition clearly rather than treating it as a rule that applies everywhere.
What is a safe first project?
Use a read-only preview with one catalog parameter, one flag, custom help and explicit missing-value checks. The reader should also be given one concrete command to test the answer. If behavior varies by build or parsing mode, state that condition clearly rather than treating it as a rule that applies everywhere.
A four-week learning and release path
Week 1 — capture the real grammar
Build a read-only sample with the installed header and compiler. Record flags, parameter names, parse modes, positional indexing and custom help. Test an absent parameter and unknown flag to learn which layer actually handles each condition. Keep the version, command, input fixture, output, status and unresolved caveat in a compact release record. This makes it easier to update the guide honestly when the parser mode or application changes.
Week 2 — write usable multilingual copy
Translate purpose, help, examples and recovery sentences. Keep literals and sample values visibly distinct. Give fluent readers a safe command and ask them to explain which fragment is replaceable. Keep the version, command, input fixture, output, status and unresolved caveat in a compact release record. This makes it easier to update the guide honestly when the parser mode or application changes.
Week 3 — test the boundaries
Check string extraction, negative values, equals splitting, empty parameters, shell quoting, Unicode paths, Windows argument conversion, CJK wrapping and bidi order. Capture streams and process status. Keep the version, command, input fixture, output, status and unresolved caveat in a compact release record. This makes it easier to update the guide honestly when the parser mode or application changes.
Week 4 — independent reader review
Provide a clean executable and localized guide to someone unfamiliar with the source. Observe a valid run and a deliberate failure; revise unclear instructions and archive the tested conditions. Keep the version, command, input fixture, output, status and unresolved caveat in a compact release record. This makes it easier to update the guide honestly when the parser mode or application changes.
Final checklist and connected reading
A reliable C++ argh translation explains the user’s goal clearly, preserves the real command syntax, documents application-owned validation, and tests actual terminal behavior. It avoids claiming automatic help or strict checking that the library does not provide. The best guide helps a reader decide what to enter, understand what the program did and recover safely from mistakes, in the language they use every day.
- Information-first opening paragraphs explain argh and the parser’s limits.
- Copyable examples preserve real flags and distinguish replaceable values.
- Missing and unknown inputs are tested at the correct application layer.
- Unicode, shell quoting, terminal width and output streams receive separate checks.
- The article includes primary documentation and architectural connections.