Gunshi CLI localization helps developers make JavaScript and TypeScript command-line tools understandable across languages without changing the command grammar that software actually executes. If you are searching for @gunshi/plugin-i18n, Gunshi multilingual help, typed translation resources, resolveKey, locale configuration, subcommand namespaces or Unicode CLI testing, the essential task is to distinguish what a person reads from what a parser accepts. A successful translation preserves the user’s goal, not merely a sequence of English words.
Consider a voluntary museum archive tool used by people in different countries. An English-speaking curator can type a command to inspect a catalogue and understand the summary. A colleague reading Japanese or French needs the same safe task, the same warnings about absent files and the same meaning for every option. Yet a friendly French description beside –language cannot quietly turn –language into an unrecognized switch. The program’s promise and the documentation’s example must agree.
Gunshi provides declarative commands, subcommands, configurable rendering and an official internationalization plugin. Its documented @gunshi/plugin-i18n supports locale-aware resources and type-oriented helpers; the integration is not a reason to assume every application string has been localized automatically. This guide begins with a small harmless command, then explains resources, namespaces, interpolation, errors, terminals, cross-runtime delivery and the release evidence that users can trust.
Quick answer: translating Gunshi 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 JavaScript and TypeScript, 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.
// Conceptual excerpt: integrate according to the installed Gunshi release.
import { cli } from 'gunshi'
import i18n from '@gunshi/plugin-i18n'
import resources from '@gunshi/resources'
await cli(process.argv.slice(2), command, {
name: 'archive-inspector',
plugins: [i18n({
locale: process.env.ARCHIVE_LANG || 'en-US',
builtinResources: resources
})]
})
// Define and register "command" with the version-matched Gunshi API.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.
The Gunshi core resolves declared commands and arguments; the i18n plugin resolves human-facing strings. Built-in resources, application resources and command namespaces need to be reasoned about separately. If a displayed string changes without a corresponding parser alias, users should still type the original supported flag. The application’s locale selection must be explicit and testable, especially in teams whose terminals, operating systems and account settings use different languages.
An organized field guide to 24 Gunshi decisions
1. cli entry point
The cli function receives an argument vector and command definition, and its options configure how the application is exposed. 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.
Translate the task description and command context, not the process argv array; examples should show which tokens are typed verbatim. 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.
Passing a whole command string in place of an argv array invites tokenization errors when filenames contain spaces. 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.
Run the compiled example with a quoted Unicode input path and check the argument count. 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. declarative command metadata
Command definitions give Gunshi a structured place for descriptions and execution behavior rather than burying help in printed strings. 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.
Write descriptions as a promise of what a command actually does, and avoid vague labels such as process or handle. 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 translated label that implies upload while the program only inspects files can cause a serious user mistake. 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.
Compare the description with the command handler and a harmless fixture. 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. official i18n plugin
The documented @gunshi/plugin-i18n supplies localization integration instead of requiring each command to reinvent locale routing. 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 installation and activation precisely, including which package and application version the example uses. 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.
Assuming the plugin is active simply because a translation file exists can leave default-language help in production. 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.
Switch locales deliberately and confirm a known translated help sentence appears. 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. built-in resource package
The optional @gunshi/resources package supplies supported common UI vocabulary rather than all of an application’s domain terminology. 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.
Identify which standard messages come from the package and which custom messages require your resource catalogue. 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 built-in translation cannot know the difference between a museum accession number and a stock-keeping unit. 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 a language’s default help and then a deliberately custom description. 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. locale selection
The plugin accepts a locale configuration, while applications may obtain the requested locale from their own environment or settings. 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.
Say whether the chosen locale comes from an explicit option, environment value, profile or fallback; publish that precedence. 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 the application silently chooses an unexpected locale, the same command seems inconsistent on different machines. 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.
Run with an explicit locale and an unset locale, recording both results. 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. fallback language
A missing regional resource should not make critical usage advice disappear or turn into a blank column. 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.
Explain that fallback wording is a deliberate product choice and identify any untranslated item honestly. 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.
Mixing languages inside a safety or deletion warning can hide the most important verb from a novice. 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.
Remove one optional resource in a test build and inspect the complete visible message. 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. typed translation keys
Type-oriented helpers can connect documented resource keys to application code and catch some mistakes before release. 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.
Treat type checks as protection against missing identifiers, not proof that translated sentences express the same intent. 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 key can be valid while the French sentence assigns the action to the wrong person or changes a negative into a positive. 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 keys in source, build for type errors and test a real reader’s interpretation. 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. defineI18nWithTypes
The official guide uses defineI18nWithTypes to define translation-aware commands with application-specific typing. 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.
Keep the difference between a helper’s type declaration and the runtime resource lookup clear to readers. 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.
Copying a version-specific generic signature from an unrelated application may make a tutorial fail to compile. 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.
Match the helper to the pinned documentation and compile its smallest sample. 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. resolveKey namespaces
The documented resolveKey helper resolves custom keys in the command namespace so nested commands do not collide. 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 separate labels for inspect success, validate failure and export warning even if an English draft says done for all three. 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.
Two subcommands using the same unqualified key can display a sentence describing the other operation. 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 every command path with its own locale-specific resource and intentionally distinct messages. 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. translation interpolation
Documented Gunshi i18n interpolation uses brace-dollar placeholders such as {$name} inside resource strings. 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 surrounding grammar while preserving placeholder identifiers and checking order in languages whose sentences reorder subjects. 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 translator may replace a placeholder with a printed example and cause the real filename to disappear. 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.
Test messages with an accent, a long name, an empty value and a non-Latin value. 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. command descriptions in help
A command’s short description helps readers decide which task to run before they know the full command syntax. 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 the first clause name the user action and give an observable outcome rather than a slogan. 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 help says archive but the command only verifies metadata, readers may expect an output file that never appears. 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.
Ask a new reader to choose the correct command from the localized top-level 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. subcommand resource separation
Nested commands can have their own resource namespaces and are shown in the translated command listing. 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 inspect, compare and report distinct descriptions and keep their machine names stable unless code deliberately supports aliases. 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.
Copying parent messages into children confuses whether an option belongs before or after a command. 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.
Test the root help, one nested help and a nested validation error independently. 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. lazy commands
Lazy-loaded commands allow programs to defer loading code until needed, but their descriptions still have to be discoverable at the right moment. 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.
Verify localized help for commands that were not loaded during the program’s opening screen. 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 translation bundled only with an eagerly loaded module may vanish when a rarely used child is invoked. 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.
Launch the process fresh and request the child help directly. 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. argument schema
Declarative argument descriptions explain options, value types, required status and defaults in a way a user can act on. 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.
Keep literal tokens like –name distinct from placeholders like PERSON and explanatory prose in another language. 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.
Translating a placeholder into a shell token without registering it creates a polished but nonfunctional example. 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 each localized help example into an isolated test 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.
15. boolean flags
Boolean options represent a choice, not a translated natural-language sentence about a choice. 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 which exact flag enables the feature and whether a negative form is really supported. 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 warning that says disabled when the stored value is true is a semantic defect even though parsing succeeds. 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.
Record parsed values for both the absent and present flag cases. 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. required arguments
Required values should be described in terms of what a person must provide and where the value comes from. 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 concrete safe values, such as a path to a synthetic catalogue file, instead of assuming access to production data. 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 required field translated as optional can make the first-run experience look like a broken installation. 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.
Omit the argument and verify that the localized recovery message identifies it. 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. validation errors
The runtime may reject an unknown option, wrong value type or missing command before the application’s business logic begins. 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.
Distinguish syntax failures from file-not-found failures and permissions failures, since each calls for a different repair. 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 generic translation of invalid hides the token, condition and next action from the reader. 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.
Trigger three separate failures and compare the code, stderr and wording. 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. custom renderers
Gunshi supports customizable usage and validation rendering, which changes presentation but not the underlying accepted grammar. 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.
Check line wrapping, headings and readable order in each language when customizing renderer behavior. 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 beautiful box that truncates a long option description is an accessibility and safety regression. 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.
Capture plain output at narrow widths and inspect the complete content. 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. help discoverability
A person should reach a short explanation without having to know developer terminology or read source code. 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.
Put a concrete quick-start example near the top and label placeholders before advanced options. 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 translation full of implementation nouns makes a command feel inaccessible even when every noun is technically correct. 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.
Time how long a novice takes to find the safest read-only command. 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. output channels
Command help, progress, warnings and structured results may travel through stdout or stderr for different reasons. 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.
Keep diagnostic prose separate from machine-consumed output so translated language does not corrupt a pipeline. 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.
Printing a translated banner into JSON stdout can break automation even when the JSON fields remain valid. 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.
Pipe stdout to a parser and capture stderr separately in each 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.
21. Unicode and filenames
JavaScript tools can receive paths containing spaces, combining marks and characters outside Latin scripts. 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.
Translate surrounding instructions, not the exact filename or the user’s data value, and quote examples for the relevant shell. 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.
Assuming all terminals display the same glyph widths can hide the file that the message is referring to. 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.
Run filenames in several scripts and check copying, quoting and the resulting 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.
22. cross-runtime packaging
Gunshi targets multiple JavaScript runtimes, so distribution commands and environment access may differ across Node.js, Deno and Bun. 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.
Document the runtime you actually tested and avoid advertising equivalent command invocation without evidence. 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 tutorial may work in one runtime but lose a resource file or locale setting in another package. 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.
Test one packaged build per supported runtime and compare both help and errors. 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. error recovery text
Recovery instructions are part of a translation because they tell a reader what to try after a rejected command. 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.
Name the bad value, show a corrected harmless example and distinguish retrying from doing irreversible work. 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 warning that suggests the original bad command again leaves the user trapped in a loop. 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.
Have a new reader repair one intentional typo using only localized stderr. 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 matrix
A localized CLI is a versioned artifact, not a collection of phrases floating outside a build. 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.
Record package versions, locale list, operating systems, terminal widths, parser behavior and any known fallback. 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.
If tests only cover English, passing automated tests does not establish that translated help is usable. 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 exact release candidate and repeat a small scenario under every announced 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: Museum volunteer
The starting problem is concrete: A volunteer wants to inspect a local collection file but does not know the English term accession. 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.
Make the command’s localized description say that it reads catalogue records without changing them; retain the literal inspect token and show a sample fixture. 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.
Ask the volunteer to choose the right command from help and identify whether a file will be modified. 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: Regional support worker
The starting problem is concrete: A colleague sees a missing required filename error in a locale different from their desktop. 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 declared locale, the plugin resources and the fallback behavior before rewriting a sentence. 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.
Repeat with the locale specified and omitted, and compare stderr with the command’s actual parsing path. 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: Maintainer of nested commands
The starting problem is concrete: A translated success message appears under the wrong subcommand. 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.
Give each command a documented resource namespace and use resolveKey where appropriate. 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.
Make two subcommands emit visibly distinct messages in two locales; check direct nested invocation. 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: Publisher of JSON reports
The starting problem is concrete: A machine consumer stops reading a report after localization was enabled. 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.
Keep JSON keys and stdout stable; send human errors or explanations to the intended stream. 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 the report through a JSON parser and compare its field names across supported 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: Small-screen terminal user
The starting problem is concrete: A long translated description wraps over the option name. 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.
Shorten wording without deleting the condition; test Gunshi’s renderer and narrow-width 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.
Capture full and narrow output and confirm required values still appear beside the right switches. 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 Gunshi 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://gunshi.dev/guide/advanced/internationalization
- https://gunshi.dev/guide/essentials/auto-usage-generation
- https://gunshi.dev/
- Master Art of Translation — complete system
- Translate Like a Pro — series index
The strongest Gunshi 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.