Mensajes en React

Mantén el texto de origen y el contexto en tus componentes y renderiza los catálogos traducidos con valores, reglas gramaticales y elementos de React.

El mensaje de un componente debe estar junto a la acción que explica. «Guardar» en un formulario envía los cambios; «Guardar» en un artículo crea un marcador. Mantener juntos el texto de origen y su significado permite a quienes traducen distinguir ambos casos y a quienes desarrollan entender el componente sin tener que buscar una clave en otro archivo.

@lingo.dev/react utiliza llamadas explícitas a mensajes:

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

export function SaveButton() {
  const l = useLingo();
  return <button type="submit">{l.text("Save", { context: "Submit changes to account settings" })}</button>;
}

El texto de origen y el contexto identifican un mensaje en un catálogo, un mapa que asocia claves a cadenas traducidas. Un proveedor proporciona ese catálogo y el idioma activo. El componente recibe el texto traducido o, si la entrada no existe o está vacía, el texto de origen.

De un componente a otro idioma #

Primero, renderiza una traducción local. Un catálogo pequeño permite ver cómo funciona la búsqueda sin necesidad de una cuenta ni de una solicitud de red.

Para el flujo de trabajo de la aplicación, lingo extract recopila las llamadas reconocibles en un catálogo de origen JSONC y genera declaraciones de TypeScript. La CLI envía ese archivo para traducirlo y recupera la versión de destino. Tu cargador convierte el archivo en el mapa de cadenas del proveedor. Extracción y carga de catálogos detalla el proceso completo, incluido cómo conservar los mensajes activos cuando el JSONC traducido ha perdido sus comentarios de metadatos.

El renderizado es local. El entorno de ejecución no se conecta a ningún motor de localización ni contiene una clave de API. Mantén la traducción en el servidor dentro de la integración con la API y entrega los catálogos resultantes a la aplicación mediante su proceso habitual de compilación o de carga al recibir una solicitud.

Escribe el mensaje que necesita quien lo lee #

Usa una frase completa con marcadores de posición en lugar de concatenar fragmentos traducidos por separado. En otro idioma, el nombre, la cantidad o el enlace pueden ocupar otra posición en la frase.

Qué necesita el mensajeQué usar
Texto sin formato con valoresl.text.
Enlaces, énfasis u otro elemento de Reactl.rich, con funciones de retorno de renderizado con nombre.
Reglas gramaticales según la cantidad o una elección entre categoríasl.plural y l.select.
Números, fechas, listas u operaciones de texto adaptadas al idiomaMétodos de formato, que utilizan Intl nativo.

La referencia de proveedor y hooks explica los catálogos anidados y el uso de createLingo en código fuera de los componentes. Metadatos del idioma ofrece información sobre la dirección del texto, el sistema de escritura y la región para tomar decisiones fundamentadas sobre el documento y su diseño.

Conecta la aplicación en torno a los mensajes #

Los adaptadores de Next.js Pages y TanStack Start conectan los catálogos con sus respectivos sistemas de enrutamiento. Si utilizas otra configuración, carga el idioma y los mensajes antes de renderizar y mantén esa combinación durante el renderizado en el servidor y la hidratación.

Usa los tipos generados para detectar errores en el texto de origen, el contexto y los valores mientras editas. Usa las pruebas de renderizado para comprobar las plantillas que se han cargado realmente. Si una traducción no aparece, la sección de resolución de problemas recorre la búsqueda desde el componente hasta el catálogo.

Exportaciones #

El módulo raíz exporta LingoProvider, useLingo, createLingo y computeKey, además de los tipos LingoProviderProps, Lingo, Messages, LingoMessages, MessageKey, TextOptions, RichOptions, PluralForms, SelectForms y FormatMethods. El punto de entrada independiente @lingo.dev/react/testing exporta withLingo y renderStatic.