Inicio rápido para create-t3-app

Cómo configurar Lingo.dev Compiler con create-t3-app

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 create-t3-app, un framework de aplicación web full-stack que combina Next.js, TypeScript, Tailwind CSS y tRPC.

Lo que aprenderás

  • Cómo inicializar Lingo.dev Compiler en un proyecto create-t3-app
  • Cómo configurar el compilador para que sea compatible con create-t3-app
  • 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:

  1. Inicia sesión en Lingo.dev Engine.

  2. Navega a la página de Projects.

  3. Haz clic en API key > Copy.

  4. Almacena la clave API en una variable de entorno:

    export LINGODOTDEV_API_KEY="<your_api_key>"

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. Deshabilitar Turbopack

Cuando se utiliza create-t3-app, Lingo.dev Compiler no es compatible con Turbopack. Si está habilitado, el proceso de compilación fallará.

Para deshabilitar Turbopack, elimina la bandera --turbopack del script dev:

{
  "scripts": {
    "dev": "next dev"
  }
}

Paso 4. Inicializar el Compilador

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

  1. Importa el compilador:

    import lingoCompiler from "lingo.dev/compiler";

  2. Inicializa el compilador con el método next:

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

    Para compatibilidad con create-t3-app, asegúrate de que:

    • sourceRoot esté configurado como "src"
    • rsc esté configurado como true

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

  3. Combina la configuración del compilador con la configuración existente y expórtala:

    export default withLingo(config);

Con esta configuración en su lugar, 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á el/los modelo(s) de IA configurado(s) para generar traducciones
  • Almacenará el contenido original y traducido en un archivo dictionary.js
  • Reemplazará el contenido localizado con marcadores de posición

Paso 5. 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 basado en 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/app/layout.tsx, envuelve la aplicación en el componente LingoProvider y pasa la función loadDictionary a este:

import { LingoProvider, loadDictionary } from "lingo.dev/react/rsc";

export default function RootLayout({
  children,
}: Readonly<{ children: React.ReactNode }>) {
  return (
    <LingoProvider loadDictionary={(locale) => loadDictionary(locale)}>
      <html lang="en" className={`${geist.variable}`}>
        <body>
          <TRPCReactProvider>{children}</TRPCReactProvider>
        </body>
      </html>
    </LingoProvider>
  );
}

La función loadDictionary:

  • Recupera el idioma actual de la cookie lingo-locale (por defecto es "en")
  • Carga el contenido localizado desde el archivo dictionary.js

El componente LingoProvider es un proveedor de contexto de React que reemplaza los marcadores de posición creados por el compilador con el contenido localizado.

Paso 6. 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 7. Ejecutar la Aplicación

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

  1. Inicia el servidor de desarrollo:

    npm run dev

  2. Navega a localhost:3000.

  3. 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:

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

Lecturas adicionales