i18n.json 설정

i18n.json은 Lingo.dev CLI와 CI/CD 통합을 제어하는 설정 파일입니다. 어떤 언어로 번역할지, 번역 가능한 콘텐츠가 어디에 있는지, 어떤 번역 백엔드를 사용할지 정의합니다.

최소 예제#

json

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

$schema 필드는 IDE 자동 완성과 유효성 검사를 지원합니다. version 필드는 자동 마이그레이션 호환성을 위해 스키마 버전을 추적합니다.

로캘#

locale 섹션에서 소스 언어와 대상 언어를 정의합니다:

json

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

필드	설명
`locale.source`	원본 콘텐츠가 작성된 언어입니다. 모든 번역은 이 로캘을 기준으로 진행됩니다.
`locale.targets`	대상 언어 배열입니다. 각 대상 언어는 버킷 형식에 따라 별도의 파일 또는 섹션으로 생성됩니다.

언어 코드는 BCP 47 표준을 따릅니다. en, en-US, es-ES, zh-Hans는 물론 Android의 en-rUS 같은 플랫폼별 형식도 지원합니다.

사용 가능한 로캘 코드를 확인하려면 다음을 실행하세요:

bash

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

버킷#

버킷은 파일 검색 패턴과 처리 규칙을 정의합니다. 각 버킷 키는 파일 형식을 지정하고, 값에는 포함하거나 제외할 파일을 설정합니다:

json

{
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "exclude": ["locales/[locale]/internal.json"]
    },
    "markdown": {
      "include": ["docs/[locale]/*.md"]
    }
  }
}

필드	설명
`include`	`[locale]` 플레이스홀더가 포함된 파일 패턴 배열입니다. glob 와일드카드(`*`)를 지원합니다.
`exclude`	선택 사항. 처리 중 건너뛸 패턴 배열입니다.
`lockedKeys`	선택 사항. 값을 번역하지 않고 원문에서 그대로 복사하는 키입니다. Key Locking을 참조하세요.
`ignoredKeys`	선택 사항. 번역 대상에서 완전히 제외되는 키로, 대상 파일에는 나타나지 않습니다. Key Ignoring을 참조하세요.
`preservedKeys`	선택 사항. 원문에서 한 번만 초기화한 뒤 자동 업데이트로부터 보호되는 키입니다. Key Preserving을 참조하세요.
`injectLocale`	선택 사항. 대상 로캘 코드가 자동으로 삽입되는 키입니다.

포함 패턴#

포함 패턴은 [locale] 플레이스홀더를 사용하며, 런타임에 설정된 로캘 코드로 치환됩니다:

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

재귀 glob 패턴(**/*.json)은 지원되지 않습니다. 대신 명시적인 디렉터리 경로를 사용하세요.

사용자 지정 로캘 구분자#

기본적으로 파일 이름의 로캘 코드는 대시(-)를 구분자로 사용합니다: en-US.json. 대신 밑줄을 사용하려면 delimiter 필드가 포함된 객체를 전달하세요:

json

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

이렇게 하면 legacy/en-US.json 대신 legacy/en_US.json이 생성됩니다.

키 경로 표기법#

lockedKeys, ignoredKeys, preservedKeys 배열은 중첩 키에 슬래시(/) 표기법을 사용하고, 와일드카드에는 별표(*)를 사용합니다:

json

{
  "lockedKeys": ["brand/name", "config/*"]
}

지원되는 버킷 유형 전체 목록은 Supported Formats를 참조하세요.

Provider#

provider 섹션에서는 번역에 사용할 raw LLM provider를 설정합니다. 이 섹션은 선택 사항이며, 생략하면 CLI는 Lingo.dev의 로컬라이제이션 엔진을 사용합니다.

json

{
  "provider": {
    "id": "openai",
    "model": "gpt-4o-mini",
    "prompt": "Translate the provided text from {source} to {target}."
  }
}

필드	설명
`provider.id`	provider 식별자입니다: `openai`, `anthropic`, `google`, `mistral`, `openrouter`, 또는 `ollama`.
`provider.model`	provider에서 사용하는 모델 이름입니다(예: `gpt-4o-mini`, `claude-3-haiku`).
`provider.prompt`	시스템 프롬프트입니다. `{source}` 및 `{target}`는 런타임에 로캘 코드로 대체됩니다.
`provider.baseUrl`	선택 사항. 사용자 지정 API 엔드포인트입니다(Ollama의 경우 필수: `http://localhost:11434`).

엔진 연결#

특정 로컬라이제이션 엔진으로 번역을 라우팅하려면 engineId 필드를 추가하세요:

json

{
  "engineId": "eng_SxjMwMsfOIsvV1wh"
}

engineId이 설정되면 모든 번역 요청에 엔진의 브랜드 보이스, glossary, instructions, model configuration이 자동으로 적용됩니다. 이를 생략하고 LINGO_API_KEY이 설정되어 있으면 CLI는 조직의 기본 엔진을 사용합니다.

전체 설정 가이드는 Connect Your Engine에서 확인하세요.

환경 변수#

변수	필수 여부	설명
`LINGO_API_KEY`	Lingo.dev Engine용	Lingo.dev API 키입니다.
`LINGO_API_URL`	아니요	사용자 지정 API 기본 URL입니다(셀프 호스팅 또는 스테이징용).
`OPENAI_API_KEY`	OpenAI provider용	OpenAI API 키입니다.
`ANTHROPIC_API_KEY`	Anthropic provider용	Anthropic API 키입니다.
`GOOGLE_API_KEY`	Google provider용	Google API 키입니다.
`MISTRAL_API_KEY`	Mistral provider용	Mistral API 키입니다.
`OPENROUTER_API_KEY`	OpenRouter provider용	OpenRouter API 키입니다.

전체 예제#

json

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "lockedKeys": ["brand/name", "brand/tagline"],
      "ignoredKeys": ["internal/*"]
    },
    "markdown": {
      "include": ["docs/[locale]/*.md"]
    }
  },
  "engineId": "eng_SxjMwMsfOIsvV1wh"
}

버전 마이그레이션#

CLI는 이전 버전의 i18n.json 설정을 최신 스키마 버전으로 자동 마이그레이션합니다. 현재 파일의 백업을 생성하고 스키마를 업데이트하며, 모든 설정은 그대로 유지합니다. 별도의 수동 작업은 필요하지 않습니다.

다음 단계#

Supported Formats

모든 버킷 유형과 설정 방법

i18n.lock

lockfile이 번역 상태를 추적하는 방식

Connect Your Engine

로컬라이제이션 엔진을 통해 번역 라우팅하기

Setup

CLI를 설치하고 시작하기

최소 예제#

json

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

$schema 필드는 IDE 자동 완성과 유효성 검사를 지원합니다. version 필드는 자동 마이그레이션 호환성을 위해 스키마 버전을 추적합니다.

로캘#

locale 섹션에서 소스 언어와 대상 언어를 정의합니다:

json

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

필드	설명
`locale.source`	원본 콘텐츠가 작성된 언어입니다. 모든 번역은 이 로캘을 기준으로 진행됩니다.
`locale.targets`	대상 언어 배열입니다. 각 대상 언어는 버킷 형식에 따라 별도의 파일 또는 섹션으로 생성됩니다.

언어 코드는 BCP 47 표준을 따릅니다. en, en-US, es-ES, zh-Hans는 물론 Android의 en-rUS 같은 플랫폼별 형식도 지원합니다.

사용 가능한 로캘 코드를 확인하려면 다음을 실행하세요:

bash

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

버킷#

버킷은 파일 검색 패턴과 처리 규칙을 정의합니다. 각 버킷 키는 파일 형식을 지정하고, 값에는 포함하거나 제외할 파일을 설정합니다:

json

{
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "exclude": ["locales/[locale]/internal.json"]
    },
    "markdown": {
      "include": ["docs/[locale]/*.md"]
    }
  }
}

필드	설명
`include`	`[locale]` 플레이스홀더가 포함된 파일 패턴 배열입니다. glob 와일드카드(`*`)를 지원합니다.
`exclude`	선택 사항. 처리 중 건너뛸 패턴 배열입니다.
`lockedKeys`	선택 사항. 값을 번역하지 않고 원문에서 그대로 복사하는 키입니다. Key Locking을 참조하세요.
`ignoredKeys`	선택 사항. 번역 대상에서 완전히 제외되는 키로, 대상 파일에는 나타나지 않습니다. Key Ignoring을 참조하세요.
`preservedKeys`	선택 사항. 원문에서 한 번만 초기화한 뒤 자동 업데이트로부터 보호되는 키입니다. Key Preserving을 참조하세요.
`injectLocale`	선택 사항. 대상 로캘 코드가 자동으로 삽입되는 키입니다.

포함 패턴#

포함 패턴은 [locale] 플레이스홀더를 사용하며, 런타임에 설정된 로캘 코드로 치환됩니다:

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

재귀 glob 패턴(**/*.json)은 지원되지 않습니다. 대신 명시적인 디렉터리 경로를 사용하세요.

사용자 지정 로캘 구분자#

json

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

이렇게 하면 legacy/en-US.json 대신 legacy/en_US.json이 생성됩니다.

키 경로 표기법#

lockedKeys, ignoredKeys, preservedKeys 배열은 중첩 키에 슬래시(/) 표기법을 사용하고, 와일드카드에는 별표(*)를 사용합니다:

json

{
  "lockedKeys": ["brand/name", "config/*"]
}

지원되는 버킷 유형 전체 목록은 Supported Formats를 참조하세요.

Provider#

provider 섹션에서는 번역에 사용할 raw LLM provider를 설정합니다. 이 섹션은 선택 사항이며, 생략하면 CLI는 Lingo.dev의 로컬라이제이션 엔진을 사용합니다.

json

{
  "provider": {
    "id": "openai",
    "model": "gpt-4o-mini",
    "prompt": "Translate the provided text from {source} to {target}."
  }
}

필드	설명
`provider.id`	provider 식별자입니다: `openai`, `anthropic`, `google`, `mistral`, `openrouter`, 또는 `ollama`.
`provider.model`	provider에서 사용하는 모델 이름입니다(예: `gpt-4o-mini`, `claude-3-haiku`).
`provider.prompt`	시스템 프롬프트입니다. `{source}` 및 `{target}`는 런타임에 로캘 코드로 대체됩니다.
`provider.baseUrl`	선택 사항. 사용자 지정 API 엔드포인트입니다(Ollama의 경우 필수: `http://localhost:11434`).

엔진 연결#

특정 로컬라이제이션 엔진으로 번역을 라우팅하려면 engineId 필드를 추가하세요:

json

{
  "engineId": "eng_SxjMwMsfOIsvV1wh"
}

전체 설정 가이드는 Connect Your Engine에서 확인하세요.

환경 변수#

변수	필수 여부	설명
`LINGO_API_KEY`	Lingo.dev Engine용	Lingo.dev API 키입니다.
`LINGO_API_URL`	아니요	사용자 지정 API 기본 URL입니다(셀프 호스팅 또는 스테이징용).
`OPENAI_API_KEY`	OpenAI provider용	OpenAI API 키입니다.
`ANTHROPIC_API_KEY`	Anthropic provider용	Anthropic API 키입니다.
`GOOGLE_API_KEY`	Google provider용	Google API 키입니다.
`MISTRAL_API_KEY`	Mistral provider용	Mistral API 키입니다.
`OPENROUTER_API_KEY`	OpenRouter provider용	OpenRouter API 키입니다.

전체 예제#

json

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "lockedKeys": ["brand/name", "brand/tagline"],
      "ignoredKeys": ["internal/*"]
    },
    "markdown": {
      "include": ["docs/[locale]/*.md"]
    }
  },
  "engineId": "eng_SxjMwMsfOIsvV1wh"
}

버전 마이그레이션#

다음 단계#

Supported Formats

모든 버킷 유형과 설정 방법

i18n.lock

lockfile이 번역 상태를 추적하는 방식

Connect Your Engine

로컬라이제이션 엔진을 통해 번역 라우팅하기

Setup

CLI를 설치하고 시작하기