feat(plugin-i18n): registerGlobalOptionResources extension

e2e/fixture/advanced/internationalization/loading/english-help.snap

@@ -4,8 +4,8 @@ USAGE:
   i18n-example <OPTIONS>
 
 OPTIONS:
-  -h, --help
-  -v, --version
+  -h, --help                 Display this help message
+  -v, --version              Display this version
   -n, --name <name>          Name to greet
   -f, --formal               Use formal greeting
 

e2e/fixture/advanced/internationalization/loading/japanese-help.snap

@@ -4,8 +4,8 @@ i18n-example (i18n-example v1.0.0)
   i18n-example <オプション>
 
 オプション:
-  -h, --help                 Display this help message
-  -v, --version              Display this version
+  -h, --help                 このヘルプメッセージを表示
+  -v, --version              このバージョンを表示
   -n, --name <name>          挨拶する相手の名前
   -f, --formal               丁寧な挨拶を使用する
 

e2e/fixture/advanced/internationalization/sub-command/english-create-help.snap

@@ -6,7 +6,7 @@ USAGE:
   resource-cli create <OPTIONS>
 
 OPTIONS:
-  -h, --help
-  -v, --version
+  -h, --help             Display this help message
+  -v, --version          Display this version
   --name <name>          Resource name
 

e2e/fixture/advanced/internationalization/sub-command/english-help.snap

@@ -12,6 +12,6 @@ For more info, run any command with the `--help` flag:
   resource-cli create --help
 
 OPTIONS:
-  -h, --help
-  -v, --version
+  -h, --help             Display this help message
+  -v, --version          Display this version
 

e2e/fixture/advanced/internationalization/sub-command/japanese-create-help.snap

@@ -6,7 +6,7 @@ resource-cli (resource-cli v1.0.0)
   resource-cli create <オプション>
 
 オプション:
-  -h, --help             Display this help message
-  -v, --version          Display this version
+  -h, --help             このヘルプメッセージを表示
+  -v, --version          このバージョンを表示
   --name <name>          リソース名
 

e2e/fixture/advanced/internationalization/sub-command/japanese-help.snap

@@ -12,6 +12,6 @@ resource-cli (resource-cli v1.0.0)
   resource-cli create --help
 
 オプション:
-  -h, --help             Display this help message
-  -v, --version          Display this version
+  -h, --help             このヘルプメッセージを表示
+  -v, --version          このバージョンを表示
 

knip.config.ts

@@ -12,6 +12,9 @@ export default {
     'packages/plugin-completion': {
       ignore: ['examples/**/*.ts', 'src/bombshell/*.ts']
     },
+    'packages/plugin-i18n': {
+      ignoreDependencies: ['@gunshi/plugin-global']
+    },
     'packages/docs': {
       entry: ['src/.vitepress/config.ts', 'src/.vitepress/theme/index.ts']
     }

packages/docs/src/guide/plugin/guidelines.md

@@ -56,8 +56,8 @@ export const pluginId = 'g:i18n' as const
 Follow consistent naming for plugin packages:
 
 - Standalone packages: `gunshi-plugin-{feature}`
-- Scoped packages: `@{org}/gunshi-plugin-{feature}`
-- Example: `gunshi-plugin-logger`, `@mycompany/gunshi-plugin-auth`
+- Scoped packages: `@{org}/gunshi-plugin-{feature}` or `@{org}/gunshi-plugin`
+- Example: `gunshi-plugin-logger`, `@mycompany/gunshi-plugin-auth`, `@feature/gunshi/plugin`
 
 > [!NOTE]
 > Packages following the pattern `@gunshi/plugin-{feature}` (e.g., `@gunshi/plugin-i18n`) are official plugins maintained by the Gunshi team. These are not third-party plugins but are part of the official Gunshi ecosystem. Third-party developers should use their own organization scope or standalone naming as described above.

packages/gunshi/src/__snapshots__/cli.test.ts.snap

@@ -292,8 +292,8 @@ exports[`auto generate usage > strictly sub commands > console output 1`] = `
     gunshi command2 --help
 
 オプション:
-    -h, --help                    Display this help message
-    -v, --version                 Display this version
+    -h, --help                    このヘルプメッセージを表示
+    -v, --version                 このバージョンを表示
     -f, --foo <foo>               The foo option
 
 例:
@@ -354,8 +354,8 @@ exports[`auto generate usage > strictly sub commands > entry 1`] = `
     gunshi command2 --help
 
 オプション:
-    -h, --help                    Display this help message
-    -v, --version                 Display this version
+    -h, --help                    このヘルプメッセージを表示
+    -v, --version                 このバージョンを表示
     -f, --foo <foo>               The foo option
 
 例:

packages/gunshi/src/types.ts

@@ -432,8 +432,8 @@ export interface CommandContext<G extends GunshiParamsConstraint = DefaultGunshi
    *
    * If {@linkcode CommandEnvironment.usageSilent} is true, the message is not output.
    *
-   * @param message - an output message, @see {@linkcode console.log}
-   * @param optionalParams - an optional parameters, @see {@linkcode console.log}
+   * @param message - an output message, see {@linkcode console.log}
+   * @param optionalParams - an optional parameters, see {@linkcode console.log}
    */
   log: (message?: any, ...optionalParams: any[]) => void // eslint-disable-line @typescript-eslint/no-explicit-any -- NOTE(kazupon): generic optional parameters
   /**

packages/plugin-i18n/README.md

@@ -340,6 +340,7 @@ Available extensions:
 - `locale: Intl.Locale`: The current locale
 - `translate<T>(key: T, values?: Record<string, unknown>): string`: Translation function
 - `loadResource(locale: string | Intl.Locale, ctx: CommandContext, command: Command): Promise<boolean>`: Manually load resources for a specific locale and command
+- `registerGlobalOptionResources: (option: string, resources: Record<string, string>) => void`: Register global option resources. If your global option description needs the localization, you can install resource of it at `extension` or `onExtension` hook
 
 ## 📝 Resource Key Naming Conventions
 

packages/plugin-i18n/package.json

@@ -71,6 +71,9 @@
     }
   },
   "devDependencies": {
+    "@gunshi/bone": "workspace:*",
+    "@gunshi/plugin-global": "workspace:*",
+    "@gunshi/plugin-renderer": "workspace:*",
     "@gunshi/resources": "workspace:*",
     "@gunshi/shared": "workspace:*",
     "@intlify/core": "next",

packages/plugin-i18n/src/index.test.ts

@@ -1,3 +1,8 @@
+import { cli } from '@gunshi/bone'
+import { plugin } from '@gunshi/plugin'
+import globals from '@gunshi/plugin-global'
+import renderer from '@gunshi/plugin-renderer'
+import resources from '@gunshi/resources'
 import { namespacedId, resolveArgKey, resolveBuiltInKey, resolveKey } from '@gunshi/shared'
 import { MessageFormat } from 'messageformat'
 import { afterEach, describe, expect, test, vi } from 'vitest'
@@ -6,13 +11,14 @@ import {
   createTranslationAdapterForIntlifyMessageFormat,
   createTranslationAdapterForMessageFormat2
 } from '../test/helper.ts'
-import i18n, { defineI18n } from './index.ts'
+import i18n, { defineI18n, pluginId } from './index.ts'
 
 import type { Args, Command, GunshiParams } from '@gunshi/plugin'
 import type {
   CommandResource,
   CommandResourceFetcher,
   I18nExtension,
+  PluginId,
   TranslationAdapter
 } from './types.ts'
 
@@ -60,8 +66,6 @@ describe('extension: translate', () => {
         'For more info, run any command with the `--help` flag'
       )
       expect(extension.translate(resolveBuiltInKey('NEGATABLE'))).toEqual('Negatable of')
-      expect(extension.translate(resolveBuiltInKey('help'))).toEqual('Display this help message')
-      expect(extension.translate(resolveBuiltInKey('version'))).toEqual('Display this version')
     })
 
     test('custom locale: ja-JP', async () => {
@@ -85,8 +89,6 @@ describe('extension: translate', () => {
         '詳細は、コマンドと`--help`フラグを実行してください'
       )
       expect(extension.translate(resolveBuiltInKey('NEGATABLE'))).toEqual('否定可能な')
-      expect(extension.translate(resolveBuiltInKey('help'))).toEqual('このヘルプメッセージを表示')
-      expect(extension.translate(resolveBuiltInKey('version'))).toEqual('このバージョンを表示')
     })
   })
 
@@ -136,6 +138,57 @@ describe('extension: translate', () => {
   })
 })
 
+describe('extension: registerGlobalOptionResources', () => {
+  test('register and translate global option resources', async () => {
+    const debugDescriptionEn = 'Enable debug mode'
+    const debugDescriptionJa = 'デバッグモードを有効にする'
+
+    const id = 'debug'
+    const dependencies = [
+      {
+        id: pluginId,
+        optional: true
+      }
+    ] as const
+    const debug = plugin<Record<PluginId, I18nExtension>, typeof id, typeof dependencies>({
+      id,
+      dependencies,
+      setup: async ctx => {
+        ctx.addGlobalOption('debug', {
+          type: 'boolean',
+          description: debugDescriptionEn
+        })
+      },
+      onExtension: ctx => {
+        const i18n = ctx.extensions[pluginId]
+        i18n?.registerGlobalOptionResources('debug', {
+          'en-US': debugDescriptionEn,
+          'ja-JP': debugDescriptionJa
+        })
+      }
+    })
+
+    function entry() {}
+
+    const outputEn = await cli(['-h'], entry, {
+      usageSilent: true,
+      plugins: [i18n({ builtinResources: resources }), debug, renderer(), globals()]
+    })
+    expect(outputEn).toContain(debugDescriptionEn)
+
+    const outputJa = await cli(['-h'], entry, {
+      usageSilent: true,
+      plugins: [
+        i18n({ locale: 'ja-JP', builtinResources: resources }),
+        debug,
+        renderer(),
+        globals()
+      ]
+    })
+    expect(outputJa).toContain(debugDescriptionJa)
+  })
+})
+
 describe('translation adapter', () => {
   test('Intl.MessageFormat (MF2)', async () => {
     const args = {