Astro Starlight + LunariaJS: 완벽한 다국어 문서 사이트 구축하기

앞선 글들에서는 LunariaJS의 핵심 기능과 Git 워크플로우 통합을 배웠습니다. 오늘은 LunariaJS와 Astro Starlight의 완벽한 조합을 살펴보고, 전문적인 다국어 문서 사이트를 구축하는 방법을 단계별로 안내해 드리겠습니다.

💡 공식 문서: LunariaJS 한국어 문서 - Starlight 통합

Starlight 소개

Astro Starlight란 무엇인가요?

Astro Starlight는 Astro 프레임워크 기반으로 구축된 현대적인 문서 테마로, 다음을 제공합니다:

특성	설명
🚀 극한 성능	Astro의 부분 하이드레이션 기술로 페이지 로딩이 매우 빠름
🎨 아름다운 디자인	즉시 사용 가능한 전문적인 문서 인터페이스
📱 반응형	데스크톱과 모바일 기기에 완벽하게 최적화
🔍 내장 검색	Pagefind 전문 검색
🌙 다크 모드	시스템 선호도 자동 감지
🌐 국제화	네이티브 다국어 지원

왜 LunariaJS가 필요한가요?

Starlight는 국제화(i18n) 지원을 제공하지만, 번역 관리 기능은 포함하지 않습니다:

요구 사항	Starlight	+ LunariaJS
다국어 라우팅	✅	✅
언어 전환기	✅	✅
번역 UI 컴포넌트	✅	✅
번역 상태 추적	❌	✅
시각화 대시보드	❌	✅
Git 워크플로우 통합	❌	✅

LunariaJS는 Starlight의 번역 관리 격차를 완벽하게 메워줍니다.

@lunariajs/starlight 설치

사전 요구 사항

프로젝트가 다음 조건을 충족하는지 확인하세요:

• Astro 4.0+ 또는 5.0+
• Starlight가 설치됨
• Git으로 버전 관리되는 프로젝트

설치 단계

1. 의존성 설치

# npm 사용
npm install @lunariajs/starlight

# yarn 사용
yarn add @lunariajs/starlight

# pnpm 사용
pnpm add @lunariajs/starlight

2. 버전 호환성 확인

# 설치된 버전 확인
npm list @astrojs/starlight @lunariajs/starlight

버전 호환성 확인:

@astrojs/starlight	@lunariajs/starlight
0.25.x	0.4.x
0.26.x+	0.5.x+

Starlight 설정 통합

기본 설정

astro.config.mjs에서 LunariaJS 통합을 추가합니다:

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Documentation',
      defaultLocale: 'en',
      locales: {
        en: { label: 'English' },
        'zh-cn': { label: '简体中文' },
        ja: { label: '日本語' },
        ko: { label: '한국어' },
      },
      sidebar: [
        { label: 'Guide', link: '/guide/' },
        { label: 'Reference', link: '/reference/' },
      ],
    }),
    lunaria({
      // LunariaJS 설정
      sourceLanguage: 'en',
      languages: ['en', 'zh-cn', 'ja', 'ko'],
    }),
  ],
});

i18n 설정과 LunariaJS 동기화

Starlight의 i18n 설정이 LunariaJS와 일치하도록 유지:

// astro.config.mjs
const languages = ['en', 'zh-cn', 'ja', 'ko'];
const sourceLanguage = 'en';

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Documentation',
      defaultLocale: sourceLanguage,
      locales: Object.fromEntries(
        languages.map(lang => [
          lang,
          { label: getLanguageLabel(lang) }
        ])
      ),
    }),
    lunaria({
      sourceLanguage,
      languages,
    }),
  ],
});

function getLanguageLabel(lang) {
  const labels = {
    en: 'English',
    'zh-cn': '简体中文',
    ja: '日本語',
    ko: '한국어',
  };
  return labels[lang] || lang;
}

라우팅 구조 설계

Starlight + LunariaJS의 권장 디렉토리 구조:

src/
└── content/
    └── docs/
        ├── en/                    # 영어 (원본 언어)
        │   ├── index.md
        │   ├── guide.md
        │   └── reference.md
        ├── zh-cn/                 # 중국어 번역
        │   ├── index.md
        │   ├── guide.md
        │   └── reference.md
        ├── ja/                    # 일본어 번역
        │   └── ...
        └── ko/                    # 한국어 번역
            └── ...

전체 설정 예시

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

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

export default defineConfig({
  site: 'https://docs.example.com',
  integrations: [
    starlight({
      title: 'My Project',
      defaultLocale: config.sourceLanguage,
      locales: Object.fromEntries(
        config.languages.map(lang => [
          lang,
          { label: config.languageLabels[lang] }
        ])
      ),
      sidebar: {
        en: [
          { label: 'Home', link: '/' },
          { label: 'Guide', link: '/guide/' },
          { label: 'API Reference', link: '/reference/' },
        ],
        'zh-cn': [
          { label: '首页', link: '/' },
          { label: '指南', link: '/guide/' },
          { label: 'API 参考', link: '/reference/' },
        ],
        // 다른 언어...
      },
      social: {
        github: 'https://github.com/your-org/your-repo',
      },
    }),
    lunaria({
      sourceLanguage: config.sourceLanguage,
      languages: config.languages,
      files: [
        {
          sourcePath: 'src/content/docs/{lang}/{slug}.md',
          localizationPath: 'src/content/docs/{lang}/{slug}.md',
        },
      ],
      dashboard: {
        outputDir: 'public/i18n-status',
        title: 'My Project - Translation Status',
      },
    }),
  ],
});

대시보드 임베드

방식 1: 독립 경로로

LunariaJS 대시보드를 /i18n-status/ 경로에 배치:

// astro.config.mjs
lunaria({
  dashboard: {
    outputDir: 'public/i18n-status',
  },
})

빌드 후 /i18n-status/에 접속하여 대시보드를 볼 수 있습니다.

방식 2: 내비게이션 메뉴에 추가

Starlight 내비게이션에 대시보드 링크를 추가:

// astro.config.mjs
starlight({
  title: 'My Documentation',
  sidebar: [
    { label: 'Guide', link: '/guide/' },
    { label: 'Reference', link: '/reference/' },
    {
      label: 'Translation Status',
      link: '/i18n-status/',
      badge: 'New',
    },
  ],
})

방식 3: 사용자 정의 내비게이션 컴포넌트

번역 진행 상황을 표시하는 사용자 정의 내비게이션 컴포넌트 생성:

---
// src/components/I18nStatus.astro
---
<a href="/i18n-status/" class="i18n-status-link">
  <span class="icon">🌐</span>
  <span>Translation Status</span>
</a>

<style>
  .i18n-status-link {
    display: flex;
    align-items: center;
    gap: 0.5rem;
    padding: 0.5rem 1rem;
    background: var(--sl-color-bg);
    border-radius: 0.5rem;
    text-decoration: none;
    color: var(--sl-color-text);
    transition: background 0.2s;
  }

  .i18n-status-link:hover {
    background: var(--sl-color-bg-hover);
  }
</style>

스타일 사용자 정의

LunariaJS 대시보드의 기본 스타일 덮어쓰기:

/* src/styles/lunaria-custom.css */
:root {
  /* Starlight의 색상 변수 사용 */
  --lunaria-color-primary: var(--sl-color-accent);
  --lunaria-color-success: var(--sl-color-green);
  --lunaria-color-warning: var(--sl-color-orange);
  --lunaria-color-danger: var(--sl-color-red);

  /* 배경색 */
  --lunaria-bg-primary: var(--sl-color-bg);
  --lunaria-bg-secondary: var(--sl-color-bg-sidebar);
}

그 다음 설정에서 참조:

// astro.config.mjs
lunaria({
  dashboard: {
    customCss: './src/styles/lunaria-custom.css',
  },
})

실전: 삼국어 문서 사이트 구축

전체 실전 사례를 통해 중국어, 일본어, 한국어를 지원하는 삼국어 문서 사이트를 구축해 보겠습니다.

단계 1: Starlight 프로젝트 생성

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

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

# 의존성 설치
npm install

단계 2: LunariaJS 설치

npm install @lunariajs/starlight

단계 3: 다국어 설정

astro.config.mjs 편집:

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Project Docs',
      defaultLocale: 'en',
      locales: {
        en: { label: 'English', lang: 'en' },
        'zh-cn': { label: '简体中文', lang: 'zh-CN' },
        ja: { label: '日本語', lang: 'ja' },
        ko: { label: '한국어', lang: 'ko' },
      },
      sidebar: {
        en: [
          { label: 'Home', link: '/' },
          { label: 'Getting Started', items: [
            { label: 'Introduction', link: '/getting-started/' },
            { label: 'Installation', link: '/installation/' },
          ]},
        ],
        'zh-cn': [
          { label: '首页', link: '/' },
          { label: '快速开始', items: [
            { label: '简介', link: '/getting-started/' },
            { label: '安装', link: '/installation/' },
          ]},
        ],
        ja: [
          { label: 'ホーム', link: '/' },
          { label: 'はじめに', items: [
            { label: '概要', link: '/getting-started/' },
            { label: 'インストール', link: '/installation/' },
          ]},
        ],
        ko: [
          { label: '홈', link: '/' },
          { label: '시작하기', items: [
            { label: '소개', link: '/getting-started/' },
            { label: '설치', link: '/installation/' },
          ]},
        ],
      },
    }),
    lunaria({
      sourceLanguage: 'en',
      languages: ['en', 'zh-cn', 'ja', 'ko'],
    }),
  ],
});

단계 4: 콘텐츠 파일 생성

src/content/docs/
├── en/
│   ├── index.md
│   ├── getting-started.md
│   └── installation.md
├── zh-cn/
│   ├── index.md
│   └── getting-started.md      # 설치 문서는 아직 번역되지 않음
├── ja/
│   ├── index.md
│   └── getting-started.md
└── ko/
    └── index.md                 # 다른 문서는 아직 번역되지 않음

단계 5: 번역 메타데이터 추가

각 Markdown 파일에는 frontmatter가 포함되어야 합니다:

---
title: Getting Started
description: Learn how to get started with our project.
---

# Getting Started

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

단계 6: 빌드 및 미리보기

# 사이트 및 대시보드 빌드
npm run build

# 미리보기
npm run preview

접속:

• 문서 사이트: http://localhost:4321/
• 번역 대시보드: http://localhost:4321/i18n-status/

단계 7: 번역 상태 확인

대시보드를 열면 다음과 같은 내용을 볼 수 있습니다:

Translation Status
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Language         Progress    Status
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🇺🇸 English       100%        Source
🇨🇳 简体中文       67%         2/3 done, 1 missing
🇯🇵 日本語         67%         2/3 done, 1 missing
🇰🇷 한국어          33%         1/3 done, 2 missing
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

일반적인 문제와 해결 방법

Q1: 대시보드 404 오류

문제: /i18n-status/ 접속 시 404 표시.

해결 방법:

# LunariaJS 설정의 출력 디렉토리가 public/ 디렉토리 하위인지 확인
lunaria({
  dashboard: {
    outputDir: 'public/i18n-status',  // public/ 디렉토리 하위여야 함
  },
})

# 먼저 build를 실행했는지 확인
npm run build

Q2: 언어 코드 불일치

문제: Starlight는 zh-CN을 사용하고, LunariaJS는 zh-cn을 사용함.

해결 방법:

starlight({
  locales: {
    'zh-cn': { label: '简体中文', lang: 'zh-CN' },  // 주의: 구분 필요
  },
})

Q3: 대시보드 스타일 충돌

문제: 대시보드 스타일이 문서 사이트와 일치하지 않음.

해결 방법: 사용자 정의 CSS로 스타일 통일:

/* lunaria 대시보드에서 Starlight 변수 사용 */
:root {
  --lunaria-color-primary: var(--sl-color-accent);
  --lunaria-bg-primary: var(--sl-color-bg);
}

Q4: 빌드 시 메모리 부족

문제: 대규모 문서 사이트 빌드 시 메모리 부족.

해결 방법:

# Node.js 메모리 제한 증가
NODE_OPTIONS="--max-old-space-size=4096" npm run build

Q5: 라우팅 충돌

문제: 대시보드 경로가 문서 경로와 충돌함.

해결 방법: 문서와 충돌하지 않는 경로 선택:

// /docs/, /guide/ 등 일반적인 문서 경로는 피할 것
lunaria({
  dashboard: {
    outputDir: 'public/localization-status',  // 고유한 경로 사용
  },
})

모범 사례

1. 통합 언어 설정

공유 설정 파일 생성:

// src/i18n-config.js
export const languages = ['en', 'zh-cn', 'ja', 'ko'];
export const sourceLanguage = 'en';
export const languageLabels = {
  en: 'English',
  'zh-cn': '简体中文',
  ja: '日本語',
  ko: '한국어',
};

여러 위치에서 참조:

// astro.config.mjs
import { languages, sourceLanguage, languageLabels } from './src/i18n-config.js';

2. 자동화된 번역 검사

package.json에 스크립트 추가:

{
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "i18n:check": "lunaria build",
    "i18n:preview": "lunaria preview"
  }
}

3. 번역 가이드 추가

문서에 번역 기여 가이드 추가:

# Contributing Translations

We welcome translation contributions! Here's how to help:

1. Check the [Translation Status Dashboard](/i18n-status/)
2. Find a file marked as "missing" or "outdated"
3. Fork the repository and create a translation
4. Submit a pull request

Thank you for helping make our documentation accessible to everyone!

4. CI/CD 검사 설정

# .github/workflows/i18n-check.yml
name: i18n Status

on: [pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm ci
      - run: npm run i18n:check

      - name: Upload Dashboard
        uses: actions/upload-artifact@v4
        with:
          name: i18n-dashboard
          path: public/i18n-status/

요약

LunariaJS와 Astro Starlight의 통합은 완전한 다국어 문서 솔루션을 제공합니다:

기능	Starlight	+ LunariaJS
다국어 라우팅	✅	✅
언어 전환	✅	✅
번역 UI	✅	✅
번역 상태 추적	❌	✅
시각화 대시보드	❌	✅
Git 워크플로우	❌	✅

핵심 포인트:

• @lunariajs/starlight 패키지로 원활한 통합
• Starlight와 LunariaJS 간에 언어 코드가 일치하도록 유지
• 내비게이션 메뉴에 대시보드를 임베드해 쉽게 접근
• 통합 설정 파일로 중복 유지보수 방지

다음 단계

다음 글에서는 LunariaJS의 CI/CD 통합을 살펴보고, 다음 방법을 배우겠습니다:

• GitHub Actions 자동화 빌드 설정
• 번역 상태 검사 파이프라인 설계
• 알림 및 보고 메커니즘 설정
• 지속적인 현지화 워크플로우 구현

기대해 주세요!

---

💡 추천 읽기:

• LunariaJS 한국어 문서
• LunariaJS Starlight 통합
• LunariaJS 영어 문서
• LunariaJS 일본어 문서
• LunariaJS 중국어 문서