readme-i18n

readme-i18n 스킬 개요

readme-i18n가 하는 일

readme-i18n는 단일 GitHub 스타일 README.md를 유지보수 가능한 다국어 README 세트로 바꾸는 데 특화된 스킬입니다. 일반적인 앱 현지화용 도구는 아닙니다. 핵심 역할은 원본 README를 번역하고, README.zh.md 같은 형제 파일을 만들고, Markdown 구조와 저장소 동작 방식을 보존하며, 모든 언어 버전에 공통으로 쓰는 언어 선택기를 추가하거나 정리하는 것입니다.

누가 readme-i18n를 써야 하나

이 스킬은 저장소 문서를 다루는 메인테이너, 오픈소스 기여자, AI 에이전트에 잘 맞습니다. 여기서 진짜 목표는 단순히 “텍스트를 번역”하는 것이 아니라, “GitHub에서 실제로 문제없이 동작하는 번역된 README 파일을 배포”하는 데 있습니다. 배지, 링크, 코드 펜스, 파일명, 언어 전환기가 일관되게 유지되어야 한다면, 일반 번역 프롬프트보다 readme-i18n가 더 나은 출발점입니다.

실제로 해결해야 하는 일

대부분의 README 번역은 어휘보다 구조에서 실패합니다. 사용자에게 필요한 워크플로는 다음을 만족해야 합니다:

• 하나의 파일을 source-of-truth로 취급한다
• 섹션 순서를 원본과 맞춘다
• 명령어, 경로, 코드, 링크 동작을 보존한다
• 모든 언어 버전을 일관되게 업데이트한다
• 중복되거나 깨진 언어 선택기를 만들지 않는다

이것이 바로 readme-i18n skill의 실질적인 가치입니다.

일반 프롬프트와 다른 이유

가장 큰 차이는 판단 로직에 있습니다. 이 스킬은 무엇을 정확히 보존해야 하는지, 언제 한 번만 확인 질문을 해야 하는지, 기존 파일에서 관례를 어떻게 추론해야 하는지, 새 선택기를 또 만드는 대신 기존 선택기를 제자리에서 어떻게 갱신해야 하는지를 에이전트에 알려줍니다. 함께 제공되는 참고 자료도 도입 단계에서 특히 유용합니다. 언어 선택기 배치와 번역에 안전한 Markdown 처리 방식에서 흔히 생기는 추측을 줄여주기 때문입니다.

readme-i18n 스킬 사용 방법

readme-i18n 설치 맥락

이 스킬은 이미 사용 중인 Skills 호환 환경에서 xixu-me/skills 저장소로부터 설치하면 됩니다. 환경이 GitHub 직접 설치를 지원한다면 보통 다음 패턴을 씁니다.

npx skills add https://github.com/xixu-me/skills --skill readme-i18n

환경마다 스킬 관리 방식이 다르다면, 소스 기준으로 https://github.com/xixu-me/skills/tree/main/skills/readme-i18n 저장소 URL을 사용하고 skills/readme-i18n에서 스킬을 불러오면 됩니다.

처음 쓰기 전에 읽어야 할 파일

이 스킬은 아래 순서대로 읽는 것이 가장 빠르고 핵심 정보 밀도가 높습니다.

1. skills/readme-i18n/SKILL.md
2. skills/readme-i18n/references/language-selector-reference.md
3. skills/readme-i18n/references/preservation-checklist.md

이 순서가 중요합니다. SKILL.md는 전체 워크플로를 설명하고, selector reference는 기대되는 블록 형태와 배치 위치를 보여주며, preservation checklist는 절대 바뀌면 안 되는 요소를 짚어줍니다.

readme-i18n에 필요한 입력값

이 스킬은 다음 정보를 제공할 때 가장 잘 작동합니다.

• 원본 README 경로, 보통 README.md
• 원본 언어
• 대상 언어 또는 대상 언어들
• 용어집 또는 번역하지 말아야 할 용어
• 저장소가 이미 README 현지화를 하고 있다면 기존 파일명 규칙

대상 언어를 생략해도, 이 스킬은 먼저 기존 번역 파일, 선택기, 파일명, 이슈, 저장소 관례를 살펴보도록 설계되어 있습니다. 그래도 언어가 명확하지 않다면, 임의로 대상을 만들어내는 대신 한 번만 확인 질문을 해야 합니다.

알아두면 좋은 기본 가정

문서화된 기본값은 실무적으로 유용하며, readme-i18n를 실행하기 전에 알아두면 좋습니다.

• 별도 지정이 없다면 루트의 README.md를 source-of-truth로 본다
• 애매하지 않다면 원본 언어는 영어로 가정한다
• 섹션 순서는 원본과 맞춰 유지해야 한다
• 기존 다국어 파일명 체계가 있다면 새로운 체계를 강제하지 않고 그것을 따른다

이 기본값 덕분에 빈 번역 요청보다 기존 저장소에 더 안전하게 적용할 수 있습니다.

readme-i18n를 잘 쓰는 프롬프트 방식

약한 요청은 이런 식입니다. “Translate my README into Chinese.”

더 강한 readme-i18n usage 프롬프트는 다음과 같습니다.

• translate README.md from English to Simplified Chinese
• create README.zh.md
• preserve commands, paths, badge URLs, code fences, and relative links
• add a top language selector to both files
• keep heading order identical
• do not translate product name AcmeCLI or env vars
• follow any existing filename convention if found

이처럼 구체적으로 써주면 결과 품질이 바로 좋아집니다. 스킬이 전제로 삼는 보존 규칙과 selector 규칙에 정확히 맞기 때문입니다.

번역용 예시 워크플로

실무적인 readme-i18n for Translation 워크플로는 다음과 같습니다.

1. source-of-truth README를 식별한다.
2. 번역된 버전이 이미 있는지 확인한다.
3. 저장소의 파일명 패턴과 현재 selector 스타일을 파악한다.
4. 자연어 텍스트만 번역한다.
5. 코드, 명령어, URL, 파일 경로는 정확히 유지한다.
6. 각 버전 상단 근처에 selector 블록 하나를 추가하거나 정규화한다.
7. 모든 파일에서 링크, 서식, 일관성을 검증한다.

핵심 관점은 “텍스트 번역”이 아니라 “README 제품군 유지관리”입니다.

언어 선택기는 어떻게 동작해야 하나

이 스킬에서 가장 강력한 보조 파일은 selector reference입니다. 각 README 버전 상단 근처, 보통 제목과 배지 묶음 다음에 언어 선택기 블록 하나를 두고, 다음과 같은 안정적인 마커를 권장합니다.

<!-- README-I18N:START -->
<!-- README-I18N:END -->

이 마커가 중요한 이유는 이후 실행에서 선택기를 제자리에서 갱신할 수 있기 때문입니다. 현재 언어는 강조하되 링크를 걸지 않고, 다른 언어는 링크로 연결해야 합니다. 언어 순서는 모든 버전에서 동일하게 유지해야 합니다.

반드시 정확히 보존해야 하는 것

preservation checklist는 이 readme-i18n guide를 도입할 때 가장 중요한 부분입니다. 실무적으로는 다음 항목을 번역하면 안 됩니다.

• 인라인 코드
• fenced code block
• 명령어, 플래그, env var, 경로
• badge URL과 query param
• 이미지 소스 경로
• 테이블 구조
• raw HTML 동작 방식

사용자에게 보이는 설명 문구는 번역하되, README를 실제로 작동하게 만드는 메커니즘은 그대로 유지해야 합니다.

readme-i18n가 존중하는 일반적인 저장소 관례

저장소가 이미 기본값과 다른 파일명 체계를 쓰고 있다면

• README.md
• README.zh.md
• README.es.md

스킬은 그 체계를 유지해야 합니다. 이는 이미 일부 현지화가 진행된 저장소나, CI 참조, 기여자 기대치가 파일명에 연결되어 있는 경우 특히 중요합니다.

readme-i18n가 시간을 가장 많이 아껴주는 경우

이 스킬의 가치는 아래와 같은 도입 장애물이 있을 때 가장 큽니다.

• 여러 개의 현지화된 README 파일을 서로 동기화해 유지해야 한다
• 저장소에 지저분하거나 중복된 언어 전환기가 이미 있다
• 과거 번역이 Markdown이나 링크를 망가뜨린 적이 있다
• 일회성 수작업이 아니라 반복 가능한 업데이트 흐름이 필요하다

반대로 README 내용을 대충 이해하기 위한 개인용 번역만 필요하다면, 이 스킬은 필요 이상으로 절차가 많을 수 있습니다.

readme-i18n 스킬 FAQ

readme-i18n는 초보자에게도 괜찮을까?

네. 목표가 README 현지화에 한정된다면 괜찮습니다. 이 스킬은 작업을 명확한 입력값과 보존 규칙으로 좁혀주기 때문에, 번역 워크플로를 처음부터 직접 짜는 것보다 쉽습니다. 다만 초보자라도 결과물 검토는 필요하며, 특히 링크 대상, 제목, selector 일관성은 꼭 확인해야 합니다.

일반 번역 프롬프트 대신 언제 readme-i18n를 써야 할까?

번역된 README가 실제로 저장소에 커밋될 예정이라면 readme-i18n를 쓰는 편이 좋습니다. 일반 프롬프트는 과하게 번역하거나, 코드 예제를 바꾸거나, 배지 링크를 깨뜨리거나, 파일 간 이동 링크를 놓치기 쉽습니다. 속도보다 결과의 정확성이 더 중요할 때 이 스킬이 더 적합합니다.

readme-i18n는 GitHub 저장소에서만 쓸 수 있나?

이 스킬은 GitHub 스타일의 저장소 README와 Markdown 관례에 최적화되어 있습니다. 다른 Git 호스팅 플랫폼에서도 도움은 될 수 있지만, 전체 문서 사이트나 제품 현지화 시스템보다는 README.md 중심의 오픈소스 저장소에 가장 잘 맞는 가정을 갖고 있습니다.

readme-i18n가 전체 문서 세트도 처리하나?

아니요. 이것은 README 중심 워크플로입니다. 웹사이트, 앱, 혹은 전체 문서 세트에 대한 i18n이 필요하다면 readme-i18n skill은 범위가 너무 좁습니다. 이 스킬의 강점은 저장소의 대표 문서 하나와 그 번역된 형제 파일들을 일관되게 유지하는 데 있습니다.

어떤 언어를 사용할 수 있나?

대상 언어를 명시하거나 저장소에서 이미 충분히 드러나는 한, 이 스킬은 특정 언어에 종속되지 않습니다. 저장소에 근거가 부족할 때 대상 언어를 지어내지 않는다는 점이 명시적인 특징입니다.

readme-i18n로 기존 다국어 README 구성을 업데이트할 수 있나?

네. 오히려 가장 좋은 사용 사례 중 하나입니다. 현재 번역 파일과 selector를 조사하고, 파일명 관례를 유지하며, 두 번째 전환기를 추가하는 대신 기존 전환기를 정규화하도록 설계되어 있습니다.

언제 readme-i18n가 맞지 않나?

다음 경우에는 건너뛰는 편이 좋습니다.

• 가볍게 읽기 위한 비공식 번역만 원한다
• 문서가 README 바깥에 있다
• 큰 문서 코퍼스 전반에서 용어 관리를 해야 한다
• 저장소 정책상 README 파일에 언어 선택기 링크를 두지 않는다

이런 경우에는 더 가벼운 프롬프트나, 더 넓은 범위의 문서 현지화 워크플로가 더 잘 맞을 수 있습니다.

readme-i18n 스킬 개선 방법

readme-i18n에 더 강한 원본 제약을 제공하라

입력이 좋을수록 README 결과물도 좋아집니다. 다음 정보를 포함하세요.

• 정확한 원본 파일 경로
• 정확한 대상 로케일
• 절대 번역하지 말아야 할 용어
• 언어 이름 표기에 쓸 preferred autonym
• 기존 번역 파일을 덮어쓸지, 업데이트만 할지

이렇게 하면 가장 흔한 실패 패턴, 즉 번역은 맞지만 저장소 동작은 틀리는 상황을 줄일 수 있습니다.

이름과 기술 용어에 대한 용어집을 제공하라

README에 제품명, CLI 명령어, 패키지명, 도메인 특화 용어가 들어 있다면 이를 명시적으로 나열하세요. readme-i18n도 기본적으로 리터럴 보존을 시도하지만, 짧은 용어집만 있어도 제목, 기능 설명, 예시 전반에서 일관성이 더 좋아집니다.

스킬에 손대지 말아야 할 범위를 분명히 알려라

readme-i18n usage를 개선하는 가장 좋은 방법 중 하나는 강한 경계를 명시하는 것입니다.

• 모든 코드 블록은 byte-for-byte identical하게 유지
• relative link 보존
• 요청이 없으면 파일명 변경 금지
• badge target 변경 금지
• 섹션 순서 변경 금지

이 지시는 preservation checklist와 매우 밀접하게 맞물리며, “도와주려다 망치는” 편집을 막아줍니다.

커밋 전에 selector 배치를 검토하라

흔한 결과물 문제 중 하나는 어색하거나 중복된 언어 전환기입니다. 생성된 selector를 references/language-selector-reference.md와 비교하고 다음을 확인하세요.

• 파일마다 selector가 하나만 존재한다
• 버전 간 배치가 일관된다
• 현재 언어는 링크가 아니라 굵게 표시된다
• 링크가 실제 형제 파일명을 가리킨다

작은 검토 단계지만 효과는 큽니다.

현지화된 제목과 앵커를 확인하라

번역된 제목은, 제목 텍스트로부터 fragment ID를 생성하는 플랫폼에서 앵커 동작에 영향을 줄 수 있습니다. 이 스킬은 제목 계층을 보존하려고 하지만, 번역 후에는 내부 제목 링크를 직접 테스트하는 것이 좋습니다. 특히 긴 README일수록 더 중요합니다.

임의 수정이 아니라 원본 변경 기준으로 반복하라

장기 유지보수를 위해서는 README.md를 source-of-truth로 유지하고, 각 현지화 파일을 제각각 손으로 고치기보다 원본 변경을 기준으로 readme-i18n를 다시 실행하는 편이 좋습니다. 그래야 시간이 지나도 섹션 순서, selector 내용, 용어가 함께 맞춰집니다.

첫 실행 후에는 나란히 비교 검증하라

첫 번째 결과가 나온 뒤에는 원본과 번역본을 나란히 비교하면서 다음을 확인하세요.

• 섹션 수가 같은지
• 코드 블록 수가 같은지
• 테이블과 목록 구조가 같은지
• 이미지와 배지가 같은지
• selector 링크가 정상 동작하는지

이 방법은 모든 문장을 다시 읽는 것보다 구조적 회귀를 더 빨리 잡아냅니다.

다음 실행을 위해 저장소 관례를 명시하라

저장소가 비표준 다국어 패턴을 쓴다면, 다음에 readme-i18n를 호출할 때 프롬프트에 직접 적어주세요. 예:

• “Use README.ja.md, not README.jp.md”
• “Keep the existing unmarked selector and normalize it in place”
• “Spanish variant should be README.es-419.md”

저장소 관례를 추론에 맡기지 않고 명시해주면 이 스킬의 신뢰도가 훨씬 높아집니다.