로케일별 CSV

Lingo.dev CLI를 사용한 로케일별 개별 파일 기반 CSV 파일 AI 번역

로케일별 CSV란 무엇인가요?

로케일별 CSV는 여러 열이 있는 단일 CSV 파일에 모든 로케일을 저장하는 대신, 각 로케일마다 별도의 CSV 파일을 사용하는 번역 방식입니다. 이 형식은 각 행이 레코드를 나타내고 열이 서로 다른 필드를 나타내는 구조화된 데이터(제품 카탈로그, 사용자 데이터 또는 콘텐츠 관리 시스템 등)가 여러 열로 구성되어 있을 때 유용합니다.

예시:

id,name,description,created,enabled,sort
1,Welcome,Welcome to our application,2024-01-01,true,1
2,Save,Save your changes,2024-01-01,true,2
3,Error,An error occurred,2024-01-01,true,3

표준 CSV 버킷이 KEY,en,es와 같은 열로 모든 로케일을 하나의 파일에 저장하는 것과 달리, csv-per-locale 버킷은 각 로케일에 대해 별도의 파일을 유지하면서 모든 열이 포함된 원본 CSV 구조를 보존합니다.

Lingo.dev CLI란 무엇인가요?

Lingo.dev CLI는 AI를 사용하여 앱과 콘텐츠를 번역하는 무료 오픈 소스 CLI입니다. 기존 파이프라인과 통합하면서 기존 번역 관리 소프트웨어를 대체하도록 설계되었습니다.

자세한 내용은 개요를 참조하세요.

이 가이드에 대하여

이 가이드는 Lingo.dev CLI에서 csv-per-locale 버킷을 사용하여 CSV 파일을 번역하는 방법을 설명합니다.

다음 내용을 배우게 됩니다:

  • 처음부터 프로젝트 생성하기
  • 로케일별 개별 CSV 파일을 사용한 번역 파이프라인 구성하기
  • AI로 번역 생성하기
  • 잠긴 키와 무시된 키 사용하기

사전 요구 사항

Lingo.dev CLI를 사용하려면 Node.js v18 이상이 설치되어 있어야 합니다:

❯ node -v
v22.17.0

1단계. 프로젝트 설정하기

프로젝트 디렉터리에 i18n.json 파일을 생성합니다:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

이 파일은 번역할 언어와 파일 시스템에서 현지화 가능한 콘텐츠가 존재하는 위치를 포함하여 번역 파이프라인의 동작을 정의합니다.

사용 가능한 속성에 대해 자세히 알아보려면 i18n.json을 참조하세요.

2단계. 소스 로케일 구성

_소스 로케일_은 콘텐츠가 작성된 원본 언어 및 지역입니다. 소스 로케일을 구성하려면 i18n.json 파일에서 locale.source 속성을 설정하세요:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

소스 로케일은 BCP 47 언어 태그로 제공되어야 합니다.

Lingo.dev CLI가 지원하는 로케일 코드의 전체 목록은 지원되는 로케일 코드를 참조하세요.

3단계. 타겟 로케일 구성

_타겟 로케일_은 콘텐츠를 번역하려는 언어 및 지역입니다. 타겟 로케일을 구성하려면 i18n.json 파일에서 locale.targets 속성을 설정하세요:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

4단계. 소스 콘텐츠 생성

아직 생성하지 않았다면 소스 로케일에 대한 CSV 파일을 생성하세요. 파일에는 다음이 포함되어야 합니다:

  • 열 이름이 있는 헤더 행
  • 하나 이상의 데이터 행
  • 필요한 모든 열(특정 열 이름으로 제한되지 않음)

CSV 파일은 경로 어딘가에 소스 로케일이 포함된 위치에 있어야 합니다(예: en/와 같은 디렉토리 이름 또는 data.en.csv와 같은 파일 이름의 일부).

참고: 표준 CSV 버킷과 달리 "KEY" 열이나 소스 로케일과 일치하는 열이 필요하지 않습니다. csv-per-locale 버킷은 각 행을 레코드로 처리하며 구조를 유지하면서 CSV의 모든 텍스트 콘텐츠를 번역합니다.

5단계. 버킷 생성

  1. i18n.json 파일에서 buckets 객체에 "csv-per-locale" 객체를 추가합니다:

    {
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "csv-per-locale": {}
  }
}

  2. "csv-per-locale" 객체에서 하나 이상의 include 패턴 배열을 정의합니다:

    {
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "csv-per-locale": {
      "include": ["./[locale]/example.csv"]
    }
  }
}

    이 패턴들은 번역할 파일을 정의합니다.

    패턴 자체는:

    • 구성된 로케일의 플레이스홀더로 [locale]를 포함해야 합니다
    • 파일 경로를 가리킬 수 있습니다 (예: "[locale]/data.csv")
    • 와일드카드 플레이스홀더로 별표를 사용할 수 있습니다 (예: "[locale]/*.csv")

    재귀적 glob 패턴 (예: **/*.csv)은 지원되지 않습니다.

  3. 선택적으로 lockedKeys 및 ignoredKeys를 구성할 수 있습니다:

    {
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "csv-per-locale": {
      "include": ["./[locale]/example.csv"],
      "lockedKeys": ["locked_key_1"],
      "ignoredKeys": ["ignored_key_1"]
    }
  }
}
    • lockedKeys: 번역하지 않아야 하는 키 (첫 번째 열의 열 값, 일반적으로 ID)
    • ignoredKeys: 대상 로케일 파일에 나타나지 않아야 하는 키

6단계. LLM 구성

Lingo.dev CLI는 대규모 언어 모델(LLM)을 사용하여 AI로 콘텐츠를 번역합니다. 이러한 모델 중 하나를 사용하려면 지원되는 제공업체의 API 키가 필요합니다.

가능한 한 빠르게 시작하려면 매월 10,000개의 무료 토큰 사용량을 제공하는 자체 호스팅 플랫폼인 Lingo.dev Engine을 사용하는 것이 좋습니다:

  1. Lingo.dev 계정에 가입합니다.

  2. 다음 명령을 실행합니다:

    npx lingo.dev@latest login

    기본 브라우저가 열리고 인증을 요청합니다.

  3. 안내에 따릅니다.

7단계. 번역 생성

i18n.json 파일이 포함된 디렉터리에서 다음 명령을 실행합니다:

npx lingo.dev@latest run

이 명령어는:

  1. i18n.json 파일을 읽습니다.
  2. 번역이 필요한 파일을 찾습니다.
  3. CSV 파일에서 번역 가능한 콘텐츠를 추출합니다.
  4. 구성된 LLM을 사용하여 추출된 콘텐츠를 번역합니다.
  5. 번역된 콘텐츠를 각 대상 로케일별로 별도의 CSV 파일에 작성합니다.

번역이 처음 생성될 때 i18n.lock 파일이 생성됩니다. 이 파일은 번역된 콘텐츠를 추적하여 후속 실행 시 불필요한 재번역을 방지합니다.

예제

en/example.csv (번역 전)

id,name,description,created,enabled,sort
1,Welcome,Welcome to our application,2024-01-01,true,1
2,Save,Save your changes,2024-01-01,true,2
3,Error,An error occurred,2024-01-01,true,3
4,Success,Operation completed successfully,2024-01-01,true,4
5,Loading,Please wait while we load your data,2024-01-01,true,5

es/example.csv (번역 후)

id,name,description,created,enabled,sort
1,Bienvenida,Bienvenido a nuestra aplicación,2024-01-01,true,1
2,Guardar,Guarda tus cambios,2024-01-01,true,2
3,Error,Ha ocurrido un error,2024-01-01,true,3
4,Éxito,Operación completada con éxito,2024-01-01,true,4
5,Cargando,Por favor espera mientras cargamos tus datos,2024-01-01,true,5

i18n.json

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "csv-per-locale": {
      "include": ["./[locale]/example.csv"],
      "lockedKeys": ["locked_key_1"],
      "ignoredKeys": ["ignored_key_1"]
    }
  }
}

i18n.lock

version: 1
checksums:
  e8b273672f895de0944f0a2317670d7c:
    0/name: 1308168cca4fa5d8d7a0cf24e55e93fc
    0/description: 8de4bc8832b11b380bc4cbcedc16e48b
    1/name: f7a2929f33bc420195e59ac5a8bcd454
    1/description: 8de4bc8832b11b380bc4cbcedc16e48b
    2/name: d3d99b147cc363dc6db8a48e8a13d4c1
    2/description: 7cd986af1fe5e89abe7ecffba5413110

CSV 버킷과의 차이점

csv-per-locale 버킷은 표준 csv 버킷과 여러 면에서 다릅니다:

  • 파일 구조: csv-per-locale는 각 로케일별로 별도의 파일을 사용하는 반면(예: en/example.csv, es/example.csv), csv는 여러 열이 있는 단일 파일을 사용합니다(예: KEY,en,es).

  • 열 요구사항: csv-per-locale는 "KEY" 열이나 로케일 이름의 열이 필요하지 않습니다. 데이터에 맞는 모든 열 구조를 사용할 수 있습니다.

  • 사용 사례: csv-per-locale는 제품 카탈로그, 콘텐츠 관리 시스템 또는 각 행이 여러 필드가 있는 레코드를 나타내는 데이터베이스와 같은 구조화된 데이터에 이상적입니다. 표준 csv 버킷은 간단한 키-값 번역 테이블에 더 적합합니다.

  • 파일 변경: 두 버킷 모두 파일을 직접 변경하지만, csv-per-locale는 각 로케일별로 별도의 파일을 생성하는 반면, csv는 기존 파일에 새 열을 추가합니다.