Markdown

AI translation for Markdown files with Lingo.dev CLI

What is Markdown?

Markdown is a lightweight markup language that uses plain text formatting syntax to create structured documents. It's widely used for documentation, README files, blogs, and content management systems.

For example:

---
title: "Product Launch Guide"
description: "Everything you need to know about our latest product features"
author: "Product Team"
---

# Welcome to Our New Dashboard

Discover powerful new features designed to streamline your workflow and boost productivity.

## Getting Started

Follow these simple steps to set up your account and begin using our platform effectively.

![Dashboard overview screenshot](image.jpg)

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 Markdown 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 Markdown 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.md).

Step 5. Create a bucket

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

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

  2. In the "markdown" 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": {
    "markdown": {
      "include": ["./[locale]/example.md"]
    }
  }
}

    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.md")
    • can use asterisks as wildcard placeholders (e.g., "[locale]/*.md")

    Recursive glob patterns (e.g., **/*.md) 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.md

---
title: "Product Launch Guide"
description: "Everything you need to know about our latest product features"
author: "Product Team"
date: 2024-01-15
tags: ["apples", "bananas", "pears"]
---

# Welcome to Our New Dashboard

Discover powerful new features designed to streamline your workflow and boost productivity.

## Getting Started

Follow these simple steps to set up your account and begin using our platform effectively.

---

Our advanced analytics help you make data-driven decisions with confidence.

![Dashboard overview screenshot](image.jpg)

The intuitive interface makes it easy to navigate between different features and tools.

[View documentation](https://example.com)

Need help getting started? Our support team is available 24/7 to assist you.

***

Join thousands of satisfied customers who have transformed their business with our platform.

es/example.md

---
title: Guía de lanzamiento de producto
description: Todo lo que necesitas saber sobre las últimas características de
  nuestro producto
author: Equipo de producto
date: 2024-01-15
tags:
  - apples
  - bananas
  - pears
---

# Bienvenido a nuestro nuevo panel de control

Descubre nuevas y potentes funciones diseñadas para optimizar tus flujos de trabajo y aumentar la productividad.

## Primeros pasos

Sigue estos sencillos pasos para configurar tu cuenta y comenzar a utilizar nuestra plataforma de manera efectiva.

---

Nuestros análisis avanzados te ayudan a tomar decisiones basadas en datos con confianza.

![Captura de pantalla de la visión general del panel](image.jpg)

La interfaz intuitiva facilita la navegación entre diferentes funciones y herramientas.

[Ver documentación](https://example.com)

¿Necesitas ayuda para empezar? Nuestro equipo de soporte está disponible 24/7 para asistirte.

---

Únete a miles de clientes satisfechos que han transformado su negocio con nuestra plataforma.

i18n.json

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

i18n.lock

version: 1
checksums:
  eed9ef23a605b747d38b8916cee1d500:
    md-section-0: d53f61b8c8922fb62d9df5678d9b44a8
    md-section-1: 98aec271471bedce0e12b530c7060827
    md-section-2: 9e5a786192608844493dfbb6e4100886
    md-section-3: 1a5299c38bb20c1b8af0e64e33d7b2b0
    md-section-4: 51adf33450cab2ef392e93147386647c
    md-section-5: e56cc804e3e06b5f5fb2484e88c18adc
    md-section-6: 0ea86a3338305070c865e8fe138da890
    md-section-7: bbabf7f391569a72099001e3d81eb251
    md-section-8: 36cbfd93f42528edce4faac2ac3c2c12
    md-section-9: a1c50054ab23d70be8d453789b214580
    md-section-10: 51adf33450cab2ef392e93147386647c
    md-section-11: cb596c9608828f7b87a0ab8fa37beb07
    fm-attr-title: f3469c4e3d3377c39a705c844930b3a5
    fm-attr-description: 2e988d98001e44997a3f5fa3fb487ca6
    fm-attr-author: ec8c8711fce61265a4fe296ce2ba3b6f
    fm-attr-tags: 313ac6f17ee08e4f4a6a2ca95e5ae024