MDX

Traducción con IA para archivos MDX con Lingo.dev CLI

¿Qué es MDX?

MDX es un formato que combina Markdown con JSX, permitiéndote usar componentes de React directamente en tu contenido Markdown. Se utiliza comúnmente para sitios de documentación y aplicaciones web con contenido enriquecido.

Por ejemplo:


---

title: "Reseña de restaurante: Bella Vista"
description: "Nuestra experiencia gastronómica en el nuevo restaurante italiano del centro"
author: "not-localized-author"

---

# Cena en Bella Vista

Finalmente probamos el nuevo restaurante italiano que abrió el mes pasado en la Calle Principal.

## El ambiente

El restaurante tiene un ambiente cálido y acogedor con:

- **Iluminación tenue** que crea un entorno íntimo
- *Música suave de jazz* sonando de fondo

¿Qué es Lingo.dev CLI?

Lingo.dev CLI es una CLI gratuita y de código abierto para traducir aplicaciones y contenido con IA. Está diseñada para reemplazar el software tradicional de gestión de traducciones mientras se integra con los flujos de trabajo existentes.

Para obtener más información, consulta Descripción general.

Acerca de esta guía

Esta guía explica cómo traducir archivos MDX con Lingo.dev CLI.

Aprenderás a:

  • Crear un proyecto desde cero
  • Configurar un flujo de trabajo de traducción
  • Generar traducciones con IA

Requisitos previos

Para usar Lingo.dev CLI, asegúrate de tener instalado Node.js v18+:

❯ node -v
v22.17.0

Paso 1. Configurar un proyecto

En el directorio de tu proyecto, crea un archivo i18n.json:

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

Este archivo define el comportamiento del flujo de trabajo de traducción, incluyendo entre qué idiomas traducir y dónde existe el contenido localizable en el sistema de archivos.

Para obtener más información sobre las propiedades disponibles, consulta i18n.json.

Paso 2. Configurar el idioma de origen

El idioma de origen es el idioma y región original en el que se escribió tu contenido. Para configurar el idioma de origen, establece la propiedad locale.source en el archivo i18n.json:

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

El idioma de origen debe proporcionarse como una etiqueta de idioma BCP 47.

Para obtener la lista completa de los códigos de idioma que Lingo.dev CLI admite, consulta Códigos de idioma admitidos.

Paso 3. Configurar los idiomas de destino

Los idiomas de destino son los idiomas y regiones a los que quieres traducir tu contenido. Para configurar los idiomas de destino, establece la propiedad locale.targets en el archivo i18n.json:

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

Paso 4. Crear el contenido de origen

Si aún no lo has hecho, crea uno o más archivos MDX que contengan el contenido a traducir. Estos archivos deben estar ubicados en una ruta que incluya el idioma de origen en alguna parte de la ruta (por ejemplo, como un nombre de directorio como en/ o como parte del nombre del archivo como messages.en.mdx).

Paso 5. Crear un bucket

  1. En el archivo i18n.json, añade un objeto "mdx" al objeto buckets:

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

  2. En el objeto "mdx", define un array de uno o más patrones include:

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

    Estos patrones definen qué archivos traducir.

    Los patrones en sí:

    • deben contener [locale] como marcador de posición para el idioma configurado
    • pueden apuntar a rutas de archivo (por ejemplo, "[locale]/blog.mdx")
    • pueden usar asteriscos como marcadores de posición comodín (por ejemplo, "[locale]/*.mdx")

    Los patrones glob recursivos (por ejemplo, **/*.mdx) no son compatibles.

Paso 6. Configurar un LLM

Lingo.dev CLI utiliza modelos de lenguaje de gran tamaño (LLMs) para traducir contenido con IA. Para usar uno de estos modelos, necesitas una clave API de un proveedor compatible.

Para comenzar lo más rápido posible, recomendamos usar Lingo.dev Engine — nuestra propia plataforma alojada que ofrece 10,000 tokens de uso mensual gratuito:

  1. Regístrate para obtener una cuenta de Lingo.dev.

  2. Ejecuta el siguiente comando:

    npx lingo.dev@latest login

    Esto abrirá tu navegador predeterminado y te pedirá que te autentiques.

  3. Sigue las instrucciones.

Paso 7. Generar las traducciones

En el directorio que contiene el archivo i18n.json, ejecuta el siguiente comando:

npx lingo.dev@latest run

Este comando:

  1. Lee el archivo i18n.json.
  2. Encuentra los archivos que necesitan ser traducidos.
  3. Extrae el contenido traducible de los archivos.
  4. Utiliza el LLM configurado para traducir el contenido extraído.
  5. Escribe el contenido traducido de vuelta al sistema de archivos.

La primera vez que se generan traducciones, se crea un archivo i18n.lock. Este archivo realiza un seguimiento del contenido que ha sido traducido, evitando retraducciones innecesarias en ejecuciones posteriores.

Ejemplo

en/example.mdx


---

title: "Reseña de restaurante: Bella Vista"
description: "Nuestra experiencia gastronómica en el nuevo restaurante italiano del centro"
author: "not-localized-author"
published: "2024-03-15"
rating: 4.5
locked_key_1: "This value should remain unchanged in all locales"
ignored_key_1: "This field should not appear in target locales"

---

# Cena en Bella Vista

Finalmente probamos el nuevo restaurante italiano que abrió el mes pasado en la Calle Principal. Aquí está nuestra reseña honesta.

## La atmósfera

El restaurante tiene una atmósfera cálida y acogedora con:

- **Iluminación tenue** que crea un ambiente íntimo
- *Música suave de jazz* sonando de fondo
- Flores frescas en cada mesa

es/example.mdx


---

title: "Reseña de Restaurante: Bella Vista"
description: "Nuestra experiencia gastronómica en el nuevo restaurante italiano del centro"
author: "not-localized-author"
published: "2024-03-15"
rating: 4.5
locked_key_1: "This value should remain unchanged in all locales"

---

# Cena en Bella Vista

Finalmente probamos el nuevo restaurante italiano que abrió el mes pasado en Main Street. Esta es nuestra reseña honesta.

## El Ambiente

El restaurante tiene un ambiente cálido y acogedor con:

- **Iluminación tenue** que crea un ambiente íntimo
- *Música de jazz suave* sonando de fondo
- Flores frescas en cada mesa

i18n.json

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

i18n.lock

version: 1
checksums:
  0d5b5aa6d2b9937d47fd63868ef9e9f6:
    meta/title: a4bdd0dee24f8318f3300dcae130a353
    meta/description: 609213841f122e494f62262618ee4761
    meta/author: f3f7164b5963b4da6cd31a2ec0251630
    content/0: 8a8520492d23503da5691602e60bd22a
    content/1: 1fc859854cda505b2a94a04c8b09ab43
    content/2: 8add667f2a1d5d791a64b50bde54fa59
    content/3: e6e34c4c92eda512ec209266abe8e074
    content/4: 07f1896ad050b9606d7674f70d847818
    content/5: bd4d40a4f0cc92ac8a880c8d9ce8b43d
    content/6: 3036a07a887121ea080427d84fc80912
    content/7: f555318416c5c5388c1d961ef02f5955
    content/8: 90e02688ab103de60e42c70ece7efc4d
    content/9: 8c5be3cd002a3a194c991821e0182e08
    content/10: 3495801a7461ac5ea8d78369873a5409
    content/11: d444739ce3d48afb7976067c67149a9e
    content/12: 5f02c0a3b6385f80bdd08cf7e2d8c04d
    content/13: 0a15fd446b87d907f58c303aece0882b
    content/14: 778ed0aa1f81768280a23afe559c55f7
    content/15: fa244af2d8e558d6c3644ff8c1a64562
    content/16: 14f593e7cf3b3df84a21e17db318912e
    content/17: 5f42d26a42aa29be063019eea27ad07c
    content/18: 48bb7e89e72d68d6de12f5cdac64fc18
    content/19: 1639b9ef57bf363e04293e27d1c13952
    content/20: bb1c8d22064f7af4879c69d444e6e769
    content/21: 52f9d6beaa85591f77811e1162d756c4