LunariaJS 완전 실전: 기업급 다국어 문서 플랫폼 구축하기

LunariaJS 시리즈의 아홉 편의 글을 완료하신 것을 축하드립니다! 오늘은 배운 모든 지식을 종합적으로 활용하여 처음부터 완전한 기업급 다국어 문서 플랫폼을 구축해 보겠습니다. 이 글은 본 시리즈의 마지막 글이자, 여러분의 학습 성과를 검증하는 최고의 실천 편입니다.

💡 공식 문서: LunariaJS 한국어 문서

프로젝트 계획

요구사항 분석

프로젝트 배경: 오픈소스 프로젝트를 위한 다국어 문서 사이트 구축이 필요하며, 요구 사항은:

요구 사항	설명	우선순위
다국어 지원	중국어, 일본어, 한국어 네 가지 언어 지원	높음
번역 상태 시각화	실시간 번역 진행 상황 추적	높음
팀 협업	커뮤니티 기여자의 번역 참여 지원	높음
자동화	CI/CD 자동 빌드 및 배포	중간
성능 최적화	빠른 로딩 및 응답	중간
SEO 최적화	검색 엔진 친화적	중간

기술 선택

요구사항 분석에 기반하여 다음 기술 스택을 선택합니다:

기술	용도	선택 이유
Astro 5.0	프레임워크	고성능, SEO 친화적
Starlight	문서 테마	즉시 사용 가능한 문서 솔루션
LunariaJS	번역 관리	Git 기반 워크플로우, 시각화 대시보드
GitHub Actions	CI/CD	GitHub와 깊은 통합
Vercel	호스팅	빠른 배포, 엣지 네트워크

아키텍처 설계

┌─────────────────────────────────────────────────────────────────────┐
│                         사용자 계층                                  │
│                    (개발자/기여자/독자)                               │
├─────────────────────────────────────────────────────────────────────┤
│                       접근 계층                                      │
│   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐              │
│   │ 문서 사이트  │   │ 번역 대시보드│   │  GitHub Repo │              │
│   │ (Vercel)    │   │ (Vercel)    │   │             │              │
│   └─────────────┘   └─────────────┘   └─────────────┘              │
├─────────────────────────────────────────────────────────────────────┤
│                       애플리케이션 계층                               │
│   ┌─────────────────────────────────────────────────────────────┐   │
│   │                    Astro + Starlight                        │   │
│   │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │   │
│   │  │  콘텐츠 관리 │  │  i18n 라우팅 │  │  검색 기능   │        │   │
│   │  └─────────────┘  └─────────────┘  └─────────────┘        │   │
│   └─────────────────────────────────────────────────────────────┘   │
│   ┌─────────────────────────────────────────────────────────────┐   │
│   │                      LunariaJS                              │   │
│   │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │   │
│   │  │  상태 추적   │  │  대시보드   │  │  Git 통합   │        │   │
│   │  │             │  │    생성     │  │             │        │   │
│   │  └─────────────┘  └─────────────┘  └─────────────┘        │   │
│   └─────────────────────────────────────────────────────────────┘   │
├─────────────────────────────────────────────────────────────────────┤
│                       인프라 계층                                    │
│   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐              │
│   │  Git        │   │ GitHub      │   │ CI/CD       │              │
│   │  (버전 관리) │   │ (코드 호스팅)│   │ (자동화)     │              │
│   └─────────────┘   └─────────────┘   └─────────────┘              │
└─────────────────────────────────────────────────────────────────────┘

기술 스택 구축

단계 1: 프로젝트 초기화

# Starlight 템플릿으로 프로젝트 생성
npm create astro@latest my-docs -- --template starlight

# 프로젝트 디렉토리로 이동
cd my-docs

# LunariaJS 설치
npm install @lunariajs/starlight

# Git 초기화 (아직 안 한 경우)
git init
git add .
git commit -m "Initial commit"

단계 2: Astro 설정

// astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import lunaria from '@lunariajs/starlight';

// 언어 설정
const languages = ['en', 'zh-cn', 'ja', 'ko'];
const sourceLanguage = 'en';
const languageLabels = {
  en: 'English',
  'zh-cn': '简体中文',
  ja: '日本語',
  ko: '한국어',
};

export default defineConfig({
  site: 'https://docs.example.com',

  integrations: [
    starlight({
      title: 'My Project Documentation',
      defaultLocale: sourceLanguage,

      locales: Object.fromEntries(
        languages.map(lang => [
          lang,
          { label: languageLabels[lang], lang }
        ])
      ),

      sidebar: {
        en: [
          { label: 'Home', link: '/' },
          {
            label: 'Getting Started',
            items: [
              { label: 'Introduction', link: '/introduction/' },
              { label: 'Installation', link: '/installation/' },
              { label: 'Quick Start', link: '/quick-start/' },
            ],
          },
        ],
        'zh-cn': [
          { label: '首页', link: '/' },
          {
            label: '快速开始',
            items: [
              { label: '简介', link: '/introduction/' },
              { label: '安装', link: '/installation/' },
              { label: '快速上手', link: '/quick-start/' },
            ],
          },
        ],
        ja: [
          { label: 'ホーム', link: '/' },
          {
            label: 'はじめに',
            items: [
              { label: '概要', link: '/introduction/' },
              { label: 'インストール', link: '/installation/' },
              { label: 'クイックスタート', link: '/quick-start/' },
            ],
          },
        ],
        ko: [
          { label: '홈', link: '/' },
          {
            label: '시작하기',
            items: [
              { label: '소개', link: '/introduction/' },
              { label: '설치', link: '/installation/' },
              { label: '빠른 시작', link: '/quick-start/' },
            ],
          },
        ],
      },

      social: {
        github: 'https://github.com/your-org/your-repo',
      },
    }),

    lunaria({
      sourceLanguage,
      languages,
      files: [
        {
          sourcePath: 'src/content/docs/{lang}/{slug}.md',
          localizationPath: 'src/content/docs/{lang}/{slug}.md',
        },
      ],
      dashboard: {
        outputDir: 'public/i18n-status',
        title: 'Translation Status',
        description: 'Track the progress of documentation translations',
      },
    }),
  ],
});

다국어 콘텐츠 조직

디렉토리 구조

src/content/docs/
├── en/                        # 영어 (원본 언어)
│   ├── index.md
│   ├── introduction.md
│   ├── installation.md
│   ├── quick-start.md
│   ├── guides/
│   │   ├── configuration.md
│   │   └── deployment.md
│   └── reference/
│       ├── api.md
│       └── cli.md
├── zh-cn/                     # 중국어 번역
│   ├── index.md
│   ├── introduction.md
│   ├── installation.md
│   ├── quick-start.md
│   ├── guides/
│   │   └── configuration.md   # deployment.md 미번역
│   └── reference/
│       └── api.md
├── ja/                        # 일본어 번역
│   ├── index.md
│   ├── introduction.md
│   └── installation.md
└── ko/                        # 한국어 번역
    └── index.md

콘텐츠 템플릿

---
# src/content/docs/en/introduction.md
title: Introduction
description: Get started with My Project and learn about its core concepts.
---

# Introduction

Welcome to **My Project**! This guide will help you understand the fundamentals.

## What is My Project?

My Project is a powerful tool that helps you...

## Key Features

- **Feature 1**: Description of feature 1
- **Feature 2**: Description of feature 2
- **Feature 3**: Description of feature 3

## Next Steps

Ready to get started? Check out our [Installation Guide](/installation/).

번역 버전 예시:

---
# src/content/docs/ko/introduction.md
title: 소개
description: My Project를 시작하고 핵심 개념을 배워보세요.
---

# 소개

**My Project**에 오신 것을 환영합니다! 이 가이드는 기본 사항을 이해하는 데 도움을 드립니다.

## My Project란 무엇인가요?

My Project는 다음을 도와주는 강력한 도구입니다...

## 주요 기능

- **기능 1**: 기능 1에 대한 설명
- **기능 2**: 기능 2에 대한 설명
- **기능 3**: 기능 3에 대한 설명

## 다음 단계

시작할 준비가 되셨나요? [설치 가이드](/installation/)를 확인하세요.

CI/CD 완전 파이프라인

GitHub Actions 워크플로우

# .github/workflows/ci.yml
name: CI/CD Pipeline

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  workflow_dispatch:

env:
  NODE_VERSION: '20'

jobs:
  # 작업 1: 코드 검사
  lint:
    name: Lint
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run linters
        run: npm run lint

  # 작업 2: 빌드 검사
  build:
    name: Build
    runs-on: ubuntu-latest
    needs: lint
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # LunariaJS용 전체 히스토리

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build Astro site
        run: npm run build

      - name: Build Lunaria dashboard
        run: npx lunaria build

      - name: Upload build artifacts
        uses: actions/upload-artifact@v4
        with:
          name: build-output
          path: dist/
          retention-days: 7

  # 작업 3: 번역 상태 확인
  i18n-check:
    name: Translation Check
    runs-on: ubuntu-latest
    needs: lint
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Check translation status
        id: i18n
        run: |
          npx lunaria build --silent
          REPORT=$(node scripts/i18n-report.js)
          echo "report<<EOF" >> $GITHUB_OUTPUT
          echo "$REPORT" >> $GITHUB_OUTPUT
          echo "EOF" >> $GITHUB_OUTPUT

      - name: Comment on PR
        if: github.event_name == 'pull_request'
        uses: actions/github-script@v7
        with:
          script: |
            const report = `${{ steps.i18n.outputs.report }}`;
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `## 🌙 Translation Status\n\n${report}`
            });

  # 작업 4: 배포 (main 브랜치만)
  deploy:
    name: Deploy
    runs-on: ubuntu-latest
    needs: [build, i18n-check]
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'

    permissions:
      contents: read
      deployments: write

    steps:
      - name: Download build artifacts
        uses: actions/download-artifact@v4
        with:
          name: build-output
          path: dist

      - name: Deploy to Vercel
        uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
          vercel-args: '--prod'
          working-directory: ./

번역 상태 보고서 스크립트

// scripts/i18n-report.js
const fs = require('fs');
const path = require('path');

function generateReport() {
  const statusPath = path.join('public', 'i18n-status', 'data', 'status.json');

  if (!fs.existsSync(statusPath)) {
    return 'No translation status data available.';
  }

  const status = JSON.parse(fs.readFileSync(statusPath, 'utf8'));

  let report = '| Language | Done | Outdated | Missing | Progress |\n';
  report += '|----------|------|----------|---------|----------|\n';

  const languages = Object.entries(status.languages);

  for (const [lang, data] of languages) {
    if (lang === status.sourceLanguage) continue;

    const progress = Math.round((data.done / data.total) * 100);
    const emoji = progress >= 90 ? '✅' : progress >= 70 ? '⚠️' : '❌';

    report += `| ${lang} | ${data.done} | ${data.outdated} | ${data.missing} | ${emoji} ${progress}% |\n`;
  }

  report += '\n📊 [View Full Dashboard](/i18n-status/)';

  return report;
}

console.log(generateReport());

팀 협업 워크플로우

번역 기여 가이드

TRANSLATING.md 파일 생성:

# Translation Guide

Thank you for your interest in translating our documentation!

## How to Contribute

### 1. Check Current Status

Visit our [Translation Status Dashboard](/i18n-status/) to see which files need translation.

### 2. Claim a File

Before starting, check if anyone is already working on the file:

1. Search existing [Pull Requests](https://github.com/your-org/your-repo/pulls)
2. If no one is working on it, create an issue or comment on the dashboard

### 3. Translate

1. Fork the repository
2. Create a branch: `git checkout -b translate/ko/introduction`
3. Copy the source file: `cp src/content/docs/en/introduction.md src/content/docs/ko/introduction.md`
4. Translate the content
5. Test locally: `npm run dev`

### 4. Submit

1. Commit your changes: `git commit -m "Translate introduction to Korean"`
2. Push to your fork: `git push origin translate/ko/introduction`
3. Create a Pull Request

## Translation Guidelines

- **Preserve formatting**: Keep Markdown syntax intact
- **Keep code examples**: Usually, code doesn't need translation
- **Be consistent**: Use consistent terminology
- **Add context**: Use comments for difficult terms

## Need Help?

Join our [Discord](https://discord.gg/example) and ask in the #translations channel.

PR 템플릿

.github/pull_request_template.md 생성:

## Description

<!-- Describe your changes -->

## Type of Change

- [ ] 📝 Documentation update
- [ ] 🌐 Translation
- [ ] ✨ New feature
- [ ] 🐛 Bug fix

## Translation Checklist (if applicable)

- [ ] I have checked the [Translation Status Dashboard](/i18n-status/)
- [ ] I have preserved the original Markdown formatting
- [ ] I have tested the translation locally
- [ ] I have reviewed the terminology consistency

## Screenshots (if applicable)

<!-- Add screenshots to help explain your changes -->

시리즈 요약 및 전망

LunariaJS 능력 개요

능력	설명	장
설치 설정	빠른 프로젝트 초기화	제 2편
CLI 작업	명령줄 도구 사용	제 3편
대시보드	시각화 번역 상태	제 4편
Git 통합	버전 기반 번역 추적	제 5편
Starlight 통합	문서 사이트 통합	제 6편
CI/CD 통합	자동화 워크플로우	제 7편
핵심 아키텍처	소스 코드 수준 이해	제 8편
고급 설정	기업급 사용자 정의	제 9편
완전 실전	엔드 투 엔드 실천	제 10편

학습 경로 회고

입문 단계
    │
    ├── 제 1편: LunariaJS가 무엇인지 이해
    ├── 제 2편: 설치 및 설정 배우기
    ├── 제 3편: CLI 명령어 마스터
    ├── 제 4편: 대시보드 사용법
    ├── 제 5편: Git 워크플로우 이해
    ├── 제 6편: Starlight 통합
    └── 제 7편: CI/CD 설정
        │
        ▼
심화 단계
    │
    ├── 제 8편: 소스 코드 아키텍처 심층 분석
    ├── 제 9편: 기업급 설정
    └── 제 10편: 완전 실전
        │
        ▼
    LunariaJS 전문가가 되었습니다!

미래 발전 방향

LunariaJS는 활발한 오픈소스 프로젝트로서 앞으로 다음이 가능합니다:

더 많은 파일 포맷 지원: Excel, PO 파일 등
더 깊은 CMS 통합: Headless CMS 지원
AI 보조 번역: 기계 번역 서비스와 통합
실시간 협업: 다중 사용자 동시 편집
고급 분석: 번역 품질 평가

커뮤니티 리소스 추천

리소스	링크
공식 문서	https://lunaria.libdoc.top/
한국어 문서	https://lunaria.libdoc.top/ko/
GitHub 저장소	https://github.com/withastro/lunaria
Discord 커뮤니티	https://discord.gg/astro
Astro 공식 문서	https://docs.astro.build/

결어

LunariaJS 입문에서 마스터까지 완전한 학습 여정을 완료하신 것을 축하드립니다!

열 편의 시리즈 튜토리얼을 통해 여러분은 다음을 마스터했습니다:

✅ LunariaJS의 핵심 개념과 설치 설정
✅ CLI 명령어와 대시보드 사용
✅ Git 워크플로우와 팀 협업
✅ Astro Starlight 통합
✅ CI/CD 자동화 배포
✅ 핵심 아키텍처와 소스 코드 이해
✅ 기업급 고급 설정
✅ 완전한 프로젝트 실전

이제 LunariaJS를 사용해 전문적인 다국어 문서 플랫폼을 구축할 수 있는 역량을 갖추셨습니다. 다음 프로젝트를 시작해 보세요!

이 시리즈가 도움이 되셨다면, 더 많은 개발자에게 공유하여 LunariaJS라는 강력한 현지화 관리 도구를 더 많은 분이 알게 해 주세요.

💡 추천 읽기:

LunariaJS 한국어 문서

LunariaJS 영어 문서

LunariaJS 일본어 문서

LunariaJS 중국어 문서

Astro 공식 문서

Starlight 문서