Renderiza tu primer mensaje traducido

Muestra un saludo en español, sustituye un nombre y comprueba cómo se usa el texto de origen como alternativa con un catálogo local.

Renderiza Hola, Ana. a partir de un mensaje de origen en inglés. Este ejemplo incluye su propia traducción al español para que veas exactamente cómo funcionan juntos un componente, un catálogo y un proveedor. No necesitas una cuenta de Lingo.dev ni una clave de API.

Instala el paquete en una aplicación React 19 #

sh
npm install @lingo.dev/react@1.17.1

Usa una aplicación React 19 existente para este ejemplo. Aunque el paquete declara React 18 y 19 como dependencias entre pares, su proveedor utiliza la sintaxis abreviada de React 19 para proveedores de contexto. Instalar el paquete en un proyecto React 18 no garantiza que pueda renderizarse en él.

Añade el saludo y el catálogo #

Coloca este componente en src/App.tsx y renderízalo desde el punto de entrada existente de tu aplicación:

tsx
import { computeKey, LingoProvider, useLingo } from "@lingo.dev/react";

const messages = {
  [computeKey("Hello, {name}.", "Greeting on the account dashboard")]:
    "Hola, {name}.",
};

function Greeting() {
  const l = useLingo();
  return (
    <h1>
      {l.text("Hello, {name}.", {
        context: "Greeting on the account dashboard",
        values: { name: "Ana" },
      })}
    </h1>
  );
}

export default function App() {
  return (
    <LingoProvider locale="es" messages={messages}>
      <Greeting />
    </LingoProvider>
  );
}

Ejecuta el comando de desarrollo de tu aplicación y abre la página. El encabezado muestra Hola, Ana. El entorno de ejecución calcula la misma clave a partir del texto de origen y del contexto, encuentra la plantilla en español y sustituye {name} por Ana.

El catálogo contiene la frase completa, de modo que la traducción puede cambiar el orden de las palabras. El nombre es un valor, no forma parte de la clave; si usas otro nombre, se utiliza la misma entrada del catálogo. Mantén el texto de origen y el contexto como valores literales en la llamada a l.text para que el extractor pueda detectarlos más adelante.

Comprueba qué ocurre cuando no hay traducción #

Pasa temporalmente messages={{}} al proveedor. El encabezado ahora muestra Hello, Ana. El texto de origen se usa como plantilla alternativa y la sustitución de valores sigue funcionando. Una entrada cuyo valor sea "" también hace que se use el texto de origen.

Restablece messages y cambia solo el contexto de la llamada a "Greeting on the profile page". Esto cambia la identidad del mensaje, por lo que la traducción original deja de coincidir. Restablece el contexto original para volver a Hola, Ana. Estas comprobaciones permiten distinguir entre la falta de un catálogo y una discrepancia entre el mensaje solicitado y el traducido.

Sustituye el mapa local por catálogos extraídos #

El componente está listo para la extracción. Extracción y carga de catálogos explica cómo generar locales/en.jsonc, seleccionarlo en la configuración de la CLI, obtener un catálogo de destino en español y cargarlo de forma segura. Ese es el siguiente paso completo; el ejemplo local anterior sigue siendo útil como prueba de renderizado.

Si tu aplicación utiliza rutas, continúa con Next.js Pages o TanStack Start. Al cambiar de idioma, el nuevo idioma y sus mensajes deben estar disponibles a la vez, para que la interfaz nunca combine el texto de un idioma con el formato de otro.