10가지 i18n 실수와 피하는 방법

한 개발자가 JSX에서 버튼 레이블을 직접 작성합니다: <button>Submit Order</button>.

앱이 영어로 제공되고 제대로 작동합니다. 6개월 후 회사는 독일로 확장합니다.

로컬라이제이션 팀은 2,000개 이상의 하드코드 문자열을 발견합니다. 후속 작업은 3주가 걸리고 47개의 버그가 발생합니다.

첫 번째 컴포넌트를 작성하기 전에 i18n 프레임워크를 구성합니다 (예: next-intl, react-i18next, vue-i18n).

리소스 파일 구조를 만들고 messages/de.json 와 같은 파일에 모든 문자열을 t('checkout.submitButton') 같은 번역 키로 참조합니다.

UI 컴포넌트의 원시 문자열을 표시하는 린트 규칙이나 프리커밋 훅을 추가합니다.

번역 파일에는 회사 이름 'CloudForge Inc.' 및 기술 용어 'OAuth 2.0 Token'이 일반적으로 번역 가능한 문자열로 포함되어 있습니다.

스페인어 번역가는 'CloudForge'를 'ForjaNube'로, 'OAuth 2.0 Token'을 'ficha OAuth 2.0'으로 번역합니다.

결과: 사용자는 회사의 실제 이름으로 회사를 찾지 못하고, 스페인어 문서를 읽는 개발자들은 번역된 알 수 없는 전문 용어로 혼란스러워합니다.

'번역 제외' 용어집을 만들어, 변경되어서는 안 되는 모든 브랜드명, 제품명, 법인명 및 전문 용어를 나열하십시오.

번역 불가 콘텐츠에는 별도의 네임스페이스나 특수 키를 사용하세요. 많은 i18n 도구가 번역자가 편집할 수 없는 '잠긴' 세그먼트를 지원합니다.

번역 파일에 맥락을 설명하는 번역가 주석/설명을 추가하십시오: '이것은 브랜드명 — 번역하지 마세요' 또는 '전문 용어 — 영어로 유지'.

개발자가 쓴다: 'You have ' + count + ' items in your ' + cartType + ' cart' — 영어에서 완벽하게 작동합니다.

독일어 번역자는 세 개의 개별 조각을 받으며 어순을 바꿔야 하기 때문에 문법적으로 올바른 문장을 만들 수 없다.

결과: 독일 사용자는 'Sie haben 5 Artikel in Ihrem Warenkorb Standard'를 보게 되어 어색하고 비전문적으로 보인다.

연결 대신 플레이스홀더가 포함된 단일 메시지 키로 교체: 'cart.summary': '당신의 '{cartType}' 장바구니에 {count}개 항목이 있습니다.'

변수를 번역 함수의 매개변수로 전달합니다: t('cart.summary', { count: 5, cartType: 'Premium' }).

이제 번역자가 자유롭게 재배치 가능: '당신의 '{cartType}' 장바구니에는 {count}개 항목이 있습니다' — 문법적으로 올바른 독일어.

개발자가 쓴다: count + (count === 1 ? 'Datei' : 'Dateien') — 독일어를 올바르게 처리합니다.

폴란드어 번역가는 4가지 형태가 필요합니다: 1 plik, 2-4 pliki, 5-21 plików, 22-24 pliki. 단순 삼항연산으로는 이를 표현할 수 없습니다.

결과: 폴란드어 사용자는 '5 pliki'(잘못된 형태)를 보게 되고, 올바른 형태인 '5 plików'가 아니라 앱이 엉망으로 보인다.

ICU 구문으로 메시지를 정의합니다: 'fileCount': '{count, plural, one {# Datei} other {# Dateien}}'.

번역가는 각 언어에 필요한 모든 복수형 형태를 제공합니다. 폴란드어: '{count, plural, one {# plik} few {# pliki} many {# plików} other {# pliku}}'.

활성 로케일의 CLDR 규칙에 따라 런타임에 자동으로 올바른 형태를 선택합니다.

디자이너는 정확히 100픽셀 폭의 5개 버튼으로 구성된 네비게이션 바를 만듭니다 — 영어 버전에서는 멋져 보입니다.

독일어 번역: 'Settings'는 'Einstellungen'으로 바뀌고(13 대 8 글자), 'Submit'은 'Absenden'으로 바뀌고(8 대 6 글자). 네비게이션 바가 넘쳐 흐릅니다.

결과: 모바일 기기에서 버튼이 서로 겹치거나 텍스트가 잘려 독일어 사용자의 네비게이션이 사용할 수 없게 됩니다.

고정 너비를 min-width, max-width 및 Flex 레이아웃으로 교체하세요. CSS Grid 또는 Flexbox를 사용해 공간을 동적으로 분배합니다.

텍스트 컨테이너를 줄 바꿈에 맞춰 설정하세요: overflow-wrap: break-word를 사용하고 번역 가능한 콘텐츠에 대해 white-space: nowrap을 피하세요.

Worst Case를 시뮬레이션하기 위해 모든 문자열을 40% 길게 하는 의사 지역화로 UI를 테스트하세요 — 문자열을 번역자에게 보내기 전에.

개발자는 날짜를 MM/DD/YYYY 형식으로, 가격을 $1,234.50로 포맷합니다 — 미국 사용자를 위한 올바른 형식입니다.

독일 사용자는 날짜 03/04/2025를 보고 이를 3월 4일로 읽습니다(DD/MM/YYYY 관례). 가격 $1,234.50는 1.234,50으로 표시되어야 한다고 보입니다.

결과: 사용자가 잘못된 날짜로 항공편을 예약하고 요금 형식을 의심합니다. 독일 시장에서 지원 티켓이 15% 증가합니다.

날짜에는 Intl.DateTimeFormat(locale)를 사용하고 가격에는 Intl.NumberFormat(locale, { style: 'currency', currency })를 사용하여 수동 포맷을 대체하세요.

데이터를 내부적으로 ISO 8601 형식(YYYY-MM-DD)으로 저장하고, 사용자 로케일로 표시할 때만 포맷하십시오.

필수적인 날짜/숫자 표시를 최소 5개의 서로 다른 로케일(en-US, de-DE, ja-JP, ar-SA, zh-CN)로 테스트하여 가장 중요한 형식 변형을 다룹니다.

개발자는 전체 앱에서 margin-left: 16px와 text-align: left를 사용합니다 — 표준 LTR 관례입니다.

앱은 사우디아라비아에서 시작됩니다. 뒤로 가기 아이콘이 앞쪽을 가리키고, 사이드바가 잘못된 쪽에 나타나며, 숫자 데이터의 정렬이 올바르게 되어 있지 않습니다.

결과: 아랍어 사용자는 30초 만에 앱을 떠납니다. 팀은 문제를 해결하기 위해 4주간의 긴급 CSS 리팩토링이 필요합니다.

모든 물리적 CSS 속성을 논리적 동등 값으로 교체하십시오: margin-left → margin-inline-start, padding-right → padding-inline-end, text-align: left → text-align: start.

활성 로케일에 따라 HTML 루트 요소에 dir 속성을 설정합니다. RTL 특화 재정의를 위해 CSS 의 :dir(rtl) 의사 클래스를 사용하세요.

모든 아이콘을 방향 표시 여부를 확인합니다. 방향 의존 아이콘은 반영된 버전으로 교체하거나 RTL 컨텍스트에 대해 CSS transform: scaleX(-1)를 사용하세요.

한 디자이너가 'Start Your Free Trial' 텍스트를 이미지 안에 직접 삽입한 프로모션 배너를 만듭니다.

로컬라이제이션 팀은 모든 UI 문자열을 번역하지만 독일어 페이지의 배너에는 여전히 영어 텍스트가 표시됩니다.

결과: 독일어 랜딩페이지에 혼란스러운 영어 배너가 있습니다. 15개 언어에 맞춘 로컬라이즈드 배너를 만드는 데 디자이너 작업 3일이 필요하고 출시가 지연됩니다.

배경 이미지 위에 번역 가능한 텍스트를 배치하려면 CSS를 사용하세요: 텍스트 레이어를 이미지 컨테이너 위에 절대 위치로 배치합니다.

인포그래픽이나 다이어그램의 경우, 번역 키를 참조하는 <text> 요소가 있는 SVG를 사용하고 원시 문자열을 삽입하지 마십시오.

마케팅 자료의 앱 스크린샷에 대해 Fastlane(모바일) 또는 Playwright(웹)와 같은 도구를 사용하여 모든 로케일에서 화면을 캡처하는 스크린샷 생성을 자동화합니다.

개발자가 새 'Premium Features' 섹션과 15개의 새로운 번역 키를 추가합니다. 영어 버전이 즉시 배포됩니다.

프랑스어 번역이 아직 완료되지 않았습니다. 프랑스어 페이지에는 원시 키가 표시됩니다: 'premium.feature1.title', 'premium.feature1.description'.

결과: 프랑스어 사용자는 개발자 측 키 이름으로 가득 찬 깨진 페이지를 봅니다. 지원 팀은 수십 건의 버그 보고서를 받습니다.

i18n 구성에서 폴백 언어 체인을 설정합니다: 누락된 프랑스어(fr) 키는 자동으로 영어(en)로 되돌아갑니다.

미번역 키를 모니터링 시스템(예: Sentry, Datadog)에 로깅하는 Missing-Key 핸들러를 추가하되, 사용자 경험이 깨지지 않도록 하세요.

국가별/로케일별 번역 커버리지 대시보드를 만들어 커버리지가 임계값(예: 95%) 아래로 떨어지면 릴리스를 차단합니다.

개발자는 오래된 표준인 latin1 콜레이션을 사용하는 MySQL 데이터베이스를 구성합니다. 애플리케이션 소스 코드는 UTF-8을 사용합니다.

일본인 사용자는 실제 이름으로 등록합니다. 데이터베이스는 '田中太郎'를 손상된 바이트로 저장합니다.

결과: 사용자 프로필에 손상된 텍스트가 표시됩니다. 더 나아가 모든 CJK 이름의 검색 및 정렬이 깨져 수천 명의 사용자가 영향을 받습니다.

모든 소스 파일을 UTF-8로 설정합니다(에디터 및 .editorconfig 구성). HTML에 <meta charset='UTF-8'>를 추가하고 API 응답에 'Content-Type: application/json; charset=utf-8'을 포함시킵니다.

데이터베이스를 utf8mb4로 구성합니다( MySQL에서 utf8은 3바이트 하위집합일 뿐입니다). 연결 정렬을 utf8mb4_unicode_ci로 설정합니다.

대상 문자 시스템을 커버하는 글꼴을 선택합니다: 라틴어, 키릴 문자, CJK, 아랍어, 데바나가리. 로딩 최적화를 위해 시스템 폰트 스택 또는 언어 하위 집합이 있는 Google Fonts를 사용하세요.