정적 콘텐츠 로컬라이제이션

Lingo.dev CLI는 리포지토리의 정적 파일(Markdown, MDX, Markdoc, JSON, YAML, 자막 등)을 구성된 로컬라이제이션 엔진을 통해 번역합니다. 콘텐츠 경로만 지정해 한 번 실행하면, 원본 파일과 나란히 번역된 파일이 생성됩니다.

지원 콘텐츠 유형#

CLI는 파일 확장자를 기준으로 각 파일 형식을 자동으로 감지하므로 bucket type을 따로 설정할 필요가 없습니다. 로캘은 경로에 포함되므로(content/en/x.md가 content/de/x.md로 바뀜) [locale] 플레이스홀더도 필요하지 않습니다.

지원되는 전체 파일 형식 목록은 formats 레퍼런스에서 확인하세요.

사전 준비#

실행할 때마다 콘텐츠는 로컬라이제이션 엔진을 거칩니다. 이 설정에 따라 어떤 LLM 모델, 용어집, 브랜드 보이스, 규칙이 적용될지가 결정됩니다. 먼저 Lingo.dev 대시보드에서 엔진을 만든 다음, CLI(Node 22+)를 설정하세요:

npm install -g @lingo.dev/cli
lingo login
lingo init
lingo link

lingo init 및 lingo link를 실행하면 .lingo/config.json가 생성되어 CLI가 조직과 엔진에 연결됩니다. 모든 환경에서 동일한 구성을 공유할 수 있도록 이 파일은 커밋해 두세요.

{
  "orgId": "org_abc123",
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de", "ja"],
  "files": [{ "pattern": "docs/en/getting-started.md" }]
}

CI에서는 lingo login를 건너뛰고, 대신 LINGO_API_KEY를 환경 변수로 제공하세요. 이 값은 API keys에서 생성할 수 있습니다.

문서 사이트#

대부분의 문서 프레임워크는 번역된 콘텐츠를 로캘별 디렉터리로 구성합니다. 소스 파일마다 패턴(또는 glob)을 files에 추가하세요. CLI는 Markdown, MDX, Markdoc를 번역하면서 frontmatter, 코드 블록, 컴포넌트 문법은 그대로 유지합니다.

{
  "orgId": "org_abc123",
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de", "ja"],
  "files": [
    { "pattern": "docs/en/getting-started.md" },
    { "pattern": "docs/en/setup.mdx" }
  ]
}

첫 번역을 실행해 모든 대상 로캘을 한 번에 채우세요:

lingo push --backfill-missing

이후 실행에서는 lingo push가 변경된 내용만 번역합니다. 다른 곳에서 생성된 번역을 가져오려면 lingo pull를 사용하세요.

사용 중인 프레임워크의 디렉터리 규칙에 맞게 소스 경로를 조정하세요:

구조화된 데이터#

JSON과 YAML 파일은 확장자를 기준으로 자동 번역됩니다. 번역하면 안 되는 값(ID, URL, 구성 플래그)이 수정되지 않도록 key controls를 활용하세요.

{
  "orgId": "org_abc123",
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de", "ja"],
  "files": [
    { "pattern": "content/en.json" },
    { "pattern": "data/en.yaml" }
  ]
}

Generic YAML에는 format 필드가 필요하지 않습니다. yaml-openapi, yaml-root-key, android만 파일 항목에 "format"을(를) 명시해야 합니다.

자막#

SRT 자막 파일은 확장자를 기준으로 번역됩니다. CLI는 모든 타이밍 데이터, 큐 인덱스, 서식 태그를 그대로 보존하고 텍스트 콘텐츠만 번역합니다.

{
  "orgId": "org_abc123",
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de", "ja"],
  "files": [{ "pattern": "subs/en/intro.srt" }]
}

대규모 콘텐츠 다루기#

정적 콘텐츠 리포지토리에는 수천 개의 파일이 들어 있을 수 있습니다. CLI는 이런 규모도 효율적으로 처리합니다:

파일을 쓰지 않고 번역이 최신 상태인지 확인하려면(CI 게이트로 활용하기 좋습니다) lingo check를 실행하세요.

다음 단계#