跟踪

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"
    }
  ]
}

在此示例中，Lunaria 将跟踪 src/content/docs 目录及其子目录中的所有 Markdown 文件。可以向 files 数组中添加更多条目，以分别跟踪不同的文件集，或更好地组织生成的仪表板，因为数组中的顺序会被保留。

继续阅读以了解这些字段的具体作用。

`location`

location 字段需要一个 glob 模式字符串，用于匹配所有目标语言中需要跟踪的文件。

Lunaria 的 glob 模式由 micromatch 支持。虽然本文档不会详细解释 glob 模式，但以下是一些常见且实用的模式片段：

**/*.md：匹配目录及其子目录下的所有 .md 文件。
*.md：匹配目录下的所有 .md 文件。
**/*.{md,mdx}：匹配目录及其子目录下的所有 .md 和 .mdx 文件。
**/!(index).md：匹配目录及其子目录下的所有 .md 文件，但排除 index.md 文件。

`pattern`

pattern 字段需要一个 path-to-regexp 格式的字符串，用于提取文件的共享路径并推断其关联关系。Lunaria 添加了 @lang 和 @path 占位符，帮助你指定本地化语言和其余路径应插入的位置。

在极少数情况下，@lang 与 @path 可能无法准确反映你的项目文件结构。内部上，这些占位符会被替换为略带偏好的 :lang 与 :path 路径参数。你也可以直接使用这些参数，并通过前缀、后缀和/或修饰符进行调整，以适配项目的实际结构。

例如，为支持 Nextra 独特的 i18n 文件结构，可以使用 :path+ 而非 @path，如下所示：

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

`type`

type 字段决定了 Lunaria 如何处理这些文件。不同类型的文件会影响它们在仪表板中的显示方式、有不同要求（如支持的文件类型），以及其“过时”或“已完成”状态的计算方式。

有关更多信息，请参阅配置参考文档中的文件类型部分。

`ignore`

可选地，可以通过添加 ignore 字段来排除特定文件的跟踪。它接受一个 glob 模式字符串数组，用于匹配需要忽略的文件，例如：

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

精细启用文件的本地化

你可能只想对部分文件启用本地化，例如仅启用源语言中存在超过一周的文件，或那些短期内不会重新设计的文件。

一种实现方式是使用 ignore 字段排除特定文件，但这要求你在每次文件准备就绪时手动更新配置文件。

更优的方式是使用 localizableProperty。此选项适用于支持前端元数据的文件（如 Markdown、MDX、YAML）。只有当该属性值为 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": []
}
```

按文件触发变更

有时，一次提交可能同时包含应触发状态变更的更改和不应触发的更改，特别是在存在文件间的循环引用且必须在同一拉取请求中合并以避免错误的情况下。此时，最佳方案是使用跟踪指令。

跟踪指令是一种添加在提交描述中的自定义语法，格式为以 ; 分隔的文件列表或 glob 模式，这些文件将被跟踪指令识别：

@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