Inicio rápido

La principal fortaleza de Lingo.dev CLI es localizar eficientemente aplicaciones y contenido markdown a idiomas de destino utilizando un único comando CLI.

Esta guía de inicio rápido asume que estás a punto de hacer tu aplicación multilingüe, o ya la has configurado para manejar 2 o más idiomas. Por lo tanto, la guía está diseñada para ser lo suficientemente breve como para completarse en menos de 10 minutos, pero lo suficientemente detallada para entender el funcionamiento interno.

Al completar esta guía, podrás:

1. Localizar el contenido de la aplicación al español y japonés utilizando un motor de traducción de IA;
2. Entender cómo los archivos fuente, los archivos de destino y la configuración funcionan juntos;
3. Configurar un flujo de trabajo de localización que pueda escalar tu aplicación y contenido markdown a docenas de idiomas y decenas de miles de palabras.

¡Comencemos!

Requisitos previos

Markdown

Los archivos Markdown son documentos estructurados, lo que significa que no se necesita configuración previa. Lingo.dev CLI procesa archivos .md directamente, manteniendo el formato mientras localiza el contenido, por lo que puedes continuar al Paso 1.

Aplicaciones

Para hacer una aplicación multilingüe, las aplicaciones web y móviles modernas requieren que los desarrolladores configuren primero la internacionalización (i18n).

Para este inicio rápido, crearemos un archivo JSON independiente para demostrar cómo Lingo.dev CLI localiza el contenido de la aplicación.

Cuando integres con tu aplicación real, sigue nuestras guías de framework recomendadas:

• React: react-intl
• Vue: vue-i18n
• Svelte: svelte-i18n
• Angular: ngx-translate
• iOS: Localizable.xcstrings
• Android: strings.xml

Paso 1. Inicializar el proyecto

Lingo.dev CLI utiliza el archivo de configuración estándar i18n.json para declarar tus ajustes de localización. Para crearlo de forma interactiva, ejecuta:

npx lingo.dev@latest init

Te hará preguntas sobre tu proyecto y luego creará un archivo i18n.json en la raíz de tu proyecto.

El archivo debería verse así:

{
  "locale": {
    "source": "en",
    "targets": ["es", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

Vamos a desglosar cada elemento de configuración:

• locale.source — El idioma en el que escribe tu equipo. Esta configuración identifica qué archivos contienen el contenido autoritativo. Toda la localización fluye desde la fuente hacia los objetivos.

• locale.targets — Un array de códigos de idioma ISO 639-1 que representan tus mercados objetivo. Cada código corresponde a un archivo separado (o sección dentro de un archivo, dependiendo del formato). Puedes comenzar con uno o dos idiomas y añadir más a medida que te expandes.

• buckets.json.include — Patrones tipo glob que indican al CLI dónde encontrar y crear archivos de idioma. El token especial [locale] se expande a cada código de idioma. Con el patrón locales/[locale].json, el CLI busca locales/en.json como fuente y genera locales/es.json y locales/ja.json como objetivos. Puedes especificar múltiples patrones e incluso mezclar formatos dentro de una sola configuración.

Funciones avanzadas que descubrirás a medida que tu proyecto crezca:

• Múltiples buckets para diferentes tipos de archivos o secciones de tu aplicación
• Patrones exclude para omitir ciertos archivos
• lockedKeys para evitar que valores específicos sean traducidos

Crear el archivo fuente en inglés

Para esta guía rápida, crearemos un archivo de localización:

mkdir -p locales
echo '{"greeting":"Hello, world!","button.submit":"Submit"}' > locales/en.json

Esto crea un directorio locales y un archivo fuente en inglés con dos claves de traducción. Las claves como greeting funcionan para estructuras planas, mientras que las claves con espacios de nombres como button.submit ayudan a organizar aplicaciones más grandes.

También se admiten objetos anidados. Encontrará más detalles sobre los diferentes formatos de archivo en el resto de la documentación.

Paso 2. Autenticación

El CLI de Lingo.dev envía su contenido al motor de traducción de IA para la localización, por lo que necesitamos autenticarnos primero.

Opción 1. Acceso directo a la API de LLM

El CLI de Lingo.dev le ayuda a utilizar modelos LLM como OpenAI o Anthropic para localización y traducción.

Esto significa que se le factura por token procesado, usted controla la selección del modelo, los prompts del sistema y todos los parámetros del modelo.

Para autenticarse, cree un archivo .env en la raíz de su proyecto con su clave API:

# si está utilizando OpenAI

OPENAI_API_KEY=sk-...

# si está utilizando Anthropic

ANTHROPIC_API_KEY=sk-...

Alternativamente, en lugar de usar .env, puede exportar la variable en su sesión actual de shell:

export ANTHROPIC_API_KEY=sk-ant-...

¿Desea añadir soporte para otro proveedor? El CLI de Lingo.dev es de código abierto y acepta contribuciones. Haga un fork del repositorio y envíe una solicitud de extracción: github.com/lingodotdev/lingo.dev.

Opción 2. Motor de Lingo.dev

Alternativamente, puede crear una cuenta gratuita de Motor de Lingo.dev y utilizarla como su motor de traducción de IA.

Proporciona selección dinámica de modelos, enrutamiento automático a diferentes modelos para cada par de idiomas, respaldos automáticos de modelos, memoria de traducción que considera traducciones anteriores y soporte de glosario para la terminología específica del dominio de su proyecto. Hay opciones tanto gratuitas como de pago, y el nivel gratuito Hobby debería ser suficiente para este tutorial.

Para autenticarse, ejecute:

npx lingo.dev@latest login

Detalle importante. Si está utilizando el navegador Brave, o si sus extensiones del navegador están bloqueando el flujo de autenticación, puede autenticarse manualmente añadiendo una variable de entorno LINGODOTDEV_API_TOKEN a su archivo .env:

LINGODOTDEV_API_TOKEN=...

Encontrará el token en la Configuración del Proyecto del Motor de Lingo.dev.

Paso 3. Configurar el motor de traducción de IA

Ahora que estás autenticado, necesitas configurar qué motor de traducción de IA utilizar.

Opción 1. Acceso directo a la API de LLM

Para usar OpenAI, actualiza tu configuración i18n.json para utilizar el proveedor openai:

{
  "locale": {
    "source": "en",
    "targets": ["es", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  },
  "provider": {
    "id": "openai",
    "model": "gpt-4o-mini",
    "prompt": "Act as a professional software localization expert. Translate each key from {source} to {target}. Preserve ICU message format placeholders like {name} and {{count}}. Maintain Markdown formatting including links and code blocks. Match the tone and formality of the source text. Technical terms that are typically untranslated in the industry should remain in English."
  }
}

¡Puedes experimentar con diferentes prompts para personalizar el comportamiento de localización, pero hemos encontrado que este es un buen punto de partida!

La configuración provider controla el acceso directo al LLM:

• id — Puede ser openai o anthropic
• model — La versión específica del modelo a utilizar. Ejemplos: gpt-4o-mini, gpt-4o (OpenAI), o claude-3-haiku, claude-3-sonnet (Anthropic).
• prompt — Un prompt de sistema que guía el comportamiento de traducción. Los marcadores {source} y {target} se reemplazan con los códigos de idioma reales en tiempo de ejecución. Este prompt es tu oportunidad para imponer terminología, estilo y reglas específicas del dominio.

Opción 2. Motor Lingo.dev

Si estás utilizando el Motor Lingo.dev como tu motor de traducción de IA, puedes omitir completamente el nodo provider.

El motor selecciona automáticamente los modelos y prompts basándose en la investigación del equipo de Lingo.dev y la configuración de tu motor.

Tu configuración i18n.json:

{
  "locale": {
    "source": "en",
    "targets": ["es", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

Nota: Cuando uses el Motor Lingo.dev, omite completamente el nodo provider. El motor selecciona automáticamente los modelos y prompts.

Paso 4. Traducir

Para localizar tu aplicación, ejecuta:

npx lingo.dev@latest i18n

La CLI creará los archivos de destino y actualizará el archivo i18n.lock que rastrea las huellas digitales del contenido. Esto garantiza actualizaciones incrementales en ejecuciones posteriores.

¡Ya has localizado el contenido de tu aplicación!

Próximos pasos

Has completado el flujo de trabajo de localización principal. Tu repositorio ahora contiene archivos localizados que pueden ser confirmados, revisados e implementados como cualquier otro artefacto de código.

Desde aquí, puedes:

• Automatizar el flujo de trabajo: Integración CI/CD — Configura la integración CI/CD para localizar en cada push, y confirmar los cambios automáticamente a tu repositorio, mediante pull requests o commits directos;
• Comprender el funcionamiento interno: Cómo funciona — Aprende sobre los algoritmos, optimizaciones de rendimiento y decisiones arquitectónicas.