PHP Aura.Cli localization helps developers explain command-line programs that inspect records, process local files or guide operators through a safe task. Readers searching for Aura.Cli Getopt, Context and Stdio, localized PHP terminal help, command-line option definitions, multilingual error messages or Unicode input need a clear account of where a command gets its inputs and how its messages reach the user. Translating a usage sentence is useful, but it is only one part of preserving a working command.
Imagine a community library running a PHP script to inspect a local list of book records. A volunteer in another country must understand the difference between the filename supplied to the program, the –language option controlling a report and the human explanation printed after inspection. If the translation calls a required value optional or tells a user to run an unsafe command to diagnose a missing file, the interface has failed even when every printed word is grammatically correct.
Aura.Cli provides context for command-line inputs, standard input and output facilities, Getopt handling and an independent Help component. These pieces form a useful map for internationalizing a program, but they do not imply a universal automatic translation catalogue. We will follow the flow from arguments to parsed values to reports and error messages, then build an accessible test plan for people working with different languages, shells, encodings and terminal widths.
Quick answer: translating PHP Aura.Cli without changing its parser
Begin with one observable reader task. A person must know which command is accepted, which parts are replaced with their own values, what the program is expected to do and how to recover from the first mistake. A localized help page should pass the same practical test as a trustworthy instruction sheet: a beginner can run a safe example, understand its result and identify the right next step. In PHP, that means keeping executable spelling stable while changing the human explanation deliberately. Translation should increase comprehension without inventing an alias, a feature or a successful outcome.
- Check the installed library and command version before writing examples.
- Choose a local, read-only fixture so the exercise cannot destroy valuable data.
- Copy exact option names and command paths from the real parser.
- Translate user goals, choices, warnings and recovery steps in ordinary language.
- Check the default, missing-value and invalid-value paths independently.
- Test one non-Latin filename and one narrow terminal before releasing help.
- Keep structured data contracts and exit-code meanings stable across languages.
A safe example: see the difference between code and explanation
The following small example is meant to make the boundary between code and reader-facing language visible. It is not a claim that a real archive, researcher or museum has installed the program, and it is not a substitute for the documentation associated with the package version on your machine. Treat file names as harmless synthetic fixtures. Where an excerpt is labelled conceptual, it illustrates the integration boundary rather than a complete application. Start with a script that displays parsed values or prints a read-only summary; add any file-changing behavior only after you understand the exact command contract.
<?php
// Illustrative structure; check the installed Aura.Cli major version.
require 'vendor/autoload.php';
$factory = new \Aura\Cli\CliFactory;
$context = $factory->newContext($GLOBALS);
$stdio = $factory->newStdio();
$options = $context->getopt(['l:', 'language:']);
$stdio->outln('Read-only catalogue inspection requested.');Notice that the sample provides a different kind of information in each place. Programming-language identifiers must satisfy a compiler or interpreter. Command-line tokens must satisfy a parser. The values supplied by a user must satisfy the receiving types and application rules. Prose is for helping a person make a correct choice. These categories overlap in one help screen, but they cannot be interchanged casually. A reader may translate a task description without changing any executable token; a developer adding a translated alias, by contrast, has changed the grammar and must test that new public interface.
The four layers of dependable command-line translation
First comes intention: the user wants to inspect, compare, describe or export something. A translation should name that goal in a way a beginner can recognize, preferably with an observable result. A bare instruction such as run the process is usually less helpful than inspect the selected local file without changing it. A command’s name may sound like a general verb, but the description should account for what that particular implementation actually does.
Second comes grammar: accepted commands, options, option values, positionals and their order. Here the authority is the installed executable, not a dictionary. If the documentation changes a literal switch without registering a new alias, the instruction is incorrect. The reader may have copied the example faithfully, yet the parser rejects it. A strong guide consistently distinguishes fixed syntax from replaceable placeholders, and tells readers when an option is genuinely optional.
Third comes data: filenames, user-provided text, configuration entries, structured result keys, numbers and booleans. They may carry meaning in another language, but the program’s type and schema rules still apply. When people write decimals differently in ordinary language, a command does not automatically acquire the ability to parse each format. When a CSV column name is consumed by another program, translating it can constitute a breaking change. Human reports can be localized; machine interfaces deserve an explicit compatibility decision.
Fourth comes evidence: the version that ran, the observed result, the error path, the platform and the locale. A well-written example can still be wrong if it was copied from another release or if a shell breaks a quoted path. Test the small safe task before explaining complicated variations. Keep any limits visible. This is how an educational guide becomes reliable for a reader who cannot ask the original author to clarify every assumption.
Aura.Cli deliberately separates command-line context, input/output and help construction. That separation lets developers place application-owned translations at the right interface boundaries: accepted option spellings remain parser data, an explanation belongs to help and messages, and values passed to downstream code should not change just because the user’s locale changes. Always check the release branch because older official documentation and newer package versions can differ.
An organized field guide to 24 PHP Aura.Cli decisions
1. CliFactory construction
The factory creates the command-line service objects used by a PHP application, depending on installed package conventions. Start by asking what a novice needs to know before typing a command. The first explanation should describe the user-visible consequence, and only then introduce the underlying technical detail. A developer may recognize the name immediately; a reader working in a second language should not have to infer it.
Explain the factory’s role as assembling tools, not interpreting a person’s selected language. In localization work, that is a distinction between language and contract. A translator can improve clarity, make an example culturally legible and remove unnecessary jargon, but only a deliberate implementation change can alter what the parser accepts. Keep those decisions separate in the release notes.
An example copied from a different major branch may fail before it reaches the parser. The problem is not simply cosmetic: a misleading instruction changes the user’s next action. A false description of a missing value, a bad flag or a default may lead them to repeat the command or modify a file unnecessarily.
Check the installed package version and execute its documented initialization path. Record the exact command, locale, return status and what the user saw. The purpose is not to collect screenshots for their own sake, but to establish that a person following the guide gets the same kind of result.
2. Context
A Context object exposes the environment and command-line inputs the PHP process receives. This part becomes easier when we separate the value the computer receives from the decision the human makes. A feature may be represented by a short token yet carry a much larger promise in context. Give that promise one precise sentence, then show the supported notation.
Make clear that arguments arrive from the shell as values, while descriptions are for readers. Think about a person using the tool for the first time. They may read the description as a guarantee that a particular value will be accepted. Every example must therefore be copyable, and every placeholder must be visibly identified as something to replace.
If a tutorial says a translated word changes argv automatically, it confuses the interface with its explanation. This failure is especially hard to detect with a screenshot review. The translated output may look polished, but appearance cannot prove that a command parses. Check the literal invocation with the released executable.
Print a harmless diagnostic of received values and inspect quoting. Do not start by exercising a destructive operation. Choose a synthetic input and compare the behavior under two locales. If the same machine-readable value changes unintentionally, investigate before publishing the description.
3. Stdio
Stdio provides an abstraction over a command’s input and output streams. It is tempting to explain this feature only through implementation vocabulary. Instead, begin with the simplest observable difference between two invocations. The reader should be able to predict what changes before seeing the output, and know when a choice is omitted.
Translate terminal-facing prompts and reports without mixing them with structured data piped to other programs. Help wording should work without requiring the reader to know the source language. Say what action is available and how the result will be reported. If the user needs to supply a file, a unit or a choice, mention that close to the option rather than burying it in a later paragraph.
A localized greeting on stdout can corrupt a JSON consumer even if the underlying records are unchanged. If a novice cannot explain the difference between the expected result and the observed result, provide a clearer recovery sentence. Do not hide the failed condition behind an umbrella term such as invalid or unsuccessful.
Capture output and error streams separately with a synthetic report. Then ask a reader unfamiliar with the code to explain the result. Successful execution is necessary, but a correct user decision is the larger goal. Reword the help if the reader expects a different action.
4. getopt input
Context Getopt handling parses option specifications against argv instead of guessing from translated prose. This is one of the places where a good longform guide should slow down. Show the smallest safe instance before presenting the full command. The user needs to understand what is fixed, what can vary and which effect they should expect, not merely memorize syntax.
Describe each supported short and long option with literal characters and their exact value rules. When translating terminology, test the word in a full sentence: who acts, on what input, with what result? A fluent word may still describe the wrong operation. Preserve exact technical tokens alongside the explanation so that the reader does not have to guess which words go in the shell.
A translated –lengua example fails if only –language was registered in code. Treat this as an opportunity to improve the original language too. Ambiguity found while translating often reveals an existing problem with English help text, an undocumented default or an untested assumption.
Run published commands using the installed parser and compare recognized flags. Repeat the check with a Unicode path and a narrow terminal. This exposes assumptions that ordinary English letters, a wide screen and a single development shell often conceal.
5. short flags
A short option such as -l gives regular users a compact way to set a known parameter. Start by asking what a novice needs to know before typing a command. The first explanation should describe the user-visible consequence, and only then introduce the underlying technical detail. A developer may recognize the name immediately; a reader working in a second language should not have to infer it.
Keep the short letter literal and explain its effect in sentences suited to the target language. In localization work, that is a distinction between language and contract. A translator can improve clarity, make an example culturally legible and remove unnecessary jargon, but only a deliberate implementation change can alter what the parser accepts. Keep those decisions separate in the release notes.
Replacing -l with the first letter of a translated noun changes the machine token without registration. The problem is not simply cosmetic: a misleading instruction changes the user’s next action. A false description of a missing value, a bad flag or a default may lead them to repeat the command or modify a file unnecessarily.
Test long and short forms for equivalent parsed values. Record the exact command, locale, return status and what the user saw. The purpose is not to collect screenshots for their own sake, but to establish that a person following the guide gets the same kind of result.
6. long flags
A long option should be memorable, explicit and stable for scripts that call it. This part becomes easier when we separate the value the computer receives from the decision the human makes. A feature may be represented by a short token yet carry a much larger promise in context. Give that promise one precise sentence, then show the supported notation.
Translate its purpose without treating the displayed word as an alias for the parser’s literal switch. Think about a person using the tool for the first time. They may read the description as a guarantee that a particular value will be accepted. Every example must therefore be copyable, and every placeholder must be visibly identified as something to replace.
Documentation may become a broken command if translators silently rename –language to something else. This failure is especially hard to detect with a screenshot review. The translated output may look polished, but appearance cannot prove that a command parses. Check the literal invocation with the released executable.
Copy the command from the final localized page into a safe run. Do not start by exercising a destructive operation. Choose a synthetic input and compare the behavior under two locales. If the same machine-readable value changes unintentionally, investigate before publishing the description.
7. required option values
In Aura.Cli option definitions, the specification syntax indicates whether an option accepts or requires a parameter. It is tempting to explain this feature only through implementation vocabulary. Instead, begin with the simplest observable difference between two invocations. The reader should be able to predict what changes before seeing the output, and know when a choice is omitted.
Explain what required means for the option value, not whether the entire command must always include that option. Help wording should work without requiring the reader to know the source language. Say what action is available and how the result will be reported. If the user needs to supply a file, a unit or a choice, mention that close to the option rather than burying it in a later paragraph.
A translated help line can hide the colon-based definition and leave users unsure where to put the value. If a novice cannot explain the difference between the expected result and the observed result, provide a clearer recovery sentence. Do not hide the failed condition behind an umbrella term such as invalid or unsuccessful.
Test a missing value and confirm the parser’s actual complaint. Then ask a reader unfamiliar with the code to explain the result. Successful execution is necessary, but a correct user decision is the larger goal. Reword the help if the reader expects a different action.
8. optional option values
Where the installed library supports optional-value syntax, the option specification must be documented precisely. This is one of the places where a good longform guide should slow down. Show the smallest safe instance before presenting the full command. The user needs to understand what is fixed, what can vary and which effect they should expect, not merely memorize syntax.
Give examples distinguishing absence, an explicit blank and a real value where behavior differs. When translating terminology, test the word in a full sentence: who acts, on what input, with what result? A fluent word may still describe the wrong operation. Preserve exact technical tokens alongside the explanation so that the reader does not have to guess which words go in the shell.
Users may unintentionally consume the next positional argument as a value when they copy a misleading example. Treat this as an opportunity to improve the original language too. Ambiguity found while translating often reveals an existing problem with English help text, an undocumented default or an untested assumption.
Inspect the remaining positional arguments after each variation. Repeat the check with a Unicode path and a narrow terminal. This exposes assumptions that ordinary English letters, a wide screen and a single development shell often conceal.
9. repeated options
Aura.Cli documentation describes a star marker for definitions that accept a flag more than once. Start by asking what a novice needs to know before typing a command. The first explanation should describe the user-visible consequence, and only then introduce the underlying technical detail. A developer may recognize the name immediately; a reader working in a second language should not have to infer it.
Explain whether repeated occurrences accumulate, override or are combined by application logic. In localization work, that is a distinction between language and contract. A translator can improve clarity, make an example culturally legible and remove unnecessary jargon, but only a deliberate implementation change can alter what the parser accepts. Keep those decisions separate in the release notes.
If a translation says the last value wins when the parser returns an array, readers may lose data. The problem is not simply cosmetic: a misleading instruction changes the user’s next action. A false description of a missing value, a bad flag or a default may lead them to repeat the command or modify a file unnecessarily.
Supply two repeated harmless values and inspect what the application receives. Record the exact command, locale, return status and what the user saw. The purpose is not to collect screenshots for their own sake, but to establish that a person following the guide gets the same kind of result.
10. GetoptValues
The parsed result provides program code with values associated with the configured flags. This part becomes easier when we separate the value the computer receives from the decision the human makes. A feature may be represented by a short token yet carry a much larger promise in context. Give that promise one precise sentence, then show the supported notation.
Separate a boolean switch from a string value and a missing key in the user explanation. Think about a person using the tool for the first time. They may read the description as a guarantee that a particular value will be accepted. Every example must therefore be copyable, and every placeholder must be visibly identified as something to replace.
A translation that says enabled merely because the option name appears in the help is not evidence of a parsed true value. This failure is especially hard to detect with a screenshot review. The translated output may look polished, but appearance cannot prove that a command parses. Check the literal invocation with the released executable.
Log parsed results in a local fixture before writing business code. Do not start by exercising a destructive operation. Choose a synthetic input and compare the behavior under two locales. If the same machine-readable value changes unintentionally, investigate before publishing the description.
11. positional arguments
Not every input comes after a named option; some are simply remaining argv values. It is tempting to explain this feature only through implementation vocabulary. Instead, begin with the simplest observable difference between two invocations. The reader should be able to predict what changes before seeing the output, and know when a choice is omitted.
Explain order, quoting and placeholders clearly, especially when a path contains spaces. Help wording should work without requiring the reader to know the source language. Say what action is available and how the result will be reported. If the user needs to supply a file, a unit or a choice, mention that close to the option rather than burying it in a later paragraph.
Calling a positional filename a flag makes first-time users put — before something the command does not accept. If a novice cannot explain the difference between the expected result and the observed result, provide a clearer recovery sentence. Do not hide the failed condition behind an umbrella term such as invalid or unsuccessful.
Run a single synthetic filename and compare its position with the help. Then ask a reader unfamiliar with the code to explain the result. Successful execution is necessary, but a correct user decision is the larger goal. Reword the help if the reader expects a different action.
12. independent Help object
Aura.Cli provides a Help component for describing a command independently from input parsing. This is one of the places where a good longform guide should slow down. Show the smallest safe instance before presenting the full command. The user needs to understand what is fixed, what can vary and which effect they should expect, not merely memorize syntax.
Translate the Help object’s prose, headings and examples while confirming they still match Getopt definitions. When translating terminology, test the word in a full sentence: who acts, on what input, with what result? A fluent word may still describe the wrong operation. Preserve exact technical tokens alongside the explanation so that the reader does not have to guess which words go in the shell.
Documentation maintained in a separate object can drift away from actual accepted options. Treat this as an opportunity to improve the original language too. Ambiguity found while translating often reveals an existing problem with English help text, an undocumented default or an untested assumption.
Build a small acceptance test comparing documented and parsed switch spellings. Repeat the check with a Unicode path and a narrow terminal. This exposes assumptions that ordinary English letters, a wide screen and a single development shell often conceal.
13. command synopsis
The synopsis is a compact grammar that tells a reader what is fixed, optional and repeatable. Start by asking what a novice needs to know before typing a command. The first explanation should describe the user-visible consequence, and only then introduce the underlying technical detail. A developer may recognize the name immediately; a reader working in a second language should not have to infer it.
Use conventional notation consistently and explain brackets or angle brackets outside the literal command. In localization work, that is a distinction between language and contract. A translator can improve clarity, make an example culturally legible and remove unnecessary jargon, but only a deliberate implementation change can alter what the parser accepts. Keep those decisions separate in the release notes.
A translator may turn a placeholder like FILE into a required literal word that users paste unmodified. The problem is not simply cosmetic: a misleading instruction changes the user’s next action. A false description of a missing value, a bad flag or a default may lead them to repeat the command or modify a file unnecessarily.
Ask a newcomer to mark which parts they must replace. Record the exact command, locale, return status and what the user saw. The purpose is not to collect screenshots for their own sake, but to establish that a person following the guide gets the same kind of result.
14. option descriptions
Descriptions should say what happens after a valid option is supplied and mention units where relevant. This part becomes easier when we separate the value the computer receives from the decision the human makes. A feature may be represented by a short token yet carry a much larger promise in context. Give that promise one precise sentence, then show the supported notation.
Prefer inspect the named local file over process an argument for clear first-run guidance. Think about a person using the tool for the first time. They may read the description as a guarantee that a particular value will be accepted. Every example must therefore be copyable, and every placeholder must be visibly identified as something to replace.
A description that says export when the code only prints a summary creates an incorrect expectation. This failure is especially hard to detect with a screenshot review. The translated output may look polished, but appearance cannot prove that a command parses. Check the literal invocation with the released executable.
Read the implementation beside every localized help entry. Do not start by exercising a destructive operation. Choose a synthetic input and compare the behavior under two locales. If the same machine-readable value changes unintentionally, investigate before publishing the description.
15. language selection
An application’s own locale preference may arrive from a flag, environment setting or configuration file. It is tempting to explain this feature only through implementation vocabulary. Instead, begin with the simplest observable difference between two invocations. The reader should be able to predict what changes before seeing the output, and know when a choice is omitted.
Declare the actual precedence and fallback chosen by the application rather than attributing it to Aura.Cli automatically. Help wording should work without requiring the reader to know the source language. Say what action is available and how the result will be reported. If the user needs to supply a file, a unit or a choice, mention that close to the option rather than burying it in a later paragraph.
If the locale setting is different in two shells, identical commands may print inconsistent advice. If a novice cannot explain the difference between the expected result and the observed result, provide a clearer recovery sentence. Do not hide the failed condition behind an umbrella term such as invalid or unsuccessful.
Test explicit and absent language settings while capturing all visible messages. Then ask a reader unfamiliar with the code to explain the result. Successful execution is necessary, but a correct user decision is the larger goal. Reword the help if the reader expects a different action.
16. stdin prompts
Some command-line tools ask for data interactively, while others should run without a terminal attached. This is one of the places where a good longform guide should slow down. Show the smallest safe instance before presenting the full command. The user needs to understand what is fixed, what can vary and which effect they should expect, not merely memorize syntax.
Translate prompts to request one answer at a time and state any side effects before confirmation. When translating terminology, test the word in a full sentence: who acts, on what input, with what result? A fluent word may still describe the wrong operation. Preserve exact technical tokens alongside the explanation so that the reader does not have to guess which words go in the shell.
An automated invocation may hang indefinitely if localization introduces a question into noninteractive mode. Treat this as an opportunity to improve the original language too. Ambiguity found while translating often reveals an existing problem with English help text, an undocumented default or an untested assumption.
Run with stdin closed and check whether the application fails safely. Repeat the check with a Unicode path and a narrow terminal. This exposes assumptions that ordinary English letters, a wide screen and a single development shell often conceal.
17. stdout reports
stdout is useful for ordinary output and machine-consumed records. Start by asking what a novice needs to know before typing a command. The first explanation should describe the user-visible consequence, and only then introduce the underlying technical detail. A developer may recognize the name immediately; a reader working in a second language should not have to infer it.
Keep JSON or CSV field names stable unless schema versioning explicitly permits translating them. In localization work, that is a distinction between language and contract. A translator can improve clarity, make an example culturally legible and remove unnecessary jargon, but only a deliberate implementation change can alter what the parser accepts. Keep those decisions separate in the release notes.
Localized report headings inserted into a data stream can make a downstream parser reject the result. The problem is not simply cosmetic: a misleading instruction changes the user’s next action. A false description of a missing value, a bad flag or a default may lead them to repeat the command or modify a file unnecessarily.
Compare structured stdout byte-for-byte after normalizing human-only timestamps. Record the exact command, locale, return status and what the user saw. The purpose is not to collect screenshots for their own sake, but to establish that a person following the guide gets the same kind of result.
18. stderr errors
Errors should identify failed inputs and help a reader recover without obscuring the failure layer. This part becomes easier when we separate the value the computer receives from the decision the human makes. A feature may be represented by a short token yet carry a much larger promise in context. Give that promise one precise sentence, then show the supported notation.
Describe syntax failure, file absence and permission denial with distinct words and solutions. Think about a person using the tool for the first time. They may read the description as a guarantee that a particular value will be accepted. Every example must therefore be copyable, and every placeholder must be visibly identified as something to replace.
A single error translated as command not found for every failure sends users to reinstall software unnecessarily. This failure is especially hard to detect with a screenshot review. The translated output may look polished, but appearance cannot prove that a command parses. Check the literal invocation with the released executable.
Trigger one example from each layer and check stderr and exit status. Do not start by exercising a destructive operation. Choose a synthetic input and compare the behavior under two locales. If the same machine-readable value changes unintentionally, investigate before publishing the description.
19. exit status
Shell automation uses exit codes as signals of success and failure, independent of written messages. It is tempting to explain this feature only through implementation vocabulary. Instead, begin with the simplest observable difference between two invocations. The reader should be able to predict what changes before seeing the output, and know when a choice is omitted.
Make translations describe the same success or failure outcome without changing exit-code semantics. Help wording should work without requiring the reader to know the source language. Say what action is available and how the result will be reported. If the user needs to supply a file, a unit or a choice, mention that close to the option rather than burying it in a later paragraph.
A message that says completed while the program returns failure is confusing for both humans and scripts. If a novice cannot explain the difference between the expected result and the observed result, provide a clearer recovery sentence. Do not hide the failed condition behind an umbrella term such as invalid or unsuccessful.
Test success and failure cases and record exit code plus visible text. Then ask a reader unfamiliar with the code to explain the result. Successful execution is necessary, but a correct user decision is the larger goal. Reword the help if the reader expects a different action.
20. encoding
PHP applications run on terminals and files that may use different character encodings. This is one of the places where a good longform guide should slow down. Show the smallest safe instance before presenting the full command. The user needs to understand what is fixed, what can vary and which effect they should expect, not merely memorize syntax.
Use UTF-8 test data and explicit conversion where the application’s environment requires it. When translating terminology, test the word in a full sentence: who acts, on what input, with what result? A fluent word may still describe the wrong operation. Preserve exact technical tokens alongside the explanation so that the reader does not have to guess which words go in the shell.
Accented names may become unreadable through a bad encoding boundary even when translations are correct. Treat this as an opportunity to improve the original language too. Ambiguity found while translating often reveals an existing problem with English help text, an undocumented default or an untested assumption.
Try a fixture with non-Latin characters and inspect displayed and saved bytes. Repeat the check with a Unicode path and a narrow terminal. This exposes assumptions that ordinary English letters, a wide screen and a single development shell often conceal.
21. terminal layout
Long help strings and multibyte glyphs affect wrapping, alignment and the scanability of options. Start by asking what a novice needs to know before typing a command. The first explanation should describe the user-visible consequence, and only then introduce the underlying technical detail. A developer may recognize the name immediately; a reader working in a second language should not have to infer it.
Write a short first sentence and verify that an option’s required condition remains visible at narrow widths. In localization work, that is a distinction between language and contract. A translator can improve clarity, make an example culturally legible and remove unnecessary jargon, but only a deliberate implementation change can alter what the parser accepts. Keep those decisions separate in the release notes.
A table aligned by byte count may shift columns in East Asian text and hide values. The problem is not simply cosmetic: a misleading instruction changes the user’s next action. A false description of a missing value, a bad flag or a default may lead them to repeat the command or modify a file unnecessarily.
Capture both wide and narrow terminal output as plain text. Record the exact command, locale, return status and what the user saw. The purpose is not to collect screenshots for their own sake, but to establish that a person following the guide gets the same kind of result.
22. version differences
Official Aura.Cli pages for earlier branches may show syntax or requirements different from a current installed major version. This part becomes easier when we separate the value the computer receives from the decision the human makes. A feature may be represented by a short token yet carry a much larger promise in context. Give that promise one precise sentence, then show the supported notation.
Call out the tested branch and do not silently mix snippets from different documentation generations. Think about a person using the tool for the first time. They may read the description as a guarantee that a particular value will be accepted. Every example must therefore be copyable, and every placeholder must be visibly identified as something to replace.
A reader following a mixed-version tutorial may mistake a compatibility error for a translation issue. This failure is especially hard to detect with a screenshot review. The translated output may look polished, but appearance cannot prove that a command parses. Check the literal invocation with the released executable.
Run installation and the first help command in a clean environment. Do not start by exercising a destructive operation. Choose a synthetic input and compare the behavior under two locales. If the same machine-readable value changes unintentionally, investigate before publishing the description.
23. security boundaries
A translated instruction should never ask a reader to run destructive commands merely to confirm a parser flag. It is tempting to explain this feature only through implementation vocabulary. Instead, begin with the simplest observable difference between two invocations. The reader should be able to predict what changes before seeing the output, and know when a choice is omitted.
Use synthetic local files and distinguish inspect from delete, overwrite or publish before any real operation. Help wording should work without requiring the reader to know the source language. Say what action is available and how the result will be reported. If the user needs to supply a file, a unit or a choice, mention that close to the option rather than burying it in a later paragraph.
An ambiguous localized confirm prompt can make a risky action look like a safe preview. If a novice cannot explain the difference between the expected result and the observed result, provide a clearer recovery sentence. Do not hide the failed condition behind an umbrella term such as invalid or unsuccessful.
Review the read-only and modifying paths with people who speak each supported language. Then ask a reader unfamiliar with the code to explain the result. Successful execution is necessary, but a correct user decision is the larger goal. Reword the help if the reader expects a different action.
24. release proof
A trustworthy PHP CLI guide reflects the package version, actual option definitions, shell, locale and tested outputs. This is one of the places where a good longform guide should slow down. Show the smallest safe instance before presenting the full command. The user needs to understand what is fixed, what can vary and which effect they should expect, not merely memorize syntax.
Document known limitations instead of advertising language coverage based solely on the presence of strings. When translating terminology, test the word in a full sentence: who acts, on what input, with what result? A fluent word may still describe the wrong operation. Preserve exact technical tokens alongside the explanation so that the reader does not have to guess which words go in the shell.
Tests that only assert an English help page cannot establish a multilingual release. Treat this as an opportunity to improve the original language too. Ambiguity found while translating often reveals an existing problem with English help text, an undocumented default or an untested assumption.
Package the application and verify the same harmless task in each supported locale. Repeat the check with a Unicode path and a narrow terminal. This exposes assumptions that ordinary English letters, a wide screen and a single development shell often conceal.
Five real reader journeys, from first question to a tested answer
Reader journey 1: Community library volunteer
The starting problem is concrete: The volunteer does not know whether a synopsis expects a filename or a flag. This is the moment when documentation can either reduce uncertainty or make a reader guess. A useful explanation identifies the intended task before offering a command. It does not assume familiarity with the development team’s vocabulary, account settings or operating system. Give the reader a small preview of what should happen, and say plainly if the operation could modify data.
Show a working quoted path and define the FILE placeholder separately from literal switches. The decision sequence is to identify the actual executable, open the help, inspect the accepted argument or value, run a harmless fixture and read the outcome. A translation that skips any of these steps can sound convincing while remaining unusable. Use explicit examples with distinct placeholder and literal text, and keep any special quoting visible.
Have the volunteer reproduce the read-only run without developer assistance. If the outcome differs, do not immediately blame the target language. Check the shell, parsed data, locale precedence, package version and output stream one at a time. Give the reader a single corrective step after each observed failure rather than a dense wall of possible causes. That sequence turns troubleshooting from guesswork into understandable evidence.
Reader journey 2: PHP application maintainer
The starting problem is concrete: The Help object and Getopt definitions disagree about whether an option needs a value. This is the moment when documentation can either reduce uncertainty or make a reader guess. A useful explanation identifies the intended task before offering a command. It does not assume familiarity with the development team’s vocabulary, account settings or operating system. Give the reader a small preview of what should happen, and say plainly if the operation could modify data.
Treat parser definitions as the authority and rewrite the help to reflect actual behavior. The decision sequence is to identify the actual executable, open the help, inspect the accepted argument or value, run a harmless fixture and read the outcome. A translation that skips any of these steps can sound convincing while remaining unusable. Use explicit examples with distinct placeholder and literal text, and keep any special quoting visible.
Test missing and supplied values and compare the result to the final synopsis. If the outcome differs, do not immediately blame the target language. Check the shell, parsed data, locale precedence, package version and output stream one at a time. Give the reader a single corrective step after each observed failure rather than a dense wall of possible causes. That sequence turns troubleshooting from guesswork into understandable evidence.
Reader journey 3: Regional operator
The starting problem is concrete: A report displays accented names as replacement characters. This is the moment when documentation can either reduce uncertainty or make a reader guess. A useful explanation identifies the intended task before offering a command. It does not assume familiarity with the development team’s vocabulary, account settings or operating system. Give the reader a small preview of what should happen, and say plainly if the operation could modify data.
Trace the input encoding, PHP string handling and terminal rendering instead of translating the names again. The decision sequence is to identify the actual executable, open the help, inspect the accepted argument or value, run a harmless fixture and read the outcome. A translation that skips any of these steps can sound convincing while remaining unusable. Use explicit examples with distinct placeholder and literal text, and keep any special quoting visible.
Compare the original synthetic file bytes with captured output. If the outcome differs, do not immediately blame the target language. Check the shell, parsed data, locale precedence, package version and output stream one at a time. Give the reader a single corrective step after each observed failure rather than a dense wall of possible causes. That sequence turns troubleshooting from guesswork into understandable evidence.
Reader journey 4: Automation engineer
The starting problem is concrete: A translated sentence unexpectedly appears before the CSV header. This is the moment when documentation can either reduce uncertainty or make a reader guess. A useful explanation identifies the intended task before offering a command. It does not assume familiarity with the development team’s vocabulary, account settings or operating system. Give the reader a small preview of what should happen, and say plainly if the operation could modify data.
Separate human messages from machine output and keep the data schema stable. The decision sequence is to identify the actual executable, open the help, inspect the accepted argument or value, run a harmless fixture and read the outcome. A translation that skips any of these steps can sound convincing while remaining unusable. Use explicit examples with distinct placeholder and literal text, and keep any special quoting visible.
Pipe stdout to a CSV parser in two locales. If the outcome differs, do not immediately blame the target language. Check the shell, parsed data, locale precedence, package version and output stream one at a time. Give the reader a single corrective step after each observed failure rather than a dense wall of possible causes. That sequence turns troubleshooting from guesswork into understandable evidence.
Reader journey 5: Support writer
The starting problem is concrete: A permission failure is described as a malformed option. This is the moment when documentation can either reduce uncertainty or make a reader guess. A useful explanation identifies the intended task before offering a command. It does not assume familiarity with the development team’s vocabulary, account settings or operating system. Give the reader a small preview of what should happen, and say plainly if the operation could modify data.
Inspect the failed layer and give a repair appropriate to filesystem access. The decision sequence is to identify the actual executable, open the help, inspect the accepted argument or value, run a harmless fixture and read the outcome. A translation that skips any of these steps can sound convincing while remaining unusable. Use explicit examples with distinct placeholder and literal text, and keep any special quoting visible.
Induce both errors separately and verify the outcomes differ. If the outcome differs, do not immediately blame the target language. Check the shell, parsed data, locale precedence, package version and output stream one at a time. Give the reader a single corrective step after each observed failure rather than a dense wall of possible causes. That sequence turns troubleshooting from guesswork into understandable evidence.
A disciplined release plan for multilingual command-line help
Week one: record the real grammar
Install the intended release and capture the top-level help, one nested or advanced command where relevant, a success and three distinct failures. Annotate which strings are literal parser tokens, which are replaceable values and which are descriptive. Make a small corpus of safe synthetic inputs. Have an uninvolved reader identify the required arguments before any translation is added.
Week two: write the explanations
Draft concise task descriptions, argument purposes, defaults and error recovery sentences. Use a glossary for concepts that recur, but do not force the same translated word onto distinct actions. Keep machine-readable keys and data types stable. Translate complete example journeys rather than only isolated UI strings, because context often changes the correct wording.
Week three: test behavior and comprehension
Run the localized help, normal path, bad option, missing value, malformed type and input-file failure. Repeat with spaces and Unicode in filenames. Capture stdout, stderr and exit codes, then ask a reader to perform the harmless task without the original-language page. Record where the reader hesitates or expects another outcome.
Week four: distribute with evidence
Package the same code and resource versions used in testing. State supported locales and platforms, preserve any legacy flags that scripts rely on, and explain known fallbacks. Re-run smoke tests from the packaged artifact rather than the developer checkout. Keep a correction pathway visible because translations must change when command behavior changes.
After release: correct the smallest failing claim
When someone reports a broken example, collect the exact invocation, locale and version without requesting secrets or private files. Reproduce it with a synthetic fixture. Fix the wrong layer: grammar, input encoding, help wording, locale fallback or documentation example. A reliable guide improves through specific verified corrections, not blanket assurances that every environment is supported.
The practical multilingual QA matrix
- English baseline: The original-language help is a control. Preserve its actual accepted command spellings, default values and task semantics when comparing translations.
- Second locale: Choose one complete translation, including success and error states. Test it with the same fixture and verify that the outcome remains equivalent.
- Missing resource: Remove or disable one nonessential translated string in a test build. Check that fallback is understandable and that required warnings remain present.
- Narrow terminal: Review plain text at a narrow width so long labels, bullets and value placeholders are not clipped or detached from their options.
- Unicode input: Use a synthetic file path with accented and non-Latin characters. Make sure the shell quotes it and the program receives the intended value.
- Error channel: Capture parse errors and application errors separately; compare the exit status and the advice given to the user.
- Data output: If the command prints CSV, JSON or other structured data, compare keys and schema across locales. Human-readable reports may change; machine contracts require explicit versioning.
- No hidden side effects: Run read-only fixtures first and name every operation that can overwrite, upload, delete or publish before introducing it as an example.
Common questions answered from the user’s point of view
Can I translate every flag into another language?
No. A localized description is not a new registered parser alias. Keep exact supported flag names in commands; add localized aliases only through deliberate code and compatibility testing.
Does PHP Aura.Cli automatically localize my whole application?
Do not assume so. Distinguish generated parser help, library or plugin resources, separately authored business messages and descriptions stored in application code. Test each category.
Why does a translated example fail when the English one works?
Compare copied syntax, option names, quoting, locale-specific number formatting and argument order. The translation may have changed a machine token accidentally.
Should I translate the JSON field names?
Only as an intentional versioned schema change. Translation of human labels is usually separate from the stable keys consumed by software.
What should a useful error message say?
Identify the failed input, the stage of failure, the correction and a safe complete example. Avoid a generic invalid label when a precise repair is available.
Is a translated default also an actual default?
Only if the parser or application uses that value when the option is omitted. Test omission and explicit setting separately; documentation cannot establish behavior by itself.
How do I handle long translated sentences in terminal help?
Use concise openings, clear option grouping and narrow-width tests. Preserve the required condition and recovery advice even when text must wrap.
Can automatic translation replace technical testing?
It can propose language, but it cannot demonstrate accepted grammar, typed values or correct file effects. Keep a real executable test beside editorial review.
What if two languages use different decimal separators?
Document the program’s accepted numeric notation and show valid literal inputs. Natural-language formatting conventions do not automatically change a numeric parser.
How should I explain an input filename with spaces?
Use the quoting rules for the tested shell and preserve the actual filename. Test a synthetic file with spaces and Unicode.
What if a user has a different runtime or package version?
State which release the example describes, point to official documentation and avoid promising untested platform equivalence. A version difference may affect help rendering.
When should this page be updated?
Update it when accepted flags, defaults, error behavior, locale resources, required dependencies or distribution steps change. Validate the new package before changing the instructions.
Primary documentation and further reading
A technical reference should distinguish documented framework behavior from application-specific decisions. The links below help you confirm the API against your installed release. Use the Master Art of Translation — complete system for the larger meaning-and-fidelity principles and the Translate Like a Pro series index to find adjacent frameworks without confusing their parser grammars. These links are supporting reading, not substitutes for a test against the exact command you distribute.
- https://github.com/auraphp/Aura.Cli
- https://auraphp.com/packages/2.x/Cli
- https://www.php.net/manual/en/features.commandline.php
- Master Art of Translation — complete system
- Translate Like a Pro — series index
The strongest PHP Aura.Cli translation is not the longest catalogue of technical terms. It is a set of instructions that helps a person choose the correct safe action, run a command the software really accepts, recognize the result and recover from the first failure without relying on the source language. Keep that practical promise in view each time the interface, runtime or documentation changes.