Open Source Localization Too Hard? LunariaJS Makes Translation Management Simple

How many languages does your open source project support? How are translation files managed? After each source document update, can you quickly know which translations need to be synced?

If you’re an open source project maintainer, these questions have likely given you headaches. Multilingual support is key to increasing project reach, but translation management often becomes a maintainer’s nightmare. Today, I want to introduce a tool that’s changing all that — LunariaJS.

💡 Official Documentation: LunariaJS Documentation

Developer Localization Pain Points

Let’s first look at common issues in open source project localization:

Pain Point 1: Invisible Translation Progress

“How far along is the Chinese documentation? How much is left for the Japanese version? Has Korean translation kept up with recent updates?”

These questions usually require manually checking each translation file or maintaining a complex spreadsheet. As the project supports more and more languages, tracking becomes increasingly difficult.

Pain Point 2: Hard to Detect Outdated Translations

The source document gets updated, but the corresponding translation file isn’t synced. The result: users see outdated translated content that’s inconsistent with the latest source. Worse yet, maintainers often don’t know which translations have become outdated.

Pain Point 3: Lack of Tool Support for Collaborative Translation

Community contributors want to help with translations but don’t know which files need translation or which are already claimed. The result: duplicate translations, missed translations, and even translation conflicts.

Pain Point 4: Complex CI/CD Integration

Want to automatically check translation completeness in your CI/CD pipeline? You need to write your own scripts, parse files, compare content. Every project implements it differently, with high maintenance costs.

The root cause of these problems: lack of a localization management tool designed specifically for open source projects.

What is LunariaJS?

LunariaJS is an open-source localization management toolchain designed specifically for open source projects.

It consists of two core packages:

Package	Purpose	Description
@lunariajs/core	Core library	Provides basic localization management functionality including file parsing, status tracking, dashboard generation
@lunariajs/starlight	Starlight integration	Seamless integration with Astro Starlight documentation framework, adding localization management with one click

Difference from Traditional Translation Tools

You might ask: Don’t Crowdin, Transifex, and Weblate already exist?

Yes, but LunariaJS is fundamentally different from them:

Feature	Traditional Translation Platforms	LunariaJS
Deployment	Cloud service	Local / Self-hosted
Cost	Usually paid	Completely free and open source
Git Integration	Requires sync configuration	Native Git-based
Translation Method	Online editor	Git workflow
Use Case	Professional translation teams	Open source community collaboration

LunariaJS’s core philosophy: translations are part of the code and should be managed with Git.

This means:

• Translation files are stored directly in the code repository
• Translation updates are submitted via Pull Request
• Translation status is tracked through Git commit history
• Fully integrated into existing development workflows

Core Features Overview

1. Git-based Workflow Tracking

LunariaJS leverages Git commit history to track translation status:

• Automatic source file change detection: When source language files are updated, related translations are automatically flagged for syncing
• Timestamp comparison: Determines if translations are outdated by comparing last modified times of source and translation files
• Commit association: Each translation status links to specific Git commits for traceability

2. Visual Localization Dashboard

LunariaJS generates a beautiful static dashboard showing the entire project’s translation status at a glance:

• Overall progress statistics: Translation completion percentage for each language
• File status list: Translation status for each file at a glance
• Status filtering: Quickly filter files that need attention

3. Three Translation States

Each translation file has a clear status indicator:

Status	Meaning	Display Color
Done	Translation complete and synced with source	Green
Outdated	Translation exists but source has been updated	Yellow
Missing	Translation file doesn’t exist	Red

4. Multiple Format Support

LunariaJS supports common localization file formats:

• JSON: Most commonly used format, best compatibility
• YAML: Strong readability, suitable for manual maintenance
• CSV: Easy for non-technical personnel to edit

5. Astro Starlight Seamless Integration

If you use Astro Starlight to build documentation sites, LunariaJS integrates perfectly:

• One-click installation and configuration
• Dashboard embedded directly in documentation site
• Seamless coordination with Starlight’s i18n routing

5-Minute Quick Start

Let’s experience LunariaJS’s core features in the simplest way possible.

Environment Preparation

Ensure your project meets these conditions:

• Node.js 18.0.0 or higher
• Project uses Git for version control
• Has localization files to manage

Install LunariaJS

# Using npm
npm install @lunariajs/core

# Using yarn
yarn add @lunariajs/core

# Using pnpm
pnpm add @lunariajs/core

Initialize Configuration

Run the initialization command to generate the configuration file:

npx lunaria init

This command creates a lunaria.config.json file in the project root.

Configuration File Example

A basic configuration file looks like this:

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

Configuration explanation:

• sourceLanguage: Source language (usually English)
• languages: List of all supported languages
• files: File patterns to track
• dashboard: Dashboard output configuration

Build Dashboard

Run the build command to generate the dashboard:

npx lunaria build

Preview Dashboard

Start the local preview server:

npx lunaria preview

Open your browser and visit http://localhost:3000 to see your project’s localization dashboard!

The dashboard will show:

• Translation completion for each language
• Translation status for each file (done/outdated/missing)
• Last update time for source and translation files

Who Should Use LunariaJS?

Open Source Project Maintainers

If you maintain an open source project that needs multilingual support, LunariaJS can help you:

• Automatically track translation status without manually maintaining spreadsheets
• Quickly identify outdated translations and timely remind contributors to update
• Provide clear translation task lists for community contributors

Documentation Site Developers

If you use Astro Starlight to build documentation sites, LunariaJS is the best choice:

• Perfect integration with Starlight
• Dashboard can be embedded directly in documentation site
• Supports multilingual routing

Internationalization/Localization Engineers

If you’re responsible for project localization work, LunariaJS provides:

• Visual translation progress monitoring
• Git-based collaborative translation workflow
• CI/CD integration capabilities

Translation Team Leaders

If you manage a translation team, LunariaJS helps you:

• Clearly assign translation tasks
• Track team work progress
• Ensure translations stay synced with source documents

LunariaJS vs Other Tools

Feature	LunariaJS	Crowdin	Transifex	i18next
Open source & free	Yes	No	No	Yes
Git workflow	Native support	Requires config	Requires config	No
Visual dashboard	Yes	Yes	Yes	No
Translation status tracking	Yes	Yes	Yes	No
CI/CD integration	Yes	Yes	Yes	Partial
Self-hosted	Yes	No	No	Yes
Learning curve	Low	Medium	Medium	Low

Real-World Examples

Astro Official Documentation

Astro framework’s official documentation uses LunariaJS to manage multilingual translations. Through LunariaJS, the Astro team can:

• Clearly see translation progress for each language
• Quickly identify translations that need updating
• Make it easy for community contributors to participate in translation

💡 Recommended Reading: LunariaJS Documentation for more real-world application examples

Summary

LunariaJS is a localization management toolchain designed for open source projects, with core advantages including:

Feature	Value
Git-based tracking	No extra learning required, integrates into existing workflows
Visual dashboard	Understand translation progress at a glance
Automatic status detection	Automatically identifies outdated and missing translations
Multiple format support	JSON/YAML/CSV - your choice
Astro Starlight integration	Best choice for documentation sites
Completely free and open source	No usage costs

In one sentence: Open source localization too hard? LunariaJS makes translation management simple.

Next Steps

Want to learn more about LunariaJS in detail? Visit LunariaJS Documentation for:

• Complete configuration options reference
• Detailed CLI command usage
• Astro Starlight integration guide
• CI/CD integration best practices

In the upcoming series of articles, we’ll dive deep into each topic:

1. Part 2: Complete Installation and Configuration Guide
2. Part 3: CLI Commands Detailed
3. Part 4: Localization Dashboard Usage
4. Part 5: Git Workflow Integration
5. Part 6: Astro Starlight Integration
6. Part 7: CI/CD Integration in Practice
7. Part 8: @lunariajs/core Deep Dive
8. Part 9: Advanced Configuration and Custom Strategies
9. Part 10: Complete Practical Guide

In the next article, we’ll explain in detail how to install and configure LunariaJS, guiding you step-by-step to build a localization workflow from scratch. Stay tuned!

---

💡 Recommended Reading:

• LunariaJS Documentation
• LunariaJS Chinese Documentation
• LunariaJS Japanese Documentation
• LunariaJS Korean Documentation