YAML con claves raíz - Lingo.dev CLI

¿Qué es YAML con claves raíz?

YAML con claves raíz es un formato de localización donde las traducciones de cada idioma se organizan bajo una clave de nivel raíz nombrada según el código del idioma. Este formato permite almacenar múltiples idiomas en la misma estructura de directorios mientras los mantiene organizados por idioma.

Por ejemplo:

en:
  navigation:
    home: "Home"
    about: "About Us"
    contact: "Contact"
  forms:
    title: "Contact Form"
    name_label: "Your Name"
    submit_button: "Send Message"

¿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 YAML con claves raíz de idioma utilizando 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 utilizar 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 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 la lista completa de códigos de idioma que Lingo.dev CLI soporta, consulta Códigos de idioma soportados.

Paso 3. Configurar los idiomas de destino

Los idiomas de destino son los idiomas y regiones a los que deseas 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 YAML con claves raíz de idioma 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.yml).

Paso 5. Crear un bucket

En el archivo i18n.json, añade un objeto "yaml-root-key" al objeto buckets:

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

En el objeto "yaml-root-key", 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": {
    "yaml-root-key": {
      "include": ["./[locale]/example.yml"]
    }
  }
}
```
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]/translations.yml")
- pueden usar asteriscos como comodines (por ejemplo, "[locale]/*.yml")
Los patrones glob recursivos (por ejemplo, **/*.yml) 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:

Regístrate para obtener una cuenta de Lingo.dev.
Ejecuta el siguiente comando:
```
npx lingo.dev@latest login
```
Esto abrirá tu navegador predeterminado y te pedirá que te autentiques.
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:

Lee el archivo i18n.json.
Encuentra los archivos que necesitan ser traducidos.
Extrae el contenido traducible de los archivos.
Utiliza el LLM configurado para traducir el contenido extraído.
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.yml

en:
  navigation:
    home: "Home"
    about: "About Us"
    contact: "Contact"
    services: "Services"
  forms:
    title: "Contact Form"
    name_label: "Your Name"
    email_label: "Email Address"
    message_label: "Message"
    submit_button: "Send Message"
    success_message: "Thank you for your message!"

es/example.yml

es:
  navigation:
    home: "Inicio"
    about: "Sobre Nosotros"
    contact: "Contacto"
    services: "Servicios"
  forms:
    title: "Formulario de Contacto"
    name_label: "Su Nombre"
    email_label: "Dirección de Correo Electrónico"
    message_label: "Mensaje"
    submit_button: "Enviar Mensaje"
    success_message: "¡Gracias por su mensaje!"

i18n.json

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

i18n.lock

version: 1
checksums:
  1b0d7c9f07dcc31a978bc337763270ea: {}
  87b1c33c3f85415e0906ece6cfed17c5:
    navigation/home: 104a3db3b671c04e167eafbe21e57881
    navigation/about: 8f89131a66d4659be07cd5af2c7ea898
    navigation/contact: 9afa39bc47019ee6dec6c74b6273967c
    navigation/services: 8ea10b45b9abab2a3bfc3c07e1c9cdc6
    forms/title: ac85dea7c7f0bf1cd7d48cc1b4da3acc
    forms/name_label: 03c6ae7996d5841f743cd406b4eff72d
    forms/email_label: 0ee22bbbe989a0c61a18023407d12dc2
    forms/message_label: f2f72126bd244cfc534eab395e054362
    forms/submit_button: 487177489aafc9c0243c57ef3850a2d9
    forms/success_message: a0a7aa980dffa31d4d194af718a917b3