i18n & 지역화
국제화(i18n) 및 지역화(L10n) 모범 사례
1. 핵심 개념
| 용어 | 의미 |
|---|
| i18n | 국제화 - 앱을 번역 가능하게 만드는 과정 |
| L10n | 지역화 - 실제 번역 작업 |
| Locale | 언어 + 지역 (en-US, tr-TR) |
| RTL | 오른쪽에서 왼쪽으로 쓰는 언어 (아랍어, 히브리어) |
2. i18n 적용 시점
| 프로젝트 유형 | i18n 필요 여부 |
|---|
| 공개 웹 앱 | ✅ 필요 |
| SaaS 제품 | ✅ 필요 |
| 내부 도구 | ⚠️ 고려 |
| 단일 지역 앱 | ⚠️ 향후 고려 |
| 개인 프로젝트 | ❌ 선택 사항 |
3. 구현 패턴
React (react-i18next)
import { useTranslation } from 'react-i18next';
function Welcome() {
const { t } = useTranslation();
return <h1>{t('welcome.title')}</h1>;
}
Next.js (next-intl)
import { useTranslations } from 'next-intl';
export default function Page() {
const t = useTranslations('Home');
return <h1>{t('title')}</h1>;
}
Python (gettext)
from gettext import gettext as _
print(_("Welcome to our app"))
4. 파일 구조
locales/
├── en/
│ ├── common.json
│ ├── auth.json
│ └── errors.json
├── tr/
│ ├── common.json
│ ├── auth.json
│ └── errors.json
└── ar/ # RTL
└── ...
5. 모범 사례
권장 사항 ✅
- 번역 키를 사용하고 원시 텍스트는 사용하지 않음
- 기능별로 번역을 네임스페이스화
- 복수형 지원
- 로케일별 날짜/숫자 형식 처리
- 처음부터 RTL 계획
- 복잡한 문자열에는 ICU 메시지 형식 사용
금지 사항 ❌
- 컴포넌트에 문자열 하드코딩
- 번역된 문자열 연결
- 텍스트 길이 무시 (독일어는 30% 더 김)
- RTL 레이아웃 무시
- 같은 파일에 언어 혼용
6. 일반적인 문제
| 문제 | 해결 방법 |
|---|
| 번역 누락 | 기본 언어로 폴백 |
| 하드코딩된 문자열 | 린터/체커 스크립트 사용 |
| 날짜 형식 | Intl.DateTimeFormat 사용 |
| 숫자 형식 | Intl.NumberFormat 사용 |
| 복수형 | ICU 메시지 형식 사용 |
7. RTL 지원
.container {
margin-inline-start: 1rem;
padding-inline-end: 1rem;
}
[dir="rtl"] .icon {
transform: scaleX(-1);
}
8. 체크리스트
배포 전 확인:
스크립트
| 스크립트 | 목적 | 명령어 |
|---|
scripts/i18n_checker.py | 하드코딩된 문자열 및 번역 누락 감지 | python scripts/i18n_checker.py <project_path> |