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

说明：

列出项目支持的所有语言
包含源语言和所有目标语言

语言代码规范：

格式	示例	说明
两字母代码	`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`	仪表板界面语言
`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/zh-cn/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"
    }
  ]
}

混合格式项目

一个项目可以同时追踪多种文件格式：

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

实战：配置一个多语言文档项目

让我们通过一个完整的实战案例，配置一个支持四种语言的文档项目。

项目结构

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'], // 开发环境只追踪两种语言
  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 韩文文档