Inicio rápido

Agrega soporte multilingüe a tu aplicación React en menos de 5 minutos.

Requisitos previos

  • Node.js 18+
  • Aplicación React usando Next.js (App Router) o Vite

Instalación

pnpm install @lingo.dev/compiler

Configuración

Next.js

Haz tu configuración asíncrona y envuélvela con withLingo:

// next.config.ts
import type { NextConfig } from "next";
import { withLingo } from "@lingo.dev/compiler/next";

const nextConfig: NextConfig = {};

export default async function (): Promise<NextConfig> {
  return await withLingo(nextConfig, {
    sourceRoot: "./app",
    sourceLocale: "en",
    targetLocales: ["es", "de", "fr"],
    models: "lingo.dev",
    dev: {
      usePseudotranslator: true, // Fake translations for development
    },
  });
}

Vite

Agrega el plugin de Lingo a tu configuración de Vite:

// vite.config.ts
import { defineConfig } from "vite";
import { lingoCompilerPlugin } from "@lingo.dev/compiler/vite";

export default defineConfig({
  plugins: [
    lingoCompilerPlugin({
      sourceRoot: "src",
      sourceLocale: "en",
      targetLocales: ["es", "de", "fr"],
      models: "lingo.dev",
      dev: {
        usePseudotranslator: true,
      },
    }),
    // ...other plugins
  ],
});

Configurar el proveedor

Next.js

Envuelve tu aplicación con LingoProvider en tu layout raíz:

// app/layout.tsx
import { LingoProvider } from "@lingo.dev/compiler/react";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <LingoProvider>
      <html>
        <body>{children}</body>
      </html>
    </LingoProvider>
  );
}

Vite

Envuelve tu aplicación con LingoProvider en tu punto de entrada:

// src/main.tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { LingoProvider } from "@lingo.dev/compiler/react";
import App from "./App";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <LingoProvider>
      <App />
    </LingoProvider>
  </StrictMode>
);

Autenticación

El compilador utiliza Lingo.dev Engine por defecto para las traducciones.

Opción 1: Lingo.dev Engine (recomendado)

Regístrate en lingo.dev y autentícate:

npx lingo.dev@latest login

Usuarios de Windows: Si npx lingo.dev no se ejecuta en tu entorno:

  1. Instala el paquete: npm install lingo.dev@latest
  2. Usa npx lingo en su lugar (por ejemplo, npx lingo login)

Esto guarda tu clave API localmente. El plan gratuito Hobby es suficiente para la mayoría de proyectos.

¿Tienes problemas de autenticación? Si tu navegador bloquea el flujo de autenticación, añade manualmente tu clave API a .env:

LINGODOTDEV_API_KEY=your_key_here

Encuentra tu clave API en la configuración del proyecto de Lingo.dev.

Opción 2: proveedor LLM directo

Alternativamente, usa cualquier proveedor LLM compatible directamente. Actualiza tu configuración:

{
  models: {
    "*:*": "groq:llama-3.3-70b-versatile",
    // or "google:gemini-2.0-flash"
    // or "openai:gpt-4o"
    // or "anthropic:claude-3-5-sonnet"
  }
}

Añade la clave API correspondiente a .env:

GROQ_API_KEY=your_key
# or GOOGLE_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY

Consulta proveedores de traducción para ver todos los proveedores compatibles.

Ejecutar servidor de desarrollo

Inicia tu servidor de desarrollo:

npm run dev

El compilador:

  1. Escaneará tu JSX en busca de texto traducible
  2. Generará pseudotraducciones (traducciones falsas para visualizar qué se traduce)
  3. Las inyectará en tus componentes
  4. Almacenará metadatos en .lingo/metadata.json

¿Por qué pseudotraducciones? Son instantáneas (sin llamadas API), muestran exactamente qué se traduce y ayudan a probar tu interfaz con longitudes de texto variables, todo sin gastar créditos API.

Probar traducción

Añade un componente simple:

export function Welcome() {
  return (
    <div>
      <h1>Welcome to our app</h1>
      <p>This text will be translated automatically</p>
    </div>
  );
}

No se necesitan cambios en el código: el texto se extrae y traduce automáticamente.

Añadir selector de idioma (opcional)

Permite a los usuarios cambiar de idioma:

"use client"; // For Next.js

import { useLingoContext } from "@lingo.dev/compiler/react";

export function LanguageSwitcher() {
  const { locale, setLocale } = useLingoContext();

  return (
    <select value={locale} onChange={(e) => setLocale(e.target.value)}>
      <option value="en">English</option>
      <option value="es">Español</option>
      <option value="de">Deutsch</option>
      <option value="fr">Français</option>
    </select>
  );
}

Generar traducciones reales

Cuando estés listo para traducciones reales, actualiza tu configuración:

{
  dev: {
    usePseudotranslator: false, // Disable fake translations
  }
}

Reinicia tu servidor de desarrollo. El compilador ahora generará traducciones reales con IA para cualquier texto nuevo o modificado.

¿Preocupado por los costos? Las pseudotraducciones son gratuitas e instantáneas. Solo desactívalas cuando necesites revisar la calidad real de las traducciones.

Preguntas frecuentes

¿Necesito marcar cada cadena traducible? No. El compilador detecta automáticamente el texto JSX. Para optar por la inclusión manual, establece useDirective: true y añade 'use i18n' al inicio de los archivos que desees traducir.

¿Qué pasa con el contenido dinámico o las props? El compilador maneja automáticamente atributos de cadena como alt, aria-label y placeholder. Para texto dinámico, usa la sintaxis de plantilla: <p>Hello {name}</p> funciona como se espera.

¿Puedo personalizar traducciones específicas? Sí. Usa el atributo data-lingo-override:

<h1 data-lingo-override={{ es: "Bienvenido", de: "Willkommen" }}>
  Welcome
</h1>

¿Cómo confirmo las traducciones? Confirma el directorio .lingo/ en el control de versiones. Contiene metadatos y traducciones en caché: es seguro confirmarlo y debe versionarse junto con tu código.

Próximos pasos