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> |
사용 시기
이 스킬은 개요에 설명된 워크플로우 또는 작업을 실행하는 데 적합합니다.
제한 사항
- 이 스킬은 작업이 위에서 설명한 범위와 명확히 일치하는 경우에만 사용하십시오.
- 출력을 환경별 검증, 테스트 또는 전문가 검토를 대체하는 것으로 간주하지 마십시오.
- 필요한 입력, 권한, 안전 경계 또는 성공 기준이 없는 경우 질문하고 명확히 하십시오.