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.10"
}

구성 요소:

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

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

로케일 구성

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

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

언어 코드는 언어 태그에 대한 BCP 47 표준을 따르며, ISO 639의 언어 코드와 ISO 3166-1의 선택적 지역 코드를 통합합니다. 예시로는 en, en-US, es-ES, zh-Hans 등이 있습니다.

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

npx lingo.dev@latest show locale sources  # Available source languages
npx lingo.dev@latest show locale targets  # Available target languages

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

구성 요소:

  • 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] 플레이스홀더와 함께 glob 유사 구문을 사용합니다:

  • 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 — Android XML 리소스 파일
  • csv — 각 대상 언어별로 별도 파일이 있는 CSV 파일
  • flutter — Flutter ARB 파일
  • html — 각 대상 언어별로 별도 파일이 있는 HTML 파일
  • json — 각 대상 언어별로 별도 파일이 있는 JSON 파일
  • markdown — 각 대상 언어별로 별도 파일이 있는 Markdown 파일
  • mdx — 각 대상 언어별로 별도 파일이 있는 MDX 파일
  • xcode-strings — 레거시 Xcode .strings 파일
  • xcode-stringsdict — 복수형을 위한 Xcode .stringsdict 파일
  • xcode-xcstrings — Xcode strings catalog 파일
  • 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.10",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

모노레포 구성

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "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 업데이트와 호환되도록 보장합니다.