YAML - Lingo.dev CLI

YAML이란 무엇인가요?

YAML(YAML Ain't Markup Language)은 사람이 읽기 쉬운 데이터 직렬화 형식으로, 주로 구성 파일, 데이터 교환 및 구조화된 데이터 저장에 사용됩니다. 계층 구조를 표현하기 위해 들여쓰기를 사용하며 복잡한 데이터 구조를 지원합니다.

예시:

title: "MyApp"
description: Hello, world!
welcome_message: 'Welcome to MyApp'

user_profile:
  display_name: "John Doe"
  bio: Software developer

navigation_items:
  - "Home"
  - "About"
  - "Contact"

product:
  name: "MyWidget"
  tagline: The best widget ever

Lingo.dev CLI란 무엇인가요?

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

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

이 가이드에 대하여

이 가이드는 Lingo.dev CLI를 사용하여 YAML 파일을 번역하는 방법을 설명합니다.

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

처음부터 프로젝트 생성하기
번역 파이프라인 구성하기
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단계. 소스 콘텐츠 생성하기

아직 생성하지 않았다면, 번역할 콘텐츠가 포함된 하나 이상의 YAML 파일을 생성하세요. 이 파일들은 경로 어딘가에 소스 로케일이 포함된 위치에 있어야 합니다(예: en/과 같은 디렉토리 이름이나 messages.en.yml과 같은 파일 이름의 일부로).

5단계. 버킷 생성하기

i18n.json 파일에서 buckets 객체에 "yaml" 객체를 추가하세요:

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

"yaml" 객체에서 하나 이상의 include 패턴 배열을 정의하세요:
```
{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "yaml": {
      "include": ["./[locale]/example.yml"]
    }
  }
}
```
이 패턴들은 번역할 파일을 정의합니다.

패턴 자체는:
- 구성된 로케일의 플레이스홀더로 [locale]을 포함해야 합니다
- 파일 경로를 가리킬 수 있습니다(예: "[locale]/config.yml")
- 와일드카드 플레이스홀더로 별표를 사용할 수 있습니다(예: "[locale]/*.yml")
재귀적 글로브 패턴(예: **/*.yml)은 지원되지 않습니다.

6단계. LLM 구성하기

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

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

Lingo.dev 계정에 가입하세요.
다음 명령을 실행하세요:
```
npx lingo.dev@latest login
```
이렇게 하면 기본 브라우저가 열리고 인증을 요청합니다.
안내에 따르세요.

7단계. 번역 생성하기

'i18n.json' 파일이 있는 디렉토리에서 다음 명령어를 실행하세요:

npx lingo.dev@latest run

이 명령어는 다음과 같은 작업을 수행합니다:

'i18n.json' 파일을 읽습니다.
번역이 필요한 파일들을 찾습니다.
파일에서 번역 가능한 콘텐츠를 추출합니다.
구성된 LLM을 사용하여 추출된 콘텐츠를 번역합니다.
번역된 콘텐츠를 파일 시스템에 다시 작성합니다.

번역이 처음 생성될 때 'i18n.lock' 파일이 생성됩니다. 이 파일은 어떤 콘텐츠가 번역되었는지 추적하여 이후 실행 시 불필요한 재번역을 방지합니다.

예시

en/example.yml

title: "MyApp"
description: Hello, world!
welcome_message: 'Welcome to MyApp'

user_profile:
  display_name: "John Doe"
  bio: Software developer

navigation_items:
  - "Home"
  - "About"
  - "Contact"

product:
  name: "MyWidget"
  tagline: The best widget ever
  features:
    - "Easy to use"
    - "Fast and reliable"

settings:
  max_users: 100
  enabled: true
  timeout: 30.5

complex_structure:
  level_one:
    level_two:
      message: "Deep nested text"
locked_key_1: "This value is locked and should not be changed"
ignored_key_1: "This value is ignored and should not appear in target locales"

es/example.yml

title: "MyApp"
description: "¡Hola, mundo!"
welcome_message: "Bienvenido a MyApp"
user_profile:
  display_name: "Juan Pérez"
  bio: "Desarrollador de software"
navigation_items:
  - "Inicio"
  - "Acerca de"
  - "Contacto"
product:
  name: "MyWidget"
  tagline: "El mejor widget de todos"
  features:
    - "Fácil de usar"
    - "Rápido y confiable"
settings:
  max_users: 100
  enabled: true
  timeout: 30.5
complex_structure:
  level_one:
    level_two:
      message: "Texto anidado profundo"
locked_key_1: "This value is locked and should not be changed"

i18n.json

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

i18n.lock

version: 1
checksums:
  1b0d7c9f07dcc31a978bc337763270ea:
    title: 7dc70110429d46e3685f385bd2cc941c
    description: 0468579ef2fbc83c9d520c2f2f1c5059
    welcome_message: d1c3a9f35e377554a4ccaa467ca26614
    user_profile/display_name: febee8e9ab40b2fe5106d72675228d00
    user_profile/bio: 155ddcb7c93493ac72a37074eea0a653
    navigation_items/0: 104a3db3b671c04e167eafbe21e57881
    navigation_items/1: 944521eeeed2511833d2299931273c71
    navigation_items/2: 9afa39bc47019ee6dec6c74b6273967c
    product/name: ed21de171d538a49db999c47875f75a5
    product/tagline: b7ac41680e82d75ae7f5774f7ceef1b4
    product/features/0: c916ba887951a02793ff851853fd964f
    product/features/1: 1c60a04d6890c6ec910a7f2e6ec0ae7b
    complex_structure/level_one/level_two/message: b53034560bf657106e5aaea9160e357e