버킷 - Lingo.dev CLI

소개

i18n.json 파일에서 buckets 속성은 다음을 정의합니다:

파일에서 현지화 가능한 콘텐츠를 추출하는 데 사용되는 파서
파일 시스템에서 현지화 가능한 콘텐츠가 존재하는 위치
키 잠금과 같은 특정 버킷별 기능

버킷 구성은 Lingo.dev CLI로 번역 파이프라인을 설정하는 데 필수적인 단계입니다.

버킷 유형

Lingo.dev CLI는 다양한 업계 표준 파일 형식(및 일부 비표준 형식)과 호환됩니다. 이러한 각 형식은 특정 유형의 버킷과 연결됩니다.

버킷 유형은 일반적으로 파일 형식과 동의어이지만 항상 일대일 매핑은 아닙니다. 예를 들어, "json" 및 "json-dictionary" 버킷은 모두 JSON 파일의 현지화 가능한 콘텐츠를 처리하지만, CLI는 파일이 다르게 구조화되기를 기대하므로 버킷은 구별됩니다.

출력 모드

콘텐츠를 현지화할 때 일부 버킷은 소스 콘텐츠가 있는 파일을 변경하는 반면, 다른 버킷은 각 대상 로케일에 대해 별도의 파일을 생성합니다.

이러한 동작 차이의 이유는 버킷에 따라 두 옵션 중 하나가 가장 적합하기 때문입니다. 모든 버킷 유형에 적용할 수 있는 단일하고 올바른 옵션은 없습니다.

예를 들어, CSV 버킷을 사용할 때 .csv 파일은 직접 변경됩니다. 이는 CSV 파일이 일반적으로 각 로케일에 대한 현지화된 콘텐츠를 동일한 파일의 별도 열에 저장하기 때문입니다:

KEY,en,es
welcome_message,Welcome to our application,Bienvenido a nuestra aplicación

반면에 Markdown 버킷을 사용할 때는 현지화된 콘텐츠가 별도의 파일로 출력됩니다. 이는 모든 현지화된 변형을 단일 파일에 저장하는 것이 일반적이지 않기 때문입니다.

다음과 같은 몇 가지 이유로 이를 이해하는 것이 중요합니다:

서로 다른 버킷이 다르게 동작한다는 것이 즉시 명확하지 않습니다.
파일이 출력되는 방식에 따라 include 및 exclude 패턴을 다르게 정의해야 합니다.

버킷 생성

버킷을 생성하려면 i18n.json 파일의 buckets 객체에 항목을 추가하세요:

{
  "buckets": {
    "json": {}
  }
}

각 키는 지원되는 버킷 유형 중 하나에 해당해야 하며, 값은 해당 버킷에 대한 유효한 구성을 포함하는 객체여야 합니다.

buckets 속성은 최소한 하나의 유효한 항목을 가져야 합니다.

파일 포함

최소한 버킷은 현지화할 콘텐츠를 정의하는 include 속성을 가져야 합니다:

{
  "buckets": {
    "json": {
      "include": []
    }
  }
}

이 속성은 문자열 배열이어야 합니다.

각 문자열은 다음 중 하나일 수 있습니다:

파일 경로 (예: "some/dir/labels.json")
glob 패턴 (예: "some/dir/*.json")

이러한 값은 항상 i18n.json 파일을 기준으로 상대 경로입니다.

`[locale]` 플레이스홀더

버킷이 현지화된 콘텐츠를 별도의 파일로 출력할 때 (즉, 기존 파일을 변경하지 않을 때), include 패턴은 특수한 [locale] 플레이스홀더를 포함해야 합니다:

{
  "buckets": {
    "json": {
      "include": ["[locale]/*.mdx"]
    }
  }
}

이 플레이스홀더는 런타임에 대체되며 CLI가 다음을 수행하는 위치에 영향을 미칩니다:

소스 콘텐츠를 찾는 위치
현지화된 콘텐츠를 출력하는 위치

예를 들어, 소스 로케일이 "en"이고 대상 로케일이 "es"인 경우, [locale]/*.mdx는 en/ 디렉터리에서 모든 MDX 파일을 찾아 현지화된 파일을 es/ 디렉터리로 출력합니다.

[locale] 플레이스홀더의 위치는 중요하지 않으며, 다음은 모두 유효한 패턴입니다:

content/[locale]/*.mdx
[locale]/*.mdx
*.[locale].mdx

재귀 glob 패턴

Lingo.dev CLI는 재귀 glob 패턴을 지원하지 않습니다. 즉, "**/*.json"와 같은 패턴은 작동하지 않습니다. 재귀 glob 패턴을 구성하려고 하면 오류가 발생합니다.

파일 확장자

include 패턴에서 파일 확장자는 중요하지 않습니다. Lingo.dev CLI는 확장자에 관계없이 버킷 유형에 따라 지정된 파일을 파싱하려고 시도합니다.

파일 제외

include 패턴 외에도 버킷은 로컬라이제이션에서 파일 경로 또는 glob 패턴을 제외하기 위한 exclude 패턴을 지원합니다:

{
  "buckets": {
    "json": {
      "include": ["[locale]/*.mdx"],
      "exclude": ["[locale]/ignored/*.mdx"],
    }
  }
}

이러한 패턴은 include 패턴과 동일한 규칙을 따릅니다.

버킷별 기능

일부 버킷에는 다른 버킷에는 없는 특정 기능이 있습니다. 이는 일반적으로 해당 기능이 해당 버킷의 컨텍스트에서만 논리적으로 의미가 있기 때문입니다.

버킷별 기능은 다음과 같습니다:

이러한 기능에 대한 자세한 내용은 링크된 문서를 참조하세요.

버킷

소개