국제화 헬퍼
다국어 애플리케이션에서 국제화(i18n) 및 로컬라이제이션(l10n)을 관리하는 데 도움을 줍니다.
사용 시기
- 사용자가 i18n 지원을 요청할 때
- 새로운 언어를 추가할 때
- 번역되지 않은 문자열을 찾을 때
- 번역 파일을 관리할 때
- 사용자가 "번역", "i18n", "l10n", "로케일"을 언급할 때
지침
1. i18n 프레임워크 감지
JavaScript/React:
- react-i18next
- react-intl (FormatJS)
- i18next
- LinguiJS
Vue:
- vue-i18n
Python:
- gettext
- Django i18n
- Flask-Babel
Ruby/Rails:
- I18n gem (내장)
import 구문, 설정 파일 또는 번역 디렉터리를 찾아보세요.
2. 하드코딩된 문자열 찾기
번역되지 않은 텍스트를 검색하세요:
// 나쁨: 하드코딩됨
<button>제출</button>
<p>환영합니다, {user.name}님!</p>
// 좋음: 번역됨
<button>{t('common.submit')}</button>
<p>{t('welcome.message', { name: user.name })}</p>
검색 패턴:
- JSX/템플릿 태그 내 문자열
- 알림/오류 메시지
- 폼 레이블 및 placeholder
- 버튼 텍스트
- 유효성 검사 메시지
다음은 제외: 코드 주석, console.log, 테스트 문자열
3. 번역 파일로 추출
React-i18next 형식 (JSON):
{
"common": {
"submit": "제출",
"cancel": "취소"
},
"welcome": {
"message": "환영합니다, {{name}}님!"
}
}
Gettext 형식 (.po):
msgid "submit_button"
msgstr "제출"
msgid "welcome_message"
msgstr "환영합니다, %(name)s님!"
4. 번역 키 구성
모범 사례:
- 기능별로 네임스페이스 지정:
users.profile.title - 공통 문자열 그룹화:
common.buttons.save - 콘텐츠가 아닌 맥락을 설명:
errors.login.invalid(오류.로그인.유효하지않음) - 하지 말 것errors.wrong_password(오류.잘못된_비밀번호) - 일관된 명명 규칙 사용
5. 번역 커버리지 확인
로케일 파일을 비교하여 누락된 번역 찾기:
en.json: 150개 키
ko.json: 142개 키 (8개 누락)
fr.json: 150개 키 ✓
ko.json에 누락된 키:
- users.profile.bio
- settings.privacy.title
[...]
6. 복수화 처리
언어마다 복수 규칙이 다릅니다:
// react-i18next
t('items', { count: 0 }) // "0개 항목"
t('items', { count: 1 }) // "1개 항목"
t('items', { count: 5 }) // "5개 항목"
// 번역 파일
{
"items_zero": "{{count}}개 항목",
"items_one": "{{count}}개 항목",
"items_other": "{{count}}개 항목"
}
7. 날짜, 시간, 숫자 형식 지정
로케일 인식 형식 사용:
// 숫자
const price = new Intl.NumberFormat('ko-KR', {
style: 'currency',
currency: 'KRW'
}).format(29900);
// 날짜
const date = new Intl.DateTimeFormat('ko-KR').format(new Date());
8. 오른쪽에서 왼쪽(RTL) 지원
아랍어, 히브리어 등:
- CSS:
direction: rtl; - HTML:
<html dir="rtl"> - 논리적 속성:
margin-left대신margin-inline-start
9. 번역 템플릿 생성
새 로케일용 템플릿 생성:
# 기본 언어에서 키를 복사하고 값은 비워둠
cp locales/en.json locales/de.json
# 번역을 위해 표시
10. 모범 사례
- 번역은 별도 파일로 유지
- 소스 텍스트가 아닌 키 사용
- 번역가에게 맥락 제공
- 긴 문자열로 테스트 (독일어는 종종 더 길어짐)
- 복잡한 문자열에는 ICU MessageFormat 사용
- 번역된 문자열을 연결(concatenate)하지 않음
- 사용자에게 보이는 모든 텍스트 추출
지원 파일
templates/i18n-config.js: 설정 예제templates/locale-file.json: 번역 파일 템플릿