Starlight

Traducción con IA para Starlight con Lingo.dev CLI

¿Qué es Starlight?

Starlight es un tema de documentación construido sobre el framework Astro. Proporciona navegación del sitio integrada, búsqueda, internacionalización y características SEO para crear sitios de documentación hermosos y accesibles.

¿Qué es Lingo.dev CLI?

Lingo.dev es una plataforma de traducción impulsada por IA. El CLI de Lingo.dev lee archivos fuente, envía contenido traducible a modelos de lenguaje de gran escala y escribe los archivos traducidos de vuelta a tu proyecto.

Acerca de esta guía

Esta guía explica cómo configurar Lingo.dev CLI en un sitio de documentación Starlight. Aprenderás cómo estructurar un proyecto con Starlight, configurar un pipeline de traducción y ver los resultados.

Paso 1. Configurar un proyecto Starlight

  1. Crea una nueva aplicación Starlight:

    npm create astro@latest -- --template starlight

  2. Navega al directorio del proyecto:

    cd <your-starlight-project>

Paso 2. Crear contenido fuente

  1. Crea un directorio para almacenar la documentación en el idioma de origen:

    mkdir -p src/content/docs/en

  2. Crea un archivo que contenga contenido de documentación (por ejemplo, src/content/docs/en/index.mdx):

    ---
title: "Bienvenido"
description: "Comenzando con nuestra documentación"
---

## Introducción

Esta documentación es traducida automáticamente por Lingo.dev.

## Características

Nuestro producto incluye capacidades potentes para el desarrollo moderno.

Paso 3. Configurar el CLI

En la raíz del proyecto, crea un archivo i18n.json:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": 1.8,
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "mdx": {
      "include": [
        "src/content/docs/[locale]/*.mdx",
        "src/content/docs/[locale]/*/*.mdx"
      ]
    }
  }
}

Este archivo define:

  • los archivos que Lingo.dev CLI debe traducir
  • los idiomas entre los que traducir

En este caso, la configuración traduce archivos MDX del inglés al español.

Es importante tener en cuenta que:

  • [locale] es un marcador de posición que se reemplaza en tiempo de ejecución. Asegura que el contenido se lea desde una ubicación (por ejemplo, src/content/docs/en/index.mdx) y se escriba en una ubicación diferente (por ejemplo, src/content/docs/es/index.mdx).
  • Lingo.dev CLI no admite patrones glob recursivos (por ejemplo, **/*.mdx). Necesitarás crear patrones include adicionales para traducir archivos que existen dentro de directorios anidados.

Para saber más, consulta configuración i18n.json.

Paso 4. Traducir el contenido

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

  2. Inicia sesión en Lingo.dev a través de la CLI:

    npx lingo.dev@latest login

  3. Ejecuta el proceso de traducción:

    npx lingo.dev@latest run

    La CLI creará un directorio src/content/docs/es/ para almacenar el contenido traducido y un archivo i18n.lock para realizar un seguimiento de lo que se ha traducido (para evitar retraducciones innecesarias).

Paso 5. Utilizar las traducciones

  1. En el archivo astro.config.mjs, configura los idiomas soportados:

    import { defineConfig } from "astro/config";
import starlight from "@astrojs/starlight";

export default defineConfig({
  integrations: [
    starlight({
      title: "My Docs",
      defaultLocale: "en",
      locales: {
        en: {
          label: "English",
          lang: "en",
        },
        es: {
          label: "Español",
          lang: "es",
        },
      },
    }),
  ],
});

  2. Inicia el servidor de desarrollo:

    npm run dev

  3. Navega a las siguientes URLs: