コンテンツへスキップ
Lunaria

設定

Lunaria は、デフォルトの動作を広くカスタマイズできるようにしています。このリファレンスでは、lunaria.config.json ファイルに利用可能なすべてのオプションについて説明します。

lunaria.config.json
{
  "$schema": "./node_modules/@lunariajs/core/config.schema.json"
}

ルートレベルのオプション

repository (必須)

型: Repository

ダッシュボードに表示される Git ホスティングリンクを設定します。期待されるプロパティは以下の通りです：

  • name — Git ホスティングプラットフォーム上のリポジトリの一意な名前（例：'yanthomasdev/lunaria'）。
  • branch — コンテンツを追跡するリポジトリのブランチ名（デフォルトは 'main'）。
  • rootDir — モノレポを使用している場合のプロジェクトのルートディレクトリ（例：'docs'）。
  • hosting — 利用している Git ホスティングプラットフォーム（例：'github' や 'gitlab'）。

Repository

type Repository = {
  name: string;
  branch: string;
  rootDir?: string;
  hosting: 'github' | 'gitlab';
};

defaultLocale (必須)

型: { label: string; lang: string }

プロジェクトのデフォルトロケールを設定します。これはソースコンテンツの元となるロケールです。

label はロケールの表示名（例："English"）であり、lang は BCP-47タグ または、トラッキング対象ファイルのパスで使用される他の識別コード（例："en"）です。

{
  "defaultLocale": {
    "label": "English",
    "lang": "en"
  }
}

locales (必須)

型: { label: string; lang: string }[]

プロジェクトのローカライゼーションに使用するすべてのロケールを設定します。エントリは defaultLocale と同じ構造に従います。

{
  "locales": [
    {
      "label": "Spanish",
      "lang": "es"
    },
    {
      "label": "Português",
      "lang": "pt"
    }
  ]
}

files (必須)

型: File[]

ダッシュボードのトラッキング対象ファイルを設定します。

files 内のエントリの順序は、ダッシュボードでの表示順序として尊重されます。各エントリには以下のプロパティが必要です：

  • location — トレーブルなファイルのグロブパターン（例：'src/content/docs/**/*.mdx'）。
  • ignore — トレーブルから除外するグロブパターンの配列（デフォルト値：['node_modules']）。
  • pattern — path-to-regexp パターン によるファイルパスのパターン（例：'src/content/docs/@lang/@path'）。@lang および @path は Lunaria が提供するカスタム構文であり、より複雑なケースでは通常の :lang および :path パラメータに置き換えることができます。

ファイルタイプ

files の各エントリには type を含める必要があります。これにより、トラッキングシステムの動作、ダッシュボードでのファイルの表示方法、および新しいプロパティの追加が変わります。

universal

universal ファイルタイプは、ファイルの状態を単に Git 歴史に基づいて追跡するとともに、任意のファイル拡張子を許可します。

{
  "files": [
    {
      "location": "**/*.md",
      "pattern": "@lang/@path",
      "type": "universal"
    }
  ]
}
dictionary

通常の Git 歴史追跡に加え、dictionary ファイルタイプはキーの完成度をチェックします。ソース辞書内の各キーは、ローカライゼーションに存在しなければ「完了」とはみなされません。

対応するファイル拡張子は以下の通り：json, yml, md, markdown, mdx, mdoc, js, cjs, mjs, ts, cts, mts。

ローカライゼーションにキーが欠けていた場合、そのロケールに対するダッシュボードの詳細には、完了のために必要な未入力キーの一覧（折りたたみ可能）が含まれます。

追加の optionalKeys プロパティにより、キーをオプション（ローカライゼーションが完了するために不要）として扱うことができます。各 optionalKeys のキーは共有パスを指し、その配列内にある辞書キーがオプションと見なされます。

{
  "files": [
    {
      "location": "ui/**/*.{json,yml}",
      "pattern": "ui/@lang/@path",
      "type": "dictionary",
      "optionalKeys": {
        "ui/nav.json": ["footer", "sidebar"],
        "ui/ui.yml": ["search"]
      }
    }
  ]
}

File

type File = {
  location: string;
  ignore: string[];
  pattern: string;
} & (
  | { type: 'universal' }
  | { type: 'dictionary'; optionalKeys?: Record<string, string[]> }
);

ignoreKeywords

型: string[]
デフォルト: ['lunaria-ignore', 'fix typo']

Lunaria が自動的に無視してステータス変更をトリガーしないコミットタイトル内のキーワードリスト。デフォルトでは、lunaria-ignore または fix typo が含まれるコミットタイトルは無視されます。

空の配列（[]）を指定することで機能を無効化したり、独自のキーワードで上書きできます。

{
  "ignoreKeywords": ["i18nIgnore", "en-only"]
}

localizableProperty

型: string

ファイルのローカライズ可否を決定する真偽値を持つフロントマターのプロパティ名。

このプロパティが存在しないか、false とされているファイルはトラッキングされず、true とされているファイルのみがトラッキングされます。また、非真偽値が検出された場合はエラーが発生します。

フロントマターをサポートしないファイルの場合、このオプションは無視され、ファイルはローカライズ可能と見なされます。

このオプションは、フロントマターのメタデータをサポートするファイル形式（例：Markdown、MDX、YAML）を使用しており、徐々にファイルをローカライズ可能にする必要がある場合に推奨されます。特定のファイルが決してローカライズされないことが予想される場合は、最初からトラッキング対象外にするのが良いでしょう。

{
  "localizableProperty": "readyForL10n"
}

outDir

型: string
デフォルト: './dist/lunaria'

lunaria build が最終的なダッシュボードとステータスを出力するディレクトリを設定します。

期待される値は、プロジェクトのルートからの相対パスです。

{
  "outDir": "./lunaria"
}

cloneDir

型: string
デフォルト: './node_modules/.cache/lunaria/history'

シャローリポジトリを使用する際に、Lunaria が一時的な Git 歴史を保存するディレクトリを設定します。

期待される値は、プロジェクトのルートからの相対パスです。

{
  "cloneDir": "./lunaria/history"
}

renderer

型: string

ダッシュボードレンダラーの設定が記述された .(c/m)js または .(c/m)ts ファイルのパスを設定します。

期待される値は、プロジェクトのルートからの相対パスです。

{
  "renderer": "./renderer.config.ts"
}

ダッシュボードオプション

dashboard.title

型: string
デフォルト: 'Localization Status'

ダッシュボードのタイトルを定義します。これはダッシュボードのヘッダーおよびメタタグで使用されます。

{
  "dashboard": {
    "title": "My Project's Localization Status"
  }
}

dashboard.description

型: string
デフォルト: 'Online localization status dashboard of the project'

ダッシュボードの説明を定義します。これはダッシュボードのメタタグで使用されます。

{
  "dashboard": {
    "description": "The localization status dashboard of my project"
  }
}

dashboard.site

型: string

デプロイされたダッシュボードの URL を定義します。これはダッシュボードのメタタグで使用されます。

{
  "dashboard": {
    "site": "https://localization.lunaria.dev/"
  }
}

dashboard.basesToHide

型: string

生成されたダッシュボードのリンクから除外するパスベースの配列。

トラッキング対象ファイルのリンクがディレクトリ構造の深い位置にある場合（例：src/content/docs/file.mdx）、より簡潔なリンクラベル（例：file.mdx）を表示したい場合があります。

{
  "dashboard": {
    "basesToHide": ["src/content/docs/"]
  }
}

dashboard.customCss

型: string

ダッシュボードにインライン化する外部 .css ファイルの相対パスの配列。

{
  "dashboard": {
    "customCss": ["./lunaria/css/theme.css", "./lunaria/css/custom.css"]
  }
}

dashboard.favicon

型: Favicon

生成されたダッシュボードのファビコンを定義します。

external は、以下のプロパティを持つ外部ファビコンの配列を受け入れます：

  • link — 外部ファビコンの URL（例：'https://lunaria.dev/favicon.svg'）。
  • type — 外部リソースの MIME タイプ（例：'image/svg+xml'）。

inline は、ダッシュボードにインライン化される .svg ファイルへの相対パスを受け入れます（例：'./lunaria/favicon.svg'）。

{
  "dashboard": {
    "favicon": {
      "external": [
        {
          "link": "https://lunaria.dev/favicon.svg",
          "type": "image/svg+xml"
        }
      ],
      "inline": "./lunaria/favicon.svg"
    }
  }
}

Favicon

type Favicon = {
  external?: { link: string; type: string }[];
  inline?: string;
};

dashboard.ui

型: Record<string, string>

ダッシュボードの UI 文字列を定義します。特に、lang および dir キーは生成されたダッシュボードで使用される同じ名前の HTML 属性を指し、他のキーはページの UI そのものを直接変更します。

以下のコードサンプルは dashboard.ui に含まれるすべてのキーとそのデフォルト値を示しています：

{
  "dir": "ltr",
  "lang": "en",
  "status.emojiDone": "✔️",
  "status.emojiMissing": "❌",
  "status.emojiOutdated": "🔄",
  "status.done": "done",
  "status.missing": "missing",
  "status.outdated": "outdated",
  "statusByFile.heading": "Localization status by file",
  "statusByFile.tableRowFile": "File",
  "statusByFile.tableSummaryFormat": "{missing_emoji} {missing_word} &nbsp; {outdated_emoji} {outdated_word} &nbsp; {done_emoji} {done_word}",
  "statusByLocale.completeLocalization": "This localization is complete, amazing job! 🎉",
  "statusByLocale.createFileLink": "Create file",
  "statusByLocale.detailsSummaryFormat": "{done_amount} {done_word}, {outdated_amount} {outdated_word}, {missing_amount} {missing_word}",
  "statusByLocale.detailsTitleFormat": "{locale_name} ({locale_tag})",
  "statusByLocale.heading": "Localization progress by locale",
  "statusByLocale.outdatedLocalizationLink": "outdated localization",
  "statusByLocale.sourceChangeHistoryLink": "source change history",
  "statusByLocale.incompleteLocalizationLink": "incomplete localization",
  "statusByLocale.missingKeys": "Missing keys"
}

いくつかの UI 文字列キーは Format で終わっています。これらは中括弧内に動的に挿入されるテキスト（他の UI 文字列からのものもある）を含んでおり、例えば {locale_name} などが該当します。必要に応じて順序を変更したり省略したりできます。