i18next-cli 🚀
SWC 기반의 통합 고성능 i18next CLI 도구 모음입니다.
기본적으로
i18next-cli는 JavaScript 및 TypeScript 파일(.js,.jsx,.ts,.tsx)에서만 번역 키를 추출합니다. 다른 파일 형식(예:.pug,.vue,.svelte등)에서 추출하려면 플러그인을 사용하거나 생성해야 합니다.extract.input구성에서 추가 파일 확장자를 지정하는 것만으로는 충분하지 않으며, JS/TS 외 형식에는 플러그인이 필요합니다. 자세한 내용과 예제는 플러그인 시스템 섹션을 참조하세요.
i18next-cli는 i18next 생태계를 위한 정적 분석 도구 체인의 완전한 재해석입니다. 핵심 추출, 타입 안전성 생성, 로케일 동기화, 린팅, 클라우드 통합을 하나의 응집력 있고 매우 빠른 CLI로 통합합니다.
🚀 지금 시도해보세요 - 설정 불필요!
구성 없이 기존 i18next 프로젝트를 즉시 분석할 수 있습니다. 저장소의 루트 디렉토리에서 다음 명령어를 실행하기만 하면 됩니다:
npx i18next-cli status또는 하드코딩된 문자열 찾기:
npx i18next-cli lint
권장사항:
i18next-cli와 함께 사용할 관리형 백엔드를 찾고 있다면 Locize를 확인해보세요 — i18next-cli에는 이미 locize-download, locize-sync, locize-migrate 명령어가 포함되어 있습니다. i18next와 동일한 팀이 구축했으며, CDN 전송, AI 번역, 검토 워크플로우, 복사 변경을 위한 재배포 불필요 기능을 제공합니다.
i18next-cli를 선택해야 하는 이유?
i18next-cli는 현대 웹 개발의 요구 사항을 충족하도록 처음부터 구축되었습니다.
- 🚀 성능: 네이티브 Rust 기반 파서(SWC)를 활용하여 JavaScript 기반 파서보다 훨씬 뛰어난 성능을 제공합니다.
- 🧠 지능: 상태 저장, 범위 인식 분석기가
useTranslation('ns1', { keyPrefix: '...' }),getFixedT, 별칭t함수와 같은 복잡한 패턴을 올바르게 이해하여 수동 해결 방법의 필요성을 최소화합니다. - ✅ 통합 워크플로우: 하나의 도구, 하나의 구성 파일, 하나의 통합 워크플로우. 다양한 동기화 스크립트를 대체합니다.
- 🔌 확장성: 현대적인 플러그인 아키텍처로 어떤 프레임워크나 사용자 정의 워크플로우에도 적응할 수 있습니다.
- 🧑💻 개발자 경험: 완전한 타입 정의 구성 파일, 실시간
--watch모드, CLI 출력, 레거시 도구로부터의 마이그레이션을 제공합니다.
기능
- 키 추출: 소스 코드(JavaScript/TypeScript 등)에서 사용되는 모든 번역 키를 코드 구조(AST) 분석을 통해 자동으로 찾아 수집합니다. 이를 통해 번역이 필요한 모든 문자열이 식별되고 번역 파일에 포함되어 수작업을 줄이고 누락된 키를 방지합니다.
- 타입 안전성: 완전한 자동 완성 및 타입 안전성을 위한 TypeScript 정의를 생성합니다.
- 로케일 동기화: 모든 언어 파일을 기본 언어와 동기화 상태로 유지합니다.
- 정확한 코드 린팅: 하드코딩된 문자열을 높은 정확도로 감지하고 구성 가능한 규칙을 제공합니다.
- 번역 상태: 프로젝트 번역 완성도에 대한 개괄적인 개요 또는 키별 상세 보고서를 제공합니다.
- 플러그인 시스템: 사용자 정의 추출 패턴 및 파일 형식(예: HTML, Handlebars)을 위한 확장 가능한 아키텍처입니다.
- 레거시 마이그레이션:
i18next-parser구성에서 자동으로 마이그레이션합니다. - 클라우드 통합: Locize 번역 관리 플랫폼과의 원활한 통합을 제공합니다.
설치
npm install --save-dev i18next-cli
빠른 시작
한 번의 명령어로 제로에서 현지화까지: 하드코딩된 문자열이 있는 앱(예: v0, Lovable, Bolt 또는 Cursor로 생성된 앱)에서 시작하시나요?
npx i18next-cli localize를 실행하세요 — 설정을 감지하고, 하드코딩된 문자열을t()호출로 감싸고, 키를 추출하고, Locize에 연결하여 AI가 앱을 번역합니다.localize명령어를 참조하세요. AI 코딩 에이전트(Claude Code, Cursor, ...)와 함께 작업 중이신가요?npx i18next-cli localize --print-agent-prompt는 동일한 흐름을 복사-붙여넣기 에이전트 런북으로 출력합니다. 아래 단계는 수동 경로입니다.
1. 구성 초기화
대화형으로 구성 생성:
npx i18next-cli init
또는 프로젝트 루트에 i18next.config.ts를 수동으로 생성:
import { defineConfig } from 'i18next-cli';
export default defineConfig({
locales: ['en', 'de'],
extract: {
input: ['src/**/*.{js,jsx,ts,tsx}'],
output: 'public/locales/{{language}}/{{namespace}}.json',
},
});
2. 번역 상태 확인
프로젝트의 현지화 상태 개요 확인:
npx i18next-cli status
3. 번역 키 추출
npx i18next-cli extract
4. 타입 생성 (선택 사항)
npx i18next-cli types
명령어
init
구성 파일 생성을 위한 대화형 설정 마법사입니다.
npx i18next-cli init
옵션:
--ci: 백엔드(예: Locize)가 선택된 경우 브라우저 실행을 건너뜁니다. 대신 가입 URL이 출력됩니다. 스크립트 실행에 유용합니다. 마법사는 또한CI=true를 자동 감지하고 헤드리스 Linux(DISPLAY/WAYLAND_DISPLAY없음)에서는 URL 출력으로 대체되므로, 이 플래그가 명시적으로 필요한 경우는 거의 없습니다.--inlang: inlang 프로젝트(project.inlang/settings.json)도 함께 스캐폴딩하여 inlang 도구 모음 — Sherlock VS Code 확장, 번역가를 위한 Fink 웹 편집기, Paraglide 컴파일러 — 가 번역 파일에서 직접 작동하도록 합니다. 해당 마법사 질문을 건너뜁니다.
마법사는 구성 파일 유형, 로케일, 소스 파일 글로브, 출력 경로, 마지막으로 "번역 백엔드?" 의 세 가지 옵션을 묻습니다:
- 로컬 파일 전용 (기본값) — 현재 로컬 JSON 워크플로우를 유지합니다.
- Locize (팀/프로덕션 워크플로우에 권장) — 브라우저에서 Locize 가입 페이지를 열고 프로젝트 ID와 API 키를 입력하라는 메시지를 표시합니다. 마법사는 생성된 구성에
locize블록을 작성하여locize-sync가 즉시 작동하도록 합니다. API 키 프롬프트는 비워둘 수 있습니다(읽기 전용 모드). 나중에LOCIZE_API_KEY환경 변수를 통해 추가할 수 있습니다. - 기타 / 건너뛰기 — 마법사 목적상 "로컬 파일 전용"과 동일합니다.
그런 다음 마법사는 inlang 도구 설정을 제안합니다(기본값: 아니요 — 또는 --inlang을 전달하여 질문을 건너뜁니다). 수락하면 project.inlang/settings.json을 스캐폴딩하여 inlang i18next 플러그인이 기존 번역 파일을 가리키도록 합니다: baseLocale/locales는 구성에서 가져오고, pathPattern은 extract.output에서 파생됩니다(레이아웃에 {{namespace}}가 사용된 경우 네임스페이스 객체 형식, 네임스페이스는 기본 언어 파일에서 발견됨, 그렇지 않으면 일반 패턴). 또한 .vscode/extensions.json 권장 사항에 Sherlock 확장을 추가합니다(주석 인식 병합, 기존 항목을 덮어쓰지 않음). i18next JSON 파일은 단일 진실 공급원으로 유지됩니다 — inlang 도구는 이 파일을 그 자리에서 읽고 쓰므로, 동기화가 깨질 두 번째 카탈로그가 없습니다. 기존 project.inlang/settings.json은 절대 덮어쓰지 않습니다. init을 다시 실행해도 안전합니다. JSON 리소스 파일이 필요합니다. 플러그인은 정확히 검증된 버전(@inlang/[email protected])에 고정됩니다 — settings.json의 modules URL을 업데이트하여 최신 플러그인 릴리즈를 적용하세요. 설계 상 settings.json만 스캐폴딩됩니다: project.inlang/은 압축 풀린 (git-friendly) 프로젝트 형식이며, inlang 도구는 첫 사용 시 나머지 파일(.gitignore, README.md, cache/)을 생성하고 관리합니다 — 따라서 Sherlock 또는 Paraglide로 프로젝트를 연 후 해당 디렉토리에 몇 개의 새 파일이 나타날 수 있습니다.
extract
소스 파일을 파싱하고, 키를 추출하며, JSON 번역 파일을 업데이트합니다.
npx i18next-cli extract [options]
옵션:
--watch, -w: 파일이 변경될 때 자동으로 다시 실행합니다.--ci: 파일이 업데이트된 경우 0이 아닌 종료 상태로 종료합니다(CI/CD용).--dry-run: 파일을 변경하지 않습니다.--ci와 함께 유용합니다(CI/CD용).--sync-primary: 기본 언어 값을 코드의 기본값과 동기화합니다.--sync-all: 기본 언어 값을 코드의 기본값과 동기화하고 다른 모든 로케일에서 동기화된 키를 지웁니다(--sync-primary를 암시).--trust-derived:--sync-primary또는--sync-all과 함께 사용할 때,t('Hello')또는keyPrefix에서 파생된 값과 같은 키에서 추론된 기본값도 신뢰합니다. 이는 기본 동기화 동작을 엄격하게 유지하고 선택적으로만 허용합니다.--with-types: 추출 후(그리고--watch모드에서 매 재실행 시) 번역 파일이 변경될 때마다 TypeScript 정의를 재생성합니다.extract -w와types -w를 별도 프로세스로 실행할 필요가 없습니다.--quiet: 스피너 및 필수적이지 않은 출력을 억제합니다(CI 또는 스크립팅용).
스피너 및 로거 출력 제어
진행 스피너를 표시하는 모든 명령어(extract, types, lint, sync)는 이제 다음을 지원합니다:
--quiet플래그: 스피너 및 필수적이지 않은 출력을 억제합니다(CI, 스크립팅 또는 로그 캡처용).- 프로그래매틱 로거 지원: 사용자 정의 로거 객체를 전달하여 자체 형식이나 스트림으로 출력을 캡처합니다.
CLI 예시:
npx i18next-cli extract --quiet
프로그래매틱 예시:
import { runExtractor } from 'i18next-cli';
const logger = {
info: (msg) => myLogStream.write(msg + '\n'),
warn: (msg) => myWarnStream.write(msg + '\n'),
error: (msg) => myErrStream.write(msg + '\n'),
};
await runExtractor(config, { quiet: false, logger });
로거를 전달하면 스피너 출력과 모든 진행/정보 메시지가 대화형 스피너 대신 로거로 라우팅됩니다.
예시:
# 일회성 추출
npx i18next-cli extract
# 개발을 위한 감시 모드
npx i18next-cli extract --watch
# CI 모드 (파일이 변경되면 실패)
npx i18next-cli extract --ci
# 기본 언어를 코드 기본값과 동기화
npx i18next-cli extract --sync-primary
# 기본 언어 동기화 및 다른 모든 로케일에서 동기화된 키 지우기
npx i18next-cli extract --sync-all
# 명시적 기본값과 추론된 키 기반 기본값을 함께 사용하여 동기화
npx i18next-cli extract --sync-all --trust-derived
# 최적의 개발 워크플로우를 위한 옵션 조합
npx i18next-cli extract --sync-primary --watch
# 단일 프로세스에서 TypeScript 정의를 동기화된 상태로 유지 (별도의 `types -w` 불필요)
npx i18next-cli extract --watch --with-types
status [locale]
프로젝트의 번역 상태에 대한 상태 점검을 표시합니다. 구성 파일 없이도 실행할 수 있습니다. 번역이 누락된 경우 0이 아닌 종료 코드로 종료됩니다.
기본 언어도 확인됩니다: 코드에서 사용되었지만 기본 언어 번역 파일에 없는 키(오타 또는 extract가 한 번도 실행되지 않은 경우)는 보고되고 0이 아닌 종료 코드를 발생시킵니다. extract가 작성한 빈 문자열 플레이스홀더는 존재하는 것으로 간주되며 확인에 실패하지 않습니다. npx i18next-cli status <primaryLanguage>를 실행하면 누락된 키가 자세히 표시됩니다.
옵션:
--namespace <ns>, -n <ns>: 특정 네임스페이스로 보고서를 필터링합니다.--hide-translated: 상세 보기에서 이미 번역된 키를 숨기고 누락된 번역만 표시합니다.status.ignoreKeys(구성): 보고되지 않아야 하고(확인에 실패하지 않아야 하는) 키에 대한 글로브 패턴입니다. 예를 들어 일부 로케일에서 의도적으로 비워둔 키가 있습니다. 선택적ns:접두사(common:help.*-href)를 사용할 수 있습니다.status에만 영향을 미칩니다.--unused: 사용되지 않는 번역 키만 보고합니다 — 번역 파일에 존재하지만 소스 코드에서 더 이상 사용되지 않는 키입니다(즉,extract가removeUnusedKeys와 함께 삭제할 키). 파일을 절대 수정하지 않으며, 사용되지 않는 키가 발견되면 0이 아닌 종료 코드로 종료되므로 일반 누락 번역 확인과 함께 전용 CI 확인으로 사용할 수 있습니다. 정적 분석은 동적으로 구성된 키(예:t(`error.${code}`))를 감지할 수 없습니다. 런타임에 실제로 사용되지 않는 키를 찾으려면 locize로 사용되지 않는 번역 찾기를 참조하세요.
사용 예시:
# 모든 로케일 및 네임스페이스에 대한 개괄적 요약
npx i18next-cli status
# 'de' 로케일에 대한 키별 상세 보고서
npx i18next-cli status de
# 모든 로케일에서 'common' 네임스페이스만 요약
npx i18next-cli status --namespace common
# 'de' 로케일에 대한 상세 보고서, 'common' 네임스페이스만 표시
npx i18next-cli status de --namespace common
# 'de' 로케일에서 번역되지 않은 키만 표시
npx i18next-cli status de --hide-translated
# 특정 네임스페이스에서 누락된 번역만 보기 위해 옵션 결합
npx i18next-cli status de --namespace common --hide-translated
# 모든 로케일에서 사용되지 않는 키만 보고 (읽기 전용, 발견 시 1로 종료)
npx i18next-cli status --unused
# 'en' 파일에서 사용되지 않는 키만 보고 — 예를 들어 별도의 CI 확인으로
npx i18next-cli status en --unused
상세 보기는 각 네임스페이스에 대한 풍부한 한눈에 보는 요약과 각 키 및 번역 상태 목록을 제공합니다.
출력 예시 (npx i18next-cli status de):
"de"의 키 상태:
전체: [■■■■■■■■■■■■■■■■■■■■] 100% (12/12)
네임스페이스: common
네임스페이스 진행률: [■■■■■■■■■■■■■■■■■■■■] 100% (4/4)
✓ button.save
✓ button.cancel
✓ greeting
✓ farewell
네임스페이스: translation
네임스페이스 진행률: [■■■■■■■■■■■■■■■■□□□□] 80% (8/10)
✓ app.title
✓ app.welc
…
[번역을 위해 잘렸습니다]