Lingo.dev - Automated AI localization for web & mobile apps

Introducción

Lingo.dev Compiler es una herramienta potenciada por IA que te permite localizar aplicaciones basadas en React sin realizar cambios en los componentes existentes. Solo configuras algunas cosas, envuelves tu aplicación en un proveedor de contexto, y eso es todo — tu aplicación está localizada.

Esta guía explica cómo configurar Lingo.dev Compiler con TanStack Start.

Lo que aprenderás

Cómo inicializar Lingo.dev Compiler en un proyecto de TanStack Start
Cómo configurar el compilador para tu aplicación de TanStack Start
Cómo configurar un selector de idioma para cambiar entre locales

Paso 1. Configura una clave API

Lingo.dev Compiler utiliza modelos de lenguaje de gran escala (LLMs) para localizar aplicaciones 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.

Para configurar una clave API:

Inicia sesión en Lingo.dev Engine.
Navega a la página de Proyectos.
Haz clic en Clave API > Copiar.
Almacena la clave API en una variable de entorno:
```
export LINGODOTDEV_API_KEY="<tu_clave_api>"
```

Alternativa: Proveedores LLM personalizados

No tienes que usar Lingo.dev Engine. Puedes configurar el compilador para integrarlo con varios proveedores LLM personalizados, incluyendo:

Groq
Google
Mistral
Ollama
OpenRouter

Paso 2. Instala el paquete

Lingo.dev Compiler se distribuye como parte del paquete npm lingo.dev. Para instalarlo, usa tu gestor de paquetes preferido:

npm install lingo.dev

Paso 3. Inicializar el compilador

Lingo.dev Compiler se integra con TanStack Start y se ejecuta durante el tiempo de compilación. Para conectarse al proceso de compilación de TanStack Start, realiza los siguientes cambios en el archivo vite.config.ts:

Importa el compilador:

import lingoCompiler from "lingo.dev/compiler";

Inicializa el compilador con el método vite:

const withLingo = lingoCompiler.vite({
  sourceRoot: "src",
  lingoDir: "lingo",
  sourceLocale: "en",
  targetLocales: ["es"],
  rsc: false,
  useDirective: false,
  debug: false,
  models: "lingo.dev",
});

Para obtener más información sobre las opciones disponibles, consulta Opciones del compilador.

Aplica la configuración del compilador a tu configuración base:
```
export default defineConfig(withLingo(baseConfig));
```

Con esta configuración implementada, Lingo.dev Compiler:

Recorrerá el árbol de sintaxis abstracta (AST) de la base de código
Encontrará contenido localizable (es decir, texto en elementos JSX y ciertos valores de atributos)
Utilizará los modelos de IA configurados para generar traducciones
Almacenará el contenido original y traducido en un archivo dictionary.js
Reemplazará el contenido localizado con marcadores de posición

Paso 4. Cargar el contenido localizado

Después de que el compilador procese tu aplicación y genere traducciones, necesitas cargar y servir este contenido localizado a tus usuarios. Esto implica:

Cargar el diccionario apropiado según la preferencia de idioma del usuario
Proporcionar las traducciones cargadas a tu aplicación a través de un proveedor de contexto

En el archivo src/routes/__root.tsx:

Importa el componente LingoProviderWrapper y la función loadDictionary desde lingo.dev/react/client:
```
import {
  LingoProviderWrapper,
  loadDictionary,
} from "lingo.dev/react/client";
```
El componente LingoProviderWrapper es un proveedor de contexto que reemplaza los marcadores de posición creados por el compilador con el contenido localizado.

La función loadDictionary:
- Recupera el idioma actual de la cookie lingo-locale
- Utiliza "en" como valor predeterminado cuando no se define un idioma
- Carga el contenido localizado desde el archivo dictionary.js

Envuelve el contenido de tu aplicación en el componente LingoProviderWrapper dentro del componente RootDocument:

function RootDocument({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <head>
        <HeadContent />
      </head>
      <body>
        <LingoProviderWrapper
          loadDictionary={(locale) => loadDictionary(locale)}
        >
          {children}
        </LingoProviderWrapper>
        <Scripts />
      </body>
    </html>
  );
}

Paso 5. Configurar un Selector de Idioma

Para permitir que los usuarios cambien entre idiomas, importa el componente LocaleSwitcher del paquete lingo.dev. Este es un componente sin estilos que:

Renderiza un desplegable de idiomas disponibles
Permite a los usuarios seleccionar un idioma
Recuerda el idioma seleccionado para futuras visitas

Para utilizar el componente, intégralo en cualquier parte de tu aplicación y establece la propiedad locales como un array que contenga los idiomas de origen y destino configurados:

import { LocaleSwitcher } from "lingo.dev/react/client";

<LocaleSwitcher locales={["en", "es"]} />;

Alternativa: Selector de Idioma Personalizado

No es obligatorio utilizar el componente LocaleSwitcher. Puedes implementar tu propia lógica e interfaz de usuario para cambiar de idioma. El único requisito es leer y escribir el idioma activo en la cookie lingo-locale.

Paso 6. Ejecutar la Aplicación

Para verificar que el Compilador Lingo.dev se ha configurado correctamente:

Inicia el servidor de desarrollo:
```
npm run dev
```
Navega a localhost:3000.
Utiliza el componente LocaleSwitcher para cambiar entre idiomas.

La página debería recargarse y mostrar el contenido localizado.

Alternativa: Configurar Cookies Manualmente

Si no estás utilizando el componente LocaleSwitcher, una forma alternativa de verificar que la localización funciona es configurando manualmente la cookie lingo-locale.

Si estás utilizando Google Chrome, sigue estas instrucciones:

Navega a Ver > Desarrollador > Herramientas para desarrolladores.
Ve a la pestaña Aplicación.
En la barra lateral izquierda, bajo Almacenamiento, expande Cookies y selecciona la URL del sitio.
En la tabla de cookies, haz clic derecho en cualquier lugar y selecciona Añadir.
En la columna Nombre, introduce lingo-locale.
En la columna Valor, introduce el idioma deseado (por ejemplo, es).
Presiona Enter para guardar la cookie.
Actualiza la página para aplicar la cookie.

Lecturas adicionales

Para entender cómo funciona el compilador, consulta Cómo funciona.
Para aprender a configurar el compilador, consulta Opciones del compilador.

Inicio rápido para TanStack Start