CLI는 6가지 파일 형식을 번역합니다. 형식은 파일 확장자를 기준으로 추론되며, 재정의하려면 files[] 항목에서 format을 설정하세요.
| 형식 | 확장자 | format 값 | 비고 |
|---|---|---|---|
| JSON | .json | json | 키/값 형식. key controls를 지원합니다. |
| JSONC | .jsonc | jsonc | 주석이 있는 JSON. 주석은 유지되며 translator notes로도 활용됩니다. |
| Markdown | .md | md | 본문은 번역되며, frontmatter는 옵트인 방식입니다. |
| MDX | .mdx | mdx | Markdown + JSX. 컴포넌트 props는 옵트인 방식입니다. |
| Markdoc | .mdoc | markdoc | Markdown + 태그. frontmatter와 태그 속성을 지원합니다. |
| OpenAPI YAML | .yaml | yaml-openapi | OpenAPI 스펙. 항상 format을 명시적으로 설정하세요. |
처음부터 끝까지 살펴보기
demo project에는 각 형식별로 필요한 설정이 정확히 적용된 파일이 하나씩 들어 있습니다. npx degit lingodotdev/lingo.dev/demo/new-cli my-lingo-demo로 클론한 뒤 push를 실행해 보세요.
npx degit lingodotdev/lingo.dev/demo/new-cli my-lingo-demo
cd my-lingo-demoJSON 및 JSONC#
기본적인 키/값 번역 방식입니다. key control로 따로 지정하지 않는 한 모든 문자열 값이 번역됩니다.
{ "pattern": "content/en/app.json", "lockedKeys": ["meta.version"] }JSONC는 주석도 함께 보존하며, 엔진은 이를 컨텍스트로 활용합니다. 자세한 내용은 translator notes를 참고하세요.
{ "pattern": "content/en/settings.jsonc", "preservedKeys": ["featureFlags"] }Markdown, MDX 및 Markdoc#
본문은 기본적으로 번역됩니다. frontmatter와 임베드된 컴포넌트는 별도로 옵트인하지 않으면 번역되지 않습니다.
Frontmatter#
번역할 frontmatter 필드는 translateFrontmatterFields에 나열하세요:
{
"pattern": "content/en/guide.md",
"translateFrontmatterFields": ["title", "description"]
}MDX 컴포넌트 props#
MDX에서는 translateComponentProps을 사용해 특정 컴포넌트의 특정 props만 번역할 수 있습니다:
{
"pattern": "content/en/landing.mdx",
"translateFrontmatterFields": ["title"],
"translateComponentProps": [{ "component": ["Hero", "Callout"], "props": ["title", "body"] }]
}이 설정을 적용하면 <Hero>와 <Callout>의 title, body props만 번역되고, 나머지 props는 그대로 유지됩니다.
Markdoc#
Markdoc는 Markdown과 비슷하게 동작하며, frontmatter와 태그 속성은 그대로 유지됩니다:
{
"pattern": "content/en/changelog.mdoc",
"translateFrontmatterFields": ["title"]
}OpenAPI YAML#
일반적인 YAML은 의미가 모호할 수 있으므로, OpenAPI 스펙에서는 format을 명시적으로 지정해야 합니다:
{ "pattern": "content/en/api.yaml", "format": "yaml-openapi" }엔진은 사용자에게 보이는 필드(요약, 설명)는 번역하고, 스키마 키, 경로, operation ID는 그대로 유지합니다.
출력 경로#
대상 파일은 소스 패턴의 로캘 세그먼트를 치환해 생성됩니다 — content/en/app.json → content/de/app.json. CLI가 대상 파일의 위치를 파악할 수 있도록 경로에는 소스 로캘을 유지하세요. 자세한 내용은 Configuration을 참고하세요.
레거시 CLI를 사용해 오셨나요?#
레거시 CLI는 약 25가지 형식(CSV, PO, XLIFF, Android/Xcode 문자열, Flutter ARB, HTML 등)을 지원했습니다. 이들 형식에 대한 지원은 사용량에 따라 현재 CLI에도 순차적으로 추가되고 있습니다. 필요한 형식이 아직 지원되지 않는다면, 그전까지는 legacy CLI docs를 참고하세요.
