LunariaJSインストール・設定完全ガイド：ゼロからローカライズワークフローを構築

前回の記事では、LunariaJSのコア概念とクイックスタートを紹介しました。今日は、LunariaJSを正しくインストール・設定する方法を詳しく解説し、プロジェクトに完全なローカライズワークフローを構築します。

💡 公式ドキュメント：LunariaJS 日本語ドキュメント - 設定

インストール方法の比較

パッケージマネージャーの選択

LunariaJSは主要なJavaScriptパッケージマネージャーをすべてサポートしています：

パッケージマネージャー	インストールコマンド	推奨シナリオ
npm	`npm install @lunariajs/core`	Node.jsデフォルト、最も安定
yarn	`yarn add @lunariajs/core`	大規模プロジェクト、依存関係管理の最適化
pnpm	`pnpm add @lunariajs/core`	Monorepo、ディスク容量重視
bun	`bun add @lunariajs/core`	インストール速度を追求

グローバルインストール vs プロジェクトインストール

推奨：プロジェクトインストール

# 推奨：開発依存関係としてインストール
npm install -D @lunariajs/core

メリット：

設定とコードのバージョンが同期
チームメンバーが同じバージョンを使用
CI/CD環境の一貫性

非推奨：グローバルインストール

# 非推奨
npm install -g @lunariajs/core

デメリット：

バージョンが一致しない可能性
設定ファイルとコードが分離
CI/CD環境に追加設定が必要

バージョン選択の推奨

// package.json
{
  "devDependencies": {
    // メジャーバージョンをロック
    "@lunariajs/core": "^0.4.0",
    // Astro Starlightを使用する場合
    "@lunariajs/starlight": "^0.4.0"
  }
}

推奨：

セマンティックバージョニング（SemVer）を使用
メジャーバージョンをロック（^0.x.x または ~0.x.x）
GitHub Releasesで更新をフォロー

設定ファイル構造の解説

LunariaJSはlunaria.config.jsonを設定ファイルとして使用します（.jsと.ts形式もサポート）。

設定ファイルの場所

設定ファイルはプロジェクトのルートディレクトリに配置します：

your-project/
├── lunaria.config.json    # LunariaJS設定
├── package.json
├── src/
└── ...

完全な設定例

以下は、一般的なオプションをすべて含む完全な設定例です：

{
  "sourceLanguage": "en",
  "languages": ["en", "zh-cn", "ja", "ko"],
  "files": [
    {
      "sourcePath": "docs/{slug}.md",
      "localizationPath": "i18n/{lang}/{slug}.md",
      "include": ["**/*.md"],
      "exclude": ["**/draft/**"]
    },
    {
      "sourcePath": "src/content/docs/{slug}.md",
      "localizationPath": "src/i18n/content/{lang}/{slug}.md"
    }
  ],
  "dashboard": {
    "outputDir": "lunaria-dashboard",
    "title": "My Project Localization Status",
    "description": "Track the translation progress of our documentation"
  },
  "ignoreKeywords": ["TODO", "FIXME", "WIP"],
  "defaultLocale": "en"
}

設定オプションの詳細解説

1. sourceLanguage（ソース言語）

{
  "sourceLanguage": "en"
}

説明：

プロジェクトのソース言語（オリジナルコンテンツの言語）を指定
他の言語はすべてこの言語から翻訳
通常はen（英語）に設定

注意点：

言語コードはBCP 47標準形式を使用
languages配列のいずれかの値と対応
ソース言語ファイルは「欠落」や「古い」としてマークされない

2. languages（サポート言語リスト）

{
  "languages": ["en", "zh-cn", "ja", "ko", "es", "fr"]
}

説明：

プロジェクトがサポートするすべての言語をリスト
ソース言語とすべてのターゲット言語を含む

言語コードの規格：

形式	例	説明
2文字コード	`en`, `ja`, `ko`	ISO 639-1標準
地域コード付き	`zh-cn`, `zh-tw`, `pt-br`	国/地域を含む
完全形式	`en-us`, `en-gb`	最も正確、方言を区別

ベストプラクティス：

既存のi18nフレームワークの言語コードと一貫性を保つ
小文字形式（zh-cnであってzh-CNではない）
翻訳完了度や重要度順に並べる

3. files（ファイルパターン設定）

これは最も重要な設定項目で、追跡するファイルを定義します：

{
  "files": [
    {
      "sourcePath": "docs/{slug}.md",
      "localizationPath": "i18n/{lang}/docs/{slug}.md"
    }
  ]
}

パラメーターの説明：

パラメーター	必須	説明
`sourcePath`	✅	ソース言語ファイルのパスパターン
`localizationPath`	✅	翻訳ファイルのパスパターン
`include`	❌	含めるファイルのglobパターン
`exclude`	❌	除外するファイルのglobパターン

パスプレースホルダー：

プレースホルダー	説明	例
`{slug}`	ファイル識別子（拡張子なし）	`getting-started`
`{lang}`	言語コード	`zh-cn`, `ja`
`{ext}`	ファイル拡張子	`md`, `json`

複数ファイルパターンの設定：

{
  "files": [
    {
      "sourcePath": "docs/{slug}.md",
      "localizationPath": "i18n/{lang}/docs/{slug}.md",
      "include": ["**/*.md"],
      "exclude": ["**/draft/**", "**/internal/**"]
    },
    {
      "sourcePath": "src/content/docs/{slug}.mdx",
      "localizationPath": "src/content/docs/{lang}/{slug}.mdx"
    },
    {
      "sourcePath": "locales/en/{slug}.json",
      "localizationPath": "locales/{lang}/{slug}.json"
    }
  ]
}

4. dashboard（ダッシュボード設定）

{
  "dashboard": {
    "outputDir": "lunaria-dashboard",
    "title": "My Project i18n Status",
    "description": "Track our translation progress"
  }
}

パラメーターの説明：

パラメーター	デフォルト値	説明
`outputDir`	`lunaria-dashboard`	ダッシュボード出力ディレクトリ
`title`	プロジェクト名	ダッシュボードタイトル
`description`	-	ダッシュボードの説明
`uiLanguage`	`en`	ダッシュボードUI言語
`site`	-	ダッシュボードサイトURL（SEO用）

ローカライズファイル形式のサポート

JSON形式

最も一般的な形式で、互換性が最高です：

// locales/en/common.json
{
  "welcome": "Welcome to our project",
  "description": "This is a sample project",
  "nav": {
    "home": "Home",
    "about": "About",
    "contact": "Contact"
  }
}

// locales/ja/common.json
{
  "welcome": "プロジェクトへようこそ",
  "description": "これはサンプルプロジェクトです",
  "nav": {
    "home": "ホーム",
    "about": "概要",
    "contact": "お問い合わせ"
  }
}

設定例：

{
  "files": [
    {
      "sourcePath": "locales/en/{slug}.json",
      "localizationPath": "locales/{lang}/{slug}.json"
    }
  ]
}

YAML形式

可読性が高く、手書きメンテナンスに適しています：

# locales/en/common.yaml
welcome: Welcome to our project
description: This is a sample project
nav:
  home: Home
  about: About
  contact: Contact

設定例：

{
  "files": [
    {
      "sourcePath": "locales/en/{slug}.yaml",
      "localizationPath": "locales/{lang}/{slug}.yaml"
    }
  ]
}

Markdown形式

ドキュメントプロジェクトに適しています：

<!-- docs/en/getting-started.md -->
---
title: Getting Started
---

# Getting Started

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

設定例：

{
  "files": [
    {
      "sourcePath": "docs/{slug}.md",
      "localizationPath": "docs/{lang}/{slug}.md"
    }
  ]
}

混合形式プロジェクト

1つのプロジェクトで複数のファイル形式を同時に追跡できます：

{
  "files": [
    {
      "sourcePath": "locales/en/{slug}.json",
      "localizationPath": "locales/{lang}/{slug}.json"
    },
    {
      "sourcePath": "docs/{slug}.md",
      "localizationPath": "docs/{lang}/{slug}.md"
    },
    {
      "sourcePath": "config/en/{slug}.yaml",
      "localizationPath": "config/{lang}/{slug}.yaml"
    }
  ]
}

実践：多言語ドキュメントプロジェクトの設定

完全な実践例を通じて、4言語をサポートするドキュメントプロジェクトを設定しましょう。

プロジェクト構造

my-docs-project/
├── src/
│   └── content/
│       └── docs/
│           ├── index.md
│           ├── getting-started.md
│           ├── configuration.md
│           └── api/
│               ├── overview.md
│               └── reference.md
├── i18n/
│   ├── zh-cn/
│   │   └── docs/
│   ├── ja/
│   │   └── docs/
│   └── ko/
│       └── docs/
├── lunaria.config.json
└── package.json

ステップ1：依存関係のインストール

npm install -D @lunariajs/core

ステップ2：設定ファイルの作成

npx lunaria init

ステップ3：設定ファイルの編集

// lunaria.config.json
{
  "sourceLanguage": "en",
  "languages": ["en", "zh-cn", "ja", "ko"],
  "files": [
    {
      "sourcePath": "src/content/docs/{slug}.md",
      "localizationPath": "i18n/{lang}/docs/{slug}.md",
      "include": ["**/*.md"],
      "exclude": ["**/draft/**"]
    }
  ],
  "dashboard": {
    "outputDir": "public/lunaria",
    "title": "My Docs - Localization Status",
    "description": "Track the translation progress of My Docs documentation"
  }
}

ステップ4：設定の検証

以下のコマンドを実行して設定が正しいか確認します：

npx lunaria build

エラー出力がなければ、設定は正しいです。

ステップ5：ダッシュボードの確認

npx lunaria preview

http://localhost:3000にアクセスして生成されたダッシュボードを確認します。

よくある設定エラーと解決策

エラー1：パス設定が正しくない

エラー現象：

Error: No matching files found for pattern "docs/{slug}.md"

解決策：

パスがプロジェクトルートからの相対パスか確認
{slug}プレースホルダーが正しく使用されているか確認
ファイルが実際に存在するか確認

// 誤り
{
  "sourcePath": "docs/{slug}"  // 拡張子がない
}

// 正しい
{
  "sourcePath": "docs/{slug}.md"
}

エラー2：言語コードが一致しない

エラー現象：翻訳状態が異常に表示され、一部の言語が常に欠落として表示される。

解決策：

すべての設定で同じ言語コード形式を使用
ファイルディレクトリ名と設定が一致するか確認

// 設定でzh-cnを使用
{
  "languages": ["en", "zh-cn"]
}

// しかしファイルディレクトリでzh-CNを使用（誤り）
// i18n/zh-CN/docs/...

// 正しくは（正しい）
// i18n/zh-cn/docs/...

エラー3：ソース言語ファイルが欠落

エラー現象：すべての翻訳が「古い」としてマークされる。

解決策：

ソース言語ファイルが存在することを確認
sourcePath設定が正しいか確認

エラー4：除外ルールが機能しない

エラー現象： draftフォルダー内のファイルがまだ追跡されている。

解決策：

{
  "files": [
    {
      "sourcePath": "docs/{slug}.md",
      "localizationPath": "i18n/{lang}/docs/{slug}.md",
      "exclude": ["**/draft/**", "**/.*/**"]
    }
  ]
}

設定のベストプラクティス

1. TypeScript設定を使用

複雑なプロジェクトでは、TypeScript設定の使用を推奨：

// lunaria.config.ts
import { defineConfig } from '@lunariajs/core';

export default defineConfig({
  sourceLanguage: 'en',
  languages: ['en', 'zh-cn', 'ja', 'ko'],
  files: [
    {
      sourcePath: 'src/content/docs/{slug}.md',
      localizationPath: 'src/i18n/{lang}/docs/{slug}.md',
    },
  ],
  dashboard: {
    outputDir: 'public/lunaria',
    title: 'My Project i18n Status',
  },
});

メリット：

型チェック
IDEの自動補完
より良いメンテナンス性

2. 環境変数設定

CI/CD環境や異なる環境設定用：

// lunaria.config.ts
import { defineConfig } from '@lunariajs/core';

const isProduction = process.env.NODE_ENV === 'production';

export default defineConfig({
  sourceLanguage: 'en',
  languages: isProduction
    ? ['en', 'zh-cn', 'ja', 'ko', 'es', 'fr']
    : ['en', 'zh-cn'], // 開発環境では2言語のみ追跡
  files: [
    {
      sourcePath: 'src/content/docs/{slug}.md',
      localizationPath: 'i18n/{lang}/docs/{slug}.md',
    },
  ],
});

3. 設定ファイルのバージョン管理

# .gitignore
# 設定ファイルを無視しない
# !lunaria.config.json

# 生成されたダッシュボードは無視可能
lunaria-dashboard/

4. package.json scriptsとの統合

// package.json
{
  "scripts": {
    "lunaria:init": "lunaria init",
    "lunaria:build": "lunaria build",
    "lunaria:preview": "lunaria preview",
    "i18n:check": "lunaria build && lunaria preview"
  }
}

設定検証チェックリスト

設定完了後、以下のチェックリストで検証してください：

ソース言語とターゲット言語リストが正しい
ファイルパスパターンが実際のディレクトリ構造と一致
サポートするすべての言語に対応する翻訳ディレクトリがある
{slug}プレースホルダーが正しく使用されている
dashboard.outputDirが既存のディレクトリと競合しない
lunaria buildの実行でエラーがない
ダッシュボードですべてのファイルと言語が正しく表示される

まとめ

この記事では、LunariaJSのインストールと設定について詳しく解説しました。重要なポイント：

ポイント	説明
インストール方法	プロジェクトに開発依存関係としてインストールすることを推奨
設定ファイル	`lunaria.config.json`をプロジェクトルートに配置
コア設定	`sourceLanguage`、`languages`、`files`
ファイル形式	JSON、YAML、Markdownをサポート
パスプレースホルダー	`{slug}`、`{lang}`、`{ext}`
ベストプラクティス	TypeScript設定、環境変数、バージョン管理

次のステップ

設定が完了したら、次の記事ではLunariaJSのCLIコマンドについて詳しく解説します：

lunaria initのインタラクティブ初期化
lunaria buildのビルドオプション
lunaria previewのプレビュー機能
コマンドの組み合わせ使用シナリオ

お楽しみに！

💡 おすすめ読書：

LunariaJS 日本語ドキュメント

LunariaJS 設定リファレンス

LunariaJS 英語ドキュメント

LunariaJS 中国語ドキュメント

LunariaJS 韓国語ドキュメント