i18n 및 지역화
국제화(i18n) 및 지역화(L10n) 모범 사례.
1. 핵심 개념
| 용어 | 의미 |
|---|
| i18n | 국제화 - 앱을 번역 가능하게 만들기 |
| L10n | 지역화 - 실제 번역 작업 |
| 로케일 | 언어 + 지역 (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> |
사용 시기
이 스킬은 개요에 설명된 워크플로우나 작업을 실행할 때 적용됩니다.