Markdoc - Lingo.dev CLI

Markdoc이란?

Markdoc은 맞춤형 문서 사이트를 만들기 위한 Markdown 기반 구문 및 도구 체인입니다. 사용자 정의 태그, 변수, 속성으로 Markdown을 확장하여 풍부하고 인터랙티브한 콘텐츠를 생성합니다.

예시:

---
title: Introduction to Markdoc
description: A comprehensive demonstration of Markdoc features and syntax
---

# Introduction to Markdoc

Welcome to this **Markdoc demonstration** document.

{% callout type="note" %}
This is a sample document demonstrating Markdoc capabilities.
{% /callout %}

## Basic Formatting

- Regular text
- *Italic text*
- **Bold text**

Lingo.dev CLI란?

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

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

이 가이드에 대하여

이 가이드는 Lingo.dev CLI로 Markdoc 파일을 번역하는 방법을 설명합니다.

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

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

아직 생성하지 않았다면, 번역할 콘텐츠가 포함된 하나 이상의 Markdoc 파일을 생성하세요. 이러한 파일은 경로 어딘가에 소스 로케일이 포함된 위치에 있어야 합니다(예: en/와 같은 디렉토리 이름 또는 messages.en.markdoc와 같은 파일명의 일부).

5단계. 버킷 생성하기

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

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

"markdoc" 객체에서 하나 이상의 include 패턴 배열을 정의하세요:
```
{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "markdoc": {
      "include": ["./[locale]/example.markdoc"]
    }
  }
}
```
이러한 패턴은 번역할 파일을 정의합니다.

패턴 자체는:
- 구성된 로케일의 플레이스홀더로 [locale]를 포함해야 합니다
- 파일 경로를 가리킬 수 있습니다(예: "[locale]/docs.markdoc")
- 와일드카드 플레이스홀더로 별표를 사용할 수 있습니다(예: "[locale]/*.markdoc")
재귀적 glob 패턴(예: **/*.markdoc)은 지원되지 않습니다.

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 파일이 생성됩니다. 이 파일은 어떤 콘텐츠가 번역되었는지 추적하여 후속 실행 시 불필요한 재번역을 방지합니다.

예제

en/example.markdoc

---
title: Introduction to Markdoc
description: A comprehensive demonstration of Markdoc features and syntax
author: Documentation Team
version: 1.0
---

# Introduction to Markdoc

Welcome to this **Markdoc demonstration** document. This file showcases various Markdoc features and syntax.

{% callout type="note" %}
This is a sample document demonstrating Markdoc capabilities.
{% /callout %}

## Basic Formatting

Markdoc supports standard Markdown features:

1. Ordered lists
2. Unordered lists
3. Text formatting like *italics* and **bold**

es/example.markdoc

---
title: Introducción a Markdoc
description: Una demostración completa de las características y sintaxis de Markdoc
author: Equipo de Documentación
version: 1.0
---

# Introducción a Markdoc

Bienvenido a este documento de **demostración de Markdoc**. Este archivo muestra varias características y sintaxis de Markdoc.

{% callout type="note" %}
Este es un documento de muestra que demuestra las capacidades de Markdoc.
{% /callout %}

## Formato Básico

Markdoc admite características estándar de Markdown:

1. Listas ordenadas
2. Listas desordenadas
3. Formato de texto como *cursiva* y **negrita**

i18n.json

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

i18n.lock

version: 1
checksums:
  829674e11a9003549b66978e9b9c259a:
    heading-0: e19079d431e6b75a7d74e9c35639ea5a
    paragraph-0: 6757b797fc6d8c5ec5628f2619274e28
    paragraph-1: cc37b30c1aca11f64dc096264761368e
    paragraph-2: 50e2b92b9e711ae7758f8edcc1767102
    paragraph-3: 7bc573b304cf3a3414dd60f85eea4e36
    heading-1: 80779abd23399c676227609057093235
    paragraph-4: dfd87f4dde3d3e12fa6781966432465f
    item-0: ad9b7460be42c194e4771cf5281d5fd0
    item-1: 7d67473952061a571de034013964c5b6
    item-2: 91cffca4db2b901a3a0310ca2ab17ed9
    item-3: 56b97b82cc030c511847d1850af088a0
    item-4: 05dc0a811ee5b04941c826293471367d
    item-5: b1701133f7e62467e354a5fc526ea951
    heading-2: ff6e4ea57280ef5a42ebbe2cf9e3273b
    paragraph-5: 3e11ad608af106c15eed82d0e5d07712
    item-6: 2b1ab56131399aab1842fc3a81dd170e
    item-7: 8aedf70e351d5e5bb41ad66ad5ad18d8
    item-8: 1d0eccad0413a69da0d45c481aa754e9
    paragraph-6: e2a208aa62fd61821848519fa2abc211
    heading-3: 2761eb3f80a7da53d2cd899f33641e98
    paragraph-7: f341db1f3167bd074937f4399c3a1158
    th-0: 58f5f3f37862b6312a2f20ec1a1fd0e8
    th-1: e17686a22ffad04cc7bb70524ed4478b
    td-0: 97813c8ae67d69575fd04e35a88aed0c
    td-1: 117451569b718867c43b26d9ee3c4e8f
    td-2: e801c1eaca53c3aa702b747ed750fdd1
    td-3: ffd3eec5497af36d7b4e4185bad1313a
    td-4: 03d20ebc4966301ceba02199a24e02dc
    td-5: 86d0ae6fea0fbb119722ed3841f8385a
    td-6: 6d26991f040628f6002efa192bebb9c2
    heading-4: c8b45e4d54115ec279a2a6bde4b8a725
    paragraph-8: 933c68ed0598328263d1146641d0ab2c
    fence-0: ffdb698812040ead47e2039dfa22d9d7
    paragraph-9: fe471cd364c38cc79a7638b4a5ffb528
    heading-5: 4cbc75f1ae6830a190eb70628c4e4b54
    paragraph-10: bc6097c6af86133a3972bdb7a5343dd2
    fence-1: 31a1aab989ce9935c98e672182bffbbe
    heading-6: fe53e9de958685ab7c70d0a973c0a146
    paragraph-11: 69f77475eb830f1aa357f45db29f809e
    item-9: 90f2650aad06503472c46ce2612b9bc8
    item-10: a392737d0507463d40d1a8ff7502607c
    item-11: 7ed6e23ffae34636a417daf72b3a5b6b
    item-12: 0f93e7285aafb5c9929b29973f047026
    item-13: 9dacb7c56bc894e4bcad39f41265e3a0
    item-14: 496e1d7de5d7ff53f1af813a2ba46d7f
    item-15: 1bd4ec30282cfc0bdf7d5f3559990a1c
    item-16: 46c9eec1392a8d9f33170569e342bf7b
    heading-7: aa8d69ad456402762aeb915a67cfa698
    paragraph-12: 275eb44389d498dab93e38ed2889e5d9
    paragraph-13: f05f450fffcb17520c441ab9789f40ce
    paragraph-14: 915fe5ce4ded772d7844df222ebd9d3e
    paragraph-15: 3fae115ccac303b7cd908b49b8509217
    heading-8: 2fdf7c243436eba4bd1fe5ebd605ab96
    paragraph-16: fc0f77d45ad1e1764d2793706eb8a049
    paragraph-17: 6b4340d30988a714d34f0df9b3e18889
    paragraph-18: a59d117938ed65f303209da2b23ad35a
    paragraph-19: 28e8b27fb60b305a9caac04d8a92a038
    tagName-0: 0421db688c4d19bb542014733d553a43
    paragraph-20: 83951ea4c30a9b5057ff046e3a0bfc07
    paragraph-21: 8d2152d9e84fff4b3cd98d1fb305be8f
    heading-9: 6fe6489310962f6bc8ad13279106568b
    item-17: 0539fa4e65545d8a334abf6e0aee57ab
    item-18: a41ccc6f28eec377fb19a95b0b6db7a8
    item-19: 45aa24cef8a5d9b037d898917a862563
    paragraph-22: 59bf7b09d603b846c2cdd63cd878f20a
    paragraph-23: 9e30a94d9122095ac52a52ed2a864a26
    paragraph-24: 3b28910e425d79f9fd23ada6d6f33bff
    paragraph-25: 05d9c0fe6c099b1e20ebdb2320a28257
    paragraph-26: 04e7322f2d3ffb2d73ff2f64b71637c8
    paragraph-27: 65ef9814c2d07fd3d54d9f7bee1bba6c
    badge-0: c2d5d8760d96802e1b9a7bac290b1cfc
    paragraph-28: df1f854bcdb047d98a68cd39704a8981
    fm-attr-title: e19079d431e6b75a7d74e9c35639ea5a
    fm-attr-description: 82574f93a40b35a16a4c9fc5c2ab58cf
    fm-attr-author: a51ec27845d1fc7cf13c810f0e2d42ab