追跡

LunariaはGitを基盤とする独自のローカリゼーション追跡システムを実装しています。このガイドでは、その仕組み、操作方法、および関連するすべての機能について説明します。

仕組み

変更を追跡するために、LunariaはリポジトリのGit履歴を使用して、元のソースファイルとローカライズされたバージョンの最新の主要コミット日時を比較します。ローカライズされたバージョンがソースよりも最後に変更されていれば、更新済みと見なされます。それ以外の場合、古いと見なされます。

「主要コミット」とは、重要なコンテンツ変更があるコミットのことです。主要コミットが追跡対象のブランチにマージされると、Lunariaでステータスの変更が発生します。これらの変更は予測可能であり、以下のいずれかの状態のみになります：

ソースコンテンツが変更された → ローカライズが古いとマークされる。
ローカライズが更新された → 作業完了とマークされる。

デフォルトでは、すべてのコミットが_主要_と見なされます。特定のコミットを主要と見なさないようにするには、Lunariaがステータス変更の操作を提供しています。

追跡の設定

Lunariaの追跡システムにファイルを追加するには、lunaria.config.jsonファイルにfilesフィールドを追加する必要があります。このフィールドにはFile型のオブジェクトの配列が渡されます。次の例のように記述します：

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

この例では、src/content/docsディレクトリおよびそのサブディレクトリ内のすべてのMarkdownファイルを追跡します。filesにさらにエントリを追加することで、異なる種類のファイルセットを別々に追跡したり、生成されたダッシュボードでの整理をより良くできます（配列内の順序が尊重されるため）。

以降、各フィールドの動作について詳しく説明します。

`location`

locationフィールドには、すべてのロケール内で追跡したいファイルに一致するグロブパターン文字列を指定します。

Lunariaのグロブパターンはmicromatchで構成されており、ここではグロブパターンの詳細を説明しませんが、以下のようなよく使うスニペットを覚えておくと便利です：

**/*.md: ディレクトリおよびそのサブディレクトリ内のすべての.mdファイルに一致。
*.md: ディレクトリ内のすべての.mdファイルに一致。
**/*.{md,mdx}: ディレクトリおよびそのサブディレクトリ内のすべての.mdおよび.mdxファイルに一致。
**/!(index).md: ディレクトリおよびそのサブディレクトリ内のすべての.mdファイルに一致（ただしindex.mdファイルを除く）。

`pattern`

patternフィールドには、path-to-regexp文字列を指定し、ファイル間の共通パスを抽出して関係性を推定するために使用します。ローカル化の場所と残りのパスの位置を示すために、@langと@pathというプレースホルダを用意しています。

極めて稀なケースにおいて、@langと@pathがプロジェクトのファイル構造を正しく表現できない場合があります。内部的には、これらのプレースホルダはやや主観的な:langおよび:pathパスパラメータに置き換えられます。代わりに、プレフィックス、サフィックス、またはモディファイアを使ってこれらのパラメータを調整し、プロジェクトのファイル構造に合わせることも可能です。

たとえば、非常に独特なi18n構造を持つNextraに対応するには、@pathの代わりに:path+を使用した次のパターンが使えます：

{
  "files": [
    {
      "location": "pages/**/*.mdx",
      "pattern": "pages/:[email protected]",
      "type": "universal"
    }
  ]
}

`type`

typeフィールドは、これらのファイルがLunariaによってどのように扱われるかを決定します。異なるタイプは、ダッシュボードでのファイルの表示方法、さまざまな要件（例：サポートされるファイル形式）、および「古くなった／完了した」ステータスの計算方法を変更・拡張することができます。

詳しくは、構成リファレンスのファイルタイプセクションをご覧ください。

`ignore`

オプションとして、ignoreフィールドを追加して特定のファイルを追跡から除外できます。このフィールドには、無視したいファイルに一致するグロブパターン文字列の配列を指定します。たとえば：

{
  "files": [
    {
      "location": "src/content/docs/**/*.md",
      "pattern": "src/content/docs/@lang/@path",
      "type": "universal",
      "ignore": ["src/content/docs/**/old.md"]
    }
  ]
}

ローカライズ向けに個別ファイルを有効化

特定のファイルだけをローカライズ対象にする必要がある場合があります。たとえば、ソースロケールで1週間以上経過したファイル、あるいはすぐ再構成される予定のないファイルなどです。

このような場合、ignoreフィールドで特定のファイルを除外する方法もありますが、それがローカライズ対象になった度に手動で構成ファイルを更新する必要があります。

代わりに、フロントマター形式のメタデータ（例：Markdown、MDX、YAML）を受け入れるファイルに利用可能なlocalizablePropertyを使用できます。このプロパティがtrueであるファイルだけがダッシュボードに追加され、そうでない場合は除外されます。

lunaria.config.jsonファイルにlocalizablePropertyフィールドを追加し、ローカライズを有効化するために使用するフロントマターのプロパティ名を指定します：
lunaria.config.json
```
{
  "localizableProperty": "isLocalizable"
}
```
ローカライズを有効にしたいファイルに、値をtrueとしたフロントマターのプロパティを追加します：
my-page.mdx
```
---
title: 私のページ
isLocalizable: true
---

# 私のMDXページ
```

ステータス変更の制御

まれに、望ましくないステータス変更が発生するのを防ぐために追跡システムに介入することが重要です。

たとえば、ソースコンテンツ内のスペルミス修正のような変更は、ローカライズを「古い」とマークすべきではない場合や、すでに古い状態のローカライズ内にある破損リンクの更新は、「完了」とマークすべきではない場合などです。

コミットの無視

コミット内のすべての変更を無視するには、コミットまたはプルリクエストのタイトルにignoreKeywordを追加できます（スクイーズマージ時）。デフォルトでは、キーワードfix typoおよびlunaria-ignoreは無視されます。

たとえば、次のコミットタイトルは無視されます：

[lunaria-ignore] ローカライズファイルのフォーマット

一方、次のコミットタイトルはステータス変更を引き起こします：

`getting-started.mdx`ファイルに新しいセクションを追加

カスタムのignoreKeywordsを追加することもでき、デフォルトのキーワードを上書きできます：

lunaria.config.jsonファイルにignoreKeywordsフィールドを追加し、無視するキーワードの配列を指定します：
lunaria.config.json
```
{
  "ignoreKeywords": ["@ignore", "[ci]", "[format]"]
}
```

ignoreKeywords機能は完全に無効化することもできます：

lunaria.config.jsonファイルにignoreKeywordsフィールドを追加し、空の配列を指定します：
lunaria.config.json
```
{
  "ignoreKeywords": []
}
```

ファイル単位での変更のトリガー

あるコミットに、ステータス変更を引き起こすべき変更と、そうでない変更が混在している場合があります。特に、エラーを回避するために同じプルリクエスト内に配置しなければならない循環参照がある場合などです。このような場合、最適な選択肢はトラッカー指令を使うことです。

トラッカー指令は、コミットの説明に追加されるカスタム構文で、;で区切られたファイル名またはグロブのリストを含み、トラッカーがこれらの変更を評価する対象となります：

@lunaria-ignore:docs/en/first.mdx;docs/ja/second.mdx;docs/**/third.mdx

`@lunaria-track`

@lunaria-track指令は、リストされたすべてのファイルの変更を追跡し、同じコミットに含まれていない変更は無視します。

例：

@lunaria-track:src/content/docs/en/**.mdx

`@lunaria-ignore`

@lunaria-ignore指令は、リストされたすべてのファイルの変更を無視し、同じコミットに含まれていない変更は追跡します。

例：

@lunaria-ignore:src/content/docs/ja/**.mdx