JSON 딕셔너리 - Lingo.dev CLI

JSON 딕셔너리란?

JSON 딕셔너리는 여러 로케일의 모든 번역을 단일 JSON 파일에 저장하는 로컬라이제이션 형식입니다. 각 키에는 로케일 코드를 키로, 번역된 문자열을 값으로 하는 객체가 포함되어 있어 모든 번역을 한 곳에서 쉽게 관리할 수 있습니다.

예시:

{
  "navigation": {
    "en": "Home"
  },
  "buttons": {
    "submit": {
      "en": "Submit"
    },
    "cancel": {
      "en": "Cancel"
    }
  },
  "forms": {
    "login": {
      "username": {
        "en": "Username"
      }
    }
  }
}

Lingo.dev CLI란?

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

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

이 가이드에 대하여

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

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

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

아직 생성하지 않았다면, 번역할 콘텐츠가 포함된 JSON 딕셔너리 파일을 생성하세요.

참고: 번역 프로세스 중에 소스 콘텐츠 파일은 번역된 콘텐츠를 포함하도록 덮어쓰여집니다(소스 콘텐츠와 함께).

5단계. 버킷 생성하기

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

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

"json-dictionary" 객체에서 하나 이상의 include 패턴 배열을 정의하세요:
```
{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "json-dictionary": {
      "include": ["./example.json"]
    }
  }
}
```
이러한 패턴은 번역할 파일을 정의하며 다음 중 하나를 사용할 수 있습니다:
- 특정 파일 경로 지정(예: "some/dir/file.json")
- 와일드카드 플레이스홀더로 별표 사용(예: "some/dir/*.json")
재귀적 glob 패턴(예: **/*.json)은 지원되지 않습니다.

6단계. LLM 구성하기

Lingo.dev CLI는 대규모 언어 모델(LLM)을 사용하여 AI로 콘텐츠를 번역합니다. 이러한 모델 중 하나를 사용하려면 지원되는 제공업체의 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 파일이 생성됩니다. 이 파일은 어떤 콘텐츠가 번역되었는지 추적하여 후속 실행 시 불필요한 재번역을 방지합니다.

예제

example.json (번역 전)

{
  "navigation": {
    "en": "Home"
  },
  "buttons": {
    "submit": {
      "en": "Submit"
    },
    "cancel": {
      "en": "Cancel"
    }
  },
  "messages": {
    "welcome": {
      "en": "Welcome to our application"
    },
    "error": {
      "en": "An error occurred"
    }
  },
  "forms": {
    "login": {
      "title": {
        "en": "Login"
      },
      "fields": {
        "username": {
          "en": "Username"
        },
        "password": {
          "en": "Password"
        }
      }
    }
  }
}

example.json (번역 후)

{
  "navigation": {
    "en": "Home",
    "es": "Inicio"
  },
  "buttons": {
    "submit": {
      "en": "Submit",
      "es": "Enviar"
    },
    "cancel": {
      "en": "Cancel",
      "es": "Cancelar"
    }
  },
  "messages": {
    "welcome": {
      "en": "Welcome to our application",
      "es": "Bienvenido a nuestra aplicación"
    },
    "error": {
      "en": "An error occurred",
      "es": "Ha ocurrido un error"
    }
  },
  "forms": {
    "login": {
      "title": {
        "en": "Login",
        "es": "Iniciar sesión"
      },
      "fields": {
        "username": {
          "en": "Username",
          "es": "Nombre de usuario"
        },
        "password": {
          "en": "Password",
          "es": "Contraseña"
        }
      }
    }
  }
}

i18n.json

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

i18n.lock

version: 1
checksums:
  455da9346f4e772000927cd2ff5bb898:
    navigation: 104a3db3b671c04e167eafbe21e57881
    buttons/submit: 7c91ef5f747eea9f77a9c4f23e19fb2e
    buttons/cancel: 2e2a849c2223911717de8caa2c71bade
    messages/welcome: 1308168cca4fa5d8d7a0cf24e55e93fc
    messages/error: 53a2b5f5e7d83c737c8e02fe18fb4bdb
    forms/login/title: f4f219abeb5a465ecb1c7efaf50246de
    forms/login/fields/username: 2ee65bc2dd2f12cf2672f95b2a054bf8
    forms/login/fields/password: 223a61cf906ab9c40d22612c588dff48
  a8f80a1a4e0e0aa2750e514a8a6abacf:
    navigation: 104a3db3b671c04e167eafbe21e57881
    buttons/submit: 7c91ef5f747eea9f77a9c4f23e19fb2e
    buttons/cancel: 2e2a849c2223911717de8caa2c71bade
    messages/welcome: 1308168cca4fa5d8d7a0cf24e55e93fc
    messages/error: 53a2b5f5e7d83c737c8e02fe18fb4bdb
    forms/login/title: f4f219abeb5a465ecb1c7efaf50246de
    forms/login/fields/username: 2ee65bc2dd2f12cf2672f95b2a054bf8
    forms/login/fields/password: 223a61cf906ab9c40d22612c588dff48