i18n.json 구성

i18n.json은 Lingo.dev CLI와 Lingo.dev CI/CD 통합의 동작을 제어하는 표준 구성 파일입니다.

i18n.json은 언어 설정, 파일 검색 패턴, AI 번역 엔진 구성을 별도의 섹션으로 분리하는 스키마 기반 구성을 구현합니다. 결과적으로 개발자는 구성 파일을 읽음으로써 로컬라이제이션 워크플로우가 정확히 어떻게 작동하는지 이해할 수 있습니다.

이 가이드는 Lingo.dev CLI가 설치되어 있고 번역 워크플로우를 구성 중이라고 가정합니다. 완료 시, 여러분은 i18n.json의 전체 구조, 구성 옵션 및 각 섹션이 번역 동작을 어떻게 제어하는지 이해하게 될 것입니다.

버전

version 필드는 구성 스키마 버전을 지정합니다:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": 1.8
}

구성 요소:

  • $schema — IDE 자동 완성 및 유효성 검사를 위한 JSON 스키마 정의를 가리킵니다. 이 스키마는 인라인 문서와 타입 검사를 제공하여 초기에 구성 오류를 포착하는 데 도움이 됩니다.
  • version — 마이그레이션 호환성을 위한 구성 스키마 버전입니다.

Lingo.dev CLI는 새로운 스키마 버전이 출시될 때 자동 구성 마이그레이션을 위해 이 필드를 사용합니다.

로케일 구성

locale 섹션은 Lingo.dev CLI가 처리하는 언어를 정의합니다:

{
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "ja", "de"]
  }
}

언어 코드는 ISO 639의 언어 코드와 ISO 3166-1의 선택적 지역 코드를 포함하는 BCP 47 표준을 따릅니다. 예시로는 en, en-US, es-ES, zh-Hans 등이 있습니다.

Lingo.dev CLI는 또한 Android의 리소스 디렉토리를 위한 en-rUS 규칙과 같은 플랫폼별 로케일 형식도 지원합니다. 지원되는 로케일 코드의 전체 목록을 얻으려면 다음을 실행하세요:

npx lingo.dev@latest show locale sources  # 사용 가능한 소스 언어
npx lingo.dev@latest show locale targets  # 사용 가능한 대상 언어

귀하의 로케일 코드가 지원되지 않는 경우, 풀 리퀘스트를 열어 추가해 주세요!

구성 요소:

  • locale.source — 권위 있는 콘텐츠를 포함하는 파일을 식별하는 소스 언어 코드입니다. 모든 번역은 소스에서 대상으로 흐릅니다.
  • locale.targets — 대상 시장을 나타내는 대상 언어 코드 배열입니다. 각 코드는 형식에 따라 별도의 파일 또는 파일 내 섹션에 해당합니다.

언어 확인 명령어:

제공자 구성

provider 섹션은 Lingo.dev CLI가 사용하는 AI 번역 서비스를 결정합니다. 이 섹션은 선택 사항이며 생략할 경우 기본값으로 Lingo.dev의 AI 번역 엔진을 사용합니다.

원시 LLM API 액세스의 경우:

{
  "provider": {
    "id": "openai",
    "model": "gpt-4o-mini",
    "prompt": "Your custom translation prompt with {source} and {target} placeholders"
  }
}

Lingo.dev 엔진의 경우:

Lingo.dev 엔진을 사용하려면 provider 섹션을 완전히 생략하세요. 엔진은 최적화 연구와 Lingo.dev 엔진 설정을 기반으로 모델과 프롬프트를 자동으로 선택합니다.

구성 요소:

  • provider.id — AI 번역 서비스 식별자(예: "openai" 또는 "anthropic").
  • provider.model — AI 번역 모델 이름(예: OpenAI의 "gpt-4o-mini" 또는 Anthropic의 "claude-3-haiku").
  • provider.prompt — 번역 동작을 안내하는 시스템 프롬프트. {source}와 {target} 플레이스홀더는 런타임에 실제 언어 코드로 대체됩니다.

버킷 구성

버킷은 파일 검색 패턴과 처리 규칙을 정의합니다. 각 버킷은 특정 포함/제외 패턴이 있는 파일 형식을 나타냅니다.

{
  "buckets": {
    "json": {
      "include": ["locales/[locale].json", "app/[locale]/*.json"],
      "exclude": ["locales/[locale]/internal.json"],
      "lockedKeys": ["app/version", "config/apiUrl"],
      "injectLocale": ["settings.language"]
    },
    "markdown": {
      "include": ["docs/[locale]/*.md"],
      "exclude": ["docs/[locale]/drafts/*.md"]
    }
  }
}

구성 요소:

  • buckets.[bucket-type] — 특정 파일 형식 버킷에 대한 구성 그룹.
    • buckets.[bucket-type].include — 파일 검색 패턴 배열. 문자열 또는 객체를 포함할 수 있습니다.
      • buckets.[bucket-type].include.[string] — [locale] 플레이스홀더가 있는 간단한 파일 경로 패턴.
      • buckets.[bucket-type].include.[object] — 다음 속성이 있는 고급 패턴 구성:
        • path — [locale] 플레이스홀더가 있는 파일 경로 패턴.
        • delimiter — 로케일 코드에 사용할 구분자. 기본값은 -(대시)이며, _(밑줄)로 재정의할 수 있습니다. 로케일 구성의 구분자를 재정의합니다.
    • buckets.[bucket-type].exclude — 처리 중 건너뛸 파일 제외 패턴 배열.
    • buckets.[bucket-type].lockedKeys — 번역하지 않아야 하는 키 배열. 중첩된 키의 구분자로 슬래시 /를 사용합니다.
    • buckets.[bucket-type].ignoredKeys — 번역 중 무시해야 하는 키 배열. 중첩된 키의 구분자로 슬래시 /를 사용합니다.
    • buckets.[bucket-type].injectLocale — 로케일 코드가 자동으로 주입되어야 하는 키 배열.

기본 패턴 구조

포함 패턴은 특수 [locale] 플레이스홀더가 있는 글로브 유사 구문을 사용합니다:

  • locales/[locale].json → locales/en.json, locales/es.json
  • docs/[locale]/*.md → docs/en/*.md, docs/es/*.md

제외 패턴은 포함 패턴 내에서 특정 파일의 처리를 방지합니다.

고급 패턴 옵션

다양한 파일명 형식을 위한 사용자 정의 로케일 구분자:

{
  "include": [
    "standard/[locale].json",
    {
      "path": "underscore/[locale].json",
      "delimiter": "_"
    }
  ]
}

사용 가능한 구분자:

  • - (대시): en-US.json
  • _ (밑줄): en_US.json

팁: 이 설정은 파일 이름에 사용되는 구분자를 제어하므로, 서로 다른 구분자 규칙을 가진 다양한 프로젝트가 있는 모노레포 설정에서 사용할 수 있습니다.

지원되는 버킷 유형

Lingo.dev CLI는 다양한 파일 형식에 대해 다음과 같은 버킷 유형을 지원합니다:

  • android — 안드로이드 XML 리소스 파일
  • csv — 대상 언어별로 별도의 파일이 있는 CSV 파일
  • flutter — Flutter ARB 파일
  • html — 대상 언어별로 별도의 파일이 있는 HTML 파일
  • json — 대상 언어별로 별도의 파일이 있는 JSON 파일
  • markdown — 대상 언어별로 별도의 파일이 있는 마크다운 파일
  • mdx — 대상 언어별로 별도의 파일이 있는 MDX 파일
  • xcode-strings — 레거시 Xcode .strings 파일
  • xcode-stringsdict — 복수형을 위한 Xcode .stringsdict 파일
  • xcode-xcstrings — Xcode 문자열 카탈로그 파일
  • yaml — 대상 언어별로 별도의 파일이 있는 YAML 파일
  • yaml-root-key — 로케일 기반 루트 키가 있는 YAML 파일
  • properties — Java .properties 파일
  • po — GNU gettext .po 파일
  • xml — 대상 언어별로 별도의 파일이 있는 일반 XML 파일
  • php — PHP 배열 파일
  • vue-json — Vue.js i18n JSON 파일
  • typescript — 대상 언어별로 별도의 파일이 있는 TypeScript 파일

구성 예시

기본 구성

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": 1.8,
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

모노레포 구성

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": 1.8,
  "locale": {
    "source": "en-US",
    "targets": ["es-ES", "fr-FR"]
  },
  "buckets": {
    "json": {
      "include": ["apps/web/locales/[locale].json"]
    },
    "mdx": {
      "include": ["packages/docs/content/[locale]/*.mdx"]
    },
    "xcode-xcstrings": {
      "include": ["ios/Localizable.xcstrings"]
    },
    "android": {
      "include": ["android/values-[locale]/strings.xml"]
    }
  }
}

버전 마이그레이션

i18n.json은 사용자 설정을 모두 유지하면서 구성을 최신 스키마 버전으로 자동 업데이트하는 스마트 버전 마이그레이션을 구현합니다.

Lingo.dev CLI가 이전 구성 버전을 감지하면 다음과 같이 처리합니다:

  1. 현재 i18n.json 파일의 백업을 생성합니다
  2. 구성을 최신 스키마 버전으로 마이그레이션합니다
  3. 사용자 정의 프로바이더, 버킷 구성, 잠긴 키를 포함한 모든 설정을 보존합니다
  4. 버전 필드를 업데이트하여 현재 스키마와 일치시킵니다

마이그레이션 동작:

구성 파일을 읽는 모든 CLI 작업 중에 마이그레이션이 자동으로 트리거됩니다. 수동 개입이 필요 없으며, 번역 워크플로우는 중단 없이 계속됩니다.

이 마이그레이션 시스템은 i18n.json 구성이 기존 프로젝트와의 하위 호환성을 유지하면서 Lingo.dev CLI 업데이트와 호환되도록 보장합니다.