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 funciones 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 grandes y escribe 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 fuente:

    mkdir -p src/content/docs/en

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

    ---
title: "Welcome"
description: "Getting started with our documentation"
---

## Introduction

This documentation is automatically translated by Lingo.dev.

## Features

Our product includes powerful capabilities for modern development.

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.10",
  "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. Garantiza 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).
  • El CLI de Lingo.dev no admite patrones glob recursivos (por ejemplo, **/*.mdx). Deberás crear patrones include adicionales para traducir archivos que existan dentro de directorios anidados.

Para obtener más información, consulta configuración de 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 del CLI:

    npx lingo.dev@latest login

  3. Ejecuta el pipeline de traducción:

    npx lingo.dev@latest run

    El 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. Usar las traducciones

  1. En el archivo astro.config.mjs, configura los locales admitidos:

    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 URL: