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/ko/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 중국어 문서