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

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 등).
Prefer translator notes over “fixing” code logic—flag issues to maintainers instead.

Code Blocks and Inline Code

Keep code fences, language hints, and content intact. Translate only comments and human‑readable strings if required.

Example—safe vs unsafe:

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

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

Inline code must stay verbatim:

Good: “Run npm install -g acme-cli and then acme login.”
Bad: “Run npm install -g acme-cli and then acme connexion.” ❌

Validate copy‑pasteability: If a reader copies any snippet, it should run as in the source.

Placeholders and ICU MessageFormat

Preserve placeholders exactly, including spacing and punctuation around them.

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

ICU example:

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

Do not change keys (count, one, other).
Translate only the human‑readable parts (“message”, “messages”).
Do not introduce or remove plural categories without product guidance.

Links, Anchors, and Slugs

Keep Markdown link syntax and resolve strategy consistent.

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

Translate link text if needed; be cautious with URLs and anchors.
Anchors: either keep stable anchors across locales or generate per‑locale anchors and update references accordingly.
Verify relative paths and hash anchors still resolve after translation.
Do not translate file extensions or query params.

Structured Data (JSON/YAML/TOML)

Translate values only—never keys, types, or structure. Always re‑parse after editing.

JSON:

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

Keys like title, cta, limits, max must remain unchanged.
Numbers, booleans, and nulls stay as types, not words.

YAML (watch folded scalars):

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

Preserve quoting, escapes, indentation, and trailing commas (where applicable).

Filenames, CLI, and API Names

Do not translate filenames, package names, endpoints, or CLI flags.
Keep case sensitivity exactly as in source (e.g., --DryRun vs --dry-run).
Maintain commands verbatim; add callouts if locale‑specific differences exist.

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

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

Markdown Gotchas

Tables: keep pipes and alignment; do not break columns.

| 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 항목)

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