配置

Lunaria 允许对其默认行为进行广泛自定义。本参考文档涵盖了 lunaria.config.json 文件中所有可用的配置选项。

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

顶层选项

repository (必需)

类型: Repository

配置仪表板中显示的 Git 托管链接。预期属性包括：

name — 你在 Git 托管平台上的仓库唯一名称，例如 'yanthomasdev/lunaria'。
branch — 跟踪内容的仓库分支名称，默认为 'main'。
rootDir — 如果使用 monorepo，项目根目录路径，例如 '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 — 要跟踪的文件的 glob 模式，例如 'src/content/docs/**/*.mdx'。
ignore — 要忽略的 glob 模式数组，不参与跟踪，默认为 ['node_modules']。
pattern — 文件路径的 path-to-regexp 模式，例如 'src/content/docs/@lang/@path'（@lang 和 @path 是 Lunaria 提供的自定义语法，在更复杂的情况下可替换为标准的 :lang 和 :path 参数）。

文件类型

files 中的每个条目都必须包含一个 type，该类型会改变追踪系统的运作方式、文件在仪表板中的显示方式，并添加新的属性：

`universal`

universal 文件类型使 Lunaria 仅通过 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

定义您仪表板的部署地址，用于仪表板的元标签中。

{
  "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}。您可以根据需要更改顺序或省略这些内容。