정적 콘텐츠 현지화

번역된 문서와 카탈로그를 사이트나 렌더러가 사용하는 파일에 매핑한 뒤, 구조와 링크, 최종 출력 결과를 확인하세요.

사이트의 소스 트리에는 이미 문서가 경로, 메타데이터, 탐색 메뉴, 렌더러와 연결되어 있습니다. 이 시스템이 불러올 수 있는 위치에 번역 파일을 추가하세요. 먼저 지정된 경로에서 열리고, 링크가 정상적으로 작동하며, 원문과 동일한 코드 예제를 담은 완전한 대상 언어 페이지 하나를 완성하는 것이 중요합니다.

파일을 사용하는 시스템별로 목록 정리하기 #

장문 문서, 구조화된 카탈로그, 특수 용도 리소스를 구분하세요. 마크다운, MDX, Markdoc에는 렌더러와 스키마가 필요합니다. JSON, YAML, TypeScript, PHP 카탈로그에는 로더가 필요합니다. PO와 XLIFF는 각각 고유한 메시지 시스템에 연결됩니다. SRT는 시간 정보에 맞춰 처리하는 미디어 워크플로에 속합니다.

각 그룹에서 대표 소스 하나를 골라 출력 경로와 해당 파일을 불러올 로더를 파악하세요. 생성되는 대상 파일이 소스 패턴에 포함되지 않도록 하세요. 문서 식별자, URL, 코드 예제, 카탈로그 키, 값에 따라 동작이 달라지는 컴포넌트 속성은 그대로 유지하세요.

형식에서 실제로 사용할 핸들러를 선택하세요. 일반 YAML은 로캘을 루트 키로 사용하는 YAML이나 OpenAPI YAML과 다릅니다. .xml만으로는 안드로이드 리소스가 자동으로 식별되지 않습니다. 확장자가 같다고 해서 핸들러가 문서 구조까지 이해하는 것은 아닙니다.

사이트의 디렉터리 규칙에 맞추기 #

프로젝트의 로더를 기준으로 다음 파일 배치 방식을 확인하세요.

사이트번역 전에 확인할 사항
Docusaurus어떤 소스 문서가 i18n/<locale>/docusaurus-plugin-content-docs/current/ 아래에 파일로 생성되는지, 어떤 버전별 문서나 테마 문자열에 별도 입력이 필요한지 확인합니다.
Nextra현재 설치 구성에서 로캘별 페이지, 사전, 별도의 콘텐츠 트리 중 무엇을 불러오는지 확인하고 각 입력을 따로 매핑합니다.
Hugocontent/<locale>/ 아래의 어떤 파일들이 동일한 콘텐츠의 언어별 번역본인지, 언어별 링크는 어떻게 연결되는지 확인합니다.
Astro각 경로에서 어떤 로캘별 콘텐츠 컬렉션과 사용자 인터페이스 사전을 사용하는지 확인합니다.
VitePress어떤 로캘 디렉터리 접두사와 탐색 메뉴 설정으로 번역 페이지를 생성하는지 확인합니다.
MkDocs설치된 프로젝트가 어떤 국제화 플러그인과 로캘별 문서 배치를 사용하는지 확인합니다.

소스 문서를 docs/ 아래에 두는 Docusaurus 예제에서는 프로젝트 루트에서 CLI를 설치하고 연결하세요.

sh
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es --files 'docs/**/*.md' --yes
lingo link

.lingo/config.json에 있는 조직 및 로컬라이제이션 엔진 식별자는 그대로 유지하세요. 이 소스 경로에는 로캘이 없으므로 파일 항목을 출력 경로가 명시된 템플릿으로 바꾸세요.

json
{
  "pattern": "docs/**/*.md",
  "sourceRoot": "docs",
  "targetPath": "i18n/[locale]/docusaurus-plugin-content-docs/current/[path]"
}

docs/setup/install.md에서는 [path]가 setup/install.md로 바뀌므로 스페인어 출력은 i18n/es/docusaurus-plugin-content-docs/current/setup/install.md에 저장됩니다. 설치된 플러그인과 버전이 해당 디렉터리를 사용하는지 확인하세요. 템플릿 유효성 검사와 충돌 규칙은 설정에서 설명합니다.

독자에게 보이는 문서 필드를 신중하게 번역하기 #

마크다운에서는 제목과 설명처럼 독자에게 보이는 프런트매터 필드를 선택하세요. 식별 정보와 게시 관련 메타데이터는 변경하지 마세요. MDX와 Markdoc에서는 강조 상자 제목처럼 독자에게 보이는 컴포넌트 속성도 파악하세요. 동작을 제어하는 속성과 컴포넌트 이름은 애플리케이션 스키마에 속합니다.

마크다운 계열 파일을 모두 같은 방식으로 처리할 수 있다고 가정하지 말고 알맞은 핸들러를 사용하세요. .md로 저장된 Markdoc 문서를 Markdoc으로 처리하려면 markdoc 형식을 명시해야 합니다. 선택과 재구성에 관한 제약 사항은 마크다운, MDX, Markdoc에서 확인하세요. 코드 펜스는 실행 가능한 검증 자료로 보존하고, 명령어를 바꾸는 대신 주변 설명을 번역하세요.

누락된 파일을 채우는 작업을 실행하세요.

sh
lingo push --backfill-missing --wait

완료되면 사이트를 빌드하고 생성된 대상 경로를 여세요. 제목, 설명, 본문, 사용자 지정 컴포넌트, 코드 블록, 링크 하나를 확인하세요. 제목 식별자가 텍스트에서 생성된다면 번역된 문서 내 위치를 가리키는 프래그먼트 링크도 직접 열어 보세요. URL이 유지되어 있어도 연결 대상은 실제로 존재해야 합니다. Markdoc과 Next.js 활용 가이드에서 로캘별 로딩 예제를 확인할 수 있습니다.

구조화된 카탈로그의 규약 지키기 #

JSON과 일반 YAML의 문자열 값을 번역하되, 핸들러의 키 제어 기능으로 식별자, 엔드포인트 등 언어와 무관한 데이터를 보호하세요. 일반 YAML은 현재 CLI의 소스 설정에서 format: "yaml"를 명시적으로 지정하세요. 확장자로 형식을 추론할 수 있어도 설정되지 않은 YAML 소스를 푸시할 수 있는 것은 아닙니다. 로캘이 루트 키라면 yaml-root-key를, OpenAPI 문서 구조라면 yaml-openapi를 사용하세요. TypeScript와 PHP는 지원되는 카탈로그 형태로만 사용하세요. 파일 번역 기능이 임의의 소스 코드를 안전하게 평가해 주는 것은 아닙니다.

PO에서는 메시지 식별 정보, 문맥, 복수형 구조, 대상 시스템에서 사용하는 컴파일 단계를 유지하세요. XLIFF에서는 지원되는 변형 형식의 소스와 대상 구조, 플레이스홀더 구조를 보존하세요. 출력 파일의 존재 여부만 확인하지 말고, 파일을 실제로 사용하는 시스템에서 가져오기나 빌드가 제대로 되는지 검증하세요.

앱 스토어 설명 같은 일반 .txt 파일은 한 줄씩 번역되며 원본의 줄 구성을 유지합니다. metadata/en/*.txt처럼 파일 패턴에 .txt을 포함하거나 "format": "txt"을 설정하세요. docs/en/**/*처럼 범위가 넓은 패턴으로는 이러한 파일이 선택되지 않습니다. 일반 텍스트를 참고하세요. 로캘마다 열이 하나씩 있는 CSV 표는 원래 파일에서 바로 번역됩니다. CSV 문서에 설명된 대로 패턴에 .csv을 포함하거나 "format": "csv"을 설정하세요. 현재 CLI에서는 로캘별 개별 CSV 파일, WebVTT, 자바 .properties을 설정 가능한 형식으로 제공하지 않습니다. CLI 버전 0 형식 레퍼런스는 이러한 이전 워크플로를 설치해 사용 중인 사용자를 위한 문서로, 명령어와 설정은 해당 버전에만 적용됩니다. 이러한 리소스가 알림 없이 누락되지 않도록 마이그레이션 레퍼런스를 참고해 지원되는 방법을 선택하세요.

미디어와 함께 자막 점검하기 #

SRT에서는 자막 텍스트를 번역하고 자막 번호와 타이밍을 원본과 비교하세요. 번역된 자막으로 대표 장면을 재생하세요. 실제 재생기에서 읽어야 할 분량, 줄바꿈, 화자 맥락, 서식 태그를 확인하세요. 타임스탬프가 유지되었다고 해서 주어진 시간 안에 번역된 자막을 읽을 수 있는 것은 아닙니다. 파일 규약은 SubRip을 참고하세요. 둘 다 자막 형식이라는 이유로 WebVTT로 대체하지 마세요.

검증된 전달 경로를 바탕으로 확장하기 #

설정, 소스, 수락된 대상 파일, CLI의 Lockfile을 함께 보관하세요. 문단을 수정한 뒤에는 일반적인 변경분 처리에 lingo push --wait를 사용하고, 대상 파일에서 해당 문단과 변경되지 않은 구간 하나를 비교하세요. 이전 소스는 그에 대응하는 대상 파일과 짝을 맞춰 보관하세요. 문서 구조가 바뀌면 재사용 여부를 판단하기 어려워질 수 있습니다. 위치 기반 패턴은 범위별 계획을 처리하는 방식이 다릅니다. 대규모로 재번역하기 전에는 예상치 산출 워크플로를 사용하고, 예상치는 가격 견적이 아닌 계획 수립용 정보로 활용하세요.

로컬에서 수정한 대상 파일이 덮어써지지 않도록 차이를 보호해야 한다면 --wait 없이 제출하고, 가져오기 전에 lingo pull --dry-run를 확인하세요. 완료를 기다렸다가 곧바로 파일에 반영하는 방식에는 이 확인 단계가 없습니다. 검토된 번역 보존하기를 따르세요.

한 그룹이 정상적으로 빌드되면 GitHub App 또는 지속적 통합 구성 예제를 선택하세요. 사이트 빌드, 스키마 유효성 검사, 링크 점검, 콘텐츠 검토를 이 과정에 계속 포함하세요. lingo check만으로는 문서의 완전성을 확인할 수 없습니다. 업데이트할 때마다 읽을 수 있는 대상 페이지와 팀이 다음 변경에 활용할 수 있는 소스 리비전이 남아 있어야 합니다.