PHP GetOpt.php localization makes command-line options, help pages, validation failures and instructions understandable across languages without breaking scripts. The ulrichsg/getopt-php project, commonly called GetOpt.php, documents a Translator, GetOpt::setLang, bundled language resources, custom language-file paths and English fallback for missing messages. This guide explains those capabilities alongside option and operand definitions, command routing, error handling, Unicode values and reliable multilingual release testing.
Picture ParcelLedger, a fictional PHP CLI used by a logistics team to import parcel manifests and reconcile shipping records. A Spanish-speaking operator needs a clear explanation of –warehouse; an automated job must keep using that exact option; and a developer needs to distinguish a missing required argument from a malformed manifest. A fluent translation is valuable only if it preserves the data contract and tells users what a command will actually do. GetOpt.php’s documented localization support offers a useful starting point, but application-specific messages still require deliberate handling.
Readers will find a practical quick-start, a model of the parser’s human and machine responsibilities, a short code example, detailed investigations into setLang, validation, option aliases, operands, commands and help generation, plus an international QA matrix, FAQs and a four-week rollout plan. The discussion distinguishes this third-party GetOpt.php library from PHP’s native getopt() function, which has a different API. Its search intent is focused on building and checking multilingual PHP command-line interfaces rather than general translation theory.
Quick answer: localize the explanation, protect the executable contract
- Keep parser-recognized command names, options, placeholders and machine identifiers unchanged unless deliberately versioning the interface.
- Translate task explanations, friendly descriptions, warnings and help prose with full context.
- Inventory human strings separately from options, arguments, types, code, data keys, exit statuses and file paths.
- Measure the behavior of the installed version, not a remembered example from another command-line library.
- Test at least one successful command, one invalid command, a help request and a non-Latin file path.
- Check resource fallback, stdout versus stderr, screen-reader access and narrow terminal rendering.
- Use native-language task trials to assess whether a person knows what a command will actually do.
- Preserve a reproducible release and rollback path for every new locale.
The first useful action is to capture the installed tool’s help, a known-valid invocation and two failures before editing any text. Record the exact command, version, locale, operating system, result files and process status. This becomes a small but powerful baseline: it separates a disagreement about translation style from an actual change in software behavior. A localizer can then focus on helping a person make the right decision, and a developer can show that the command still performs the same operation.
The framework and the translation boundary
GetOpt.php defines options using GetOpt\Option objects or documented helper forms, and can process argument vectors using GetOpt::process. The feature model includes named options, short options, arguments, operands, commands, validation and help text. Those elements are related but not interchangeable: a command token is something a shell invocation must contain, while a description is a human explanation of that token. The safest localization strategy inventories both kinds and keeps them from being accidentally merged.
The project’s localization documentation says that user-facing parser text is handled by a Translator using PHP translation maps. It describes GetOpt::setLang(‘de’) for a predefined language and setLang(path) for a custom PHP language file returning an array. Missing custom translations fall back to English. Error messages thrown because of user input also use the translator. Those are specific, testable features; they do not mean that every sentence your application prints comes from the library’s catalog.
Option definitions add another layer. A long option such as –warehouse may have a short alias, a required argument, a description and validation. The description can change by language. The option’s recognized spelling and argument mode should not change unintentionally: –warehouse with a value is not interchangeable with a translated name or a bare toggle. It is particularly important to keep an accurate account of NO_ARGUMENT, REQUIRED_ARGUMENT, OPTIONAL_ARGUMENT and other documented modes.
Examples must also respect the surrounding shell. A path with spaces needs suitable quoting. Repeated options may accumulate values, while some short options can be clustered. Default values, error recovery and output paths should be explained using the actual installed version. The project documentation and PHP’s native getopt() manual are separate references; blending their signatures is a common way to publish instructions that look plausible but cannot be executed.
A compact code example: where meaning meets parsing
<?php
require 'vendor/autoload.php';
use GetOpt\GetOpt;
use GetOpt\Option;
GetOpt::setLang('de'); // Select a supported bundled language.
$getopt = new GetOpt([
Option::create('w', 'warehouse', GetOpt::REQUIRED_ARGUMENT)
->setDescription('Warehouse identifier'),
Option::create('v', 'verbose', GetOpt::NO_ARGUMENT)
->setDescription('Show detailed progress'),
]);
$getopt->process();
$warehouse = $getopt->getOption('warehouse');
// Business validation and import logic belong to this application.This is a learning example showing the relevant parser declarations and a valid direction of data flow, not a complete multilingual application. It deliberately leaves domain-specific I/O, sensitive-data handling and production error recovery to the surrounding program. Read it alongside the pinned library documentation. Identify the literals an operator types, the descriptions an operator reads and the values the application receives; these are different classes of information even when all three appear together on a terminal.
Practical investigations: design choices, failures and reproducible tests
The following investigations use ParcelLedger, a fictional PHP command-line program that imports parcel manifests and reconciles shipment records for small logistics teams. Each case starts with a realistic misunderstanding, explains an implementation decision and ends with a concrete test. They can be used as a review worksheet: for each problem, copy the actual source command and its translated counterpart into a disposable environment, record what changes and decide whether the difference is a user-facing improvement or an interface regression.
01. Native getopt and GetOpt.php are different
A PHP tutorial mixes the built-in getopt() signature with the object-oriented GetOpt class and fails before any translations load. The distinction matters because a translated interface is still software, not only prose. If documentation teaches a token that the installed parser rejects, the reader has learned a false command. Keep the example connected to an observed result, particularly when the tool runs unattended.
Practical repair: Install the intended Composer dependency, import its classes and check the project’s own API instead of borrowing native PHP examples. Rather than asking the translator to infer parser internals from a screenshot, give them a verified command route, the role of every value and the expected result. Keep a brief note of any compatibility decision so another developer can reproduce it.
Verification: Run the introductory command in a clean Composer project and verify the options can be read. For a fair comparison, hold the input data and executable build constant while changing the display language. Save stdout and stderr separately and note the final process status; a translated success banner is meaningless if the parser has rejected the operation.
02. setLang selects a parser language
An operator sets GetOpt::setLang(‘de’) but expects a custom ParcelLedger warning to become German automatically. This is a point where a glossary alone is insufficient. The team needs a short statement of expected behavior, an accepted input example and the failure condition. Those three items give the translator enough context to choose words that preserve operational meaning.
Practical repair: Explain that the documented Translator covers library messages; route application-created business messages through the application’s own translation catalog. Rather than asking the translator to infer parser internals from a screenshot, give them a verified command route, the role of every value and the expected result. Keep a brief note of any compatibility decision so another developer can reproduce it.
Verification: Trigger a parser error and a business-rule error in the same locale, then verify both have appropriate language ownership. When the error path is involved, check whether the proposed remedy is executable. The person reading the failure should be able to correct the exact invocation, not merely understand an abstract explanation of why computers reject input.
03. Custom language files are executable PHP resources
A team places a JSON file at the custom translation path even though the documented format expects a PHP script returning a map. A useful review asks not whether the English and translated strings look alike, but whether two readers will choose the same safe action. Examples should name the input, identify the effect and make visible any side effect that a novice could otherwise miss.
Practical repair: Supply a valid PHP translation file in the documented format and review it as executable project content, not anonymous user input. Rather than asking the translator to infer parser internals from a screenshot, give them a verified command route, the role of every value and the expected result. Keep a brief note of any compatibility decision so another developer can reproduce it.
Verification: Load a small synthetic catalog from a trusted path and verify lookup and missing-key behavior. For documentation testing, a reader should explain the command in their own words before running it. Compare their expectation with the observed files, values and status. Correct the specific instruction responsible for any mismatch.
04. English fallback avoids blank errors
A custom locale omits a validation message and the operator sees a blank line where recovery instructions should appear. The source wording may itself be incomplete. Before polishing a translation, confirm the underlying rule in executable code and describe that rule in plain language. A misleading original text becomes a misleading multilingual text unless the specification is repaired first.
Practical repair: Preserve the documented English fallback and complete critical warnings before launch; missing translations should be detectable in automated coverage reports. Rather than asking the translator to infer parser internals from a screenshot, give them a verified command route, the role of every value and the expected result. Keep a brief note of any compatibility decision so another developer can reproduce it.
Verification: Remove one entry intentionally and verify an English message remains visible while a coverage test flags the gap. The language reviewer and software tester should inspect the same reproducible case. One checks comprehension; the other checks argument binding, formatting and output compatibility. Neither kind of evidence can substitute for the other.
05. Option::create metadata holds descriptions
A translated help screen still displays the default English option description attached with setDescription. Think about the future reader who copies commands from an article into a terminal. The code sample must be literal where the parser demands literal syntax, and flexible where the reader is supposed to supply their own data. Label those boundaries rather than making people guess.
Practical repair: Provide localized description text at the point where the option is constructed, while preserving short and long identifiers. Rather than asking the translator to infer parser internals from a screenshot, give them a verified command route, the role of every value and the expected result. Keep a brief note of any compatibility decision so another developer can reproduce it.
Verification: Generate –help in two languages and inspect both the option descriptions and the registered names. If the issue appears only in a particular environment, record the operating system, shell, locale, terminal width and installed dependency version. That context matters more than a claim that the translation worked on one developer laptop.
06. Required arguments are parser semantics
The –warehouse option expects a value, but translation describes it as a switch that merely enables warehouse mode. A locale does not operate in isolation. Deployment packaging, logging, shell behavior and downstream consumers can expose failures invisible on a review spreadsheet. Preserve a practical test record so issues can be reproduced without reinterpreting the original translation.
Practical repair: Say clearly that the identifier must follow the option and explain how a missing value is rejected by the configured mode. Rather than asking the translator to infer parser internals from a screenshot, give them a verified command route, the role of every value and the expected result. Keep a brief note of any compatibility decision so another developer can reproduce it.
Verification: Compare –warehouse, –warehouse=WH-4 and -w WH-4, recording parsed values and errors. For a fair comparison, hold the input data and executable build constant while changing the display language. Save stdout and stderr separately and note the final process status; a translated success banner is meaningless if the parser has rejected the operation.
07. Optional arguments need careful examples
Help implies a value is always required for an option configured with OPTIONAL_ARGUMENT, causing unnecessary operator failures. The distinction matters because a translated interface is still software, not only prose. If documentation teaches a token that the installed parser rejects, the reader has learned a false command. Keep the example connected to an observed result, particularly when the tool runs unattended.
Practical repair: Explain the distinction between an absent option, a present option without a value and a present option with one, based on observed behavior. Rather than asking the translator to infer parser internals from a screenshot, give them a verified command route, the role of every value and the expected result. Keep a brief note of any compatibility decision so another developer can reproduce it.
Verification: Execute all three forms with the installed version and inspect default and returned values. When the error path is involved, check whether the proposed remedy is executable. The person reading the failure should be able to correct the exact invocation, not merely understand an abstract explanation of why computers reject input.
08. NO_ARGUMENT options are flags
A translated description asks the user to type –verbose=true although the parser’s registered option expects no argument. This is a point where a glossary alone is insufficient. The team needs a short statement of expected behavior, an accepted input example and the failure condition. Those three items give the translator enough context to choose words that preserve operational meaning.
Practical repair: Write the description as an action toggled by presence and avoid inventing unsupported assignment syntax. Rather than asking the translator to infer parser internals from a screenshot, give them a verified command route, the role of every value and the expected result. Keep a brief note of any compatibility decision so another developer can reproduce it.
Verification: Test a bare flag and a flag followed by an unexpected value, confirming the same failure or acceptance behavior across locales. For documentation testing, a reader should explain the command in their own words before running it. Compare their expectation with the observed files, values and status. Correct the specific instruction responsible for any mismatch.
09. Long and short aliases must be stable
The English guide uses -w and –warehouse but a translated version changes -w to an unrelated first letter. A useful review asks not whether the English and translated strings look alike, but whether two readers will choose the same safe action. Examples should name the input, identify the effect and make visible any side effect that a novice could otherwise miss.
Practical repair: Keep all accepted aliases in a canonical command registry and translate descriptions, not the literal syntax in copyable examples. Rather than asking the translator to infer parser internals from a screenshot, give them a verified command route, the role of every value and the expected result. Keep a brief note of any compatibility decision so another developer can reproduce it.
Verification: Compare both aliases in English and Spanish against the same recorded parsed value. The language reviewer and software tester should inspect the same reproducible case. One checks comprehension; the other checks argument binding, formatting and output compatibility. Neither kind of evidence can substitute for the other.
10. Short-option clusters need real examples
An editor assumes -abc is three independent switches even though the last option consumes an argument and the others may not. The source wording may itself be incomplete. Before polishing a translation, confirm the underlying rule in executable code and describe that rule in plain language. A misleading original text becomes a misleading multilingual text unless the specification is repaired first.
Practical repair: Explain the documented cluster rule with a valid example for the actual registered modes; avoid making generic claims about every combination. Rather than asking the translator to infer parser internals from a screenshot, give them a verified command route, the role of every value and the expected result. Keep a brief note of any compatibility decision so another developer can reproduce it.
Verification: Run separate and clustered forms in a disposable environment and compare parsed options. If the issue appears only in a particular environment, record the operating system, shell, locale, terminal width and installed dependency version. That context matters more than a claim that the translation worked on one developer laptop.
11. Multiple-argument options preserve collection meaning
A batch tool accepts repeated –domain values but the localized text suggests that only the final occurrence survives. Think about the future reader who copies commands from an article into a terminal. The code sample must be literal where the parser demands literal syntax, and flexible where the reader is supposed to supply their own data. Label those boundaries rather than making people guess.
Practical repair: Describe whether a particular option uses MULTIPLE_ARGUMENT or another supported mode and illustrate repeated occurrence explicitly. Rather than asking the translator to infer parser internals from a screenshot, give them a verified command route, the role of every value and the expected result. Keep a brief note of any compatibility decision so another developer can reproduce it.
Verification: Pass two domain values and assert their count, order and representation in the application’s result. For a fair comparison, hold the input data and executable build constant while changing the display language. Save stdout and stderr separately and note the final process status; a translated success banner is meaningless if the parser has rejected the operation.
12. Operand ordering explains data movement
A source manifest and destination archive are positional operands, but a translated synopsis reverses them. A locale does not operate in isolation. Deployment packaging, logging, shell behavior and downstream consumers can expose failures invisible on a review spreadsheet. Preserve a practical test record so issues can be reproduced without reinterpreting the original translation.
Practical repair: Identify source and destination roles in the Usage line and include a warning before any overwrite action. Rather than asking the translator to infer parser internals from a screenshot, give them a verified command route, the role of every value and the expected result. Keep a brief note of any compatibility decision so another developer can reproduce it.
Verification: Run in a sandbox with two distinguishable files and confirm the source remains intact and destination receives the correct output. When the error path is involved, check whether the proposed remedy is executable. The person reading the failure should be able to correct the exact invocation, not merely understand an abstract explanation of why computers reject input.
13. Commands can have their own options
A guide places an import-specific option at the root command level, making the invocation fail. The distinction matters because a translated interface is still software, not only prose. If documentation teaches a token that the installed parser rejects, the reader has learned a false command. Keep the example connected to an observed result, particularly when the tool runs unattended.
Practical repair: Document the actual GetOpt.php command routing and the point at which each command’s options are defined. Rather than asking the translator to infer parser internals from a screenshot, give them a verified command route, the role of every value and the expected result. Keep a brief note of any compatibility decision so another developer can reproduce it.
Verification: Run root and import-command help separately, verifying the option belongs to the advertised route. For documentation testing, a reader should explain the command in their own words before running it. Compare their expectation with the observed files, values and status. Correct the specific instruction responsible for any mismatch.
14. Help text may expose missing context
An operator sees a syntactically correct translated options table yet cannot tell which file will be modified. This is a point where a glossary alone is insufficient. The team needs a short statement of expected behavior, an accepted input example and the failure condition. Those three items give the translator enough context to choose words that preserve operational meaning.
Practical repair: Add clear task descriptions and concrete before-and-after examples outside the core parser synopsis, keeping copyable syntax accurate. Rather than asking the translator to infer parser internals from a screenshot, give them a verified command route, the role of every value and the expected result. Keep a brief note of any compatibility decision so another developer can reproduce it.
Verification: Ask a first-time reader to predict side effects from help alone and compare their answer with a safe test. The language reviewer and software tester should inspect the same reproducible case. One checks comprehension; the other checks argument binding, formatting and output compatibility. Neither kind of evidence can substitute for the other.
15. Validation should name expected formats
A warehouse code validator rejects accented letters but the translated message only says that the input is wrong. A useful review asks not whether the English and translated strings look alike, but whether two readers will choose the same safe action. Examples should name the input, identify the effect and make visible any side effect that a novice could otherwise miss.
Practical repair: Explain the approved code format and why the restriction exists; do not broaden allowed values in language without changing validation deliberately. Rather than asking the translator to infer parser internals from a screenshot, give them a verified command route, the role of every value and the expected result. Keep a brief note of any compatibility decision so another developer can reproduce it.
Verification: Exercise an accepted code, a Unicode variant and an invalid symbol, checking the exact error and return status. If the issue appears only in a particular environment, record the operating system, shell, locale, terminal width and installed dependency version. That context matters more than a claim that the translation worked on one developer laptop.
16. Exception wording and application wording differ
Parser-supplied input errors use setLang but a catch block prints a new hardcoded English prefix. The source wording may itself be incomplete. Before polishing a translation, confirm the underlying rule in executable code and describe that rule in plain language. A misleading original text becomes a misleading multilingual text unless the specification is repaired first.
Practical repair: Use localized wrapping text around the translated parser exception, preserving the underlying error category and remedial details. Rather than asking the translator to infer parser internals from a screenshot, give them a verified command route, the role of every value and the expected result. Keep a brief note of any compatibility decision so another developer can reproduce it.
Verification: Force an unknown option and a missing argument, then check full stderr rather than only the exception object. For a fair comparison, hold the input data and executable build constant while changing the display language. Save stdout and stderr separately and note the final process status; a translated success banner is meaningless if the parser has rejected the operation.
17. Argument quoting is the shell’s job
A localized command example with a path containing spaces omits quotation marks, so the shell splits one value into several. Think about the future reader who copies commands from an article into a terminal. The code sample must be literal where the parser demands literal syntax, and flexible where the reader is supposed to supply their own data. Label those boundaries rather than making people guess.
Practical repair: Provide platform-specific examples with appropriate quoting and say when paths are user data rather than parser options. Rather than asking the translator to infer parser internals from a screenshot, give them a verified command route, the role of every value and the expected result. Keep a brief note of any compatibility decision so another developer can reproduce it.
Verification: Use a directory named with spaces and accented characters in both Unix and Windows environments. When the error path is involved, check whether the proposed remedy is executable. The person reading the failure should be able to correct the exact invocation, not merely understand an abstract explanation of why computers reject input.
18. The double-dash terminator changes interpretation
A positional filename begins with a hyphen and a guide fails to show how to prevent it being interpreted as an option. A locale does not operate in isolation. Deployment packaging, logging, shell behavior and downstream consumers can expose failures invisible on a review spreadsheet. Preserve a practical test record so issues can be reproduced without reinterpreting the original translation.
Practical repair: Teach the actual end-of-options behavior supported by the installed parser and give a safe workaround when a version behaves differently. Rather than asking the translator to infer parser internals from a screenshot, give them a verified command route, the role of every value and the expected result. Keep a brief note of any compatibility decision so another developer can reproduce it.
Verification: Pass a leading-dash filename and inspect whether the parser treats it as data or syntax. For documentation testing, a reader should explain the command in their own words before running it. Compare their expectation with the observed files, values and status. Correct the specific instruction responsible for any mismatch.
19. Defaults are not translations
A default warehouse code is an internal identifier but a translator changes its spelling to make it more natural in a target language. The distinction matters because a translated interface is still software, not only prose. If documentation teaches a token that the installed parser rejects, the reader has learned a false command. Keep the example connected to an observed result, particularly when the tool runs unattended.
Practical repair: Keep defaults that act as machine keys stable while adding a translated description of what they select. Rather than asking the translator to infer parser internals from a screenshot, give them a verified command route, the role of every value and the expected result. Keep a brief note of any compatibility decision so another developer can reproduce it.
Verification: Run with no explicit code in two locales and compare downstream warehouse selection. The language reviewer and software tester should inspect the same reproducible case. One checks comprehension; the other checks argument binding, formatting and output compatibility. Neither kind of evidence can substitute for the other.
20. Validation messages must not leak personal data
A bad shipment record triggers an error that repeats a customer’s address or phone number in a shared terminal log. This is a point where a glossary alone is insufficient. The team needs a short statement of expected behavior, an accepted input example and the failure condition. Those three items give the translator enough context to choose words that preserve operational meaning.
Practical repair: Redact personal details, preserve a safe record identifier and give the operator a way to find the faulty row privately. Rather than asking the translator to infer parser internals from a screenshot, give them a verified command route, the role of every value and the expected result. Keep a brief note of any compatibility decision so another developer can reproduce it.
Verification: Insert synthetic sensitive values and scan stderr, logs and support exports after a failure. If the issue appears only in a particular environment, record the operating system, shell, locale, terminal width and installed dependency version. That context matters more than a claim that the translation worked on one developer laptop.
21. Number formatting should be separate from parsing
A translated example uses commas for decimals in a quantity field that the validator accepts only with a dot. A useful review asks not whether the English and translated strings look alike, but whether two readers will choose the same safe action. Examples should name the input, identify the effect and make visible any side effect that a novice could otherwise miss.
Practical repair: State supported input formats precisely and localize reports independently from numeric input syntax unless locale-aware parsing is implemented. Rather than asking the translator to infer parser internals from a screenshot, give them a verified command route, the role of every value and the expected result. Keep a brief note of any compatibility decision so another developer can reproduce it.
Verification: Test 12.5, 12,5 and whitespace variants, checking normalized quantities and rejection paths. For a fair comparison, hold the input data and executable build constant while changing the display language. Save stdout and stderr separately and note the final process status; a translated success banner is meaningless if the parser has rejected the operation.
22. Date and time zones need explicit semantics
Shipping cutoffs display as local times but a translated message omits the time zone, causing a cross-border handover mistake. The source wording may itself be incomplete. Before polishing a translation, confirm the underlying rule in executable code and describe that rule in plain language. A misleading original text becomes a misleading multilingual text unless the specification is repaired first.
Practical repair: Name the business time zone, date format and whether a value is a timestamp or only a date; do not ask a translation to repair missing specification. Rather than asking the translator to infer parser internals from a screenshot, give them a verified command route, the role of every value and the expected result. Keep a brief note of any compatibility decision so another developer can reproduce it.
Verification: Test records spanning midnight in two zones and compare stored timestamps with displayed explanations. When the error path is involved, check whether the proposed remedy is executable. The person reading the failure should be able to correct the exact invocation, not merely understand an abstract explanation of why computers reject input.
23. Terminal color is not enough
A warning changes from red to green in a localized theme and a text-only client no longer indicates severity. Think about the future reader who copies commands from an article into a terminal. The code sample must be literal where the parser demands literal syntax, and flexible where the reader is supposed to supply their own data. Label those boundaries rather than making people guess.
Practical repair: Include explicit severity words, coherent punctuation and readable line breaks that work without ANSI formatting. Rather than asking the translator to infer parser internals from a screenshot, give them a verified command route, the role of every value and the expected result. Keep a brief note of any compatibility decision so another developer can reproduce it.
Verification: Compare colored and no-color output with a narrow terminal and a screen-reader review. For documentation testing, a reader should explain the command in their own words before running it. Compare their expectation with the observed files, values and status. Correct the specific instruction responsible for any mismatch.
24. Unicode output depends on the environment
Correct UTF-8 translation text becomes garbled under an incompatible console configuration, misleading operators about data corruption. A locale does not operate in isolation. Deployment packaging, logging, shell behavior and downstream consumers can expose failures invisible on a review spreadsheet. Preserve a practical test record so issues can be reproduced without reinterpreting the original translation.
Practical repair: Check process encoding, terminal expectations and output destinations separately, and do not silently rewrite source manifest bytes. Rather than asking the translator to infer parser internals from a screenshot, give them a verified command route, the role of every value and the expected result. Keep a brief note of any compatibility decision so another developer can reproduce it.
Verification: Print accented, Arabic and CJK strings in a temporary test environment and inspect the underlying file and console output. The language reviewer and software tester should inspect the same reproducible case. One checks comprehension; the other checks argument binding, formatting and output compatibility. Neither kind of evidence can substitute for the other.
25. Package resources must ship with the release
Translation files exist in the source tree but are omitted from the distributed package, leaving production users with English-only errors. The distinction matters because a translated interface is still software, not only prose. If documentation teaches a token that the installed parser rejects, the reader has learned a false command. Keep the example connected to an observed result, particularly when the tool runs unattended.
Practical repair: Include supported language resources in deployment artifacts, verify paths and document fallback behavior. Rather than asking the translator to infer parser internals from a screenshot, give them a verified command route, the role of every value and the expected result. Keep a brief note of any compatibility decision so another developer can reproduce it.
Verification: Install the published package in a clean container without repository files and exercise every supported locale. If the issue appears only in a particular environment, record the operating system, shell, locale, terminal width and installed dependency version. That context matters more than a claim that the translation worked on one developer laptop.
26. CLI and automated API consumers have different needs
A human-readable translated status line is reused as a CSV column key and breaks a reporting script. This is a point where a glossary alone is insufficient. The team needs a short statement of expected behavior, an accepted input example and the failure condition. Those three items give the translator enough context to choose words that preserve operational meaning.
Practical repair: Keep data field names and structured status codes stable; translate separate presentation labels and documentation. Rather than asking the translator to infer parser internals from a screenshot, give them a verified command route, the role of every value and the expected result. Keep a brief note of any compatibility decision so another developer can reproduce it.
Verification: Diff machine outputs across locales and run the downstream CSV importer after switching language. For a fair comparison, hold the input data and executable build constant while changing the display language. Save stdout and stderr separately and note the final process status; a translated success banner is meaningless if the parser has rejected the operation.
27. No interpreter should receive untrusted locale files
A program accepts a locale path supplied by an untrusted manifest and executes it as PHP when loading translation maps. A useful review asks not whether the English and translated strings look alike, but whether two readers will choose the same safe action. Examples should name the input, identify the effect and make visible any side effect that a novice could otherwise miss.
Practical repair: Only load language files from trusted packaged locations, validate locale selection against an allowlist and avoid executing user-supplied catalog paths. Rather than asking the translator to infer parser internals from a screenshot, give them a verified command route, the role of every value and the expected result. Keep a brief note of any compatibility decision so another developer can reproduce it.
Verification: Submit an unrecognized locale and a path-like input and confirm neither can select arbitrary executable PHP. When the error path is involved, check whether the proposed remedy is executable. The person reading the failure should be able to correct the exact invocation, not merely understand an abstract explanation of why computers reject input.
28. Release version and upgrade notes matter
An older GetOpt.php API is mixed with current option-construction examples, causing a runtime exception that looks like a translation fault. The source wording may itself be incomplete. Before polishing a translation, confirm the underlying rule in executable code and describe that rule in plain language. A misleading original text becomes a misleading multilingual text unless the specification is repaired first.
Practical repair: Pin and document the package version, check the upgrade guide and test every example against that exact build. Rather than asking the translator to infer parser internals from a screenshot, give them a verified command route, the role of every value and the expected result. Keep a brief note of any compatibility decision so another developer can reproduce it.
Verification: Install from a lockfile in a clean environment and verify parsing, help, language selection and validation behavior. For documentation testing, a reader should explain the command in their own words before running it. Compare their expectation with the observed files, values and status. Correct the specific instruction responsible for any mismatch.
29. A translation must support task comprehension
A fluent import description never explains the difference between validating a manifest and committing changes to shipment records. Think about the future reader who copies commands from an article into a terminal. The code sample must be literal where the parser demands literal syntax, and flexible where the reader is supposed to supply their own data. Label those boundaries rather than making people guess.
Practical repair: Give readers a clear model of dry-run versus committed effects and include a complete example for each supported workflow. Rather than asking the translator to infer parser internals from a screenshot, give them a verified command route, the role of every value and the expected result. Keep a brief note of any compatibility decision so another developer can reproduce it.
Verification: Ask a new operator to choose the safe command for a rehearsal and observe whether the translated help prevents unintended writes. The language reviewer and software tester should inspect the same reproducible case. One checks comprehension; the other checks argument binding, formatting and output compatibility. Neither kind of evidence can substitute for the other.
A multilingual quality-assurance matrix that covers real use
| Test area | Recommended evidence | Release decision |
|---|---|---|
| Known-valid task | Record argv, parsed values, created files and normal exit status in each language. | Identical machine outcome; different human explanations allowed. |
| Unknown token | Invoke an unregistered option and capture stderr and process status. | Actionable message; no accidental acceptance. |
| Missing value | Omit a required argument and check the displayed remedy. | Clear expected input; no misleading success. |
| Help and version | Run both from a clean working directory with no domain data. | Readable output and no unintended side effect. |
| Unicode file paths | Use spaces, accents, CJK and a right-to-left language example. | Data remains intact; shell quoting documented. |
| Terminal layout | Capture 40-, 60- and 100-column layouts with ANSI styling disabled. | No hidden options, broken words or color-only meaning. |
| Fallback | Remove a selected optional message from a test locale resource. | Complete safe default wording, no blank warnings. |
| Downstream interface | Run an importer or script against the output of both locales. | Stable output keys, values and status contracts. |
| Installed package | Repeat tests from a distribution artifact, not the repository checkout. | Resources and runtime behavior match documentation. |
| Human comprehension | Ask a native reader to finish a safe unfamiliar workflow. | Correct task selection and recovery without assistance. |
A matrix is useful only when every row has a named owner. The language reviewer checks terminology, clarity and misleading implicatures; the engineer checks binding and side effects; a release owner checks packaging, availability and rollback. Store the evidence with the release rather than in an ephemeral chat, and update a failing example before it becomes permanent public documentation.
Four-week implementation and learning sequence
Week 1 — Establish the baseline
Pin the exact dependency version, collect executable help and error captures, classify every string as human explanation or machine contract, and choose the locale-selection policy. Walk through one complete task with an unmodified build so the team can distinguish an existing defect from a translation regression.
Week 2 — Translate the user journey
Write the target-language descriptions, explain values and defaults, supply complete copyable examples and document what the command changes. Review tricky words with a native speaker and an engineer together. Make the fallback rule visible, especially for errors that prevent accidental destructive work.
Week 3 — Test failure and recovery
Execute the case investigations for unknown flags, missing values, Unicode input, narrow terminals, no-color output and atypical environments. Compare parsed outcomes and structured results. Ask a reader to recover from a realistic error without guidance; revise source wording when confusion traces back to the original specification.
Week 4 — Package and release
Install the built distribution in a clean environment, confirm locale assets and source links, rerun the full matrix and preserve a rollback package. Publish release notes specifying supported languages, known gaps and exactly which command tokens remain unchanged. Monitor concrete user-reported misunderstandings rather than translating complaints into untested guesses.
Frequently asked questions
How does GetOpt.php localization work?
The documented Translator reads PHP mapping files, and GetOpt::setLang can select a bundled language or a trusted custom language file. Missing entries fall back to English. Application-specific messages need their own integration.
Is GetOpt.php the same as PHP getopt()?
No. PHP’s native getopt() function has its own signature. GetOpt.php is a third-party object-oriented library with option objects, commands, validation, help generation and documented localization support.
Can I translate option names?
Translate descriptions and examples for people while preserving registered aliases unless an intentional compatibility change is planned. A localized spelling in prose is not automatically a parser-recognized alias.
What should go in a translation file?
Use the documented map shape for library messages. Keep files in trusted project locations, review them as executable PHP resources and package them with the version that loads them.
How do missing translations behave?
The library documentation describes English fallback. Still test it with deliberate missing keys, particularly for warnings and errors that affect safety or data loss.
Should local numerals and separators be accepted?
Only if the application’s validators and parsers explicitly support them. Human output formatting and machine input grammar are different contracts; document both.
How should errors be localized?
Keep the correct failure category, accepted syntax and safe next step. The library may translate its own exceptions, but your wrapper and business rules also need review.
What constitutes a release test?
An installed-package test of language resources, option syntax, valid and invalid inputs, file paths, numeric formats, no-color display, exit statuses, stable data schemas and operator comprehension.
Closing principles and recommended references
A dependable GetOpt.php localization is not judged by the number of translated strings. Its success is whether someone in a different language can identify the intended task, type or copy a valid invocation, understand the result, recover from a failure and trust that any saved data retains its documented meaning. Treat grammar, validation, error presentation, shell input and downstream output as connected responsibilities, and make every reader-facing claim testable.
Use the framework’s own versioned documentation for API details and keep neighboring learning resources in their appropriate scope. The translation master describes how meaning moves across languages; the series index links separate technical cases. Those readings complement this focused chapter instead of replacing compiled tests or a human review.