번역된 로컬라이제이션 파일이 앱을 망가뜨리는 이유 (그리고 건드리면 안 되는 것)

로컬라이제이션 파일은 문장이 들어 있는 코드다

PO, YAML, .properties, RESX, XLIFF, JSON 로케일 파일은 문장 목록처럼 보이지만, 산문인 것은 값뿐입니다. 키는 코드가 조회하는 식별자이고, 플레이스홀더는 런타임에 코드가 채우는 슬롯이며, 이스케이프와 마크업은 파서가 의존하는 구문입니다. 줄 전체를 텍스트로 취급하는 번역가는 읽기에는 훌륭하지만 로드되지 않는 파일, 혹은 로드는 되지만 화면이 처음 숫자를 포맷하는 순간 충돌하는 파일을 만들어 냅니다. 이 오류는 보통 한 언어에서만 나타나기 때문에 리뷰에서 가장 잡아내기 어려운 종류의 버그가 됩니다.

번역 후에도 그대로 남아야 하는 다섯 가지

• 키와 리소스 이름 — 코드는 키로 문자열을 조회하므로, 번역된 키는 그저 누락된 문자열일 뿐입니다.
• 플레이스홀더 — %s, %1$d, {0}, {name}, ICU 인수는 코드가 채웁니다. 하나라도 이름을 바꾸거나 빼면 서식이 깨지거나 런타임에 예외가 발생합니다.
• 이스케이프와 인코딩 규칙 — 전통적인 Properties.load(InputStream) 메서드로 읽는 .properties 파일은 Latin-1로 처리되고 그 밖의 문자는 \uXXXX 이스케이프로 작성되므로, 라틴 문자가 아닌 텍스트를 그대로 넣으면 글자가 깨질(mojibake) 수 있습니다.
• 문자열 안의 마크업 — HTML 태그, XLIFF 인라인 코드, Markdown은 짝이 맞아야 하며, 그렇지 않으면 렌더링된 문자열이 주변 페이지를 망가뜨립니다.
• 파일 구조 — YAML 들여쓰기, 블록 스칼라, 앵커와 별칭, XML 중첩은 구문입니다. 들여쓰기가 밀리거나 앵커 이름이 번역되면 파일의 의미가 바뀝니다.

복수형은 단수형에 "s"를 붙인 것이 아니다

영어에는 복수형이 두 가지이므로 모든 언어가 그렇다고 생각하기 쉽습니다. GNU gettext 매뉴얼은 그것이 왜 틀렸는지 보여 줍니다. 각 언어는 자체 Plural-Forms 규칙을 선언하고, 영어는 nplurals=2를 사용하며, 러시아어는 숫자의 마지막 자릿수에 따라 선택되는 세 가지 형태가 필요합니다. 러시아어로 번역된 PO 파일에 두 가지 형태만 채워져 있으면 컴파일되고 실행도 되지만, 2, 3, 4로 끝나는 모든 수에 대해 잘못된 문법을 출력합니다. 복수형을 올바르게 처리한다는 것은 원본 언어에 우연히 있던 개수가 아니라, 대상 언어가 요구하는 개수만큼 msgstr 항목을 만드는 것입니다.

플레이스홀더는 자리를 옮겨야 할 때도 있다

어순은 언어마다 다르기 때문에, 값이 두 개 들어간 문장은 그 순서를 바꿔야 하는 경우가 많습니다. %1$s와 %2$s 같은 위치 지정 플레이스홀더, 또는 {count}와 {user} 같은 이름 있는 플레이스홀더는 바로 그 때문에 존재합니다. 번역에서 순서를 바꿀 수는 있지만, 각각은 여전히 정확히 한 번씩 나타나야 합니다. 아무 표시 없는 %s 같은 익명 플레이스홀더는 안전하게 순서를 바꿀 수 없으므로, 번역 후가 아니라 번역 전에 원본 문자열에서 고쳐 두는 것이 좋습니다.

번역 전에 알아 두어야 할 형식별 규칙

형식마다 까다로운 부분이 있습니다. YAML에서는 사양이 리터럴 블록(|)과 접힌 블록(>)에 서로 다른 줄바꿈 동작을 부여하고, 앵커(&)와 별칭(*)은 한 노드가 다른 노드를 재사용하게 해 주므로 둘 다 그대로 통과해야 합니다. XLIFF 2.1은 원래 서식을 <ph>, <pc> 같은 인라인 요소로 감싸며, 번역은 이를 올바른 단어 주변의 제자리에 유지해야 합니다. .NET에서는 RESX 리소스가 런타임에 현재 UI 문화권에 맞춰 이름으로 조회되므로, 이름이 바뀐 data 요소는 조용히 기본 언어로 대체됩니다. 그리고 Java .properties 파일은 처음 나오는 이스케이프되지 않은 =, : 또는 공백을 키 구분자로 취급하므로, 번역된 키에 섞여 든 콜론 하나가 키를 둘로 쪼갭니다.

대부분의 오류를 잡아내는 리뷰 체크리스트

1. 모든 원본 문자열과 대상 문자열에서 플레이스홀더 수를 세세요 — 순서가 달라도 다중집합은 일치해야 합니다.
2. 값이 아니라 키를 비교하세요 — 원본에는 있지만 대상에서 빠졌거나 이름이 바뀐 키는 모두 버그입니다.
3. 배포 전에 번역된 파일을 실제 파서(msgfmt, YAML 로더, ResXResourceReader)로 로드해 보세요.
4. 복수형 항목은 원본 언어가 아니라 대상 언어의 규칙에 맞춰 확인하세요.
5. 가장 긴 번역문을 가장 좁은 UI 요소에 렌더링해 보세요 — 다른 언어의 텍스트는 영어보다 긴 경우가 많습니다.