로케일 기반 콘텐츠 현지화

주어진 로케일로 콘텐츠 현지화하기

주어진 로케일로 콘텐츠를 현지화하는 스킬입니다.

작동 방식

이 스킬은 입력 콘텐츠와 대상 로케일 목록을 받습니다. 그런 다음 각 지정된 로케일로 콘텐츠를 번역하여 현지화된 버전을 제공합니다.

콘텐츠 구조

.
└── docs/                         ← 워크숍 콘텐츠 (원본 + 로케일 출력)
    ├── README.md                 ← 랜딩 페이지 (원본; 슬러그: index)
    ├── <category>/               ← 영어 워크숍 카테고리
    │   ├── README.md             ← 카테고리 랜딩 (원본; 슬러그: <category>)
    │   └── <workshop>/
    │       ├── README.md         ← 워크숍 랜딩 (원본; 슬러그: <category>/<workshop>)
    │       └── *.md
    ├── _images/              ← 공유 자산 (현지화되지 않음)
    └── <locale>/             ← 현지화된 출력, docs/의 직계 하위 디렉토리
        ├── README.md         ← 로케일 랜딩 (슬러그: <locale>)
        └── <category>/
            ├── README.md         ← 현지화된 카테고리 랜딩 (슬러그: <locale>/<category>)
            └── <workshop>/
                ├── README.md     ← 현지화된 워크숍 랜딩 (슬러그: <locale>/<category>/<workshop>)
                └── *.md

입력 콘텐츠

현지화 대상이 되는 콘텐츠는 다음과 같습니다:

• docs/ 및 그 하위 디렉토리에 있는 모든 영어 마크다운 파일 — 사이트 랜딩(docs/README.md), 카테고리 랜딩, 워크숍 레슨(docs/<category>/<workshop>/**/*.md).

_images/ (공유 자산) 또는 설정된 로케일 루트 디렉토리를 소스 입력으로 취급하지 마십시오.

이미 docs/<locale>/ 아래에 있는 파일은 출력물이지 입력이 아닙니다. 설정된 로케일 루트 디렉토리를 다시 현지화할 소스 콘텐츠로 절대 취급하지 마십시오.

대상 로케일

대상 로케일은 이 스킬의 rules 디렉토리에 마크다운 파일로 정의됩니다 (예: rules/ko-kr.md). 처리할 로케일을 확인하려면 rules/의 파일을 나열하십시오. 각 <locale>.md 파일은 정확히 하나의 지원되는 대상 로케일에 해당합니다. 각 로케일에는 번역에 대한 자체 규칙과 지침이 있어 현지화된 콘텐츠가 대상 사용자에게 적합하도록 보장합니다.

로케일 식별자는 소문자와 하이픈을 사용합니다 (예: ko-kr). 이 스킬에서 규칙 파일 이름과 출력 디렉토리 모두에 대한 표준 표기법입니다. 일관성을 유지하십시오.

출력 콘텐츠

모든 현지화된 워크숍 콘텐츠는 리포지토리 루트의 docs/ 콘텐츠 디렉토리 아래에 직접 저장되며, 각 로케일은 자체 하위 디렉토리를 갖습니다. 예를 들어, 한국어 콘텐츠는 docs/ko-kr/에 저장됩니다.

로케일 디렉토리는 docs/의 직계 하위 디렉토리여야 Starlight (website/astro.config.mjs에 구성됨)가 이를 인식하고 언어 선택기를 렌더링합니다. 중간에 localizations/ 디렉토리를 추가하지 마십시오.

현지화 프로세스

현지화에는 세 가지 경우가 있습니다. 해당 경우를 감지하려면 소스 트리를 기존 docs/<locale>/ 트리와 비교하고, 소스 파일의 git 히스토리를 사용하여 변경 사항을 감지하십시오:

• 원본 존재, 해당 로케일의 현지화 버전 없음: 새 현지화 문서를 생성합니다.
• 원본과 현지화 버전 모두 존재: 소스 트리를 docs/<locale>/와 비교한 다음, 소스 파일에 대해 git diff (또는 git log)를 실행하여 현지화 버전이 마지막으로 생성된 이후 변경된 사항을 찾습니다. 현지화 문서의 영향을 받은 섹션만 업데이트하고, 변경되지 않은 섹션을 불필요하게 다시 번역하지 마십시오.
• 현지화 버전은 존재하지만 원본이 삭제됨: 고아가 된 현지화 문서를 삭제하고 (그리고 비어 있는 로케일 하위 디렉토리를 정리합니다).

프로세스는 두 단계로 실행됩니다. 먼저 콘텐츠를 분석하여 핵심 문구와 컨텍스트를 식별합니다. 그런 다음 번역가 에이전트가 초기 현지화를 수행하고, 평가자 에이전트가 검토 및 개선 단계를 수행하여 품질과 일관성을 보장합니다.

번역가와 평가자 "에이전트"는 역할/페르소나이지 외부 도구가 아닙니다. 전용 하위 에이전트를 사용할 수 없는 경우, 순차적 페르소나로 수행하십시오: 먼저 번역가 역할을 채택하여 초안을 작성한 다음, 평가자 역할을 채택하여 로케일 규칙에 따라 해당 초안을 비판하고 개선합니다. 평가자의 기준이 통과될 때까지 개선 루프를 반복하십시오.

마크다운 및 서식 보존

로케일에 관계없이 다음은 정확히 보존되어야 하며 번역되지 않아야 합니다:

• YAML frontmatter 키 (적절한 경우에만 값을 번역, 예: title). 예외 — 랜딩 페이지(README.md)의 slug 키: 사이트는 각 폴더 랜딩을 slug로 라우팅하므로, 현지화된 랜딩은 영어 슬러그 대신 로케일 접두사가 붙은 슬러그를 가져야 합니다. 다시 작성하십시오: 로케일 루트(docs/<locale>/README.md)는 slug: <locale>을 사용하고, 현지화된 카테고리 랜딩은 slug: <locale>/<category>를 사용하며, 현지화된 워크숍 랜딩은 slug: <locale>/<category>/<workshop>을 사용합니다. 영어 랜딩 슬러그를 현지화된 파일에 그대로 복사하지 마십시오. 영어 경로와 충돌할 수 있습니다.
• 펜스 및 인라인 코드 (변수, 함수, 명령 이름 포함).
• URL 및 외부 링크 대상.
• HTML 태그, 마크다운 구조, 테이블, 경고 표시.

사람이 읽는 산문(prose)은 번역하십시오 (로케일 규칙에 따라 설명적인 코드 블록 내 주석 포함). 헤딩 순서와 문서 구조를 안정적으로 유지하십시오.

헤딩 앵커는 현지화된 텍스트를 따릅니다. 헤딩이 번역되면 자동 생성된 앵커/슬러그도 함께 변경됩니다. 이는 정상입니다. 요구 사항은 동일 문서 내 앵커 링크가 계속 작동하도록 하는 것입니다: 헤딩을 번역할 때마다 해당 헤딩을 대상으로 하는 모든 페이지 내 링크(](#...))를 현지화된 헤딩의 새 슬러그로 업데이트하십시오. 헤딩이 번역된 후에는 링크가 원래 영어 슬러그를 가리키도록 두지 말고, 더 이상 헤딩과 일치하지 않는 영어 앵커를 유지하지 마십시오. 현지화되지 않은 파일 (또는 외부 URL)을 가리키는 앵커는 원래 대상을 유지합니다.

이미지 및 에셋 경로는 현지화된 에셋이 없는 한 원본 에셋을 가리킵니다. 현지화된 파일이 docs/<locale>/ 아래에 있으므로, 소스 기준 상대 경로가 여전히 공유 에셋을 올바르게 가리키도록 필요에 따라 다시 작성하십시오 (예: docs/<locale>/real-world-development/app/2-foo.md의 레슨은 ../../../_images/x.png를 사용하여 docs/_images/에 도달). 해당 번역된 이미지가 로케일 트리 아래에 실제로 존재하는 경우에만 현지화된 에셋을 가리키십시오. 어느 쪽이든 링크는 실제 파일로 확인되어야 합니다.

번역가 에이전트

번역가 에이전트를 사용하여 현지화를 수행하십시오. rules 디렉토리의 각 대상 로케일 문서에 정의된 규칙과 지침을 따라야 합니다.

평가자 에이전트

평가자 에이전트를 사용하여 현지화된 콘텐츠의 품질을 평가하십시오. 평가자는 정확성, 문화적 관련성 및 전반적인 품질을 확인하며, rules 디렉토리의 대상 로케일에 정의된 규칙과 지침을 따릅니다.

평가자는 로케일의 평가자 채점 루브릭 (로케일의 rules/<locale>.md에 정의됨)에 대해 현지화된 문서를 채점합니다. 루브릭은 두 가지 계층을 사용합니다: 티어 A는 반드시 5점을 받아야 하는 하드-페일 기준이고, 티어 B는 1~5점으로 채점되며 4점 또는 5점을 받아야 하는 기준입니다. 적용 가능한 모든 티어 A 기준이 5점이고 적용 가능한 모든 티어 B 기준이 4점 이상일 때만 문서가 통과합니다. 기준에 미치지 못하는 부분이 있으면 특정 메모와 함께 문서를 번역가에게 반환하고, 루브릭의 반복 상한선에 도달할 때까지 번역 → 평가 루프를 다시 실행하십시오. 상한선에 도달하면 사람에게 에스컬레이션합니다.

해야 할 것과 하지 말아야 할 것

• 해야 할 것: rules 디렉토리에 정의된 대상 로케일에 대해서만 현지화를 수행하십시오 (지원되는 로케일당 하나의 <locale>.md 파일). 지원되지 않는 로케일로 현지화하지 마십시오.
• 해야 할 것: 마크다운 구조, 코드, 외부 링크/URL 대상 및 frontmatter 키를 정확히 보존하십시오 (마크다운 및 서식 보존 참조).
• 해야 할 것: 헤딩 앵커가 현지화된 헤딩 텍스트를 따르도록 하고, 동일 문서 내 앵커 링크를 새 슬러그와 일치하도록 업데이트하여 계속 작동하도록 하십시오 (마크다운 및 서식 보존 참조).
• 해야 할 것: 이미지 및 에셋 경로는 원본 에셋을 가리키도록 하고 (필요에 따라 상대 경로를 다시 작성하여 docs/<locale>/에서 확인되도록), 해당 현지화된 에셋이 존재하는 경우는 제외합니다 (마크다운 및 서식 보존 참조).
• 해야 할 것: 소스 디렉토리 구조를 docs/<locale>/ 아래에 미러링하십시오.
• 하지 말아야 할 것: 설정된 로케일 루트 디렉토리를 소스 입력으로 취급하지 마십시오.
• 하지 말아야 할 것: 콘텐츠의 순서를 변경하거나 구조를 변경하지 마십시오. 헤딩과 그 순서를 안정적으로 유지하십시오.
• 하지 말아야 할 것: 코드, 명령어 또는 식별자를 번역하지 마십시오. 설명적인 산문과 코드 주석만 번역하십시오.