코드를 손상시키지 않고 기술 문서를 번역하는 방법

TABLE OF CONTENTS

기술 문서는 엄격합니다: 단 하나의 코드 펜스, 플레이스홀더, 또는 앵커가 빌드를 깨뜨리거나, 독자를 혼란스럽게 하거나, 복사-붙여넣기 오류를 초래할 수 있습니다. 이 가이드는 코드가 손상되지 않고 문서가 배포 가능한 상태를 유지하면서 기술 문서를 자신 있게 번역할 수 있는 반복 가능하고 안전한 워크플로우를 제공합니다.

대상: 개발자 문서, API 가이드, README 스타일 콘텐츠를 작업하는 기술 작가, 개발자 옹호자, 번역가.

개요:

절대 번역해서는 안 되는 것 이해하기 (코드, 키, 토큰)
도구가 구문을 분석하는 구문 보존하기 (펜스, 중괄호, 앵커)
편집 후 구조화된 데이터와 링크 검증하기
릴리스 전에 문제를 잡기 위한 자동화 사용하기

번역 전 준비

콘텐츠 유형 목록 작성

Markdown (제목, 링크, 표), 코드 블록, 인라인 코드
구조화된 데이터: JSON/YAML/TOML 스니펫 및 구성 파일
스크린샷, 다이어그램, 임베디드 비주얼

번역 불가 토큰 정의

파일 경로, 패키지 이름, 가져오기, API 이름, CLI 플래그, 환경 변수
플레이스홀더 및 변수: {count}, %s, $HOME, {{token}}
파일 이름 및 확장자: config.yaml, .env, .md, .json

일관성 가이드레일 설정

도메인 용어 및 제품 이름에 대한 용어집/용어베이스
스타일 가이드: 톤, 형식, 구두점, 대소문자, 제목 규칙
로케일별 앵커/슬러그 전략 (안정적 vs 현지화)

안전한 검증 설정

각 배치 후 Markdown/링크를 검증하기 위한 스테이징 빌드
JSON/YAML/TOML용 파서/린터
CI에서 링크 체커 및 앵커 검증기

핵심 안전장치

코드, 식별자, 키, 파일 이름, 환경 변수, 플래그를 번역하지 마십시오.
도구가 구문을 분석하는 구두점과 구문을 보존하십시오 (백틱, 중괄호, 파이프).
중요한 공백을 유지하십시오: 코드 및 목록 구조의 들여쓰기.
언어 태그가 있는 펜스 코드 블록을 일관되게 사용하십시오 (js, bash 등).
코드 논리를 “수정”하기보다는 번역자 주석을 선호하십시오—대신 유지 관리자에게 문제를 플래그하십시오.

코드 블록 및 인라인 코드

코드 펜스, 언어 힌트 및 내용을 그대로 유지하세요. 필요한 경우 주석과 사람이 읽을 수 있는 문자열만 번역하세요.

예제—안전 vs 비안전:

// SAFE: 주석만 현지화
// 사용자 토큰을 얻습니다
import { getToken } from "@acme/sdk";
const token = await getToken();

// UNSAFE: 식별자/임포트/패키지 이름을 번역하지 마세요
// import { obtenirJeton } from "@acme/sdk"; // ❌

인라인 코드는 그대로 유지해야 합니다:

좋음: “Run npm install -g acme-cli and then acme login.”
나쁨: “Run npm install -g acme-cli and then acme connexion.” ❌

복사-붙여넣기 가능성 검증: 독자가 어떤 스니펫을 복사하더라도 원본처럼 실행되어야 합니다.

플레이스홀더 및 ICU 메시지 형식

플레이스홀더를 정확히 보존하고, 주변의 공백 및 구두점도 유지하세요.

# 토큰이나 공백을 변경하지 마세요
echo "Processing {count} files"   # ✅
echo "Processing { count } files" # ❌ 중괄호 안에 공백 추가

ICU 예제:

{count, plural,
  =0 {No messages}
  one {# message}
  other {# messages}
}

키(count, one, other)를 변경하지 마세요.
사람이 읽을 수 있는 부분(“message”, “messages”)만 번역하세요.
제품 지침 없이 복수형 범주를 추가하거나 제거하지 마세요.

링크, 앵커 및 슬러그

Markdown 링크 구문과 해결 전략을 일관되게 유지하세요.

[Read the API guide](/api/getting-started)  
[See the config section](#configuration)

필요 시 링크 텍스트를 번역하세요; URL과 앵커는 주의해서 다루세요.
앵커: 모든 로케일에서 안정적인 앵커를 유지하거나 로케일별 앵커를 생성하고 참조를 적절히 업데이트하세요.
번역 후에도 상대 경로와 해시 앵커가 여전히 해결되는지 확인하세요.
파일 확장자나 쿼리 매개변수를 번역하지 마세요.

구조화된 데이터 (JSON/YAML/TOML)

값만 번역하고, 키, 유형 또는 구조는 절대 번역하지 마세요. 편집 후 항상 다시 구문 분석하세요.

JSON:

{
  "title": "User Guide",
  "cta": "Get Started",
  "limits": { "max": 5, "unit": "requests/second" }
}

title, cta, limits, max와 같은 키는 변경하지 마십시오.
숫자, 불리언, null은 단어가 아닌 타입으로 유지합니다.

YAML (접힌 스칼라 주의):

note: >
  줄은 하나의 문단으로 접힙니다.
  들여쓰기와 마커를 그대로 유지하십시오.

인용, 이스케이프, 들여쓰기, 그리고 끝에 있는 쉼표를 유지하십시오 (해당되는 경우).

파일명, CLI, 및 API 이름

파일명, 패키지명, 엔드포인트, 또는 CLI 플래그를 번역하지 마십시오.
원본의 대소문자 구분을 정확히 유지하십시오 (예: --DryRun vs --dry-run).
명령어를 그대로 유지하십시오; 지역별 차이가 있는 경우 주석을 추가하십시오.

# 올바른 예
kubectl get pods --namespace default

# 잘못된 예 (플래그 번역됨) ❌
kubectl get pods --nom-espace defaut

Markdown 주의사항

표: 파이프와 정렬을 유지하십시오; 열을 깨지 마십시오.

| Option | Description           |
|-------:|-----------------------|
|   -v   | Verbose output        |
|   -q   | Quiet mode            |

주의/노트: 도구에서 사용하는 마커를 유지하십시오.
인라인 HTML: 태그/속성을 건드리지 마십시오.
각주: id와 순서를 유지하십시오.
스마트 인용부호: 코드 컨텍스트 내에서는 일반 인용부호를 선호하십시오.

시각적 요소와 접근성

의미를 위해 대체 텍스트를 현지화하십시오, 픽셀 콘텐츠가 아닙니다.
언어가 아닌 UI를 강조하는 지역 비특정 스크린샷을 선호하거나, 지역별 세트를 제공하십시오.
다이어그램 소스 파일 (예: Mermaid)을 지역 간에 동기화하십시오.
이미지에 포함된 텍스트를 피하십시오; 캡션과 레이블을 외부화하십시오.

SEO 및 메타데이터

제목, 설명, 헤딩을 지역에 적합한 키워드를 사용하여 번역하십시오.
사이트 규칙에 따라 정규 URL과 hreflang을 일관되게 유지하십시오.
메타/속성 키 또는 JSON‑LD 키를 번역하지 마십시오.
404를 피하기 위해 앵커 전략에 맞춰 슬러그를 정렬하십시오.

워크플로우 및 자동화

코드 범위 및 태그를 보존하는 CAT/LLM 워크플로우 사용.
용어집과 번역 금지 목록으로 용어 고정.
Markdown을 린트하고 JSON/YAML을 검증하는 사전 커밋 훅 추가.
모든 PR에서 링크 검사기와 앵커 검증기 실행.
작은 검토 가능한 청크로 변경 사항을 일괄 처리하고 차이점을 추적.

제안된 도구 (스택에 맞게 조정):

CI에서 Markdown 린팅 및 링크 검사
구문 회귀를 잡기 위한 JSON/YAML 파싱 단계
자리 표시자 및 숫자 형식을 스캔하기 위한 정규 표현식 패키지

QA 및 검증

병합 전에 다음 검사를 실행하십시오:

구문 문제를 잡기 위해 사이트 빌드: pnpm build
유형/콘텐츠 검사 (Astro 콘텐츠 컬렉션): pnpm astro check
주요 페이지 미리보기 및 스팟 테스트: pnpm preview
코드 샘플이 컴파일되거나 실행되는지 검증 (해당되는 경우)
링크 및 앵커 검사기 실행; 404 또는 손상된 해시 수정

일반적인 함정

실수로 키/자리 표시자를 번역.
코드 펜스 또는 테이블 파이프 손상.
파일 경로, 플래그 또는 API 이름 현지화.
앵커 링크를 업데이트하지 않고 제목 변경.
코드 또는 JSON 내부에 스마트 인용 부호 도입.

부록: 빠른 체크리스트

사전 점검 (5 항목)

용어집 및 번역 금지 목록 준비 완료
토큰/자리 표시자 정의 및 보호
앵커/슬러그 전략 확인
링크 대상 매핑 (내부 대 외부)
스테이징 빌드 사용 가능

코드 샘플 안전성 (5 항목)

펜스 및 언어 힌트 유지
식별자/임포트 미변경; 주석만 현지화
자리 표시자 및 인용 보존
복사-붙여넣기 테스트 통과
유지보수자에게 오래된 스니펫 플래그 지정

구조화된 데이터 (5 항목)

키 및 유형 미변경
인용/이스케이프/들여쓰기 보존
숫자 및 불리언이 유형으로 남아 있음
로컬에서 파서/린터 통과
실수로 키 변경된 부분에 대한 차이점 검토