开源项目本地化太难？LunariaJS 让翻译管理变得简单

你的开源项目支持几种语言？翻译文件是如何管理的？每次源文档更新后，你能快速知道哪些翻译需要同步吗？

如果你是一名开源项目维护者，这些问题一定让你头疼过。多语言支持是提升项目影响力的关键，但翻译管理却常常成为维护者的噩梦。今天，我要介绍一个正在改变这一切的工具 —— LunariaJS。

💡 官方文档：LunariaJS 中文文档

开发者的本地化痛点

让我们先看看开源项目本地化过程中常见的问题：

痛点一：翻译进度不可见

“中文文档翻译到哪了？日文版本还差多少？韩文翻译是否跟上了最新更新？”

这些问题通常需要手动检查每个翻译文件，或者建立一个复杂的表格来追踪。当项目支持的语言越来越多，追踪变得愈发困难。

痛点二：过时翻译难以发现

源文档更新了，但对应的翻译文件没有同步更新。结果就是：用户看到的是过时的翻译内容，与最新的源文档不一致。更糟糕的是，维护者往往不知道哪些翻译已经过时。

痛点三：协作翻译缺乏工具支持

社区贡献者想要帮忙翻译，但不知道哪些文件需要翻译，哪些已经有人认领了。结果就是重复翻译、遗漏翻译，甚至翻译冲突。

痛点四：CI/CD 集成复杂

想要在 CI/CD 流水线中自动检查翻译完整性？你需要自己写脚本、解析文件、对比内容。每个项目的实现方式都不一样，维护成本很高。

这些问题的根源在于：缺乏一个专门为开源项目设计的本地化管理工具。

LunariaJS 是什么？

LunariaJS 是一款开源的本地化管理工具链，专为开源项目设计。

它由两个核心包组成：

包名	用途	说明
`@lunariajs/core`	核心库	提供本地化管理的基础功能，包括文件解析、状态追踪、仪表板生成
`@lunariajs/starlight`	Starlight 集成	与 Astro Starlight 文档框架无缝集成，一键添加本地化管理功能

与传统翻译工具的区别

你可能会问：Crowdin、Transifex、Weblate 这些工具不是已经存在了吗？

没错，但 LunariaJS 与它们有本质区别：

特性	传统翻译平台	LunariaJS
部署方式	云服务	本地运行 / 自托管
费用	通常收费	完全免费开源
Git 集成	需要配置同步	原生基于 Git
翻译方式	在线编辑器	Git 工作流
适用场景	专业翻译团队	开源社区协作

LunariaJS 的核心理念是：翻译也是代码的一部分，应该用 Git 来管理。

这意味着：

翻译文件直接存储在代码仓库中
翻译更新通过 Pull Request 提交
翻译状态通过 Git 提交历史追踪
完全融入现有的开发工作流

核心特性一览

1. 基于 Git 的工作流追踪

LunariaJS 利用 Git 的提交历史来追踪翻译状态：

自动检测源文件变更：当源语言文件更新时，自动标记相关翻译需要同步
时间戳对比：通过对比源文件和翻译文件的最后修改时间，判断翻译是否过时
提交关联：每个翻译状态都关联到具体的 Git 提交，方便追溯

2. 可视化本地化仪表板

LunariaJS 会生成一个漂亮的静态仪表板，让你一眼看清整个项目的翻译状态：

整体进度统计：每种语言的翻译完成百分比
文件状态列表：每个文件的翻译状态一目了然
状态筛选：快速筛选出需要处理的文件

3. 三种翻译状态

每个翻译文件都有明确的状态标识：

状态	含义	显示颜色
Done（完成）	翻译已完成且与源文件同步	🟢 绿色
Outdated（过时）	翻译存在但源文件已更新	🟡 黄色
Missing（缺失）	翻译文件不存在	🔴 红色

4. 多格式支持

LunariaJS 支持常见的本地化文件格式：

JSON：最常用的格式，兼容性最好
YAML：可读性强，适合手写维护
CSV：方便非技术人员编辑

5. Astro Starlight 无缝集成

如果你使用 Astro Starlight 构建文档站点，LunariaJS 可以完美集成：

一键安装配置
仪表板直接嵌入文档站点
与 Starlight 的 i18n 路由无缝配合

5 分钟快速上手

让我们用最简单的方式体验 LunariaJS 的核心功能。

环境准备

确保你的项目满足以下条件：

Node.js 18.0.0 或更高版本
项目使用 Git 进行版本控制
有本地化文件需要管理

安装 LunariaJS

# 使用 npm
npm install @lunariajs/core

# 使用 yarn
yarn add @lunariajs/core

# 使用 pnpm
pnpm add @lunariajs/core

初始化配置

运行初始化命令，生成配置文件：

npx lunaria init

这个命令会在项目根目录创建 lunaria.config.json 文件。

配置文件示例

一个基础的配置文件如下：

{
  "sourceLanguage": "en",
  "languages": ["en", "zh-cn", "ja", "ko"],
  "files": [
    {
      "sourcePath": "docs/{slug}.md",
      "localizationPath": "i18n/{lang}/docs/{slug}.md"
    }
  ],
  "dashboard": {
    "outputDir": "lunaria-dashboard"
  }
}

配置说明：

sourceLanguage：源语言（通常是英语）
languages：所有支持的语言列表
files：需要追踪的文件模式
dashboard：仪表板输出配置

构建仪表板

运行构建命令生成仪表板：

npx lunaria build

预览仪表板

启动本地预览服务器：

npx lunaria preview

打开浏览器访问 http://localhost:3000，你就能看到项目的本地化仪表板了！

仪表板会显示：

每种语言的翻译完成度
每个文件的翻译状态（完成/过时/缺失）
源文件和翻译文件的最后更新时间

谁适合使用 LunariaJS？

开源项目维护者

如果你维护一个需要多语言支持的开源项目，LunariaJS 可以帮你：

自动追踪翻译状态，无需手动维护表格
快速识别过时翻译，及时提醒贡献者更新
为社区贡献者提供清晰的翻译任务列表

文档站点开发者

如果你使用 Astro Starlight 构建文档站点，LunariaJS 是最佳选择：

与 Starlight 完美集成
仪表板可以直接嵌入文档站点
支持多语言路由

国际化/本地化工程师

如果你负责项目的本地化工作，LunariaJS 提供：

可视化的翻译进度监控
基于 Git 的协作翻译流程
CI/CD 集成能力

翻译团队负责人

如果你管理一个翻译团队，LunariaJS 帮你：

清晰分配翻译任务
追踪团队工作进度
确保翻译与源文档同步

LunariaJS vs 其他工具

特性	LunariaJS	Crowdin	Transifex	i18next
开源免费	✅	❌	❌	✅
Git 工作流	✅ 原生支持	⚠️ 需配置	⚠️ 需配置	❌
可视化仪表板	✅	✅	✅	❌
翻译状态追踪	✅	✅	✅	❌
CI/CD 集成	✅	✅	✅	⚠️
自托管	✅	❌	❌	✅
学习成本	低	中	中	低

实际案例

Astro 官方文档

Astro 框架的官方文档就是使用 LunariaJS 管理多语言翻译的。通过 LunariaJS，Astro 团队可以：

清晰地看到每种语言的翻译进度
快速识别需要更新的翻译
方便社区贡献者参与翻译

💡 推荐阅读：LunariaJS 中文文档了解更多实际应用案例

总结

LunariaJS 是一款专为开源项目设计的本地化管理工具链，核心优势包括：

特性	价值
基于 Git 的追踪	无需额外学习，融入现有工作流
可视化仪表板	一眼看懂翻译进度
状态自动检测	自动识别过时和缺失翻译
多格式支持	JSON/YAML/CSV 任你选择
Astro Starlight 集成	文档站点最佳选择
完全开源免费	无任何使用成本

一句话总结：开源项目本地化太难？LunariaJS 让翻译管理变得简单。

下一步

想深入了解 LunariaJS 的详细用法？欢迎访问 LunariaJS 中文文档，获取：

完整的配置选项说明
CLI 命令详细用法
Astro Starlight 集成指南
CI/CD 集成最佳实践

在接下来的系列文章中，我们将逐一深入每个主题：

第 2 篇：安装配置完全指南
第 3 篇：CLI 命令详解
第 4 篇：本地化仪表板使用
第 5 篇：Git 工作流集成
第 6 篇：与 Astro Starlight 集成
第 7 篇：CI/CD 集成实战
第 8 篇：@lunariajs/core 深度解析
第 9 篇：高级配置与自定义策略
第 10 篇：完整实战指南

下一篇文章，我们将详细讲解 LunariaJS 的安装和配置，手把手教你从零搭建本地化工作流，敬请期待！

💡 推荐阅读：

LunariaJS 中文文档

LunariaJS 英文文档

LunariaJS 日文文档

LunariaJS 韩文文档