Add Japanese language support & translate some docs into Japanese (#97)

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

7 files changed, 362 insertions, 5 deletions

diff --git a/.changeset/rude-peas-jog.md b/.changeset/rude-peas-jog.md
new file mode 100644
index 00000000..89669891
--- /dev/null
+++ b/.changeset/rude-peas-jog.md
@@ -0,0 +1,5 @@
+---
+"@astrojs/starlight": patch
+---
+
+Add Japanese language support
diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
index b64d8383..83b334fd 100644
--- a/docs/astro.config.mjs
+++ b/docs/astro.config.mjs
@@ -33,11 +33,12 @@ export default defineConfig({
         root: { label: 'English', lang: 'en' },
         de: { label: 'Deutsch', lang: 'de' },
         es: { label: 'Español', lang: 'es' },
+        ja: { label: '日本語', lang: 'ja' },
       },
       sidebar: [
         {
           label: 'Start Here',
-          translations: { de: 'Beginne hier', es: 'Comienza aqui' },
+          translations: { de: 'Beginne hier', es: 'Comienza aqui', ja: 'ここから始める' },
           items: [
             { label: 'Welcome, world', link: '/' },
             { label: 'Getting Started', link: 'getting-started' },
@@ -46,12 +47,12 @@ export default defineConfig({
         },
         {
           label: 'Guides',
-          translations: { de: 'Anleitungen', es: 'Guías' },
+          translations: { de: 'Anleitungen', es: 'Guías', ja: 'ガイド' },
           autogenerate: { directory: 'guides' },
         },
         {
           label: 'Reference',
-          translations: { de: 'Referenz', es: 'Referencias' },
+          translations: { de: 'Referenz', es: 'Referencias', ja: 'リファレンス' },
           autogenerate: { directory: 'reference' },
         },
       ],
diff --git a/docs/src/content/docs/guides/i18n.md b/docs/src/content/docs/guides/i18n.md
index c4d3afcd..e8c87aa7 100644
--- a/docs/src/content/docs/guides/i18n.md
+++ b/docs/src/content/docs/guides/i18n.md
@@ -110,7 +110,7 @@ If a translation is not yet available for a language, Starlight will show reader
 
 Some of Starlight’s default UI requires text labels to work.
 For example, the table of contents on this page has an “On this page” heading in English.
-We aim to ship these labels in as many languages as possible but currently only have support for English, German, and Spanish.
+We aim to ship these labels in as many languages as possible but currently only have support for English, German, Japanese, and Spanish.
 
 You can provide translations for additional languages you support — or override our default labels — via the `i18n` data collection.
 
diff --git a/docs/src/content/docs/ja/index.mdx b/docs/src/content/docs/ja/index.mdx
new file mode 100644
index 00000000..37d8a623
--- /dev/null
+++ b/docs/src/content/docs/ja/index.mdx
@@ -0,0 +1,24 @@
+---
+title: ようこそ、世界
+description: Starlightは、Astroを使って美しく高性能なドキュメントサイトを作るためのテーマです。
+---
+
+:::caution[作業中]
+Starlightはまだ開発の初期段階にあり、開発が進むにつれバグや変更が生じることが予想されます。何か不具合を見つけた場合は、[GitHubでissueを開く](https://github.com/withastro/starlight/issues/new/choose)か、または[Discord](https://astro.build/chat)でお知らせください。
+:::
+
+## 何ができますか？
+
+Starlightには、ドキュメンテーションサイトを迅速に立ち上げるために必要なすべての機能が含まれています。
+
+- MarkdownとMDXのサポート
+- 見やすいタイポグラフィ
+- コードブロックのシンタックスハイライト
+- 簡単に設定可能なナビゲーションメニュー
+- 組み込みのサイト内検索
+- [国際化機能](/ja/guides/i18n)
+- アクセシブルなサイト構造
+- MDX[コンテンツ内でのコンポーネント](/ja/guides/components)のサポート
+- カスタムスタイルのサポート
+- 高速で[環境に優しい](/ja/environmental-impact)アーキテクチャ
+- [Astroエコシステム](https://astro.build/integrations)との互換性
diff --git a/docs/src/content/docs/ja/reference/configuration.md b/docs/src/content/docs/ja/reference/configuration.md
new file mode 100644
index 00000000..0e069a28
--- /dev/null
+++ b/docs/src/content/docs/ja/reference/configuration.md
@@ -0,0 +1,306 @@
+---
+title: 設定方法
+description: Starlightがサポートするすべての設定オプションの概要。
+---
+
+## `starlight`インテグレーションの設定
+
+以下のオプションを`starlight`インテグレーションに設定できます。
+
+### `title`（必須）
+
+**type:** `string`
+
+ウェブサイトのタイトルを設定します。メタデータとブラウザのタブのタイトルに使用されます。
+
+### `description`
+
+**type:** `string`
+
+ウェブサイトの説明を設定します。`description`がページのフロントマターに設定されていない場合、`<meta name="description">`タグで検索エンジンに共有するメタデータとして使用されます。
+
+### `logo`
+
+**type:** [`LogoConfig`](#logoconfig)
+
+ナビゲーションバーにサイトタイトルと並べて、またはその代わりとして表示するロゴ画像を設定します。単一の`src`プロパティを設定するか、`light`と`dark`用に別々の画像ソースを設定できます。
+
+```js
+starlight({
+  logo: {
+    src: '/src/assets/my-logo.svg',
+  },
+});
+```
+
+#### `LogoConfig`
+
+```ts
+type LogoConfig = { alt?: string; replacesTitle?: boolean } & (
+  | { src: string }
+  | { light: string; dark: string }
+);
+```
+
+### `tableOfContents`
+
+**type:** `{ minHeadingLevel?: number; maxHeadingLevel?: number; }`  
+**default:** `{ minHeadingLevel: 2; maxHeadingLevel: 3; }`
+
+各ページの右側に表示される目次を設定します。デフォルトでは、`<h2>`と`<h3>`の見出しがこの目次に含まれます。
+
+### `editLink`
+
+**type:** `{ baseUrl: string }`
+
+`editLink.baseUrl`を設定すると、「ページを編集」リンクが有効になります。最終的なリンクは、`editLink.baseUrl` + 現在のページのパスになります。たとえば、GitHubの`withastro/starlight`リポジトリのページを編集するには以下のようにします。
+
+```js
+starlight({
+  editLink: {
+    baseUrl: 'https://github.com/withastro/starlight/edit/main/',
+  },
+});
+```
+
+この設定により、`/introduction`ページには`https://github.com/withastro/starlight/edit/main/src/docs/introduction.md`を指す編集リンクが表示されます。
+
+### `sidebar`
+
+**type:** [`SidebarGroup[]`](#sidebargroup)
+
+サイトのサイドバーのナビゲーション項目を設定します。
+
+サイドバーはグループごとに`label`をもつ配列で、`items`配列または`autogenerate`設定オブジェクトのいずれかを含みます。
+
+リンクとサブグループを含む配列である`items`により、グループの内容を手動で設定できます。また、`autogenerate`を使用して、ドキュメントの特定のディレクトリからグループの内容を自動的に生成することも可能です。
+
+```js
+starlight({
+  sidebar: [
+    // 2つのリンクを含む、「ここから始める」というラベルのついたグループ。
+    {
+      label: 'ここから始める',
+      items: [
+        { label: 'はじめに', link: '/intro' },
+        { label: '次のステップ', link: '/next-steps' },
+      ],
+    },
+    // 参照先のディレクトリのすべてのページにリンクするグループ。
+    {
+      label: 'リファレンス',
+      autogenerate: { directory: 'reference' },
+    },
+  ],
+});
+```
+
+#### 並び順
+
+自動生成されたサイドバーグループは、ファイル名のアルファベット順に並べ替えられます。たとえば、`astro.md`から生成されたページは、`starlight.md`というページの上に表示されます。
+
+#### ラベルの翻訳
+
+多言語対応が必要なサイトの場合、各項目の`label`はデフォルトのロケールのものとみなされます。サポート対象の言語のラベルを提供するには、`translations`プロパティを設定します。
+
+```js
+sidebar: [
+  // An example sidebar with labels translated to French. フランス語に翻訳されたラベルをもつサイドバーの例。
+  {
+    label: 'ここから始める',
+    translations: { fr: 'Commencez ici' },
+    items: [
+      {
+        label: '開始する',
+        translations: { fr: 'Bien démarrer' },
+        link: '/getting-started',
+      },
+      {
+        label: 'プロジェクトの構造',
+        translations: { fr: 'Structure du projet' },
+        link: '/structure',
+      },
+    ],
+  },
+];
+```
+
+#### `SidebarGroup`
+
+```ts
+type SidebarGroup =
+  | {
+      label: string;
+      translations?: Record<string, string>;
+      items: Array<LinkItem | SidebarGroup>;
+    }
+  | {
+      label: string;
+      translations?: Record<string, string>;
+      autogenerate: {
+        directory: string;
+      };
+    };
+```
+
+#### `LinkItem`
+
+```ts
+interface LinkItem {
+  label: string;
+  link: string;
+}
+```
+
+### `locales`
+
+**type:** `{ [dir: string]: LocaleConfig }`
+
+サイトの国際化（i18n）をおこなうには、サポート対象の`locales`を設定します。
+
+各エントリは、その言語のファイルが保存されているディレクトリ名をキーとして使用する必要があります。
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+
+export default defineConfig({
+  integrations: [
+    starlight({
+      title: 'My Site',
+      // このサイトのデフォルト言語を英語に設定します。
+      defaultLocale: 'en',
+      locales: {
+        // 英語のドキュメントは`src/content/docs/en/`にあります。
+        en: {
+          label: 'English',
+        },
+        // 簡体字中国語のドキュメントは`src/content/docs/zh/`にあります。
+        zh: {
+          label: '简体中文',
+          lang: 'zh-CN',
+        },
+        // アラビア語のドキュメントは`src/content/docs/ar/`にあります。
+        ar: {
+          label: 'العربية',
+          dir: 'rtl',
+        },
+      },
+    }),
+  ],
+});
+```
+
+#### ロケールオプション
+
+各ロケールに対し以下のオプションを設定できます。
+
+##### `label`（必須）
+
+**type:** `string`
+
+たとえば言語の切替機能などでユーザーに表示する、この言語を表わすラベルです。ほとんどの場合、このラベルは、その言語を使用するユーザーが読みたいと思う言語の名前にすることが望ましいでしょう。たとえば、`"English"`、`"العربية"`、`"简体中文"`などです。
+
+##### `lang`
+
+**type:** `string`
+
+この言語のBCP-47タグです。たとえば`"en"`、`"ar"`、`"zh-CN"`などです。設定されていない場合、デフォルトでは言語のディレクトリ名が使用されます。
+
+##### `dir`
+
+**type:** `'ltr' | 'rtl'`
+
+この言語を記述する方向です。左から右へ（デフォルト）は`"ltr"`を、右から左へは`"rtl"`を設定します。
+
+#### ルートロケール
+
+`root`ロケールを設定することで、`/lang/`ディレクトリなしでデフォルト言語を提供できます。
+
+```js
+starlight({
+  locales: {
+    root: {
+      label: 'English',
+      lang: 'en',
+    },
+    fr: {
+      label: 'Français',
+    },
+  },
+});
+```
+
+この設定により、たとえば`/getting-started/`を英語のルートとし、対応するフランス語のページを`/fr/getting-started/`として提供することができます。
+
+### `defaultLocale`
+
+**type:** `string`
+
+このサイトのデフォルト言語を設定します。この値は、[`locales`](#locales)オブジェクトのキーのいずれかと一致する必要があります。（デフォルト言語が[ルートロケール](#root-locale)の場合は、この設定をスキップできます。）
+
+翻訳がない場合には、デフォルトロケールがフォールバックコンテンツとして使用されます。
+
+### `social`
+
+**type:** `{ discord?: string; github?: string; mastodon?: string; twitter?: string }`
+
+このサイトのソーシャルメディアアカウントに関する任意の項目です。これらのいずれかを追加すると、サイトヘッダーにアイコンリンクとして表示されます。
+
+```js
+starlight({
+  social: {
+    discord: 'https://astro.build/chat',
+    github: 'https://github.com/withastro/starlight',
+    mastodon: 'https://m.webtoo.ls/@astro',
+    twitter: 'https://twitter.com/astrodotbuild',
+  },
+});
+```
+
+### `customCss`
+
+**type:** `string[]`
+
+Starlightサイトの見た目をカスタマイズするためのCSSファイルを設定します。
+
+プロジェクトのルートからの相対パスで指定したローカルのCSSファイル（`'/src/custom.css'`など）と、npmモジュールとしてインストールしたCSS（`'@fontsource/roboto'`など）に対応しています。
+
+```js
+starlight({
+  customCss: ['/src/custom-styles.css', '@fontsource/roboto'],
+});
+```
+
+### `head`
+
+**type:** [`HeadConfig[]`](#headconfig)
+
+Starlightサイトの`<head>`にカスタムタグを追加します。アナリティクスやその他のサードパーティのスクリプトやリソースを追加するのに便利です。
+
+```js
+starlight({
+  head: [
+    // Fathomのアナリティクススクリプトタグを追加する例。
+    {
+      tag: 'script',
+      attrs: {
+        src: 'https://cdn.usefathom.com/script.js',
+        'data-site': 'MY-FATHOM-ID',
+        defer: true,
+      },
+    },
+  ],
+});
+```
+
+#### `HeadConfig`
+
+```ts
+interface HeadConfig {
+  tag: string;
+  attrs?: Record<string, string | boolean | undefined>;
+  content?: string;
+}
+```
diff --git a/packages/starlight/translations/index.ts b/packages/starlight/translations/index.ts
index ceff3527..e8699a8f 100644
--- a/packages/starlight/translations/index.ts
+++ b/packages/starlight/translations/index.ts
@@ -2,9 +2,10 @@ import { i18nSchema } from '../schemas/i18n';
 import en from './en.json';
 import es from './es.json';
 import de from './de.json';
+import ja from './ja.json';
 
 const parse = i18nSchema().required().strict().parse;
 
 export default Object.fromEntries(
-  Object.entries({ en, es, de }).map(([key, dict]) => [key, parse(dict)])
+  Object.entries({ en, es, de, ja }).map(([key, dict]) => [key, parse(dict)])
 );
diff --git a/packages/starlight/translations/ja.json b/packages/starlight/translations/ja.json
new file mode 100644
index 00000000..a03a8978
--- /dev/null
+++ b/packages/starlight/translations/ja.json
@@ -0,0 +1,20 @@
+{
+  "skipLink.label": "コンテンツにスキップ",
+  "search.label": "検索",
+  "search.shortcutLabel": "（/を押して検索）",
+  "search.cancelLabel": "キャンセル",
+  "themeSelect.accessibleLabel": "テーマの選択",
+  "themeSelect.dark": "ダーク",
+  "themeSelect.light": "ライト",
+  "themeSelect.auto": "自動",
+  "languageSelect.accessibleLabel": "言語の選択",
+  "menuButton.accessibleLabel": "メニュー",
+  "sidebarNav.accessibleLabel": "メイン",
+  "tableOfContents.onThisPage": "目次",
+  "tableOfContents.overview": "概要",
+  "i18n.untranslatedContent": "このコンテンツはまだ日本語訳がありません。",
+  "page.editLink": "ページを編集",
+  "page.lastUpdated": "最終更新日:",
+  "page.previousLink": "前へ",
+  "page.nextLink": "次へ"
+}