Lingo.dev CLI는 리포지토리의 정적 파일(Markdown, MDX, Markdoc, JSON, YAML, 자막 등)을 구성된 로컬라이제이션 엔진을 통해 번역합니다. 콘텐츠 경로만 지정해 한 번 실행하면, 원본 파일과 나란히 번역된 파일이 생성됩니다.
지원 콘텐츠 유형#
| 콘텐츠 유형 | 형식 | CLI 버킷 | 예시 경로 |
|---|---|---|---|
| 문서 | Markdown | markdown | docs/[locale]/getting-started.md |
| 문서 | MDX | mdx | docs/[locale]/getting-started.mdx |
| 문서 | Markdoc | markdoc | docs/[locale]/getting-started.mdoc |
| 구조화된 데이터 | JSON | json | data/[locale].json |
| 구조화된 데이터 | YAML | yaml | data/[locale].yaml |
| 블로그 포스트 | Markdown / MDX | markdown / mdx | blog/[locale]/post-slug.md |
| 자막 | SRT | srt | subs/[locale]/intro.srt |
| 자막 | VTT | vtt | subs/[locale]/intro.vtt |
| 스프레드시트 | CSV | csv-per-locale | data/[locale].csv |
| 설정 문자열 | Properties | properties | lang/[locale].properties |
| 설정 문자열 | Gettext PO | po | locale/[locale]/messages.po |
| 일반 텍스트 | TXT | txt | content/[locale]/readme.txt |
사전 준비#
CLI를 실행할 때마다 콘텐츠는 로컬라이제이션 엔진을 거쳐 처리됩니다. 이 구성에는 어떤 LLM 모델, 용어집, 브랜드 보이스, 지침을 적용할지가 담깁니다. Lingo.dev 대시보드에서 엔진을 만들고 API 키를 생성하세요.
문서 사이트#
대부분의 문서 프레임워크는 번역된 콘텐츠를 로캘별 디렉터리로 구성합니다. CLI의 markdown, mdx, markdoc 버킷은 frontmatter, 코드 블록, 컴포넌트 문법을 그대로 유지하면서 이러한 파일을 번역합니다.
{
"$schema": "https://lingo.dev/schema/i18n.json",
"version": "1.15",
"locale": {
"source": "en",
"targets": ["es", "fr", "de", "ja"]
},
"buckets": {
"markdown": {
"include": ["docs/[locale]/getting-started.md"]
},
"mdx": {
"include": ["docs/[locale]/setup.mdx"]
}
}
}사용 중인 프레임워크의 디렉터리 규칙에 맞게 include 패턴을 조정하세요:
| 프레임워크 | 로캘 디렉터리 규칙 | 참고 자료 |
|---|---|---|
| Docusaurus | i18n/[locale]/docusaurus-plugin-content-docs/current/ | Docusaurus i18n 가이드 |
| Nextra | 로캘별 페이지 또는 JSON 딕셔너리 | Nextra 문서 |
| Hugo | content/[locale]/ | Hugo 다국어 가이드 |
| Astro | src/content/[locale]/ 또는 JSON 딕셔너리 | Astro i18n 가이드 |
| VitePress | [locale]/ 디렉터리 접두사 | VitePress i18n |
| MkDocs | i18n 플러그인과 함께 사용하는 로캘별 docs/ | MkDocs i18n 플러그인 |
MDX 컴포넌트
mdx 버킷은 번역 중에도 JSX 컴포넌트 문법을 그대로 보존합니다. <Callout>, <Tabs>, <CodeBlock> 같은 커스텀 컴포넌트는 변경 없이 통과하고, 내부의 텍스트 콘텐츠만 번역됩니다.
구조화된 데이터#
JSON 및 YAML 파일은 json 및 yaml 버킷으로 번역할 수 있습니다. 번역 대상이 아닌 값(ID, URL, 설정 플래그)이 수정되지 않도록 locked keys를 사용하세요.
{
"$schema": "https://lingo.dev/schema/i18n.json",
"version": "1.15",
"locale": {
"source": "en",
"targets": ["es", "fr", "de", "ja"]
},
"buckets": {
"json": {
"include": ["content/[locale].json"],
"lockedKeys": ["id", "slug", "url"]
},
"yaml": {
"include": ["data/[locale].yaml"]
}
}
}로캘 코드를 루트 키로 사용하는 YAML 파일(Rails와 Hugo에서 흔한 방식)에는 대신 yaml-root-key 버킷을 사용하세요. 이 버킷은 소스 로캘 키에서 값을 읽고, 같은 파일 안의 대상 로캘 키에 기록합니다.
자막#
SRT 및 VTT 자막 파일은 srt 및 vtt 버킷으로 번역할 수 있습니다. CLI는 모든 타이밍 데이터, 큐 인덱스, 서식 태그를 그대로 유지하고 텍스트 콘텐츠만 번역합니다.
{
"$schema": "https://lingo.dev/schema/i18n.json",
"version": "1.15",
"locale": {
"source": "en",
"targets": ["es", "fr", "de", "ja"]
},
"buckets": {
"srt": {
"include": ["subs/[locale]/intro.srt"]
}
}
}대규모 콘텐츠 다루기#
정적 콘텐츠 리포지토리에는 수천 개의 파일이 들어 있을 수 있습니다. CLI는 다음 세 가지 메커니즘으로 이를 효율적으로 처리합니다.
| 메커니즘 | 도움이 되는 방식 |
|---|---|
| Lockfile | 소스 콘텐츠의 SHA-256 지문을 추적합니다. 이후 실행에서는 새 파일이나 변경된 파일에만 번역이 수행됩니다. |
| 병렬 처리 | 번역 작업을 여러 동시 워커에 분산합니다. run --concurrency 20로 설정할 수 있습니다. |
| 대상 지정 실행 | 특정 버킷 또는 로캘만 처리할 수 있습니다: run --bucket markdown 또는 run --target-locale es. |
