JSON5 - Lingo.dev CLI

JSON5란 무엇인가요?

JSON5는 JSON의 확장으로, 사람이 직접 작성하고 유지 관리하기 쉽게 만들어졌습니다. 주석, 따옴표 없는 키, 후행 쉼표 및 더 유연한 구문을 지원하면서도 JavaScript와의 호환성을 유지합니다.

예시:

{
  // JSON5는 주석을 허용합니다!
  title: "Hello, world!",
  description: "JSON5 기능이 있는 간단한 데모 앱",

  // 따옴표 없는 키가 허용됩니다
  author: {
    name: "John Doe",
  },

  messages: ["MyApp에 오신 것을 환영합니다", "Hello, world!"],

  // 후행 쉼표가 허용됩니다
  locked_key_1: "This value is locked and should not be changed",
}

Lingo.dev CLI란 무엇인가요?

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

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

이 가이드에 대하여

이 가이드는 Lingo.dev CLI로 JSON5 파일을 번역하는 방법을 설명합니다.

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

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

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

5단계. 버킷 생성하기

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

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

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

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

6단계. LLM 구성하기

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

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

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

7단계. 번역 생성하기

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

npx lingo.dev@latest run

이 명령어는 다음을 수행합니다:

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

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

예시

en/example.json5

{
  // JSON5는 주석을 허용합니다!
  title: "Hello, world!",
  description: "JSON5 기능이 있는 간단한 데모 앱",
  version: "1.0.0",
  support_email: "[email protected]",
  homepage: "https://lingo.dev",
  deprecated: null,
  empty: "",
  emoji: "🚀",

  // 따옴표 없는 키가 허용됩니다
  author: {
    name: "John Doe",
  },

  contributors: [{ name: "Alice" }, { name: "Bob" }],

  messages: ["MyApp에 오신 것을 환영합니다", "Hello, world!"],

  config: {
    theme: {
      primary: "블루 테마",
    },
  },

  mixed_array: [
    "여기에 혼합 콘텐츠",
    42,
    true,
    {
      nested_message: "중첩된 텍스트",
    },
  ],

  // 16진수 숫자는 JSON5에서 작동합니다
  hex_value: 0xdeadbeef,

  // 후행 쉼표가 허용됩니다
  locked_key_1: "This value is locked and should not be changed",
}

es/example.json5

{
  // JSON5는 주석을 허용합니다!
  title: "¡Hola, mundo!",
  description: "Una aplicación de demostración simple con características JSON5",
  version: "1.0.0",
  support_email: "[email protected]",
  homepage: "https://lingo.dev",
  deprecated: null,
  empty: "",
  emoji: "🚀",

  // 따옴표 없는 키가 허용됩니다
  author: {
    name: "Juan Pérez",
  },

  contributors: [{ name: "Alicia" }, { name: "Roberto" }],

  messages: ["Bienvenido a MyApp", "¡Hola, mundo!"],

  config: {
    theme: {
      primary: "Tema azul",
    },
  },

  mixed_array: [
    "Contenido mixto aquí",
    42,
    true,
    {
      nested_message: "Texto anidado",
    },
  ],

  // 16진수 숫자는 JSON5에서 작동합니다
  hex_value: 0xdeadbeef,

  // 후행 쉼표가 허용됩니다
  locked_key_1: "This value is locked and should not be changed",
}

i18n.json

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

i18n.lock

version: 1
checksums:
  455da9346f4e772000927cd2ff5bb898:
    title: 0468579ef2fbc83c9d520c2f2f1c5059
    description: 6f4922f45568161a8cdf4ad2299f6d23
    version: 54a9e730e88fb16291b852274d433923
    support_email: 10627fcc465897af0f5e1bba042685f9
    emoji: b328c432cee108a87a92f05258b6a651
    author/name: febee8e9ab40b2fe5106d72675228d00
    contributors/0/name: e80d4063a32adaad7b0a82b0bcc10551
    contributors/1/name: b2bca2fa3c890618e56d07473f26ead3
    messages/0: d1c3a9f35e377554a4ccaa467ca26614
    messages/1: 0468579ef2fbc83c9d520c2f2f1c5059
    config/theme/primary: 7535a3779d6934ea8ecf18f5cb5b93fd
    mixed_array/0: 001b5b003d96c133534f5907abffdf77
    mixed_array/3/nested_message: 5f0782dfc5993e99890c0475bc295a30
    hex_value: a1b2c3d4e5f6789012345678abcdef01