Multilingual Support (i18n)
Relevant source files
The following files were used as context for generating this wiki page:
Multilingual support in pubm is a core architectural feature designed to provide a localized experience for developers across different regions. It enables the CLI to present warnings, errors, task statuses, and interactive prompts in the user's preferred language. This system is centralized within the @pubm/core package and utilized by the main CLI and its associated plugins to ensure consistent communication.
The i18n system supports several languages including English (default), French, Spanish, German, Simplified Chinese, and Korean. It employs a key-based translation mechanism where the application code references abstract keys that are resolved at runtime based on the detected or configured locale.
Sources: CLAUDE.md:144, packages/core/src/i18n/locales/en.json:1-510
Architecture and Core Components
The i18n architecture consists of a locale resolver, a centralized translation function, and structured JSON locale files.
Locale Resolution Logic
The system determines the active locale through a resolver that prioritizes explicit user configuration before falling back to system defaults.
This flow ensures that the CLI can be forced into a specific language mode via the --locale flag, which supports values such as en, ko, zh-cn, fr, de, and es.
Sources: packages/core/src/i18n/locales/en.json:442, CLAUDE.md:144
Translation Mechanism (t function)
The core of the system is the translation function, typically imported as t. This function accepts a translation key and an optional object containing variables for interpolation.
| Component | Responsibility |
|---|---|
t(key, params?) | Resolves a string key to a localized message, performing placeholder replacement. |
Locale Files | JSON files (e.g., en.json) containing key-value pairs of messages. |
Interpolation | The ability to inject dynamic data into strings using {variable} syntax. |
For example, a task status like "Bumping version ({summary})" is resolved using the key task.version.titleWithSummary, where {summary} is dynamically replaced by the current versioning context.
Sources: packages/core/src/tasks/prompts/display.ts:7-9, packages/core/src/i18n/locales/en.json:138
Localization Data Structure
Localized strings are organized hierarchically within JSON files. This structure categorizes messages by their functional area within the CLI lifecycle.
Message Categories
The translation keys are generally prefixed based on their usage:
- label: Common UI elements (e.g.,
label.warning,label.error). - task: Progress indicators and status updates for specific operations (e.g.,
task.prerequisites.title,task.publish.publishing). - prompt: Interactive questions asked to the user (e.g.,
prompt.version.selectIncrement). - error: Descriptive error messages and technical failure details.
- cli: Help text and command-line option descriptions.
Pluralization and Interpolation
The system supports complex string construction including pluralization and variable placeholders.
"cmd.status.packageLine": "{name}: {type} ({count, plural, one {# changeset} other {# changesets}})"
In this example, the count variable determines whether to display the singular or plural form of "changeset".
Sources: packages/core/src/i18n/locales/en.json:480
Implementation in UI Components
The ui utility and display tasks leverage the i18n system to render formatted output to the terminal.
Integration with UI Utilities
The UI module utilizes specific labels for badges and warnings. While the raw labels are defined in the i18n files, the ui utility applies formatting (such as colors or bold text) to these localized strings.
// Example logic derived from UI tests and display tasks
const message = t("note.dependency.bumped", {
label: dependencyLabel,
dependencies: bumpedDependencies.join(", "),
version: suggestedVersion,
});
ui.formatNote("hint", message);
Sources: packages/core/tests/unit/utils/ui.test.ts:16-45, packages/core/src/tasks/prompts/display.ts:74-84
UI Label Reference
The following table lists common localized labels used throughout the interface:
| Key | Default (en) | Usage |
|---|---|---|
label.warning | WARNING | Prefixes warning messages in yellow |
label.error | ERROR | Prefixes error messages in red |
label.dryRun | [dry-run] | Indicates no changes are being written |
label.rollback | ROLLBACK | Displayed during automatic failure recovery |
label.success | SUCCESS | Indicates successful completion of a task |
Sources: packages/core/src/i18n/locales/en.json:1-9, packages/core/tests/unit/utils/ui.test.ts:28-40
Summary
The i18n system in pubm provides a robust framework for global accessibility. By separating the message content from the logic, it allows for easy expansion into new languages without modifying the core pipeline. The architecture ensures that every user-facing string—from low-level git errors to high-level CLI descriptions—can be localized, providing a native-feeling experience regardless of the developer's primary language.