정적 문서 사이트 - LocalizeFlow Docs

정적 문서 사이트는 Localizeflow와 완벽하게 어울립니다:

귀하의 콘텐츠는 이미 Markdown 형식입니다 – 추출이나 변환이 필요 없습니다.
GitHub가 모든 것을 관리합니다 – 버전, 리뷰, 배포가 기존 워크플로우 내에서 이루어집니다.
번역은 동일한 구조를 따릅니다 – docs/en/는 예측 가능하고 자동으로 docs/ko/가 됩니다.

핵심 원칙: Localizeflow는 항상 정확히 하나의 소스 트리를 사용합니다. 관례상, 이것은 docs/en/입니다. 나머지—번역, 오래된 i18n 폴더, 혼합 언어 파일—는 제거해야 하며, 그렇지 않으면 Localizeflow가 번역할 내용을 잘못 식별합니다.

이 페이지는 Localizeflow가 신뢰성 있게 번역할 수 있도록 정적 문서 프로젝트를 준비하고 구조화하는 방법을 설명합니다.

정적 문서 사이트란 무엇인가요?

다음과 같은 경우 정적 문서 프로젝트를 사용하고 있을 가능성이 높습니다:

사이트가 Astro, Hugo, Docusaurus 또는 유사한 정적 사이트 생성기 프레임워크로 구축된 경우.
대부분의 콘텐츠가 docs/, content/, blog/ 같은 폴더에 있는 경우.
배포가 Git에서 트리거되는 경우 (예: GitHub Actions 또는 다른 CI를 통해).

이 모든 경우에 동일한 고수준 관행이 적용됩니다.

Localizeflow가 실패하는 일반적인 시나리오

Localizeflow를 설정하기 전에 저장소에 다음 문제들이 있는지 확인하세요. 이것들이 Localizeflow가 소스 콘텐츠를 잘못 식별하는 가장 흔한 이유입니다:

❌ 시나리오 1: `docs/` 바로 아래에 혼합된 언어가 있는 경우

docs/
  getting-started.md          (English)
  getting-started.ko.md       (Korean)
  installation.md             (English)

문제: Localizeflow가 어떤 파일이 소스이고 어떤 파일이 번역본인지 구분할 수 없습니다.

해결책: 모든 영어 파일을 docs/en/로 옮기고 한국어 파일은 삭제하세요 (Localizeflow가 다시 생성합니다).

❌ 시나리오 2: 오래된 번역 폴더가 남아 있는 경우

docs/
  en/
    getting-started.md
  ko/
    getting-started.md        (old translation)
  ja/
    getting-started.md        (old translation)

문제: Localizeflow가 오래된 번역을 새 소스 콘텐츠로 인식하여 중복되거나 충돌하는 번역을 생성할 수 있습니다.

해결책: Localizeflow에 연결하기 전에 docs/ko/와 docs/ja/를 삭제해야 합니다.

❌ 시나리오 3: 번역 폴더에 영어 파일이 섞여 있는 경우

docs/
  en/
    getting-started.md
  ko/
    getting-started.md        (Korean)
    new-feature.md            (accidentally English)

문제: Localizeflow는 docs/ko/에 한국어 콘텐츠만 있어야 한다고 기대합니다. 여기 영어 파일이 있으면 시스템이 혼란스러워집니다.

해결책: new-feature.md를 docs/en/로 옮기고 docs/ko/에서는 삭제하세요.

✅ Localizeflow가 기대하는 구조

깨끗한 저장소 구조는 다음과 같습니다:

docs/
  en/
    getting-started.md
    installation.md
    configuration.md

이게 전부입니다. Localizeflow는 풀 리퀘스트를 통해 docs/ko/, docs/ja/ 등을 생성합니다.

기존 번역 정리하기

정적 문서 저장소를 Localizeflow에 연결하기 전에 기존 번역 폴더를 한 번 정리해야 합니다.

다음 항목들을 제거해야 합니다:

언어별 폴더 예:
- docs/ko, docs/ja
- blog/ko, blog/ja
생성된 번역 또는 i18n 출력물 예:
- i18n/*
- 번역된 콘텐츠 복사본을 포함하는 기타 빌드 산출물

이것이 중요한 이유 Localizeflow는 정확히 하나의 깨끗한 소스 언어 트리를 기대합니다. 오래된 번역이 남아 있으면 새 소스 콘텐츠로 오인되어 중복되거나 충돌하는 번역이 발생합니다.

소스 언어 폴더 정규화하기

다음으로, 원본 콘텐츠를 명확한 언어별 폴더로 정리하세요.

일반적이고 권장되는 패턴은 다음과 같습니다:

docs/en/** – 영어 문서
blog/en/** – 영어 블로그 게시물 또는 변경 로그

현재 프로젝트에 docs/ 또는 blog/ 바로 아래에 콘텐츠가 있다면 docs/en/ 및 blog/en/로 옮길 수 있습니다.

이 작업이 완료되면 Localizeflow는 항상 en을 소스 언어 트리로 사용하고 이를 기반으로 다른 언어(예: ko, ja)의 번역을 생성합니다.

번역된 콘텐츠는 병렬 폴더에 위치합니다:

docs/ko/**
blog/ko/**

규칙은 간단합니다: 정확히 하나의 소스 트리, 그리고 Localizeflow가 풀 리퀘스트를 통해 모든 대상 트리를 관리합니다.

저장소 연결 및 번역 구성

정리 및 폴더 정규화 후:

Localizeflow 대시보드에서 저장소를 연결합니다.
저장소 상세 페이지를 열고 번역 구성을 편집합니다.
다음을 설정합니다:
- 소스 언어 (예: en).
- 대상 브랜치 (예: main).
- 대상 언어 (예: ko, ja).
- 문서 및 블로그 콘텐츠를 가리키는 포함 경로, 예:
  - docs/en/**
  - blog/en/**

이 설정은 Localizeflow에 정적 문서 프로젝트 내에서 어떤 파일을 번역해야 하는지 정확히 알려줍니다.

번역 중 보존되는 항목

Localizeflow는 문서 구조와 기술적 요소를 보존합니다:

Frontmatter – 파일 상단의 YAML 메타데이터는 그대로 유지됩니다.
코드 블록 – 코드 예제는 번역되지 않고 (주변 텍스트만 번역).
깊은 폴더 구조 – docs/en/tutorials/getting-started/intro.md 같은 중첩 경로도 완벽히 작동합니다. Localizeflow는 대상 언어에 정확한 구조를 반영합니다.

Localizeflow가 번역하는 것(및 하지 않는 것)

Localizeflow는 Markdown 문서 파일 번역의 반복적이고 시간이 많이 드는 작업을 자동화합니다.

하지만 UI 문자열 및 사이트 요소는 Localizeflow가 자동으로 번역하지 않습니다. 여기에는 다음이 포함됩니다:

히어로 섹션 텍스트 (예: hero.en.json, hero.ko.json)
내비게이션 및 헤더 메뉴
언어 선택 드롭다운
푸터 링크 및 텍스트
사이드바 카테고리 이름
컴포넌트 파일 (.astro, .tsx, .vue 등)

이유는?

UI 문자열 구조는 팀과 프로젝트마다 크게 다릅니다.
UI 번역의 경우 JSON 기반 i18n 파일을 사용하고 AI 도구로 직접 번역하는 것이 더 빠르고 유연한 경우가 많습니다.

UI 요소 번역 방법:

AI 어시스턴트를 사용해 UI 문자열을 번역할 수 있습니다. 예를 들어:

“다음 내용을 가진 hero.en.json 파일이 있습니다: [JSON 붙여넣기]. 동일한 구조를 유지하며 한국어 번역이 포함된 hero.ko.json을 만들어 주세요.”

Localizeflow는 문서 콘텐츠를 자동화된 풀 리퀘스트를 통해 여러 언어로 동기화하는 데 집중합니다.

프레임워크별 i18n 구성

Localizeflow가 번역 파일을 생성한 후, 프레임워크가 /en, /ko 등의 언어 경로를 인식하도록 구성해야 합니다.

Astro

Astro는 내장 i18n 라우팅이 없습니다. 수동으로 구성해야 합니다.

최소 구성 예시:

// astro.config.mjs
import { defineConfig } from 'astro/config';

export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'ko', 'ja'],
    routing: {
      prefixDefaultLocale: false
    }
  }
});

폴더 구조:

src/
  content/
    docs/
      en/
        getting-started.md
      ko/
        getting-started.md    (created by Localizeflow)

Astro 페이지는 Astro.currentLocale을 사용해 올바른 콘텐츠를 렌더링할 수 있습니다.

Hugo

Hugo는 기본 다국어 지원을 제공합니다.

최소 구성 예시:

# config.toml
defaultContentLanguage = "en"

[languages]
  [languages.en]
    contentDir = "content/en"
    languageName = "English"
    weight = 1

  [languages.ko]
    contentDir = "content/ko"
    languageName = "한국어"
    weight = 2

폴더 구조:

content/
  en/
    getting-started.md
  ko/
    getting-started.md    (created by Localizeflow)

Hugo는 자동으로 /en/getting-started/ 및 /ko/getting-started/ 경로를 생성합니다.

Docusaurus

Docusaurus는 내장 i18n 플러그인을 제공합니다.

최소 구성 예시:

// docusaurus.config.js
module.exports = {
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'ko', 'ja'],
  },
};

폴더 구조:

docs/
  en/
    getting-started.md
  ko/
    getting-started.md    (created by Localizeflow)

Docusaurus는 자동으로 /en/getting-started 및 /ko/getting-started 경로를 생성합니다.

정적 문서 사이트란 무엇인가요?

Localizeflow가 실패하는 일반적인 시나리오

❌ 시나리오 1: docs/ 바로 아래에 혼합된 언어가 있는 경우

❌ 시나리오 2: 오래된 번역 폴더가 남아 있는 경우

❌ 시나리오 3: 번역 폴더에 영어 파일이 섞여 있는 경우

✅ Localizeflow가 기대하는 구조

기존 번역 정리하기

소스 언어 폴더 정규화하기

저장소 연결 및 번역 구성

번역 중 보존되는 항목

Localizeflow가 번역하는 것(및 하지 않는 것)

프레임워크별 i18n 구성

Astro

Hugo

Docusaurus

❌ 시나리오 1: `docs/` 바로 아래에 혼합된 언어가 있는 경우