Astro Starlight + LunariaJS：完璧な多言語ドキュメントサイトを構築

これまでの記事で、LunariaJSのコア機能とGitワークフロー統合を学びました。今日は、LunariaJSとAstro Starlightの完璧な組み合わせについて解説し、プロフェッショナルな多言語ドキュメントサイトをゼロから構築する方法をステップバイステップで学びましょう。

💡 公式ドキュメント：LunariaJS 日本語ドキュメント - Starlight統合

Starlightとは？

Astro Starlightの概要

Astro StarlightはAstroフレームワークをベースに構築されたモダンなドキュメントテーマで、以下を提供：

特徴	説明
🚀 最高のパフォーマンス	Astroのパーシャルハイドレーションで、ページ読み込みが超高速
🎨 美しいデザイン	そのまま使えるプロフェッショナルなドキュメントUI
📱 レスポンシブ	デスクトップとモバイルデバイスに完璧に対応
🔍 組み込み検索	Pagefindによる全文検索
🌙 ダークモード	システム設定を自動検出
🌐 国際化	ネイティブ多言語サポート

なぜLunariaJSが必要？

Starlightは国際化（i18n）サポートを提供しますが、翻訳管理機能は含まれていません：

要件	Starlight	+ LunariaJS
多言語ルーティング	✅	✅
言語切り替え	✅	✅
翻訳UIコンポーネント	✅	✅
翻訳状態追跡	❌	✅
可視化ダッシュボード	❌	✅
Gitワークフロー統合	❌	✅

LunariaJSはStarlightの翻訳管理における空白を埋めます。

@lunariajs/starlightのインストール

前提条件

プロジェクトが以下の条件を満たしていることを確認：

• Astro 4.0+ または 5.0+
• Starlightがインストール済み
• プロジェクトがGitでバージョン管理されている

インストール手順

1. 依存関係をインストール

# npmを使用
npm install @lunariajs/starlight

# yarnを使用
yarn add @lunariajs/starlight

# pnpmを使用
pnpm add @lunariajs/starlight

2. バージョンの互換性を確認

# インストール済みバージョンを確認
npm list @astrojs/starlight @lunariajs/starlight

バージョンの互換性を確保：

@astrojs/starlight	@lunariajs/starlight
0.25.x	0.4.x
0.26.x+	0.5.x+

Starlight設定との統合

基本設定

astro.config.mjsでLunariaJS統合を追加：

// astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import lunaria from '@lunariajs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Documentation',
      defaultLocale: 'en',
      locales: {
        en: { label: 'English' },
        'zh-cn': { label: '简体中文' },
        ja: { label: '日本語' },
        ko: { label: '한국어' },
      },
      sidebar: [
        { label: 'Guide', link: '/guide/' },
        { label: 'Reference', link: '/reference/' },
      ],
    }),
    lunaria({
      // LunariaJS設定
      sourceLanguage: 'en',
      languages: ['en', 'zh-cn', 'ja', 'ko'],
    }),
  ],
});

i18n設定とLunariaJSの同期

Starlightのi18n設定とLunariaJSを一貫させる：

// astro.config.mjs
const languages = ['en', 'zh-cn', 'ja', 'ko'];
const sourceLanguage = 'en';

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Documentation',
      defaultLocale: sourceLanguage,
      locales: Object.fromEntries(
        languages.map(lang => [
          lang,
          { label: getLanguageLabel(lang) }
        ])
      ),
    }),
    lunaria({
      sourceLanguage,
      languages,
    }),
  ],
});

function getLanguageLabel(lang) {
  const labels = {
    en: 'English',
    'zh-cn': '简体中文',
    ja: '日本語',
    ko: '한국어',
  };
  return labels[lang] || lang;
}

ルーティング構造設計

Starlight + LunariaJSの推奨ディレクトリ構造：

src/
└── content/
    └── docs/
        ├── en/                    # 英語（ソース言語）
        │   ├── index.md
        │   ├── guide.md
        │   └── reference.md
        ├── zh-cn/                 # 中国語翻訳
        │   ├── index.md
        │   ├── guide.md
        │   └── reference.md
        ├── ja/                    # 日本語翻訳
        │   └── ...
        └── ko/                    # 韓国語翻訳
            └── ...

完全設定例

// astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import lunaria from '@lunariajs/starlight';

// 言語設定
const config = {
  sourceLanguage: 'en',
  languages: ['en', 'zh-cn', 'ja', 'ko'],
  languageLabels: {
    en: 'English',
    'zh-cn': '简体中文',
    ja: '日本語',
    ko: '한국어',
  },
};

export default defineConfig({
  site: 'https://docs.example.com',
  integrations: [
    starlight({
      title: 'My Project',
      defaultLocale: config.sourceLanguage,
      locales: Object.fromEntries(
        config.languages.map(lang => [
          lang,
          { label: config.languageLabels[lang] }
        ])
      ),
      sidebar: {
        en: [
          { label: 'Home', link: '/' },
          { label: 'Guide', link: '/guide/' },
          { label: 'API Reference', link: '/reference/' },
        ],
        'zh-cn': [
          { label: '首页', link: '/' },
          { label: '指南', link: '/guide/' },
          { label: 'API 参考', link: '/reference/' },
        ],
        ja: [
          { label: 'ホーム', link: '/' },
          { label: 'ガイド', link: '/guide/' },
          { label: 'API リファレンス', link: '/reference/' },
        ],
        ko: [
          { label: '홈', link: '/' },
          { label: '가이드', link: '/guide/' },
          { label: 'API 참조', link: '/reference/' },
        ],
      },
      social: {
        github: 'https://github.com/your-org/your-repo',
      },
    }),
    lunaria({
      sourceLanguage: config.sourceLanguage,
      languages: config.languages,
      files: [
        {
          sourcePath: 'src/content/docs/{lang}/{slug}.md',
          localizationPath: 'src/content/docs/{lang}/{slug}.md',
        },
      ],
      dashboard: {
        outputDir: 'public/i18n-status',
        title: 'My Project - Translation Status',
      },
    }),
  ],
});

ダッシュボードの埋め込み

方法1：独立パスとして

LunariaJSダッシュボードを/i18n-status/パスに配置：

// astro.config.mjs
lunaria({
  dashboard: {
    outputDir: 'public/i18n-status',
  },
})

ビルド後、/i18n-status/にアクセスしてダッシュボードを確認できます。

方法2：ナビゲーションメニューに追加

Starlightナビゲーションにダッシュボードリンクを追加：

// astro.config.mjs
starlight({
  title: 'My Documentation',
  sidebar: [
    { label: 'Guide', link: '/guide/' },
    { label: 'Reference', link: '/reference/' },
    {
      label: 'Translation Status',
      link: '/i18n-status/',
      badge: 'New',
    },
  ],
})

方法3：カスタムナビゲーションコンポーネント

翻訳進捗を表示するカスタムナビゲーションコンポーネントを作成：

---
// src/components/I18nStatus.astro
---
<a href="/i18n-status/" class="i18n-status-link">
  <span class="icon">🌐</span>
  <span>Translation Status</span>
</a>

<style>
  .i18n-status-link {
    display: flex;
    align-items: center;
    gap: 0.5rem;
    padding: 0.5rem 1rem;
    background: var(--sl-color-bg);
    border-radius: 0.5rem;
    text-decoration: none;
    color: var(--sl-color-text);
    transition: background 0.2s;
  }

  .i18n-status-link:hover {
    background: var(--sl-color-bg-hover);
  }
</style>

スタイルのカスタマイズ

LunariaJSダッシュボードのデフォルトスタイルを上書き：

/* src/styles/lunaria-custom.css */
:root {
  /* Starlightのカラー変数を使用 */
  --lunaria-color-primary: var(--sl-color-accent);
  --lunaria-color-success: var(--sl-color-green);
  --lunaria-color-warning: var(--sl-color-orange);
  --lunaria-color-danger: var(--sl-color-red);

  /* 背景色 */
  --lunaria-bg-primary: var(--sl-color-bg);
  --lunaria-bg-secondary: var(--sl-color-bg-sidebar);
}

設定で参照：

// astro.config.mjs
lunaria({
  dashboard: {
    customCss: './src/styles/lunaria-custom.css',
  },
})

実践：3言語ドキュメントサイトの構築

完全な実践例で、中国語、日本語、韓国語をサポートする3言語ドキュメントサイトを構築します。

ステップ1：Starlightプロジェクトを作成

# テンプレートでプロジェクトを作成
npm create astro@latest -- --template starlight

# プロジェクトディレクトリに移動
cd my-docs

# 依存関係をインストール
npm install

ステップ2：LunariaJSをインストール

npm install @lunariajs/starlight

ステップ3：多言語を設定

astro.config.mjsを編集：

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import lunaria from '@lunariajs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Project Docs',
      defaultLocale: 'en',
      locales: {
        en: { label: 'English', lang: 'en' },
        'zh-cn': { label: '简体中文', lang: 'zh-CN' },
        ja: { label: '日本語', lang: 'ja' },
        ko: { label: '한국어', lang: 'ko' },
      },
      sidebar: {
        en: [
          { label: 'Home', link: '/' },
          { label: 'Getting Started', items: [
            { label: 'Introduction', link: '/getting-started/' },
            { label: 'Installation', link: '/installation/' },
          ]},
        ],
        'zh-cn': [
          { label: '首页', link: '/' },
          { label: '快速开始', items: [
            { label: '简介', link: '/getting-started/' },
            { label: '安装', link: '/installation/' },
          ]},
        ],
        ja: [
          { label: 'ホーム', link: '/' },
          { label: 'はじめに', items: [
            { label: '概要', link: '/getting-started/' },
            { label: 'インストール', link: '/installation/' },
          ]},
        ],
        ko: [
          { label: '홈', link: '/' },
          { label: '시작하기', items: [
            { label: '소개', link: '/getting-started/' },
            { label: '설치', link: '/installation/' },
          ]},
        ],
      },
    }),
    lunaria({
      sourceLanguage: 'en',
      languages: ['en', 'zh-cn', 'ja', 'ko'],
    }),
  ],
});

ステップ4：コンテンツファイルを作成

src/content/docs/
├── en/
│   ├── index.md
│   ├── getting-started.md
│   └── installation.md
├── zh-cn/
│   ├── index.md
│   └── getting-started.md      # インストールドキュメントはまだ翻訳されていないと仮定
├── ja/
│   ├── index.md
│   └── getting-started.md
└── ko/
    └── index.md                 # 他のドキュメントはまだ翻訳されていない

ステップ5：翻訳メタデータを追加

各Markdownファイルにはfrontmatterを含める：

---
title: Getting Started
description: Learn how to get started with our project.
---

# Getting Started

Welcome to our project! This guide will help you...

ステップ6：ビルドしてプレビュー

# サイトとダッシュボードをビルド
npm run build

# プレビュー
npm run preview

アクセス：

• ドキュメントサイト：http://localhost:4321/
• 翻訳ダッシュボード：http://localhost:4321/i18n-status/

ステップ7：翻訳状態を確認

ダッシュボードを開くと、以下のような表示が見られます：

Translation Status
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Language         Progress    Status
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🇺🇸 English       100%        Source
🇨🇳 简体中文       67%         2/3 done, 1 missing
🇯🇵 日本語         67%         2/3 done, 1 missing
🇰🇷 한국어          33%         1/3 done, 2 missing
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

よくある問題と解決策

Q1：ダッシュボード404エラー

問題：/i18n-status/にアクセスすると404。

解決策：

# LunariaJS設定の出力ディレクトリがpublic/ディレクトリ以下であることを確認
lunaria({
  dashboard: {
    outputDir: 'public/i18n-status',  // public/ディレクトリ以下である必要があります
  },
})

# 先にビルドを実行
npm run build

Q2：言語コードが一致しない

問題：Starlightはzh-CNを使用、LunariaJSはzh-cnを使用。

解決策：

starlight({
  locales: {
    'zh-cn': { label: '简体中文', lang: 'zh-CN' },  // 注意して区別
  },
})

Q3：ダッシュボードスタイルの競合

問題：ダッシュボードスタイルがドキュメントサイトと一致しない。

解決策：カスタムCSSで統一スタイルを使用：

/* lunariaダッシュボードでStarlight変数を使用 */
:root {
  --lunaria-color-primary: var(--sl-color-accent);
  --lunaria-bg-primary: var(--sl-color-bg);
}

Q4：ビルド時のメモリ不足

問題：大規模ドキュメントサイトのビルド時にメモリ不足。

解決策：

# Node.jsのメモリ制限を増加
NODE_OPTIONS="--max-old-space-size=4096" npm run build

Q5：ルーティング競合

問題：ダッシュボードパスがドキュメントパスと競合。

解決策：ドキュメントと競合しないパスを選択：

// /docs/、/guide/などの一般的なドキュメントパスを避ける
lunaria({
  dashboard: {
    outputDir: 'public/localization-status',  // ユニークなパスを使用
  },
})

ベストプラクティス

1. 言語設定を統一

共有設定ファイルを作成：

// src/i18n-config.js
export const languages = ['en', 'zh-cn', 'ja', 'ko'];
export const sourceLanguage = 'en';
export const languageLabels = {
  en: 'English',
  'zh-cn': '简体中文',
  ja: '日本語',
  ko: '한국어',
};

複数箇所で参照：

// astro.config.mjs
import { languages, sourceLanguage, languageLabels } from './src/i18n-config.js';

2. 翻訳チェックの自動化

package.jsonにスクリプトを追加：

{
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "i18n:check": "lunaria build",
    "i18n:preview": "lunaria preview"
  }
}

3. 翻訳ガイドを追加

ドキュメントに翻訳貢献ガイドを追加：

# Contributing Translations

We welcome translation contributions! Here's how to help:

1. Check the [Translation Status Dashboard](/i18n-status/)
2. Find a file marked as "missing" or "outdated"
3. Fork the repository and create a translation
4. Submit a pull request

Thank you for helping make our documentation accessible to everyone!

4. CI/CDチェックを設定

# .github/workflows/i18n-check.yml
name: i18n Status

on: [pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm ci
      - run: npm run i18n:check

      - name: Upload Dashboard
        uses: actions/upload-artifact@v4
        with:
          name: i18n-dashboard
          path: public/i18n-status/

まとめ

LunariaJSとAstro Starlightの統合は完全な多言語ドキュメントソリューションを提供します：

機能	Starlight	+ LunariaJS
多言語ルーティング	✅	✅
言語切り替え	✅	✅
翻訳UI	✅	✅
翻訳状態追跡	❌	✅
可視化ダッシュボード	❌	✅
Gitワークフロー	❌	✅

重要なポイント：

• @lunariajs/starlightパッケージでシームレスな統合を実現
• StarlightとLunariaJS間で言語コードを一貫させる
• ダッシュボードをナビゲーションメニューに埋め込んでアクセスしやすく
• 設定ファイルを統一して重複メンテナンスを回避

次のステップ

次の記事では、LunariaJSのCI/CD統合について解説し、以下を学びます：

• GitHub Actions自動ビルドの設定
• 翻訳状態チェックパイプラインの設計
• 通知とレポートメカニズムの設定
• 継続的ローカライズワークフローの実装

お楽しみに！

---

💡 おすすめ読書：

• LunariaJS 日本語ドキュメント
• LunariaJS Starlight統合
• LunariaJS 英語ドキュメント
• LunariaJS 中国語ドキュメント
• LunariaJS 韓国語ドキュメント