@gunshi/plugin-i18n 0.26.3

package/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 kazuya kawaguchi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,527 @@
+# @gunshi/plugin-i18n
+
+> internationalization (i18n) plugin for gunshi.
+
+This plugin provides multi-language support for your CLI applications, allowing you to create commands that can display messages in different languages based on user locale.
+
+## 💿 Installation
+
+```sh
+# npm
+npm install --save @gunshi/plugin-i18n
+
+# pnpm
+pnpm add @gunshi/plugin-i18n
+
+# yarn
+yarn add @gunshi/plugin-i18n
+
+# deno
+deno add jsr:@gunshi/plugin-i18n
+
+# bun
+bun add @gunshi/plugin-i18n
+```
+
+## 🚀 Usage
+
+```ts
+import { cli } from 'gunshi'
+import i18n, { defineI18n } from '@gunshi/plugin-i18n'
+
+/**
+ * You can define a command with `defineI18n`, which is compatible with the `define` function.
+ * This provides full type safety for i18n commands - TypeScript will suggest the 'resource' option
+ * and ensure your resource keys match the expected structure.
+ */
+
+// Define a command
+const greetCommand = defineI18n({
+  name: 'greet',
+  description: 'Greet someone',
+
+  args: {
+    name: {
+      type: 'string',
+      description: 'Name to greet'
+    }
+  },
+
+  // Define resource fetcher for translations
+  resource: async ctx => ({
+    description: 'Greet someone in their language',
+    examples: '$ your-cli --name yourname',
+    'arg:name': "The person's name",
+    greeting: 'Hello, {$name}!'
+  }),
+
+  run: async ctx => {
+    const { name } = ctx.values
+    // Use translate function from context
+    console.log(ctx.extensions['g:i18n'].translate('greeting', { name }))
+  }
+})
+
+// Run CLI with i18n plugin
+await cli(process.argv.slice(2), greetCommand, {
+  plugins: [
+    i18n({
+      locale: 'en-US' // or use process.env.LANG, navigator.language, etc.
+    })
+  ]
+})
+```
+
+## ⚙️ Plugin Options
+
+### `locale`
+
+- Type: `string | Intl.Locale`
+- Default: `'en-US'`
+- Description: The locale to use for translations. Can be a BCP 47 language tag string or an `Intl.Locale` object.
+
+### `resources`
+
+- Type: `Record<string, Record<BuiltinResourceKeys, string>>`
+- Default: `{}`
+- Description:
+  - Built-in resource translations for different locales. Used for translating gunshi built-in level messages like "USAGE", "OPTIONS", "COMMANDS", etc.
+  - for details, see [Resource Key Naming Conventions](#resource-key-naming-conventions)
+
+### `translationAdapterFactory`
+
+- Type: `(options: TranslationAdapterFactoryOptions) => TranslationAdapter`
+- Default: `createTranslationAdapter`
+- Description: Factory function to create a custom translation adapter. Useful for integrating with existing i18n libraries.
+
+## 🔗 Plugin Dependencies
+
+The i18n plugin has an optional dependency on the `g:global` plugin:
+
+- **Plugin ID**: `g:global` (optional)
+- **Purpose**: Provides global options support for `--help` and `--version`
+- **Effect**: When the globals plugin is present, the i18n plugin automatically sets up translations for the `help` and `version` built-in resources
+
+This means:
+
+- If you're using the globals plugin (which adds `--help` and `--version` options), the i18n plugin will automatically handle their translations
+- The translations for "Display this help message" and "Display this version" will be available in your configured locale
+- You can override these translations by providing your own `help` and `version` keys in your built-in resources
+
+Example with globals plugin:
+
+```ts
+import { cli } from 'gunshi'
+import i18n from '@gunshi/plugin-i18n'
+import globals from '@gunshi/plugin-global'
+
+await cli(args, command, {
+  plugins: [
+    globals(), // Adds --help and --version options
+    i18n({
+      locale: 'ja-JP',
+      resources: {
+        'ja-JP': {
+          help: 'ヘルプメッセージを表示', // Override help translation
+          version: 'バージョンを表示' // Override version translation
+          // ... other built-in translations
+        }
+      }
+    })
+  ]
+})
+```
+
+## 🛠️ Helper Functions
+
+### `defineI18n`
+
+Type-safe helper to define an i18n-aware command.
+
+```ts
+import { defineI18n } from '@gunshi/plugin-i18n'
+
+const command = defineI18n({
+  name: 'hello',
+  args: {
+    name: { type: 'string' }
+  },
+  resource: async ctx => ({
+    description: 'Say hello',
+    'arg:name': 'Your name'
+  }),
+  run: async ctx => {
+    console.log(`Hello, ${ctx.values.name}!`)
+  }
+})
+```
+
+### `withI18nResource`
+
+Add i18n resource to an existing command. This helper is useful for extending an already defined command.
+
+```ts
+import { define } from 'gunshi' // 'gunshi/definition', or '@gunshi/definition'
+import { withI18nResource } from '@gunshi/plugin-i18n'
+
+const basicCommand = define({
+  name: 'test',
+  args: {
+    target: {
+      type: 'string',
+      description: 'The test target file',
+      required: true
+    }
+  },
+  run: ctx => console.log(`test: ${ctx.values.target}`)
+})
+
+const i18nCommand = withI18nResource(basicCommand, async ctx => {
+  const resource = await import(
+    `./path/to/resources/test/${ctx.extensions['g:i18n'].locale.toString()}.json`,
+    { with: { type: 'json' } }
+  ).then(l => l.default || l)
+  return resource
+})
+```
+
+## 🧩 Context Extensions
+
+When using the i18n plugin, your command context is extended via `ctx.extensions['g:i18n']`.
+
+<!-- eslint-disable markdown/no-missing-label-refs -->
+
+> [!IMPORTANT]
+> This plugin extension is namespaced in `CommandContext.extensions` using this plugin ID `g:i18n` by the gunshi plugin system.
+
+<!-- eslint-enable markdown/no-missing-label-refs -->
+
+Available extensions:
+
+- `locale: Intl.Locale`: The current locale
+- `translate<T>(key: T, values?: Record<string, unknown>): string`: Translation function
+
+## 📝 Resource Key Naming Conventions
+
+When defining your localization resources (either directly in the `resource` function or in separate files), there are specific naming conventions to follow for the keys:
+
+- **Command Description**: Use the key `description` for the main description of the command.
+- **Examples**: Use the key `examples` for usage examples.
+- **Argument and Option Descriptions**: Keys for the descriptions of both command arguments (positional args) and options **must** be prefixed with `arg:`. For example:
+  - For an argument named `file`: use `arg:file`
+  - For an option named `verbose`: use `arg:verbose`
+  - **Negatable Argument Descriptions**: For boolean options (e.g., `--verbose`), Gunshi automatically generates a description for the negatable version (e.g., `--no-verbose`) using the built-in `NEGATABLE` key (e.g., "Negatable of --verbose"). To provide a custom translation for a specific negatable option, use the pattern `arg:no-<optionName>`, for example, `arg:no-verbose`.
+- **Custom Keys**: Any other keys you define for custom translation messages (like greetings, error messages, etc.) do not require a prefix and can be named freely (e.g., `informal_greeting`, `error_file_not_found`).
+- **Built-in Keys**: Keys for built-in functionalities are handled by Gunshi's default locales. The complete list includes:
+  - `USAGE` - Usage section header
+  - `OPTIONS` - Options section header
+  - `ARGUMENTS` - Arguments section header
+  - `COMMANDS` - Commands section header
+  - `EXAMPLES` - Examples section header
+  - `FORMORE` - Footer text for additional help
+  - `NEGATABLE` - Prefix for negatable options (e.g., "Negatable of --verbose")
+  - `DEFAULT` - Prefix for default values (e.g., "default: 5")
+  - `CHOICES` - Prefix for available choices (e.g., "choices: red, green, blue")
+  - `help` - Description for the help option ("Display this help message")
+  - `version` - Description for the version option ("Display this version")
+
+  Internally, these keys are prefixed with `_:` (e.g., `_:USAGE`, `_:OPTIONS`), but you don't need to use this prefix directly. When overriding built-in translations in your resources, use the key names without the prefix (e.g., providing your own translation for `NEGATABLE`, not `_:NEGATABLE`).
+
+Here's an example illustrating the convention:
+
+```ts
+import { defineI18n } from '@gunshi/plugin-i18n'
+
+const command = defineI18n({
+  name: 'my-command',
+  args: {
+    target: { type: 'string' },
+    verbose: { type: 'boolean' }
+  },
+  resource: async ctx => {
+    // Example for 'en-US' locale
+    return {
+      description: 'This is my command.', // No prefix
+      examples: '$ my-command --target file.txt', // No prefix
+      'arg:target': 'The target file to process.', // 'arg:' prefix
+      'arg:verbose': 'Enable verbose output.', // 'arg:' prefix
+      'arg:no-verbose': 'Disable verbose logging specifically.', // Optional custom translation for the negatable option
+      processing_message: 'Processing target...' // No prefix
+    }
+  },
+  run: ctx => {
+    /* ... */
+  }
+})
+```
+
+Adhering to these conventions ensures that Gunshi correctly identifies and uses your translations for descriptions, help messages, and within your command's logic via `ctx.extensions['g:i18n'].translate()`.
+
+<!-- eslint-disable markdown/no-missing-label-refs -->
+
+> [!IMPORTANT]
+> The resource object returned by the `resource` function (or loaded from external files like JSON) **must** be a flat key-value structure. Nested objects are not supported for translations using `ctx.extensions['g:i18n'].translate()`. Keep your translation keys simple and at the top level.
+
+<!-- eslint-enable markdown/no-missing-label-refs -->
+
+Good Flat structure:
+
+```json
+{
+  "greeting": "Hello",
+  "farewell": "Goodbye"
+}
+```
+
+Bad Nested structure (won't work with `ctx.extensions['g:i18n'].translate('messages.greeting')`):
+
+```json
+{
+  "messages": {
+    "greeting": "Hello",
+    "farewell": "Goodbye"
+  }
+}
+```
+
+## 🔤 Translation Interpolation
+
+The default translation adapter supports simple interpolation using `{$key}` syntax:
+
+```ts
+// In your resource
+const resource = {
+  welcome: 'Welcome, {$name}!',
+  'items.count': 'You have {$count} items',
+  file_deleted: 'Deleted {$path}',
+  error_message: 'Error: {$error}'
+}
+// In your command
+const { translate } = ctx.extensions['g:i18n']
+translate('welcome', { name: 'John' }) // "Welcome, John!"
+translate('items.count', { count: 5 }) // "You have 5 items"
+translate('file_deleted', { path: '/tmp/file.txt' }) // "Deleted /tmp/file.txt"
+translate('error_message', { error: 'File not found' }) // "Error: File not found"
+```
+
+<!-- eslint-disable markdown/no-missing-label-refs -->
+
+> [!NOTE]
+> The default adapter only supports simple string interpolation. For more advanced features like pluralization or formatting, you can provide a custom translation adapter.
+
+<!-- eslint-enable markdown/no-missing-label-refs -->
+
+## 🎨 Custom Translation Adapter
+
+The default translation adapter provides basic string interpolation, but you might want to integrate with more powerful i18n libraries for features like:
+
+- **Pluralization**: Different messages based on count values
+- **Date/Time formatting**: Locale-aware formatting
+- **Number formatting**: Currency, percentages, etc.
+- **Complex interpolation**: Nested values, conditional messages
+- **Message linking**: Reference other translations
+- **Custom formatters**: Domain-specific formatting logic
+
+### Creating a Translation Adapter
+
+To create a custom translation adapter, you need to implement the `TranslationAdapter` interface:
+
+```ts
+interface TranslationAdapter {
+  // Get all resources for a locale
+  getResource(locale: string): Record<string, string> | undefined
+
+  // Set resources for a locale
+  setResource(locale: string, resource: Record<string, string>): void
+
+  // Get a single message
+  getMessage(locale: string, key: string): string | undefined
+
+  // Translate a message with interpolation
+  translate(locale: string, key: string, values?: Record<string, unknown>): string | undefined
+}
+```
+
+The adapter factory receives options with locale information:
+
+```ts
+interface TranslationAdapterFactoryOptions {
+  locale: string // Current locale (BCP 47)
+  fallbackLocale: string // Fallback locale (default: 'en-US')
+}
+```
+
+### How Translation Adapters Work
+
+When you provide a custom translation adapter:
+
+1. **Initialization**: The i18n plugin calls your factory function with locale settings
+2. **Resource Loading**: When a command defines a `resource` function, the plugin:
+   - Calls the resource function to get translations
+   - Passes them to your adapter via `setResource(locale, resource)`
+3. **Translation**: When `translate()` is called:
+   - The plugin delegates to your adapter's `translate()` method
+   - Your adapter handles interpolation and formatting
+   - Returns the translated string or `undefined` if not found
+
+### Custom Case: Integrating with Intlify (Vue I18n Core)
+
+[Intlify](https://github.com/intlify/core) is the core of Intlify (Vue I18n), but it can be used independently. Here's how to create a translation adapter for Intlify:
+
+```ts
+import { cli } from 'gunshi'
+import i18n, { defineI18n } from '@gunshi/plugin-i18n'
+import {
+  createCoreContext,
+  getLocaleMessage,
+  NOT_RESOLVED,
+  setLocaleMessage,
+  translate as intlifyTranslate
+} from '@intlify/core' // need to install `npm install --save @intlify/core@next`
+
+// Create an Intlify translation adapter factory
+function createIntlifyAdapterFactory(options) {
+  return new IntlifyTranslation(options)
+}
+
+class IntlifyTranslation {
+  #options
+  #context
+
+  constructor(options) {
+    this.#options = options
+
+    const { locale, fallbackLocale } = options
+    const messages = {
+      [locale]: {}
+    }
+
+    if (locale !== fallbackLocale) {
+      messages[fallbackLocale] = {}
+    }
+
+    // Create the Intlify core context
+    this.#context = createCoreContext({
+      locale,
+      fallbackLocale,
+      messages
+    })
+  }
+
+  getResource(locale) {
+    return getLocaleMessage(this.#context, locale)
+  }
+
+  setResource(locale, resource) {
+    setLocaleMessage(this.#context, locale, resource)
+  }
+
+  getMessage(locale, key) {
+    const resource = this.getResource(locale)
+    if (resource) {
+      return resource[key]
+    }
+    return
+  }
+
+  translate(locale, key, values = {}) {
+    // Check if the message exists in the specified locale or fallback locale
+    const message =
+      this.getMessage(locale, key) || this.getMessage(this.#options.fallbackLocale, key)
+    if (message === undefined) {
+      return
+    }
+
+    // Use Intlify's translate function
+    const result = intlifyTranslate(this.#context, key, values)
+    return typeof result === 'number' && result === NOT_RESOLVED ? undefined : result
+  }
+}
+
+// Define your command
+const command = defineI18n({
+  name: 'greeter',
+
+  args: {
+    name: {
+      type: 'string',
+      short: 'n'
+    },
+    count: {
+      type: 'number',
+      short: 'c',
+      default: 1
+    }
+  },
+
+  // Define a resource fetcher with Intlify syntax
+  resource: async ctx => {
+    const locale = ctx.extensions['g:i18n'].locale.toString()
+
+    if (locale === 'ja-JP') {
+      return {
+        description: '挨拶アプリケーション',
+        'arg:name': '挨拶する相手の名前',
+        'arg:count': '挨拶の回数',
+        greeting: 'こんにちは、{name}さん！',
+        greeting_plural: 'こんにちは、{name}さん！({count}回目)'
+      }
+    }
+
+    return {
+      description: 'Greeting application',
+      'arg:name': 'Name to greet',
+      'arg:count': 'Number of greetings',
+      greeting: 'Hello, {name}!',
+      greeting_plural: 'Hello, {name}! (greeting #{count})'
+    }
+  },
+
+  run: ctx => {
+    const { name = 'World', count } = ctx.values
+    const { translate } = ctx.extensions['g:i18n']
+
+    // Use the translation function with Intlify
+    const key = count > 1 ? 'greeting_plural' : 'greeting'
+    const message = translate(key, { name, count })
+
+    console.log(message)
+  }
+})
+
+// Run the command with the Intlify translation adapter
+await cli(process.argv.slice(2), command, {
+  name: 'intlify-example',
+  version: '1.0.0',
+  plugins: [
+    i18n({
+      locale: process.env.MY_LOCALE || 'en-US',
+      translationAdapterFactory: createIntlifyAdapterFactory
+    })
+  ]
+})
+```
+
+With Intlify, you get advanced features like:
+
+- Named interpolation: `{name}` instead of `{$name}`
+- Pluralization support
+- Linked messages
+- HTML formatting
+- Custom modifiers
+- And more
+
+<!-- eslint-disable markdown/no-missing-label-refs -->
+
+> [!TIP]
+> Intlify uses `{name}` syntax for interpolation (without the `$` prefix), which is different from Gunshi's default adapter that uses `{$name}`.
+
+<!-- eslint-enable markdown/no-missing-label-refs -->
+
+## 📚 API References
+
+See the [API References](./docs/index.md)
+
+## ©️ License
+
+[MIT](http://opensource.org/licenses/MIT)

package/lib/index.d.ts

@@ -0,0 +1,356 @@
+import { Awaitable, Command, CommandContext, DefaultGunshiParams, ExtractArgs, GunshiParams, GunshiParamsConstraint, NormalizeToGunshiParams, PluginWithExtension } from "@gunshi/plugin";
+
+//#region rolldown:runtime
+
+//#endregion
+//#region ../../node_modules/.pnpm/args-tokens@0.20.1/node_modules/args-tokens/lib/resolver-U72Jg6Ll.d.ts
+//#region src/resolver.d.ts
+
+/**
+* An argument schema
+* This schema is similar to the schema of the `node:utils`.
+* difference is that:
+* - `required` property and `description` property are added
+* - `type` is not only 'string' and 'boolean', but also 'number', 'enum', 'positional', 'custom' too.
+* - `default` property type, not support multiple types
+*/
+interface ArgSchema {
+  /**
+  * Type of argument.
+  */
+  type: "string" | "boolean" | "number" | "enum" | "positional" | "custom";
+  /**
+  * A single character alias for the argument.
+  */
+  short?: string;
+  /**
+  * A description of the argument.
+  */
+  description?: string;
+  /**
+  * Whether the argument is required or not.
+  */
+  required?: true;
+  /**
+  * Whether the argument allow multiple values or not.
+  */
+  multiple?: true;
+  /**
+  * Whether the negatable option for `boolean` type
+  */
+  negatable?: boolean;
+  /**
+  * The allowed values of the argument, and string only. This property is only used when the type is 'enum'.
+  */
+  choices?: string[] | readonly string[];
+  /**
+  * The default value of the argument.
+  * if the type is 'enum', the default value must be one of the allowed values.
+  */
+  default?: string | boolean | number;
+  /**
+  * Whether to convert the argument name to kebab-case.
+  */
+  toKebab?: true;
+  /**
+  * A function to parse the value of the argument. if the type is 'custom', this function is required.
+  * If argument value will be invalid, this function have to throw an error.
+  * @param value
+  * @returns Parsed value
+  * @throws An Error, If the value is invalid. Error type should be `Error` or extends it
+  */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  parse?: (value: string) => any;
+}
+/**
+* An object that contains {@link ArgSchema | argument schema}.
+*/
+interface Args {
+  [option: string]: ArgSchema;
+} //#endregion
+//#region ../shared/src/constants.d.ts
+
+/**
+* An object that contains the values of the arguments.
+*/
+declare namespace constants_d_exports {
+  export { ARG_NEGATABLE_PREFIX, ARG_PREFIX, ARG_PREFIX_AND_KEY_SEPARATOR, BUILD_IN_PREFIX_AND_KEY_SEPARATOR, BUILT_IN_KEY_SEPARATOR, BUILT_IN_PREFIX, COMMAND_BUILTIN_RESOURCE_KEYS, COMMON_ARGS, PLUGIN_PREFIX };
+}
+/**
+ * @author kazuya kawaguchi (a.k.a. kazupon)
+ * @license MIT
+ */
+declare const BUILT_IN_PREFIX = "_";
+declare const PLUGIN_PREFIX = "g";
+declare const ARG_PREFIX = "arg";
+declare const BUILT_IN_KEY_SEPARATOR = ":";
+declare const BUILD_IN_PREFIX_AND_KEY_SEPARATOR: string;
+declare const ARG_PREFIX_AND_KEY_SEPARATOR: string;
+declare const ARG_NEGATABLE_PREFIX = "no-";
+type CommonArgType = {
+  readonly help: {
+    readonly type: 'boolean';
+    readonly short: 'h';
+    readonly description: string;
+  };
+  readonly version: {
+    readonly type: 'boolean';
+    readonly short: 'v';
+    readonly description: string;
+  };
+};
+declare const COMMON_ARGS: CommonArgType;
+declare const COMMAND_BUILTIN_RESOURCE_KEYS: readonly ["USAGE", "COMMAND", "SUBCOMMAND", "COMMANDS", "ARGUMENTS", "OPTIONS", "EXAMPLES", "FORMORE", "NEGATABLE", "DEFAULT", "CHOICES"];
+
+//#endregion
+//#region ../shared/src/types.d.ts
+type RemoveIndexSignature<T> = { [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K] };
+/**
+ * Remove index signature from object or record type.
+ */
+type RemovedIndex<T> = RemoveIndexSignature<{ [K in keyof T]: T[K] }>;
+type KeyOfArgs<A extends Args> = keyof A | { [K in keyof A]: A[K]['type'] extends 'boolean' ? A[K]['negatable'] extends true ? `no-${Extract<K, string>}` : never : never }[keyof A];
+/**
+ * Generate a namespaced key.
+ */
+type GenerateNamespacedKey<Key extends string, Prefixed extends string = typeof BUILT_IN_PREFIX> = `${Prefixed}${typeof BUILT_IN_KEY_SEPARATOR}${Key}`;
+/**
+ * Command i18n built-in arguments keys.
+ */
+type CommandBuiltinArgsKeys = keyof (typeof constants_d_exports)['COMMON_ARGS'];
+/**
+ * Command i18n built-in resource keys.
+ */
+type CommandBuiltinResourceKeys = (typeof constants_d_exports)['COMMAND_BUILTIN_RESOURCE_KEYS'][number];
+/**
+ * i18n built-in resource keys.
+ */
+type BuiltinResourceKeys = CommandBuiltinArgsKeys | CommandBuiltinResourceKeys;
+/**
+ * Command i18n built-in keys.
+ * The command i18n built-in keys are used by the i18n plugin for translation.
+ */
+type CommandBuiltinKeys = GenerateNamespacedKey<BuiltinResourceKeys> | 'description' | 'examples';
+/**
+ * Command i18n option keys.
+ * The command i18n option keys are used by the i18n plugin for translation.
+ */
+type CommandArgKeys<A extends Args> = GenerateNamespacedKey<KeyOfArgs<RemovedIndex<A>>, typeof ARG_PREFIX>;
+
+//#endregion
+//#region src/types.d.ts
+/**
+ * The unique identifier for the i18n plugin.
+ */
+declare const pluginId: GenerateNamespacedKey<'i18n', typeof PLUGIN_PREFIX>;
+/**
+ * Type representing the unique identifier for i18n plugin.
+ */
+type PluginId = typeof pluginId;
+/**
+ * Extended command context which provides utilities via i18n plugin.
+ * These utilities are available via `CommandContext.extensions['g:i18n']`.
+ */
+interface I18nCommandContext<G extends GunshiParams<any> = DefaultGunshiParams> {
+  /**
+   * Command locale
+   */
+  locale: string | Intl.Locale;
+  /**
+   * Translate a message
+   * @param key Translation key
+   * @param values Values to interpolate
+   * @returns Translated message. If the key is not found:
+   *   - For custom keys: returns an empty string ('')
+   *   - For built-in keys (prefixed with '_:'): returns the key itself
+   */
+  translate: <T extends string = CommandBuiltinKeys, O = CommandArgKeys<G['args']>, K = CommandBuiltinKeys | O | T>(key: K, values?: Record<string, unknown>) => string;
+}
+/**
+ * i18n plugin options
+ */
+interface I18nPluginOptions {
+  /**
+   * Locale to use for translations
+   */
+  locale?: string | Intl.Locale;
+  /**
+   * Translation adapter factory
+   */
+  translationAdapterFactory?: TranslationAdapterFactory;
+  /**
+   * Built-in localizable resources
+   */
+  resources?: Record<string, Record<BuiltinResourceKeys, string>>;
+}
+/**
+ * Translation adapter factory.
+ */
+type TranslationAdapterFactory = (options: TranslationAdapterFactoryOptions) => TranslationAdapter;
+/**
+ * Translation adapter factory options.
+ */
+interface TranslationAdapterFactoryOptions {
+  /**
+   * A locale (BCP 47 language tag).
+   */
+  locale: string;
+  /**
+   * A fallback locale.
+   * @default DEFAULT_LOCALE ('en-US')
+   */
+  fallbackLocale: string;
+}
+/**
+ * Translation adapter.
+ * This adapter is used to custom message formatter like {@link https://github.com/intlify/vue-i18n/blob/master/spec/syntax.ebnf | Intlify message format}, {@link https://github.com/tc39/proposal-intl-messageformat | `Intl.MessageFormat` (MF2)}, and etc.
+ * This adapter will support localization with your preferred message format.
+ */
+interface TranslationAdapter<MessageResource = string> {
+  /**
+   * Get a resource of locale.
+   * @param locale A Locale at the time of command execution. That is Unicord locale ID (BCP 47)
+   * @returns A resource of locale. if resource not found, return `undefined`.
+   */
+  getResource(locale: string): Record<string, string> | undefined;
+  /**
+   * Set a resource of locale.
+   * @param locale A Locale at the time of command execution. That is Unicord locale ID (BCP 47)
+   * @param resource A resource of locale
+   */
+  setResource(locale: string, resource: Record<string, string>): void;
+  /**
+   * Get a message of locale.
+   * @param locale A Locale at the time of command execution. That is Unicord locale ID (BCP 47)
+   * @param key A key of message resource
+   * @returns A message of locale. if message not found, return `undefined`.
+   */
+  getMessage(locale: string, key: string): MessageResource | undefined;
+  /**
+   * Translate a message.
+   * @param locale A Locale at the time of command execution. That is Unicord locale ID (BCP 47)
+   * @param key A key of message resource
+   * @param values A values to be resolved in the message
+   * @returns A translated message, if message is not translated, return `undefined`.
+   */
+  translate(locale: string, key: string, values?: Record<string, unknown>): string | undefined;
+}
+/**
+ * Command resource type for i18n plugin.
+ */
+type CommandResource<G extends GunshiParamsConstraint = DefaultGunshiParams> = {
+  /**
+   * Command description.
+   */
+  description: string;
+  /**
+   * Examples usage.
+   */
+  examples: string | CommandExamplesFetcher<NormalizeToGunshiParams<G>>;
+} & { [Arg in GenerateNamespacedKey<KeyOfArgs<RemovedIndex<ExtractArgs<G>>>, typeof ARG_PREFIX>]: string } & {
+  [key: string]: string;
+};
+/**
+ * Command examples fetcher.
+ * @param ctx A {@link CommandContext | command context}
+ * @returns A fetched command examples.
+ */
+type CommandExamplesFetcher<G extends GunshiParamsConstraint = DefaultGunshiParams> = (ctx: Readonly<CommandContext<G>>) => Awaitable<string>;
+/**
+ * Command resource fetcher.
+ * @param ctx A {@link CommandContext | command context}
+ * @returns A fetched {@link CommandResource | command resource}.
+ */
+type CommandResourceFetcher<G extends GunshiParamsConstraint = DefaultGunshiParams> = (ctx: Readonly<CommandContext<G>>) => Awaitable<CommandResource<G>>;
+/**
+ * I18n-aware command interface that extends the base Command with resource support
+ */
+interface I18nCommand<G extends GunshiParamsConstraint = DefaultGunshiParams> extends Command<G> {
+  /**
+   * Command resource fetcher for i18n support.
+   * This property is specific to i18n-enabled commands.
+   */
+  resource?: CommandResourceFetcher<G>;
+}
+
+//#endregion
+//#region src/helpers.d.ts
+/**
+ * Define an i18n-aware command with type safety
+ *
+ * @example
+ * ```ts
+ * import { defineI18n } from '@gunshi/plugin-i18n'
+ *
+ * const greetCommand = defineI18n({
+ *   name: 'greet',
+ *   args: {
+ *     name: { type: 'string', description: 'Name to greet' }
+ *   },
+ *   resource: async (ctx) => ({
+ *     description: 'Greet someone',
+ *     'arg:name': 'The name to greet'
+ *   }),
+ *   run: async (ctx) => {
+ *     console.log(`Hello, ${ctx.values.name}!`)
+ *   }
+ * })
+ * ```
+ */
+declare function defineI18n<G extends GunshiParamsConstraint = DefaultGunshiParams>(command: Command<G> & {
+  resource?: CommandResourceFetcher<G>;
+}): I18nCommand<G>;
+/**
+ * Add i18n resource to an existing command
+ *
+ * @example
+ * ```ts
+ * import { define } from '@gunshi/definition'
+ * import { withI18nResource } from '@gunshi/plugin-i18n'
+ *
+ * const myCommand = define({
+ *   name: 'myCommand',
+ *   args: {
+ *     input: { type: 'string', description: 'Input value' }
+ *   },
+ *   run: async (ctx) => {
+ *     console.log(`Input: ${ctx.values.input}`)
+ *   }
+ * })
+ *
+ * const i18nCommand = withI18nResource(basicCommand, async ctx => {
+ *   const resource = await import(
+ *     `./path/to/resources/test/${ctx.extensions['g:i18n'].locale.toString()}.json`,
+ *     { with: { type: 'json' } }
+ *   ).then(l => l.default || l)
+ *   return resource
+ * })
+ * ```
+ */
+declare function withI18nResource<G extends GunshiParamsConstraint>(command: Command<G>, resource: CommandResourceFetcher<G>): I18nCommand<G>;
+
+//#endregion
+//#region src/translation.d.ts
+declare function createTranslationAdapter(options: TranslationAdapterFactoryOptions): TranslationAdapter;
+declare class DefaultTranslation implements TranslationAdapter {
+  #private;
+  constructor(options: TranslationAdapterFactoryOptions);
+  getResource(locale: string): Record<string, string> | undefined;
+  setResource(locale: string, resource: Record<string, string>): void;
+  getMessage(locale: string, key: string): string | undefined;
+  translate(locale: string, key: string, values?: Record<string, unknown>): string | undefined;
+}
+
+//#endregion
+//#region src/index.d.ts
+/**
+ * The default locale string, which format is BCP 47 language tag.
+ */
+declare const DEFAULT_LOCALE = "en-US";
+/**
+ * i18n plugin
+ */
+declare function i18n(options?: I18nPluginOptions): PluginWithExtension<Promise<I18nCommandContext<DefaultGunshiParams>>>;
+
+//#endregion
+export { CommandExamplesFetcher, CommandResource, CommandResourceFetcher, DEFAULT_LOCALE, DefaultTranslation, I18nCommand, I18nCommandContext, I18nPluginOptions, PluginId, TranslationAdapter, TranslationAdapterFactory, TranslationAdapterFactoryOptions, createTranslationAdapter, i18n as default, defineI18n, pluginId, withI18nResource };

package/lib/index.js

@@ -0,0 +1,261 @@
+import { plugin } from "@gunshi/plugin";
+
+//#region ../shared/src/constants.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+const BUILT_IN_PREFIX = "_";
+const PLUGIN_PREFIX = "g";
+const ARG_PREFIX = "arg";
+const BUILT_IN_KEY_SEPARATOR = ":";
+const BUILD_IN_PREFIX_AND_KEY_SEPARATOR = `${BUILT_IN_PREFIX}${BUILT_IN_KEY_SEPARATOR}`;
+const ARG_PREFIX_AND_KEY_SEPARATOR = `${ARG_PREFIX}${BUILT_IN_KEY_SEPARATOR}`;
+
+//#endregion
+//#region ../resources/locales/en-US.json
+var COMMAND = "COMMAND";
+var COMMANDS = "COMMANDS";
+var SUBCOMMAND = "SUBCOMMAND";
+var USAGE = "USAGE";
+var ARGUMENTS = "ARGUMENTS";
+var OPTIONS = "OPTIONS";
+var EXAMPLES = "EXAMPLES";
+var FORMORE = "For more info, run any command with the `--help` flag";
+var NEGATABLE = "Negatable of";
+var DEFAULT = "default";
+var CHOICES = "choices";
+var help = "Display this help message";
+var version = "Display this version";
+var en_US_default = {
+	COMMAND,
+	COMMANDS,
+	SUBCOMMAND,
+	USAGE,
+	ARGUMENTS,
+	OPTIONS,
+	EXAMPLES,
+	FORMORE,
+	NEGATABLE,
+	DEFAULT,
+	CHOICES,
+	help,
+	version
+};
+
+//#endregion
+//#region ../shared/src/utils.ts
+function resolveBuiltInKey(key) {
+	return `${BUILT_IN_PREFIX}${BUILT_IN_KEY_SEPARATOR}${key}`;
+}
+function resolveArgKey(key) {
+	return `${ARG_PREFIX}${BUILT_IN_KEY_SEPARATOR}${key}`;
+}
+function namespacedId(id) {
+	return `${PLUGIN_PREFIX}${BUILT_IN_KEY_SEPARATOR}${id}`;
+}
+
+//#endregion
+//#region src/translation.ts
+function createTranslationAdapter(options) {
+	return new DefaultTranslation(options);
+}
+var DefaultTranslation = class {
+	#resources = new Map();
+	#options;
+	constructor(options) {
+		this.#options = options;
+		this.#resources.set(options.locale, Object.create(null));
+		if (options.locale !== options.fallbackLocale) this.#resources.set(options.fallbackLocale, Object.create(null));
+	}
+	getResource(locale) {
+		return this.#resources.get(locale);
+	}
+	setResource(locale, resource) {
+		this.#resources.set(locale, resource);
+	}
+	getMessage(locale, key) {
+		const resource = this.getResource(locale);
+		if (resource) return resource[key];
+		return void 0;
+	}
+	translate(locale, key, values = Object.create(null)) {
+		let message = this.getMessage(locale, key);
+		if (message === void 0 && locale !== this.#options.fallbackLocale) message = this.getMessage(this.#options.fallbackLocale, key);
+		if (message === void 0) return;
+		return message.replaceAll(/\{\$(\w+)\}/g, (_, name) => {
+			return values[name] == null ? "" : values[name].toString();
+		});
+	}
+};
+
+//#endregion
+//#region src/types.ts
+/**
+* The unique identifier for the i18n plugin.
+*/
+const pluginId = namespacedId("i18n");
+
+//#endregion
+//#region src/helpers.ts
+/**
+* Define an i18n-aware command with type safety
+*
+* @example
+* ```ts
+* import { defineI18n } from '@gunshi/plugin-i18n'
+*
+* const greetCommand = defineI18n({
+*   name: 'greet',
+*   args: {
+*     name: { type: 'string', description: 'Name to greet' }
+*   },
+*   resource: async (ctx) => ({
+*     description: 'Greet someone',
+*     'arg:name': 'The name to greet'
+*   }),
+*   run: async (ctx) => {
+*     console.log(`Hello, ${ctx.values.name}!`)
+*   }
+* })
+* ```
+*/
+function defineI18n(command) {
+	return command;
+}
+/**
+* Add i18n resource to an existing command
+*
+* @example
+* ```ts
+* import { define } from '@gunshi/definition'
+* import { withI18nResource } from '@gunshi/plugin-i18n'
+*
+* const myCommand = define({
+*   name: 'myCommand',
+*   args: {
+*     input: { type: 'string', description: 'Input value' }
+*   },
+*   run: async (ctx) => {
+*     console.log(`Input: ${ctx.values.input}`)
+*   }
+* })
+*
+* const i18nCommand = withI18nResource(basicCommand, async ctx => {
+*   const resource = await import(
+*     `./path/to/resources/test/${ctx.extensions['g:i18n'].locale.toString()}.json`,
+*     { with: { type: 'json' } }
+*   ).then(l => l.default || l)
+*   return resource
+* })
+* ```
+*/
+function withI18nResource(command, resource) {
+	return {
+		...command,
+		resource
+	};
+}
+
+//#endregion
+//#region src/index.ts
+/**
+* The default locale string, which format is BCP 47 language tag.
+*/
+const DEFAULT_LOCALE = "en-US";
+const BUILT_IN_PREFIX_CODE = BUILT_IN_PREFIX.codePointAt(0);
+/**
+* i18n plugin
+*/
+function i18n(options = {}) {
+	const locale = toLocale(options.locale);
+	const localeStr = locale.toString();
+	const resources = options.resources || Object.create(null);
+	const translationAdapterFactory = options.translationAdapterFactory || createTranslationAdapter;
+	const adapter = translationAdapterFactory({
+		locale: localeStr,
+		fallbackLocale: DEFAULT_LOCALE
+	});
+	const localeBuiltinResources = new Map();
+	let builtInLoadedResources;
+	return plugin({
+		id: pluginId,
+		name: "internationalization",
+		dependencies: [{
+			id: namespacedId("global"),
+			optional: true
+		}],
+		extension: async () => {
+			function translate(key, values = Object.create(null)) {
+				const strKey = key;
+				if (strKey.codePointAt(0) === BUILT_IN_PREFIX_CODE) {
+					const resource = localeBuiltinResources.get(localeStr) || localeBuiltinResources.get(DEFAULT_LOCALE);
+					return resource[strKey] || strKey;
+				} else return adapter.translate(localeStr, strKey, values) || "";
+			}
+			function getResource(locale$1) {
+				const targetLocale = toLocale(locale$1);
+				const targetLocaleStr = targetLocale.toString();
+				return localeBuiltinResources.get(targetLocaleStr);
+			}
+			function setResource(locale$1, resource) {
+				const targetLocale = toLocale(locale$1);
+				const targetLocaleStr = targetLocale.toString();
+				if (localeBuiltinResources.has(targetLocaleStr)) return;
+				localeBuiltinResources.set(targetLocale.toString(), mapResourceWithBuiltinKey(resource));
+			}
+			setResource(DEFAULT_LOCALE, en_US_default);
+			for (const [locale$1, resource] of Object.entries(resources)) setResource(locale$1, resource);
+			builtInLoadedResources = getResource(locale);
+			return {
+				locale,
+				translate
+			};
+		},
+		onExtension: async (ctx, cmd) => {
+			/**
+			* load command resources, after the command context is extended
+			*/
+			const loadedOptionsResources = Object.entries(ctx.args).map(([key, schema]) => [key, schema.description || ""]);
+			const defaultCommandResource = loadedOptionsResources.reduce((res, [key, value]) => {
+				res[resolveArgKey(key)] = value;
+				return res;
+			}, Object.create(null));
+			defaultCommandResource.description = cmd.description || "";
+			defaultCommandResource.examples = typeof cmd.examples === "string" ? cmd.examples : typeof cmd.examples === "function" ? await cmd.examples(ctx) : "";
+			adapter.setResource(DEFAULT_LOCALE, defaultCommandResource);
+			const originalResource = await loadCommandResource(ctx, cmd);
+			if (originalResource) {
+				const resource = Object.assign(Object.create(null), originalResource, { examples: typeof originalResource.examples === "string" ? originalResource.examples : typeof originalResource.examples === "function" ? await originalResource.examples(ctx) : "" });
+				if (builtInLoadedResources) {
+					resource.help = builtInLoadedResources.help;
+					resource.version = builtInLoadedResources.version;
+				}
+				adapter.setResource(localeStr, resource);
+			}
+		}
+	});
+}
+function toLocale(locale) {
+	return locale instanceof Intl.Locale ? locale : typeof locale === "string" ? new Intl.Locale(locale) : new Intl.Locale(DEFAULT_LOCALE);
+}
+async function loadCommandResource(ctx, command) {
+	if (!hasI18nResource(command)) return void 0;
+	let resource;
+	try {
+		resource = await command.resource(ctx);
+	} catch {}
+	return resource;
+}
+function mapResourceWithBuiltinKey(resource) {
+	return Object.entries(resource).reduce((acc, [key, value]) => {
+		acc[resolveBuiltInKey(key)] = value;
+		return acc;
+	}, Object.create(null));
+}
+function hasI18nResource(command) {
+	return "resource" in command && typeof command.resource === "function";
+}
+
+//#endregion
+export { DEFAULT_LOCALE, DefaultTranslation, createTranslationAdapter, i18n as default, defineI18n, pluginId, withI18nResource };

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@gunshi/plugin-i18n",
+  "description": "internationalization plugin for gunshi",
+  "version": "0.26.3",
+  "author": {
+    "name": "kazuya kawaguchi",
+    "email": "kawakazu80@gmail.com"
+  },
+  "license": "MIT",
+  "funding": "https://github.com/sponsors/kazupon",
+  "bugs": {
+    "url": "https://github.com/kazupon/gunshi/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kazupon/gunshi.git",
+    "directory": "packages/plugin-i18n"
+  },
+  "keywords": [
+    "gunshi",
+    "i18n",
+    "internationalization",
+    "plugin",
+    "cli"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">= 20"
+  },
+  "type": "module",
+  "files": [
+    "lib"
+  ],
+  "module": "lib/index.js",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js",
+      "require": "./lib/index.js",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "lib/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "*": [
+        "./lib/*",
+        "./*"
+      ]
+    }
+  },
+  "dependencies": {
+    "@gunshi/plugin": "0.26.3"
+  },
+  "peerDependencies": {
+    "@gunshi/plugin-global": "0.26.3"
+  },
+  "peerDependenciesMeta": {
+    "@gunshi/plugin-global": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@intlify/core": "next",
+    "deno": "^2.3.3",
+    "jsr": "^0.13.4",
+    "jsr-exports-lint": "^0.4.1",
+    "messageformat": "4.0.0-12",
+    "publint": "^0.3.12",
+    "tsdown": "^0.12.3",
+    "typedoc": "^0.28.4",
+    "typedoc-plugin-markdown": "^4.6.3",
+    "@gunshi/shared": "0.26.3",
+    "@gunshi/resources": "0.26.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "build:docs": "typedoc --excludeInternal",
+    "lint:jsr": "jsr publish --dry-run --allow-dirty",
+    "typecheck:deno": "deno check --import-map=../../importmap.json ./src"
+  }
+}