i18n-extractor
번역 키를 추출하고 기존 파일과 지능적으로 병합합니다
개요
i18n-extractor는 코드에서 t() 함수로 래핑된 모든 번역 키를 추출하여 언어별 JSON 파일을 생성하고, 기존 번역과 지능적으로 병합하는 CLI 도구입니다.
설치
전역 설치 (권장):
npm install -g i18nexus-tools또는 npx로 직접 실행:
npx i18n-extractor기본 사용법
기본 추출 및 병합
npx i18n-extractor -p "app/**/*.tsx" -d "./locales"app 디렉토리의 모든 .tsx 파일에서 번역 키를 추출하고 locales 폴더에 저장합니다.
특정 언어 파일 생성
npx i18n-extractor -l "en,ko,ja"영어, 한국어, 일본어 번역 파일을 생성합니다.
미리보기 모드
npx i18n-extractor --dry-run파일을 수정하지 않고 추출될 키와 통계만 확인합니다.
작동 방식
코드 스캔
지정된 패턴의 모든 파일을 스캔하여 t() 함수 호출을 찾습니다.
// 이런 코드를 찾습니다:
t("환영합니다")
t("시작하기")
t(\`안녕하세요 \${name}님\`)키 추출
t() 함수의 첫 번째 인자를 번역 키로 추출합니다.
// 추출된 키:
"환영합니다"
"시작하기"
"안녕하세요 \${name}님"기존 번역과 병합
기존 번역 파일을 읽고, 새로운 키만 추가하며 기존 번역은 모두 보존합니다.
기존 파일:
{
"안녕": "Hello",
"환영합니다": "Welcome"
}병합 후:
{
"안녕": "Hello",
"시작하기": "시작하기",
"환영합니다": "Welcome"
}파일 저장
정렬된 키로 각 언어의 JSON 파일을 저장하고 통계를 표시합니다.
✓ 추출 완료
- 새 키: 5개
- 기존 키: 120개
- 총 키: 125개
- 파일: locales/ko.json, locales/en.json명령어 옵션
--pattern, -p문자열스캔할 파일의 glob 패턴을 지정합니다.
--pattern "app/**/*.{ts,tsx}"--directory, -d문자열번역 파일을 저장할 디렉토리 경로를 지정합니다.
--directory "./locales"--languages, -l문자열생성할 언어 파일을 쉼표로 구분하여 지정합니다. 기본값: en,ko
--languages "en,ko,ja,zh"--dry-run플래그실제로 파일을 생성하지 않고 추출될 키와 통계만 표시합니다.
--help, -h플래그도움말 메시지를 표시합니다.
예제 출력
초기 추출 (새 프로젝트)
$ npx i18n-extractor -p "app/**/*.tsx" -d "./locales"
🔍 Scanning files...
Found 25 files
📝 Extracting translation keys...
Found 45 unique keys
📁 Creating translation files...
✓ locales/ko.json (45 keys)
✓ locales/en.json (45 keys)
✅ Extraction complete!
- New keys: 45
- Total keys: 45증분 업데이트 (기존 프로젝트)
$ npx i18n-extractor -p "app/**/*.tsx" -d "./locales"
🔍 Scanning files...
Found 30 files
📝 Extracting translation keys...
Found 52 unique keys
📁 Merging with existing translations...
Existing keys: 45
New keys: 7
✓ locales/ko.json (52 keys, +7 new)
✓ locales/en.json (52 keys, +7 new)
✅ Extraction complete!
- New keys: 7
- Existing keys: 45
- Total keys: 52
💡 Don't forget to translate the new keys in en.json스마트 병합 기능
병합 시 보장되는 사항:
- ✓기존 번역 100% 보존
이미 번역된 키는 절대 덮어쓰지 않습니다. 수동으로 작성한 번역이 안전하게 유지됩니다.
- ✓새 키만 추가
코드에 새로 추가된 키만 번역 파일에 추가됩니다.
- ✓알파벳 순 정렬
모든 키가 알파벳 순으로 정렬되어 찾기 쉽고 git diff가 깔끔합니다.
- ✓언어별 독립 관리
각 언어 파일은 독립적으로 관리되며, 한 언어의 변경이 다른 언어에 영향을 주지 않습니다.
모범 사례
✅자주 실행하기
새 기능을 추가할 때마다 extractor를 실행하여 번역 파일을 최신 상태로 유지하세요.
✅CI/CD에 통합하기
빌드 프로세스에 --dry-run을 추가하여 누락된 키가 있는지 확인하세요.
# package.json
"scripts": {
"check:i18n": "i18n-extractor --dry-run"
}✅번역 파일 버전 관리
생성된 번역 파일을 Git에 커밋하여 팀원들과 공유하세요.
💡영어 번역 추가하기
extractor 실행 후 en.json 파일을 열어 새로 추가된 키에 영어 번역을 추가하세요.