Skip to main content
Open Source CLI Tool

i18n 검증 도구

번역 파일에서 누락된 키, 손상된 플레이스홀더, 복수형 불일치를 검사해요. 명령 하나, 9가지 검사, 32개 형식, 설정은 필요 없어요.

9 checks 32 formats Zero config Native Rust binary

문제

번역 문제는 사용자가 마주치기 전까지 드러나지 않아요. 키가 없으면 실제 텍스트 대신 "settings.billing.title" 같은 원시 경로가 표시돼요. 플레이스홀더가 손상되면 "$9.99" 대신 "{price}"가 그대로 표시돼요. 복수형이 잘못되면 개수가 0일 때 앱이 비정상 종료돼요. 아무도 로케일 파일 15개의 차이를 직접 확인하지 않으므로 이런 버그는 코드 검토를 빠져나가요.

🔑

Missing keys

Blank text or key paths shown to users

🔗

Broken placeholders

{price} displays as literal text instead of $9.99

📁

Orphaned files

Outdated translations confuse the build system

💥

Malformed files

Runtime crashes when users switch languages

대부분의 검증 도구는 JSON 전용, YAML 전용처럼 특정 형식만 지원하고 프로젝트마다 맞춤 테스트 코드가 필요해요. 번역 버그는 사용자가 깨진 UI를 보는 런타임에야 발견되는 경우가 많아요.

해결책

i18n-validate는 모든 번역 파일을 한 번에 스캔해요. 디렉터리 구조와 파일 형식을 자동으로 감지하고, 모든 언어를 기준 언어와 비교해 어디에 어떤 문제가 있는지 정확히 알려 줘요. 플러그인, 설정, 맞춤 테스트 코드가 필요 없어요.

CheckSeverityWhat it catches
missing-keyserrorKey exists in reference but is absent in a translation
extra-keyserrorKey exists in translation but not in the reference
placeholderserror{price}, {{name}}, %s differ between languages
plural-structureerrorPlural forms are malformed or missing required categories
missing-languageserrorExpected language has no files or directory
orphaned-languageserrorLanguage files exist but are not in the expected list
parse-errorserrorFile fails to parse (broken JSON, XML, YAML, etc.)
empty-valueswarningKey is present but the translation is an empty string
untranslatedwarningTranslation is identical to the reference language
Terminal output
i18n-validate v0.1.0 — validating ./locales

  Reference: en (2 files: translation.json, apiTester.json)
  Languages: de, ja, fr, es, zh-Hans, pt-BR, ko (7 found, 7 expected)
  Layout   : directory (auto-detected)
  Formats  : i18next JSON (auto-detected)

────────────────────────────────────────────────

ERRORS (5)

  ✗ missing-keys │ translation.json
    Key "settings.billing.title"
      missing in: ja, ko

  ✗ placeholders │ translation.json
    Key "pricing.total" — expected: {price}, {currency}
      de:  found {price} only — missing {currency}

────────────────────────────────────────────────

WARNINGS (2)

  ⚠ empty-values │ translation.json
    Key "onboarding.step3.hint"
      empty in: de, fr

────────────────────────────────────────────────

  5 errors, 2 warnings across 7 languages
  ✗ Validation failed

설치

원하는 패키지 관리자를 사용해 전역 CLI 도구로 설치하세요. npm 패키지에는 네이티브 Rust 바이너리가 포함되어 있어 컴파일이나 런타임 종속성이 필요 없어요.

Terminal
npm install -g @i18n-agent/i18n-validate
npm 패키지에는 macOS, Linux, Windows용으로 미리 컴파일된 네이티브 바이너리가 포함되어 있어요. Rust 도구 체인이 필요 없어요.

사용법

도구에 로케일 디렉터리를 지정하세요. 기준 언어, 디렉터리 구조, 파일 형식을 자동으로 감지해요. 대부분의 프로젝트에는 별도 설정이 필요 없어요.

Terminal
# Zero-config validation
i18n-validate ./locales

# JSON output for scripting
i18n-validate ./locales --format json | jq '.summary'

# CI/CD with JUnit XML
i18n-validate ./locales --format junit -o i18n-report.xml

CI/CD 통합

풀 리퀘스트 파이프라인에 번역 검증을 추가하세요. 도구가 출력하는 JUnit XML은 GitHub Actions 테스트 리포터, GitLab CI 아티팩트 및 JUnit을 지원하는 모든 CI 시스템과 연동돼요.

.github/workflows/validate-i18n.yml
name: Validate Translations
on:
  pull_request:
    paths: ['locales/**', 'public/locales/**']

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate translations
        run: npx @i18n-agent/i18n-validate ./locales --format junit -o i18n-report.xml

      - uses: dorny/test-reporter@v1
        if: always()
        with:
          name: i18n validation
          path: i18n-report.xml
          reporter: java-junit
The tool exits with code 1 when errors are found, so it naturally fails CI. Use --strict to also fail on warnings.

지원 형식

검증 도구는 i18n-convert를 기반으로 하며 32가지 i18n 파일 형식을 기본 지원해요. 형식별 플러그인이나 설정이 필요 없으며 파일 확장자와 내용에서 형식을 자동으로 감지해요.

Mobile & Desktop

Android XML, Xcode String Catalog, iOS Strings, iOS Stringsdict, Flutter ARB, Qt Linguist

Web & Frameworks

Structured JSON, i18next JSON, JSON5, HJSON, YAML (Rails), YAML (Plain), JavaScript, TypeScript, PHP/Laravel, NEON

Standards & Exchange

XLIFF 1.2, XLIFF 2.0, Gettext PO, TMX, .NET RESX, Java Properties

Data & Other

CSV, Excel (.xlsx), TOML, INI, SRT Subtitles, Markdown, Plain Text

구성

대부분의 프로젝트는 설정 없이 작동해요. 검사 심각도를 재정의하거나, 예상 언어를 설정하거나, 작업 중인 언어를 제외하는 등 세부 제어가 필요하다면 프로젝트 루트에 .i18n-validate.toml 파일을 만드세요.

.i18n-validate.toml
# .i18n-validate.toml
ref = "en"
expect = ["de", "ja", "fr", "es", "zh-Hans", "pt-BR", "ko"]

[checks]
missing-keys = "error"
extra-keys = "error"
placeholders = "error"
empty-values = "warning"
untranslated = "warning"

[languages.ko]
missing-keys = "warning"    # Korean is WIP

[languages.ar]
skip = true                 # Exclude from validation

관련 가이드

지금 i18n Agent 사용해 보기

번역 파일을 여기에 드롭

JSON, YAML, PO, XML, CSV, Markdown, Properties

또는 클릭하여 파일 선택

대상 언어

가입 불필요즉시 견적

자주 묻는 질문