Markdoc

Lingo.dev CLIによるMarkdocファイルのAI翻訳

Markdocとは？

Markdocはカスタムドキュメンテーションサイトを作成するためのMarkdownベースの構文とツールチェーンです。カスタムタグ、変数、属性を使用してMarkdownを拡張し、豊かでインタラクティブなコンテンツを作成します。

例えば：


---

title: Markdocの紹介
description: Markdocの機能と構文の包括的なデモンストレーション

---

# Markdocの紹介

この**Markdocデモンストレーション**ドキュメントへようこそ。

{% callout type="note" %}
これはMarkdocの機能を示すサンプルドキュメントです。
{% /callout %}

## 基本的な書式

- 通常のテキスト
- *イタリック体のテキスト*
- **太字のテキスト**

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. ソースコンテンツを作成する

まだ作成していない場合は、翻訳するコンテンツを含む1つ以上のMarkdocファイルを作成します。これらのファイルは、パスのどこかにソースロケールを含むパスに配置する必要があります（例：ディレクトリ名としてen/や、ファイル名の一部としてmessages.en.markdocなど）。

ステップ 5. バケットを作成する

  1. i18n.jsonファイルのbucketsオブジェクトに"markdoc"オブジェクトを追加します：

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

  2. "markdoc"オブジェクト内で、1つ以上の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"）

    再帰的なグロブパターン（例：**/*.markdoc）はサポートされていません。

ステップ 6. LLMを設定する

Lingo.dev CLIは、AIでコンテンツを翻訳するために大規模言語モデル（LLM）を使用します。これらのモデルを使用するには、サポートされているプロバイダーからAPIキーが必要です。

可能な限り早く開始するために、毎月10,000トークンの無料使用量を提供する独自のホスティングプラットフォームであるLingo.dev Engineの使用をお勧めします：

  1. Lingo.devアカウントにサインアップする。

  2. 次のコマンドを実行します：

    npx lingo.dev@latest login

    これによりデフォルトのブラウザが開き、認証を求められます。

  3. 画面の指示に従ってください。

ステップ 7. 翻訳を生成する

i18n.jsonファイルが含まれているディレクトリで、次のコマンドを実行します：

npx lingo.dev@latest run

このコマンドは以下を実行します：

  1. i18n.jsonファイルを読み込みます。
  2. 翻訳が必要なファイルを見つけます。
  3. ファイルから翻訳可能なコンテンツを抽出します。
  4. 設定されたLLMを使用して抽出されたコンテンツを翻訳します。
  5. 翻訳されたコンテンツをファイルシステムに書き戻します。

翻訳が初めて生成されるとき、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: 1bd4ec30282cfc0bdf7d5f3559790a1c
    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