PHP native getopt() localization helps developers explain command-line options in multiple languages without changing what a PHP script accepts. Readers searching for PHP getopt examples, short versus long CLI flags, the rest_index argument, Unicode command-line input and translated PHP usage messages need one distinction from the start: getopt parses command syntax, while your application writes the text that people read.
The built-in getopt() function accepts a short-option specification string, an array of long-option specifications, and an optional rest_index output parameter. It returns recognized option values, not an automatically translated help page, validator or full command framework. A good international guide teaches precisely what the script can parse, what it still must check, and why a language switch should not silently rename a published argument.
This tutorial follows a harmless public-report preview command, then works through the details that cause most real translation mistakes: required versus optional values, the point where parsing stops, option repetition, user-facing errors, locale selection, data output, shell quoting and release testing. Examples are written to be copied, reviewed and adapted, not to suggest that PHP ships a complete localization system.
Quick answer: seven rules that keep multilingual PHP commands dependable
- Keep published option spellings stable unless aliases are really implemented.
- Use a colon for required values and two colons for optional values in the corresponding specification.
- Do not confuse an empty result array with the false failure return.
- Use rest_index and the original argv vector carefully when handling remaining positionals.
- Treat help, errors and examples as application text that must be translated independently.
- Validate locale identifiers, numbers, paths and any option that changes behavior.
- Test Unicode, missing values, exit status and machine-readable stdout on supported PHP versions.
A small command to understand before you translate it
<?php
// public-preview.php: simple illustrative CLI-only contract
$options = getopt("hl:", ["help", "locale:", "limit:"], $restIndex);
if ($options === false) {
fwrite(STDERR, "Unable to parse command options\n");
exit(2);
}
if (isset($options["h"]) || isset($options["help"])) {
echo "Usage: php public-preview.php [--locale=LANG] [--limit=N]\n";
exit(0);
}
$locale = $options["locale"] ?? $options["l"] ?? "en";
if (!is_string($locale) || !in_array($locale, ["en","fr","ja"], true)) {
fwrite(STDERR, "Supported locale: en, fr, ja\n");
exit(2);
}
$limit = $options["limit"] ?? "3";
if (!is_string($limit) || !preg_match('/^[1-9][0-9]*$/D', $limit) ||
(int)$limit > 20) {
fwrite(STDERR, "Limit must be from 1 to 20\n");
exit(2);
}
echo "Public preview: ".$locale." / ".$limit."\n";
This intentionally small program is an English-language reference implementation, not a claim that the requested locale already translates output. It permits you to inspect the parser separately from message catalogs. The example keeps help as a success path, rejects unsupported locale values and uses synthetic output instead of handling personal records or production commands.
What the PHP parser owns, and what the translator owns
The parser recognizes names, finds values and presents a data structure to your code. Your script supplies meaning: whether a value is a permitted language, a safe directory, a count within a range or an identifier that must not be modified. The translator supplies a human explanation of that meaning. Confusing those roles makes a fluent translated page less reliable than a short, accurate original.
Treat the program’s syntax like a public contract. If –limit is documented and deployed, people may have scripts that pass that exact token. Translating it to a language-specific synonym in a web page does not make that synonym work. The alternative is straightforward: show –limit literally, explain its role in the reader’s language, and create an executable alias only if the product deliberately adopts it.
Thirty-six practical details worth mastering
Recognizing short flags
The short-options string is a compact grammar. An h without a colon recognizes -h as a presence switch; an l followed by a colon requires a value. Neither character is a translated label.
A guide that replaces the letter because a local word begins differently changes the command a user types. This is an interface migration, not a translation edit, and cannot be done by prose alone.
Keep short flags in code formatting and supply a localized label beside them. For example, explain -l as the display-language selector while keeping the actual spelling untouched.
Run -h and -l fr separately. Confirm that the former selects help and that the latter supplies a value, then compare the parsed array with what your translated instructions promise.
Long-option names
The second argument to getopt is an array of long-option specification strings. A name such as locale: permits –locale with a required value, and help needs no trailing colon.
Because long flags resemble natural English, writers often assume they should be translated. Yet a script does not discover a translated –langue token from a localized caption.
Name the executable token, then translate its meaning in a full sentence. When a new alias is truly valuable, implement and test it across every supported environment before publishing the instructions.
Check both –locale=fr and the documented separated form, while using the exact version and shell combination that your distributed guide supports.
Required values
One colon in an option specification marks a required value. A missing value should lead to deliberate validation and a usable explanation, rather than accidental continuation with an unrelated default.
A misleading translation may imply that a required argument is optional. The reader then receives an error that feels arbitrary even though the parser acted consistently.
Place the requirement in the usage sentence and show a complete invocation. Distinguish a missing option from an option supplied without its needed value.
Create two tests, one omitting the option entirely and another supplying the option without the value. The expected error and any fallback policy may differ.
Optional values
Two colons mark an optional option value. PHP documentation notes that optional values cannot be separated from their option by a space in the same way as required values.
A translated example such as –format json can seem perfectly natural to readers while the native parser does not treat it as the optional value they intended.
Prefer a required value where ambiguity harms usability, or demonstrate an explicit –format=json form when that is truly supported. A friendly page cannot resolve parser ambiguity.
Test the attached and spaced forms as separate cases and inspect the remaining arguments. Do not approve screenshots without checking what the script received.
The two meanings of false
The return type allows an array or false. An empty array can simply mean no recognized options were provided, which differs from a parsing failure.
Using if (!$options) conflates a legitimate empty array with false. A translated message may then tell users their command failed when the script merely used defaults.
Compare the result strictly with false and handle the empty array according to the application contract. State default behavior in the usage section.
Invoke the command with no options, with one valid option, and with a malformed option. Review both the exit code and the message, not only its wording.
rest_index
The optional third parameter receives the index where option parsing stopped. It helps an application find trailing arguments after the recognized options.
Readers may assume getopt returns every remaining filename or positional directly. Translating a description that hides this step can make a valid filename appear to vanish.
Show how the script examines the original argv vector at the returned index, and explain whether the application permits remaining positionals at all.
Invoke a sample with flags followed by a filename containing spaces, then check the reported index and the original argv array before designing file handling.
The first non-option boundary
Native parsing is sensitive to argument order and where it encounters a non-option. It is unsafe to assume a general-purpose argument parser will freely reorder everything.
A guide might show a filename before –locale and promise that the option is still recognized; copying that command can produce behavior unlike the screenshot.
Put options and positionals in a documented order. If flexible intermixing is important, assess a different parser rather than obscuring native behavior.
Compare a command with –locale before the filename against one with the filename first. Record the actual parsed result and the remaining argv elements.
Double-dash termination
The conventional — separator distinguishes option processing from following positional arguments in many command environments, but its behavior must be checked in the actual PHP invocation.
A reader working with a filename beginning with a hyphen can otherwise see that name interpreted as an option. Translation is incomplete if it does not teach a reliable escape.
Explain the exact supported invocation and the point at which the script treats arguments as data. Avoid promising more than the deployed parser implements.
Use a synthetic filename beginning with a hyphen and verify how the rest_index and positional logic behave in the target PHP build.
Repeated option names
A caller can supply an option more than once. Depending on the option and version, values can be represented as repeated entries rather than the single scalar beginners expect.
Code that assumes every locale value is a string can fail when duplicate flags arrive. The problem is not cultural; a translated page must still tell users what repeated input means.
Define an application rule: reject duplicates, accept one chosen occurrence or deliberately support lists. Then validate both scalar and array shapes before using values.
Test two –locale occurrences, including conflicting language tags. Compare the parser result and the documented duplicate policy.
Default locale selection
A default such as en is an application choice rather than a feature built into getopt. It should be visible when a caller provides no locale.
In multilingual support, silent fallback can look like a broken translation, especially when the caller typed an unsupported value and the script quietly returned English.
Choose a documented default and an explicit unsupported-locale response. Explain whether a system environment setting influences the choice or whether only –locale does.
Run the same command with and without –locale, vary the shell environment, and record which component actually selected the displayed language.
Locale-code validation
A value after –locale is merely text until validated. Language tags such as en, fr and ja are identifiers that should be compared against a supported set.
Translating those identifiers into display names changes the input contract. Confusing the visible name Japanese with the token ja can lead to a frustrating rejection.
Display the full language name in prose, include the accepted token in code formatting and make error messages show supported codes accurately.
Try upper-case, mixed-case and unsupported values. State whether case normalization is intentionally supported, not merely assumed.
Message catalogs
PHP getopt does not provide gettext catalogs, translation files or automatic message lookup. Those are separate application-level responsibilities.
A web article that treats –locale as a magical translator can leave all output English. This creates a mismatch between what users expect and what the executable does.
Build a controlled dictionary or gettext-based localization layer, select messages using validated codes, and keep syntax separate from translatable strings.
Switch between two real catalogs in a test build and assert that only human messages change while parsed option values remain equivalent.
Full-sentence translations
Error text should communicate what happened, why the input was rejected and the next usable command. Translating words one by one frequently loses that sequence.
A fragment such as invalid input may be grammatical but gives a beginner no way to recover. Errors become especially costly in unfamiliar terminal environments.
Write complete messages with placeholders placed in a grammatically appropriate position. Keep literal option tokens visually separate from the surrounding sentence.
Give a bilingual reviewer an invalid command and the resulting translation, then ask them to produce the corrected command without reading the source code.
Placeholders and quoting
Dynamic values may include filenames, numbers or option tokens. Translated templates must identify them without letting arbitrary data masquerade as a trusted instruction.
If a filename contains quotation marks or terminal control characters, blindly echoing it can make a diagnostic difficult to read or unsafe to paste.
Use a controlled formatting function, preserve the original value as data, and choose readable delimiters for the chosen terminal and language direction.
Test a harmless filename containing spaces, apostrophes and accented characters. Inspect the actual terminal output rather than an HTML rendering.
Error exit codes
Exit status belongs to the program contract. A parse failure should not return a successful status solely because a translated sentence sounds reassuring.
Automation depends on the process code, not the natural-language paragraph. A script that prints an error but exits successfully misleads callers in every language.
Specify stable exit categories, such as success for help and nonzero for invalid usage. Keep those categories consistent across all supported translations.
Capture both stdout, stderr and the exit status for valid help, invalid counts and unsupported locales. Assert that a translation never changes status.
stdout and stderr
A PHP command can send ordinary output to stdout and errors to stderr. Those channels matter when another program captures a data file or parses the output.
Adding a localized greeting to stdout can break JSON or CSV consumers. A sentence that looks helpful to a person may be an unexpected extra row to a pipeline.
Reserve stdout for the documented result in machine modes. Put recoverable diagnostics on stderr and provide human-oriented descriptions in explicit help contexts.
Pipe a sample output into a data parser for each locale and compare the parsed structure, not just the visible characters.
Numeric limits
getopt does not know that –limit should be a positive integer below a particular maximum. The application must validate the text independently.
A multilingual guide sometimes shows localized thousands separators or non-ASCII digits in command examples even when the validator accepts only ASCII decimal forms.
Use an explicit accepted numeric grammar and show ordinary runnable values. Explain any genuine international number parsing feature as a separate supported behavior.
Test zero, negative values, leading spaces, huge integers, decimal commas and a normal small limit. Confirm errors identify the permitted range.
File path values
A path is a runtime value and can legitimately contain spaces, non-Latin letters or characters that a shell interprets. The shell and PHP both participate.
A translated example that strips quotes from a path may fail before getopt even sees it. A tutorial that changes the path to a locale-specific string also changes the file addressed.
Demonstrate shell-safe quoting with non-destructive sample paths. Explain the difference between a path as command data and a translated description of that path.
Run tests with a spaced filename and a Unicode filename on each supported operating system. Observe the exact argv values PHP receives.
Unicode source files
The PHP source file, message catalog and terminal output involve different encoding boundaries. Correct characters in a web editor do not prove correct characters in execution.
A mixed encoding can turn an otherwise accurate Japanese instruction into unreadable output. That is an encoding defect, not a translation preference.
Save source and resources in a consistent modern encoding, and define the terminal expectations of the supported deployment environment.
Use a fixture with multiple scripts and combining marks. Inspect byte-level integrity where needed and ask native readers to evaluate actual terminal text.
Bidirectional languages
Arabic and Hebrew prose can be placed beside Latin option syntax, paths and digits. Visual order may differ from storage order, especially in terminals.
A translated instruction can appear to reverse a leading hyphen or rearrange punctuation, causing users to type a different command than intended.
Keep command invocations in isolated code blocks, use directional formatting carefully in web documentation and provide copyable raw text.
Test the help in both a browser and the supported terminal. Compare copied bytes with the documented token sequence.
Help as an independent action
The parser can recognize -h or –help, but the script chooses how help is printed and when the process exits. Help needs a consistent priority rule.
If missing required operational values are checked before help, even users asking for usage may receive a distracting validation failure.
Handle help deliberately, keep it read-only, then present a compact synopsis and realistic examples. Do not perform a network request or write a file while displaying help.
Invoke help with no other options and with an intentionally incomplete operational option. Decide and verify which behavior your application promises.
Usage syntax
Square brackets, placeholders and punctuation in a usage line are editorial notation, not literal characters to type unless a guide says so.
When English-derived conventions are introduced without explanation, new readers may paste the brackets or write the word LANG instead of a language code.
Explain literal tokens, optional notation and replaceable values in one example. Use a plain invocation directly below the synopsis.
Ask a new reader to convert the usage notation into a real command for Japanese and a count of five, then run their result.
Shell quoting
Bash, zsh, PowerShell and Windows shells do not interpret all quotes and escapes identically. PHP receives arguments after the invoking shell has processed them.
A command copied from a Unix-focused article can be invalid in Windows PowerShell, although the PHP code itself is portable.
Label the shell assumed by each example and include a second tested form where quoting rules meaningfully differ. Keep locale-sensitive values separate from shell syntax.
Use the actual supported shells to exercise paths containing spaces and punctuation. Capture the argv array to find which layer changed the input.
Option aliases
A short alias and a long option can refer to the same conceptual setting, but native getopt reports the names it sees. The application combines them.
A guide that implies -l and –locale are interchangeable without explaining precedence leaves users unsure what happens when both appear.
Define precedence or duplicate rejection in application code. If the value must be unique, treat conflicting aliases as a user-visible validation error.
Submit -l en –locale fr and its reverse. Assert the documented conflict rule rather than relying on array iteration order.
Unknown options
Native parsers and their return shapes are not substitutes for a full policy on unrecognized flags. The application needs tests for misspellings and unexpected tokens.
If –local is a typo for –locale, silence can make the program appear to run with defaults. An international user may believe that translated help is wrong.
Document actual strictness and, when appropriate, implement explicit validation of input tokens or choose a parser designed for strict errors.
Try –local=fr, –loc=fr and –locale=fr. Never claim abbreviation support because a screenshot happens to look similar.
Security boundaries
A parse result is not permission to open arbitrary files, execute subcommands or reach a network service. Language selection must not weaken authorization or validation.
Translating a success message after an unverified operation can imply that a requested change was completed, even if the application never reached the service.
Use narrow safe paths in examples, avoid eval or shell concatenation, and reserve completion language for verified outcomes. Keep error categories factual and recoverable.
Use synthetic fixtures and intentionally invalid inputs. Confirm that no external operation is attempted before argument checks finish.
Repeated values in descriptions
An error may mention the same value twice, but languages differ in word order and inflection. Reconstructing sentences by concatenating fixed English fragments can be awkward.
A message catalog that translates only adjectives while inserting a filename into an English skeleton can sound inconsistent or even assign blame to the wrong argument.
Store a full message template for each language and use named placeholders where your chosen localization approach supports them.
Review messages with a short value, a long value, an empty string and an unfamiliar script. Verify that the message remains understandable.
Machine output fields
Programmatic consumers rely on field names, ordering and types. Translating a JSON property because it looks like a label changes the data contract.
A user may request Japanese help yet still expect a downstream script to read the field count. Mixing display language with schema labels creates difficult cross-locale failures.
Keep structured keys stable unless the API explicitly versions localized schemas. Localize explanatory text and human-view templates separately.
Compare JSON outputs from the same fixture across languages after parsing. Their structural differences should be planned and documented.
Fallback catalogs
Not every message will necessarily exist in every supported catalog. Fallback can maintain availability, but must be predictable and visible to maintainers.
An incomplete translation may accidentally mix languages in a way that changes a safety instruction or hides whether help is current.
Use a known fallback locale, report missing message IDs during test builds and prioritize completing critical error and recovery paths.
Remove one benign string from a test catalog, run the command and check that it falls back to the documented text without changing control flow.
Native build and version differences
PHP versions may differ in edge-case handling and diagnostic details. The documented interface must be tied to the versions the organization actually ships.
A copyable snippet taken from a newer manual may rely on behavior unavailable to readers using an older supported runtime.
State a minimum tested PHP version, inspect the manual for that version and run examples inside the target container or system image.
Repeat the same argument matrix across each supported runtime and platform before approving localized release notes.
Tests for no arguments
A command with no options is an important teaching case because it reveals defaults and whether a program expects a required positional.
Many guides skip this case, leaving a new reader uncertain whether they should type a value, request help or expect a harmless preview.
Describe the no-argument behavior clearly before advanced examples. If a command changes anything, do not silently run it on missing input.
Run php public-preview.php without options and record exact text, output channel, action and exit code.
Tests for malformed numbers
Malformed numeric values include negative signs, decimal points, thousands separators, overflow and whitespace. None becomes valid merely because the interface is localized.
An invalid count used in a file-processing command could produce unexpected resource consumption or a misleading summary if accepted without bounds.
Validate the original argument as a string before converting. Report the rule rather than just saying invalid argument.
Try –limit=-1, –limit=1.5 and an excessively long integer. Ensure the error remains comprehensible and no work is started.
Testing empty values
An option can be supplied with an empty string or with no value. Application code needs to distinguish an empty string from absence where that difference matters.
If –locale= is silently treated like a missing option, a reader may not realize their explicit input was rejected or ignored.
Choose a defined behavior for an empty value, then document it alongside normal defaults and mandatory value rules.
Compare omitted –locale, an explicitly empty value and –locale=fr; inspect both parsing and later validation.
Accessibility of terminal help
Help can be technically correct but hard to scan in a narrow terminal or with a screen reader. Translating text often increases its length.
Long right-to-left sentences, combining marks and wide CJK characters can wrap within a flag column and separate an option from its explanation.
Use simple headings, limited alignment assumptions and complete sentences. Treat color as optional decoration, never as the only error signal.
Review help without color at narrow and wide widths, then use a screen-reader or text-only inspection where available.
Release documentation consistency
A README, –help output and website article may be maintained separately, and a locale can become outdated after option behavior changes.
If a deleted flag remains in one translated example, readers may blame themselves rather than a stale page. Consistency is a real part of translation quality.
Link documentation examples to executable regression tests and review the full surface when flags, defaults or error statuses change.
Run every published example in a clean installation. Compare the current help with the translated release page before declaring support.
Support and bug reporting
International users need to describe a failure without sharing passwords, private paths or sensitive business records. Good help provides enough technical context safely.
An instruction to paste the entire command line can accidentally expose tokens, names or customer data, especially on shared support forums.
Ask for runtime version, operating system, redacted invocation, expected outcome, actual exit status and a minimal synthetic reproduction.
Create a support template and test whether an engineer can reproduce a known invalid-option problem from the anonymized information.
When to choose another library
Native getopt is intentionally small. A larger application may need nested commands, automatically generated help, rich typing or strict option-order policies.
Trying to conceal those missing capabilities through verbose translated prose leads to tutorials that promise a framework instead of describing the real program.
State the scope of the native solution, then assess a maintained parsing library when requirements exceed it. Keep migration decisions separate from language revision.
List required capabilities before choosing a replacement and write compatibility tests for existing flags, values and exit codes.
A focused international verification plan
Start with one known-good invocation in English and one in a second supported language. Preserve the same option tokens and the same synthetic input. Record the parser result, application state, visible message, stdout, stderr and process status. A localized command is correct only when the human presentation changes deliberately and the operation remains what the user requested.
Now add negative tests: an unknown flag, a missing required value, an empty locale, an excessive count and an unexpected positional. Include a right-to-left example, a CJK string and a path with spaces when the application claims those inputs. Keep a transcript that another contributor can reproduce without access to private files or accounts.
Finally test a release installation, not only a development checkout. The locale catalog must actually be packaged, the documentation must name the syntax the binary accepts, and support instructions must be useful when the reader cannot reproduce the example. The best test is whether a new user can recover from the deliberately introduced error without interpreting the source code.
Frequently asked questions
Does PHP getopt translate help automatically?
No. It parses option specifications and returns values. Your application must provide and select localized help and diagnostics.
Can I replace –locale with a translated option word?
Only if the application implements that as a real accepted alias and documents its behavior. Translating prose alone does not register syntax.
Why use a strict comparison with false?
An empty array can be a valid no-options result. A strict false test prevents it being confused with failure.
Do optional option values work with a space?
The PHP manual warns that optional values do not use a space separator like required values. Prefer explicit attached forms and test the exact command.
What is rest_index for?
It records where parsing stopped so the script can examine remaining original command-line arguments and apply its own positional rules.
Should a language change affect JSON keys?
Generally no. Keep machine-readable schemas stable unless the output format explicitly defines localized keys.
What should a malformed CLI argument return?
A nonzero status with a specific human-readable diagnostic and a corrected example, without claiming that the requested operation succeeded.
Which documentation should I check?
Use the PHP manual for the exact getopt grammar and run the examples on the PHP versions and shells you actually support.
Official references and next reading
- PHP manual: getopt()
- PHP command-line usage
- Master Art of Translation — the larger meaning system
- Translate Like a Pro — series index
The useful standard is simple. A person working in another language should be able to read a command, understand the values it accepts, run a safe example and recover from an error with confidence. The PHP parser can stay small; the explanation, validation and tests need to be complete.
Final copy-and-run exercise: prove that the instructions match the executable
One final check is worth doing before distributing a multilingual PHP command to an international team. Write down a complete invocation, including the exact shell, PHP version, argument order and expected result. Ask a colleague who has not worked on the script to follow the translated instructions without viewing the implementation. When a flag is missing, that colleague should know whether to supply a value, request help or abandon the action safely. When a locale is unsupported, the message should name supported codes rather than silently assuming that translation resources exist. When a filename contains spaces, the example must preserve the quoting needed to pass one value.
Next compare stdout, stderr and the exit status with the same command executed using the reference language. Check one normal count, one invalid count and one unknown option. The developer should be able to say which result is a parser decision, which is an application validation rule and which is only a change in wording. That comparison reveals whether the newly localized instructions have accidentally taught a different operation. A reader who can recover from a realistic mistake without interpreting PHP source code has received a useful guide, not merely an attractive translation.