Skip to content

i18n(ja): update reference file plugins.md #3709

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Yusaku01 wants to merge 3 commits into from
Closed

i18n(ja): update reference file plugins.md #3709

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
40de38e
i18n(ja): update reference file `plugins.md` to match to en doc
Yusaku01 Feb 12, 2026
c57e637
fix: some sentences and expression
Yusaku01 Feb 13, 2026
7c2a6ca
fix: missed translations and improve translation content
Yusaku01 Feb 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
232 changes: 217 additions & 15 deletions docs/src/content/docs/ja/reference/plugins.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,28 +7,38 @@ tableOfContents:

Starlightのプラグインにより、Starlightの設定、UI、および動作をカスタマイズできます。このリファレンスページでは、プラグインがアクセス可能なAPIについて説明します。

Starlightのプラグインを使用する方法について、詳しくは[設定方法のリファレンス](/ja/reference/configuration/#plugins)を参照してください。また、利用可能なプラグインの一覧については、[プラグインショーケース](/ja/resources/plugins/)を確認してください。
Starlightのプラグインを使用する方法について、詳しくは[設定方法のリファレンス](/ja/reference/configuration/#plugins)を参照してください。また、利用可能なプラグインの一覧については、[プラグインショーケース](/ja/resources/plugins/#プラグイン)を確認してください。

## API早見表

Starlightのプラグインは次の構造をもちます。各プロパティとフックパラメータの詳細については、以下を参照してください。

<!-- prettier-ignore-start -->
```ts
interface StarlightPlugin {
name: string;
hooks: {
setup: (options: {
'i18n:setup'?: (options: {
injectTranslations: (
translations: Record<string, Record<string, string>>
) => void;
}) => void | Promise<void>;
'config:setup': (options: {
config: StarlightUserConfig;
updateConfig: (newConfig: StarlightUserConfig) => void;
addIntegration: (integration: AstroIntegration) => void;
addRouteMiddleware: (config: { entrypoint: string; order?: 'pre' | 'post' | 'default' }) => void;
astroConfig: AstroConfig;
command: 'dev' | 'build' | 'preview';
isRestart: boolean;
logger: AstroIntegrationLogger;
useTranslations: (lang: string) => I18nT;
absolutePathToLang: (path: string) => string;
}) => void | Promise<void>;
};
}
```
<!-- prettier-ignore-end -->

## `name`

Expand All @@ -38,11 +48,94 @@ interface StarlightPlugin {

## `hooks`

フックは、Starlightが特定のタイミングでプラグインコードを実行するために呼び出す関数です。現在、Starlightは`setup`フックのみサポートしています。
フックは、Starlightが特定のタイミングでプラグインコードを実行するために呼び出す関数です。

フックの引数の型を取得するには、`HookParameters`ユーティリティ型を使用し、フック名を渡します。以下の例では、`options`パラメータは`config:setup`フックに渡される引数に一致するように型付けされています。

```ts
import type { HookParameters } from '@astrojs/starlight/types';

function configSetup(options: HookParameters['config:setup']) {
options.useTranslations('en');
}
```

### `i18n:setup`

Starlightが初期化されるときに呼び出される、プラグインの国際化向けのセットアップ関数です。`i18n:setup`フックは、プラグインがさまざまなロケールをサポートできるように翻訳文字列を登録するために使用できます。これらの翻訳は、`config:setup`フックの[`useTranslations()`](#usetranslations)や、UIコンポーネントの[`Astro.locals.t()`](/ja/guides/i18n/#ui翻訳を使用する)を通じて利用できます。

`i18n:setup`フックは、以下のオプションとともに呼び出されます。

#### `injectTranslations`

**type:** `(translations: Record<string, Record<string, string>>) => void`

Starlightの[ローカライズAPI](/ja/guides/i18n/#ui翻訳を使用する)で使用される翻訳文字列を追加または更新するためのコールバック関数です。

以下の例では、プラグインが`en`と`fr`ロケールの`myPlugin.doThing`というカスタムUI文字列の翻訳を登録しています。

```ts {6-13} /(injectTranslations)[^(]/
// plugin.ts
export default {
name: 'plugin-with-translations',
hooks: {
'i18n:setup'({ injectTranslations }) {
injectTranslations({
en: {
'myPlugin.doThing': 'Do the thing',
},
fr: {
'myPlugin.doThing': 'Faire le truc',
},
});
},
},
};
```

登録した翻訳をプラグインUIで使用するには、[“UI翻訳の使用“ガイド](/ja/guides/i18n/#ui翻訳を使用する)に従ってください。プラグインの[`config:setup`](#configsetup)フックのコンテキストでUI文字列を使用する必要がある場合は、[`useTranslations()`](#usetranslations)コールバックを使用できます。

プラグインが登録する翻訳文字列の型は、ユーザーのプロジェクトで自動的に生成されますが、プラグインのコードベースで作業中はまだ利用できません。プラグインのコンテキストで`locals.t`オブジェクトを型付けするには、TypeScript宣言ファイルで以下のグローバル名前空間を宣言します。

### `hooks.setup`
```ts
// env.d.ts
declare namespace App {
type StarlightLocals = import('@astrojs/starlight').StarlightLocals;
// プラグインのコンテキストで`locals.t`オブジェクトを定義します。
interface Locals extends StarlightLocals {}
}

declare namespace StarlightApp {
// `I18n`インターフェースにプラグインの追加の翻訳を定義します。
interface I18n {
'myPlugin.doThing': string;
}
}
```

プラグインのセットアップ関数は、Starlightが（[`astro:config:setup`](https://docs.astro.build/ja/reference/integrations-reference/#astroconfigsetup)インテグレーションフックにおいて）初期化される際に呼び出されます。`setup`フックは、Starlightの設定を更新したり、Astroのインテグレーションを追加したりするために使用できます。
翻訳を含むオブジェクトがあるソースファイルから、`StarlightApp.I18n`インターフェースの型を推論することもできます。

たとえば、以下のソースファイルがあるとします。

```ts title="ui-strings.ts"
export const UIStrings = {
en: { 'myPlugin.doThing': 'Do the thing' },
fr: { 'myPlugin.doThing': 'Faire le truc' },
};
```

以下の宣言は、ソースファイルの英語キーから型を推論します。

```ts title="env.d.ts"
declare namespace StarlightApp {
type UIStrings = typeof import('./ui-strings').UIStrings.en;
interface I18n extends UIStrings {}
}
```

### `config:setup`

プラグインの設定セットアップ関数は、Starlightが初期化される際に呼び出されます（[`astro:config:setup`](https://docs.astro.build/ja/reference/integrations-reference/#astroconfigsetup)インテグレーションフック内）。`config:setup`フックは、Starlightの設定を更新したり、Astroのインテグレーションを追加したりするために使用できます。

このフックは、以下のオプションとともに呼び出されます。

Expand All @@ -58,19 +151,23 @@ interface StarlightPlugin {

ユーザーが提供した[Starlightの設定](/ja/reference/configuration/)を更新するためのコールバック関数です。上書きしたいルートレベルの設定キーを指定します。ネストされた設定値を更新するには、ネストされたオブジェクトの全体を指定する必要があります。

既存の設定オプションをオーバーライドせず拡張するには、既存の値を新しい値へと展開します。以下の例では、`config.social`を新しい`social`オブジェクトに展開し、既存の設定に新しい[`social`](/ja/reference/configuration/#social)メディアアカウントを追加しています。
既存の設定オプションをオーバーライドせず拡張するには、既存の値を新しい値へと展開します。以下の例では、`config.social`を新しい`social`配列に展開し、既存の設定に新しい[`social`](/ja/reference/configuration/#social)メディアアカウントを追加しています。

```ts {6-11}
```ts {6-15}
// plugin.ts
export default {
name: 'add-twitter-plugin',
hooks: {
setup({ config, updateConfig }) {
'config:setup'({ config, updateConfig }) {
updateConfig({
social: {
social: [
...config.social,
twitter: 'https://twitter.com/astrodotbuild',
},
{
icon: 'twitter',
label: 'Twitter',
href: 'https://twitter.com/astrodotbuild',
},
],
});
},
},
Expand All @@ -92,12 +189,12 @@ import react from '@astrojs/react';
export default {
name: 'plugin-using-react',
hooks: {
setup({ addIntegration, astroConfig }) {
'config:setup'({ addIntegration, astroConfig }) {
const isReactLoaded = astroConfig.integrations.find(
({ name }) => name === '@astrojs/react'
);

// まだロードされていない場合のみ、Reactインテグレーションを追加します。
// Reactインテグレーションがまだ読み込まれていない場合のみ追加します。
if (!isReactLoaded) {
addIntegration(react());
}
Expand All @@ -106,6 +203,39 @@ export default {
};
```

#### `addRouteMiddleware`

**type:** `(config: { entrypoint: string; order?: 'pre' | 'post' | 'default' }) => void`

サイトに[ルートミドルウェアハンドラー](/ja/guides/route-data/)を追加するためのコールバック関数です。

`entrypoint`プロパティは、`onRequest`ハンドラーをエクスポートするプラグインのミドルウェアファイルのモジュール指定子である必要があります。

以下の例では、`@example/starlight-plugin`として公開されたプラグインが、npmモジュール指定子を使用してルートミドルウェアを追加しています。

```js {6-9}
// plugin.ts
export default {
name: '@example/starlight-plugin',
hooks: {
'config:setup'({ addRouteMiddleware }) {
addRouteMiddleware({
entrypoint: '@example/starlight-plugin/route-middleware',
});
},
},
};
```

##### 実行順序の制御

デフォルトでは、プラグインミドルウェアはプラグインが追加された順序で実行されます。

ミドルウェアの実行タイミングをより細かく制御する必要がある場合は、オプションの`order`プロパティを使用します。
ユーザーのミドルウェアより前に実行するには`order: "pre"`を設定します。他のすべてのミドルウェアの後に実行するには`order: "post"`を設定します。

同じ`order`値を持つミドルウェアを2つのプラグインが追加した場合、最初に追加されたプラグインが先に実行されます。

#### `astroConfig`

**type:** `AstroConfig`
Expand Down Expand Up @@ -139,16 +269,88 @@ Starlightを実行するために使用されたコマンドです。
export default {
name: 'long-process-plugin',
hooks: {
setup({ logger }) {
'config:setup'({ logger }) {
logger.info('時間が掛かる処理を開始します…');
// 何らかの時間が掛かる処理…
},
},
};
```

上記の例では、指定されたinfoメッセージを含むメッセージがログに出力されます。
上記の例では、指定した`info`レベルのメッセージを含むログが出力されます。

```shell
[long-process-plugin] 時間が掛かる処理を開始します…
```

#### `useTranslations`

**type:** `(lang: string) => I18nT`

BCP-47言語タグを指定して`useTranslations()`を呼び出すと、その言語のUI文字列にアクセスするためのユーティリティ関数が生成されます。`useTranslations()`は、Astroコンポーネントで利用可能な`Astro.locals.t()`APIと同等のものを返します。利用可能なAPIの詳細については、[“UI翻訳の使用“](/ja/guides/i18n/#ui翻訳を使用する)ガイドを参照してください。

```ts {6}
// plugin.ts
export default {
name: 'plugin-use-translations',
hooks: {
'config:setup'({ useTranslations, logger }) {
const t = useTranslations('zh-CN');
logger.info(t('builtWithStarlight.label'));
},
},
};
```

上記の例では、中国語簡体字の組み込みUI文字列を含むメッセージがログに出力されます。

```shell
[plugin-use-translations] 基于 Starlight 构建
```

#### `absolutePathToLang`

**type:** `(path: string) => string`

絶対ファイルパスを指定して`absolutePathToLang()`を呼び出すと、そのファイルの言語を取得できます。

これは、MarkdownやMDXファイルを処理する[remarkやrehypeプラグイン](https://docs.astro.build/ja/guides/markdown-content/#markdown-plugins)を追加する際に特に便利です。これらのプラグインが使用する[仮想ファイル形式](https://github.com/vfile/vfile)には、処理中のファイルの[絶対パス](https://github.com/vfile/vfile#filepath)が含まれており、`absolutePathToLang()`と組み合わせてファイルの言語を判定できます。返された言語は、[`useTranslations()`](#usetranslations)ヘルパーと組み合わせて、その言語のUI文字列を取得するために使用できます。

たとえば、以下のStarlight設定があるとします。

```js
starlight({
title: 'My Docs',
defaultLocale: 'en',
locales: {
// 英語ドキュメント: `src/content/docs/en/`
en: { label: 'English' },
// フランス語ドキュメント: `src/content/docs/fr/`
fr: { label: 'Français', lang: 'fr' },
},
});
```

プラグインは絶対パスを使用してファイルの言語を判定できます。

```ts {6-8} /fr/
// plugin.ts
export default {
name: 'plugin-use-translations',
hooks: {
'config:setup'({ absolutePathToLang, useTranslations, logger }) {
const lang = absolutePathToLang(
'/absolute/path/to/project/src/content/docs/fr/index.mdx'
);
const t = useTranslations(lang);
logger.info(t('aside.tip'));
},
},
};
```

上記の例では、フランス語の組み込みUI文字列を含むメッセージがログに出力されます。

```shell
[plugin-use-translations] Astuce
```
Loading