JSON5

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

¿Qué es JSON5?

JSON5 es una extensión de JSON que facilita la escritura y el mantenimiento manual por parte de humanos. Admite comentarios, claves sin comillas, comas finales y una sintaxis más flexible, manteniendo la compatibilidad con JavaScript.

Por ejemplo:

{
  // JSON5 allows comments!
  title: "Hello, world!",
  description: "A simple demo app with JSON5 features",

  // Unquoted keys are allowed
  author: {
    name: "John Doe",
  },

  messages: ["Welcome to MyApp", "Hello, world!"],

  // Trailing commas are allowed
  locked_key_1: "This value is locked and should not be changed",
}

¿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 pipelines existentes.

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

Acerca de esta guía

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

Aprenderás a:

  • Crear un proyecto desde cero
  • Configurar un pipeline 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 pipeline 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 la región originales en los 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 ver la lista completa de códigos de locale que soporta Lingo.dev CLI, consulta Códigos de locale soportados.

Paso 3. Configurar los locales de destino

Los locales de destino son los idiomas y regiones a los que deseas traducir tu contenido. Para configurar los locales 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 JSON5 que contengan el contenido a traducir. Estos archivos deben estar ubicados en una ruta que incluya el locale de origen en algún lugar de la ruta (por ejemplo, como nombre de directorio tipo en/ o como parte del nombre del archivo tipo messages.en.json5).

Paso 5. Crear un bucket

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

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

  2. En el objeto "json5", 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": {
    "json5": {
      "include": ["./[locale]/example.json5"]
    }
  }
}

    Estos patrones definen qué archivos traducir.

    Los patrones en sí:

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

    No se soportan patrones glob recursivos (por ejemplo, **/*.json5).

Paso 6. Configurar un LLM

Lingo.dev CLI utiliza modelos de lenguaje grandes (LLM) para traducir contenido con IA. Para usar uno de estos modelos, necesitas una clave API de un proveedor soportado.

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

  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 las 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.json5

{
  // JSON5 allows comments!
  title: "Hello, world!",
  description: "A simple demo app with JSON5 features",
  version: "1.0.0",
  support_email: "[email protected]",
  homepage: "https://lingo.dev",
  deprecated: null,
  empty: "",
  emoji: "🚀",

  // Unquoted keys are allowed
  author: {
    name: "John Doe",
  },

  contributors: [{ name: "Alice" }, { name: "Bob" }],

  messages: ["Welcome to MyApp", "Hello, world!"],

  config: {
    theme: {
      primary: "Blue theme",
    },
  },

  mixed_array: [
    "Mixed content here",
    42,
    true,
    {
      nested_message: "Nested text",
    },
  ],

  // Hexadecimal numbers work in JSON5
  hex_value: 0xdeadbeef,

  // Trailing commas are allowed
  locked_key_1: "This value is locked and should not be changed",
}

es/example.json5

{
  // JSON5 allows comments!
  title: "¡Hola, mundo!",
  description: "Una aplicación de demostración simple con características JSON5",
  version: "1.0.0",
  support_email: "[email protected]",
  homepage: "https://lingo.dev",
  deprecated: null,
  empty: "",
  emoji: "🚀",

  // Unquoted keys are allowed
  author: {
    name: "Juan Pérez",
  },

  contributors: [{ name: "Alicia" }, { name: "Roberto" }],

  messages: ["Bienvenido a MyApp", "¡Hola, mundo!"],

  config: {
    theme: {
      primary: "Tema azul",
    },
  },

  mixed_array: [
    "Contenido mixto aquí",
    42,
    true,
    {
      nested_message: "Texto anidado",
    },
  ],

  // Hexadecimal numbers work in JSON5
  hex_value: 0xdeadbeef,

  // Trailing commas are allowed
  locked_key_1: "This value is locked and should not be changed",
}

i18n.json

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

i18n.lock

version: 1
checksums:
  455da9346f4e772000927cd2ff5bb898:
    title: 0468579ef2fbc83c9d520c2f2f1c5059
    description: 6f4922f45568161a8cdf4ad2299f6d23
    version: 54a9e730e88fb16291b852274d433923
    support_email: 10627fcc465897af0f5e1bba042685f9
    emoji: b328c432cee108a87a92f05258b6a651
    author/name: febee8e9ab40b2fe5106d72675228d00
    contributors/0/name: e80d4063a32adaad7b0a82b0bcc10551
    contributors/1/name: b2bca2fa3c890618e56d07473f26ead3
    messages/0: d1c3a9f35e377554a4ccaa467ca26614
    messages/1: 0468579ef2fbc83c9d520c2f2f1c5059
    config/theme/primary: 7535a3779d6934ea8ecf18f5cb5b93fd
    mixed_array/0: 001b5b003d96c133534f5907abffdf77
    mixed_array/3/nested_message: 5f0782dfc5993e99890c0475bc295a30
    hex_value: a1b2c3d4e5f6789012345678abcdef01