LunariaJS Installation and Configuration Complete Guide - Building a Localization Workflow from Scratch

In the previous article, we introduced LunariaJS’s core concepts and quick start. Today, let’s explore how to properly install and configure LunariaJS to build a complete localization workflow for your project.

💡 Official Documentation: LunariaJS Documentation - Configuration

Installation Methods Comparison

Package Manager Selection

LunariaJS supports all mainstream JavaScript package managers:

Package Manager	Installation Command	Recommended Use Case
npm	`npm install @lunariajs/core`	Node.js default, most stable
yarn	`yarn add @lunariajs/core`	Large projects, dependency management optimization
pnpm	`pnpm add @lunariajs/core`	Monorepo, disk space sensitive
bun	`bun add @lunariajs/core`	Pursuing extreme installation speed

Global vs Project Installation

Recommended: Project Installation

# Recommended: Install as dev dependency
npm install -D @lunariajs/core

Advantages:

Configuration synced with code version
Team members use the same version
CI/CD environment consistency

Not Recommended: Global Installation

# Not recommended
npm install -g @lunariajs/core

Disadvantages:

Version may be inconsistent
Configuration files separate from code
CI/CD environment requires extra configuration

Version Selection Recommendations

// package.json
{
  "devDependencies": {
    // Lock major version number
    "@lunariajs/core": "^0.4.0",
    // If using Astro Starlight
    "@lunariajs/starlight": "^0.4.0"
  }
}

Recommendations:

Use semantic versioning (SemVer)
Lock major version number (^0.x.x or ~0.x.x)
Follow GitHub Releases for updates

Configuration File Structure Analysis

LunariaJS uses lunaria.config.json as the configuration file (also supports .js and .ts formats).

Configuration File Location

The configuration file should be placed in the project root directory:

your-project/
├── lunaria.config.json    # LunariaJS configuration
├── package.json
├── src/
└── ...

Complete Configuration Example

Here’s a complete configuration example with all common options:

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

Configuration Options Details

1. sourceLanguage (Source Language)

{
  "sourceLanguage": "en"
}

Description:

Specifies the project’s source language (original content language)
Other languages are translated from this language
Usually set to en (English)

Notes:

Language codes should use BCP 47 standard format
Should correspond to one of the values in the languages array
Source language files won’t be marked as “missing” or “outdated”

2. languages (Supported Languages List)

{
  "languages": ["en", "zh-cn", "ja", "ko", "es", "fr"]
}

Description:

Lists all languages supported by the project
Includes both source language and all target languages

Language Code Standards:

Format	Example	Description
Two-letter code	`en`, `ja`, `ko`	ISO 639-1 standard
With region code	`zh-cn`, `zh-tw`, `pt-br`	Includes country/region
Full format	`en-us`, `en-gb`	Most precise, distinguishes dialects

Best Practices:

Keep consistent with existing i18n framework language codes
Use lowercase format (zh-cn not zh-CN)
Order by translation completeness or importance

3. files (File Pattern Configuration)

This is the most important configuration item, defining which files to track:

{
  "files": [
    {
      "sourcePath": "docs/{slug}.md",
      "localizationPath": "i18n/{lang}/docs/{slug}.md"
    }
  ]
}

Parameter Description:

Parameter	Required	Description
`sourcePath`	Yes	Path pattern for source language files
`localizationPath`	Yes	Path pattern for translation files
`include`	No	File glob patterns to include
`exclude`	No	File glob patterns to exclude

Path Placeholders:

Placeholder	Description	Example
`{slug}`	File identifier (without extension)	`getting-started`
`{lang}`	Language code	`zh-cn`, `ja`
`{ext}`	File extension	`md`, `json`

Multiple File Pattern Configuration:

{
  "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 Configuration)

{
  "dashboard": {
    "outputDir": "lunaria-dashboard",
    "title": "My Project i18n Status",
    "description": "Track our translation progress"
  }
}

Parameter Description:

Parameter	Default	Description
`outputDir`	`lunaria-dashboard`	Dashboard output directory
`title`	Project name	Dashboard title
`description`	-	Dashboard description
`uiLanguage`	`en`	Dashboard interface language
`site`	-	Dashboard site URL (for SEO)

Localization File Format Support

JSON Format

Most commonly used format, best compatibility:

// 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": "Welcome to our project",
  "description": "This is a sample project",
  "nav": {
    "home": "Home",
    "about": "About",
    "contact": "Contact"
  }
}

Configuration Example:

{
  "files": [
    {
      "sourcePath": "locales/en/{slug}.json",
      "localizationPath": "locales/{lang}/{slug}.json"
    }
  ]
}

YAML Format

Better readability, suitable for manual maintenance:

# locales/en/common.yaml
welcome: Welcome to our project
description: This is a sample project
nav:
  home: Home
  about: About
  contact: Contact

Configuration Example:

{
  "files": [
    {
      "sourcePath": "locales/en/{slug}.yaml",
      "localizationPath": "locales/{lang}/{slug}.yaml"
    }
  ]
}

Markdown Format

Suitable for documentation projects:

<!-- docs/en/getting-started.md -->
---
title: Getting Started
---

# Getting Started

Welcome to our project! This guide will help you...

Configuration Example:

{
  "files": [
    {
      "sourcePath": "docs/{slug}.md",
      "localizationPath": "docs/{lang}/{slug}.md"
    }
  ]
}

Mixed Format Projects

A project can track multiple file formats simultaneously:

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

Practical: Configuring a Multilingual Documentation Project

Let’s configure a documentation project supporting four languages through a complete hands-on example.

Project Structure

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

Step 1: Install Dependencies

npm install -D @lunariajs/core

Step 2: Create Configuration File

npx lunaria init

Step 3: Edit Configuration File

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

Step 4: Verify Configuration

Run the following command to verify the configuration is correct:

npx lunaria build

If there are no error outputs, the configuration is correct.

Step 5: View Dashboard

npx lunaria preview

Visit http://localhost:3000 to see the generated dashboard.

Common Configuration Errors and Solutions

Error 1: Incorrect Path Configuration

Error:

Error: No matching files found for pattern "docs/{slug}.md"

Solution:

Check that paths are relative to the project root directory
Ensure {slug} placeholder is used correctly
Verify files actually exist

// Wrong
{
  "sourcePath": "docs/{slug}"  // Missing extension
}

// Correct
{
  "sourcePath": "docs/{slug}.md"
}

Error 2: Inconsistent Language Codes

Error: Translation status displays abnormally, some languages always show as missing.

Solution:

Ensure all configurations use the same language code format
Check that file directory names match the configuration

// Using zh-cn in configuration
{
  "languages": ["en", "zh-cn"]
}

// But file directory uses zh-CN (wrong)
// i18n/zh-CN/docs/...

// Should use (correct)
// i18n/zh-cn/docs/...

Error 3: Source Language Files Missing

Error: All translations are marked as “outdated”.

Solution:

Ensure source language files exist
Check that sourcePath configuration is correct

Error 4: Exclude Rules Not Working

Error: Files in the draft folder are still being tracked.

Solution:

{
  "files": [
    {
      "sourcePath": "docs/{slug}.md",
      "localizationPath": "i18n/{lang}/docs/{slug}.md",
      "exclude": ["**/draft/**", "**/.*/**"]
    }
  ]
}

Configuration Best Practices

1. Use TypeScript Configuration

For complex projects, TypeScript configuration is recommended:

// 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',
  },
});

Advantages:

Type checking
IDE auto-completion
Better maintainability

2. Environment Variable Configuration

For CI/CD environments or different environment configurations:

// 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'], // Only track two languages in development environment
  files: [
    {
      sourcePath: 'src/content/docs/{slug}.md',
      localizationPath: 'i18n/{lang}/docs/{slug}.md',
    },
  ],
});

3. Configuration File Version Control

# .gitignore
# Don't ignore the configuration file
# !lunaria.config.json

# But you can ignore the generated dashboard
lunaria-dashboard/

4. Integration with package.json scripts

// package.json
{
  "scripts": {
    "lunaria:init": "lunaria init",
    "lunaria:build": "lunaria build",
    "lunaria:preview": "lunaria preview",
    "i18n:check": "lunaria build && lunaria preview"
  }
}

Configuration Verification Checklist

After completing configuration, verify with this checklist:

Source language and target language list are correct
File path patterns match actual directory structure
All supported languages have corresponding translation directories
{slug} placeholder is used correctly
dashboard.outputDir doesn’t conflict with existing directories
Running lunaria build produces no errors
Dashboard correctly displays all files and languages

Summary

This article covered LunariaJS installation and configuration in detail. Key points:

Point	Description
Installation method	Recommended to install as dev dependency in project
Configuration file	`lunaria.config.json` in project root directory
Core configuration	`sourceLanguage`, `languages`, `files`
File formats	Supports JSON, YAML, Markdown
Path placeholders	`{slug}`, `{lang}`, `{ext}`
Best practices	Use TypeScript configuration, environment variables, version control

Next Steps

After completing configuration, the next article will cover LunariaJS CLI commands in detail, including:

Interactive initialization with lunaria init
Build options for lunaria build
Preview functionality of lunaria preview
Command combination usage scenarios

Stay tuned!

💡 Recommended Reading:

LunariaJS Documentation

LunariaJS Configuration Reference

LunariaJS Chinese Documentation

LunariaJS Japanese Documentation

LunariaJS Korean Documentation