Markdoc

AI translation for Markdoc files with Lingo.dev CLI

What is Markdoc?

Markdoc is a Markdown-based syntax and toolchain for creating custom documentation sites. It extends Markdown with custom tags, variables, and attributes to create rich, interactive content.

For example:

---
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**

What is Lingo.dev CLI?

Lingo.dev CLI is a free, open-source CLI for translating apps and content with AI. It's designed to replace traditional translation management software while integrating with existing pipelines.

To learn more, see Overview.

About this guide

This guide explains how to translate Markdoc files with Lingo.dev CLI.

You'll learn how to:

  • Create a project from scratch
  • Configure a translation pipeline
  • Generate translations with AI

Prerequisites

To use Lingo.dev CLI, ensure that Node.js v18+ is installed:

❯ node -v
v22.17.0

Step 1. Set up a project

In your project's directory, create an i18n.json file:

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

This file defines the behavior of the translation pipeline, including what languages to translate between and where the localizable content exists on the file system.

To learn more about the available properties, see i18n.json.

Step 2. Configure the source locale

The source locale is the original language and region that your content was written in. To configure the source locale, set the locale.source property in the i18n.json file:

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

The source locale must be provided as a BCP 47 language tag.

For the complete list of the locale codes that Lingo.dev CLI supports, see Supported locale codes.

Step 3. Configure the target locales

The target locales are the languages and regions you want to translate your content into. To configure the target locales, set the locale.targets property in the i18n.json file:

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

Step 4. Create the source content

If you haven't already, create one or more Markdoc files that contain the content to be translated. These files must be located at a path that includes the source locale somewhere in the path (e.g., as a directory name like en/ or as part of the filename like messages.en.markdoc).

Step 5. Create a bucket

  1. In the i18n.json file, add a "markdoc" object to the buckets object:

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

  2. In the "markdoc" object, define an array of one or more include patterns:

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

    These patterns define which files to translate.

    The patterns themselves:

    • must contain [locale] as a placeholder for the configured locale
    • can point to file paths (e.g., "[locale]/docs.markdoc")
    • can use asterisks as wildcard placeholders (e.g., "[locale]/*.markdoc")

    Recursive glob patterns (e.g., **/*.markdoc) are not supported.

Step 6. Configure an LLM

Lingo.dev CLI uses large language models (LLMs) to translate content with AI. To use one of these models, you need an API key from a supported provider.

To get up and running as quickly as possible, we recommend using Lingo.dev Engine — our own, hosted platform that offers 10,000 tokens of free, monthly usage:

  1. Sign up for a Lingo.dev account.

  2. Run the following command:

    npx lingo.dev@latest login

    This will open your default browser and ask you to authenticte.

  3. Follow the prompts.

Step 7. Generate the translations

In the directory that contains the i18n.json file, run the following command:

npx lingo.dev@latest run

This command:

  1. Reads the i18n.json file.
  2. Finds the files that need to be translated.
  3. Extracts the translatable content from the files.
  4. Uses the configured LLM to translate the extracted content.
  5. Writes the translated content back to the file system.

The first time translations are generated, an i18n.lock file is created. This file keeps track of what content has been translated, preventing unnecessary retranslations on subsequent runs.

Example

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