빠른 시작

Lingo.dev CLI의 핵심 강점은 단일 CLI 명령어를 사용하여 앱과 마크다운 콘텐츠를 대상 언어로 효율적으로 현지화하는 것입니다.

이 빠른 시작 가이드는 앱을 다국어로 만들려고 하거나 이미 2개 이상의 언어를 처리하도록 구성한 상태라고 가정합니다. 따라서 이 가이드는 10분 이내에 완료할 수 있을 만큼 간결하지만, 내부 작동 방식을 이해하기에 충분히 상세합니다.

이 가이드를 완료하면 다음과 같은 결과를 얻게 됩니다:

AI 번역 엔진을 사용하여 앱 콘텐츠를 스페인어와 일본어로 현지화합니다.
소스 파일, 대상 파일 및 구성이 어떻게 함께 작동하는지 이해합니다.
앱과 마크다운 콘텐츠를 수십 개의 언어와 수만 개의 단어로 확장할 수 있는 현지화 워크플로우를 설정합니다.

시작해 봅시다!

사전 요구 사항

마크다운

마크다운 파일은 구조화된 문서이므로 사전 설정이 필요하지 않습니다. Lingo.dev CLI는 .md 파일을 직접 처리하여 콘텐츠를 현지화하는 동안 형식을 유지하므로 1단계로 계속 진행할 수 있습니다.

애플리케이션

앱을 다국어로 만들기 위해서는 현대적인 웹 및 모바일 애플리케이션에서 개발자가 먼저 국제화(i18n) 구성을 설정해야 합니다.

이 빠른 시작에서는 Lingo.dev CLI가 애플리케이션 콘텐츠를 어떻게 현지화하는지 보여주기 위해 독립형 JSON 파일을 생성할 것입니다.

실제 애플리케이션과 통합할 때는 다음과 같은 권장 프레임워크 가이드를 따르세요:

React: react-intl
Vue: vue-i18n
Svelte: svelte-i18n
Angular: ngx-translate
iOS: Localizable.xcstrings
Android: strings.xml

1단계. 프로젝트 초기화

Lingo.dev CLI는 현지화 설정을 선언하기 위해 표준 i18n.json 구성 파일을 사용합니다. 대화형으로 생성하려면 다음을 실행하세요:

npx lingo.dev@latest init

프로젝트에 대한 질문을 하고 프로젝트 루트에 i18n.json 파일을 생성합니다.

파일은 다음과 같이 보일 것입니다:

{
  "locale": {
    "source": "en",
    "targets": ["es", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

각 구성 요소를 살펴보겠습니다:

locale.source — 팀이 작성하는 언어입니다. 이 설정은 권위 있는 콘텐츠를 포함하는 파일을 식별합니다. 모든 현지화는 소스에서 대상으로 흐릅니다.
locale.targets — 대상 시장을 나타내는 ISO 639-1 언어 코드 배열입니다. 각 코드는 별도의 파일(또는 형식에 따라 파일 내 섹션)에 해당합니다. 하나 또는 두 개의 언어로 시작하여 확장할 때 더 추가할 수 있습니다.
buckets.json.include — CLI에게 로케일 파일을 찾고 생성할 위치를 알려주는 글로브 패턴입니다. 특수 [locale] 토큰은 각 언어 코드로 확장됩니다. locales/[locale].json 패턴을 사용하면 CLI는 소스로 locales/en.json을 찾고 대상으로 locales/es.json 및 locales/ja.json을 생성합니다. 여러 패턴을 지정하고 단일 구성 내에서 형식을 혼합할 수도 있습니다.

프로젝트가 성장함에 따라 발견하게 될 고급 기능:

앱의 다양한 파일 유형이나 섹션에 대한 여러 버킷
특정 파일을 건너뛰기 위한 exclude 패턴
특정 값이 번역되지 않도록 방지하는 lockedKeys

영어 소스 파일 생성

이 빠른 시작에서는 로케일 파일을 생성하겠습니다:

mkdir -p locales
echo '{"greeting":"Hello, world!","button.submit":"Submit"}' > locales/en.json

이 명령은 locales 디렉토리와 두 개의 번역 키가 포함된 영어 소스 파일을 생성합니다. greeting과 같은 키는 평면 구조에 적합하며, button.submit과 같은 네임스페이스가 있는 키는 대규모 애플리케이션을 구성하는 데 도움이 됩니다.

중첩된 객체도 지원됩니다. 다양한 파일 형식에 대한 자세한 내용은 문서의 나머지 부분에서 확인할 수 있습니다.

2단계. 인증

Lingo.dev CLI는 로컬라이제이션을 위해 콘텐츠를 AI 번역 엔진으로 전송하므로 먼저 인증이 필요합니다.

옵션 1. 원시 LLM API 액세스

Lingo.dev CLI는 로컬라이제이션 및 번역을 위해 OpenAI 또는 Anthropic과 같은 LLM 모델을 사용하는 데 도움을 줍니다.

이는 처리된 토큰당 비용이 청구되며, 모델 선택, 시스템 프롬프트 및 모든 모델 매개변수를 제어할 수 있음을 의미합니다.

인증하려면 프로젝트 루트에 API 키가 포함된 .env 파일을 생성하세요:


# OpenAI를 사용하는 경우

OPENAI_API_KEY=sk-...

# Anthropic을 사용하는 경우

ANTHROPIC_API_KEY=sk-...

또는 .env 대신 현재 쉘 세션에서 변수를 내보낼 수 있습니다:

export ANTHROPIC_API_KEY=sk-ant-...

다른 제공업체에 대한 지원을 추가하고 싶으신가요? Lingo.dev CLI는 오픈 소스이며 기여를 환영합니다! 저장소를 포크하고 풀 리퀘스트를 제출하세요: github.com/lingodotdev/lingo.dev.

옵션 2. Lingo.dev 엔진

또는 무료 Lingo.dev 엔진 계정을 만들고 이를 AI 번역 엔진으로 사용할 수 있습니다.

이 엔진은 동적 모델 선택, 각 언어 쌍에 대한 다른 모델로의 자동 라우팅, 자동화된 모델 폴백, 이전 번역을 고려하는 번역 메모리, 프로젝트의 도메인별 용어를 위한 용어집 지원을 제공합니다. 무료 및 유료 옵션이 모두 있으며, 무료 Hobby 티어는 이 튜토리얼에 충분합니다.

인증하려면 다음을 실행하세요:

npx lingo.dev@latest login

중요 사항. Brave 브라우저를 사용하거나 브라우저 확장 프로그램이 인증 흐름을 차단하는 경우, .env 파일에 LINGODOTDEV_API_TOKEN 환경 변수를 추가하여 수동으로 인증할 수 있습니다:

LINGODOTDEV_API_TOKEN=...

Lingo.dev 엔진 프로젝트 설정에서 토큰을 찾을 수 있습니다.

3단계. AI 번역 엔진 설정

인증이 완료되었으므로 이제 사용할 AI 번역 엔진을 구성해야 합니다.

옵션 1. 원시 LLM API 액세스

OpenAI를 사용하려면 i18n.json 구성을 업데이트하여 openai 제공자를 사용하세요:

{
  "locale": {
    "source": "en",
    "targets": ["es", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  },
  "provider": {
    "id": "openai",
    "model": "gpt-4o-mini",
    "prompt": "Act as a professional software localization expert. Translate each key from {source} to {target}. Preserve ICU message format placeholders like {name} and {{count}}. Maintain Markdown formatting including links and code blocks. Match the tone and formality of the source text. Technical terms that are typically untranslated in the industry should remain in English."
  }
}

다양한 프롬프트로 실험하여 현지화 동작을 사용자 정의할 수 있지만, 이 프롬프트가 좋은 시작점이라는 것을 발견했습니다!

provider 구성은 직접적인 LLM 액세스를 제어합니다:

id — openai 또는 anthropic 중 하나
model — 사용할 특정 모델 버전. 예: gpt-4o-mini, gpt-4o (OpenAI) 또는 claude-3-haiku, claude-3-sonnet (Anthropic).
prompt — 번역 동작을 안내하는 시스템 프롬프트. {source}와 {target} 플레이스홀더는 런타임에 실제 언어 코드로 대체됩니다. 이 프롬프트는 용어, 스타일 및 도메인별 규칙을 적용할 수 있는 기회입니다.

옵션 2. Lingo.dev 엔진

Lingo.dev 엔진을 AI 번역 엔진으로 사용하는 경우 provider 노드를 완전히 생략할 수 있습니다.

엔진은 Lingo.dev 팀의 연구와 엔진 설정에 기반하여 모델과 프롬프트를 자동으로 선택합니다.

i18n.json 구성:

{
  "locale": {
    "source": "en",
    "targets": ["es", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

참고: Lingo.dev 엔진을 사용할 때는 provider 노드를 완전히 생략하세요. 엔진이 자동으로 모델과 프롬프트를 선택합니다.

4단계. 번역

앱을 현지화하려면 다음을 실행하세요:

npx lingo.dev@latest i18n

CLI는 대상 파일을 생성하고 콘텐츠 지문을 추적하는 i18n.lock 파일을 업데이트합니다. 이를 통해 후속 실행 시 증분 업데이트가 보장됩니다.

이제 앱 콘텐츠를 현지화했습니다!

다음 단계

핵심 현지화 워크플로우를 완료했습니다. 이제 저장소에는 다른 코드 아티팩트와 마찬가지로 커밋, 검토 및 배포할 수 있는 현지화된 파일이 포함되어 있습니다.

여기서 다음과 같은 작업을 수행할 수 있습니다:

워크플로우 자동화: CI/CD 통합 — CI/CD 통합을 설정하여 모든 푸시에서 현지화하고, 풀 리퀘스트나 직접 커밋을 통해 변경 사항을 자동으로 저장소에 커밋합니다;
내부 구조 이해하기: 작동 방식 — 알고리즘, 성능 최적화 및 아키텍처 결정에 대해 알아보세요.