Mensajes de React
Mantén el texto de origen y su contexto en tus componentes y luego renderiza los catálogos traducidos con valores, gramática 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 entre esos usos y a quienes desarrollan entender el componente sin tener que buscar una clave en otro archivo.
@lingo.dev/react usa llamadas explícitas para los mensajes:
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 con cadenas traducidas. Un proveedor entrega 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 reúne las llamadas que reconoce en un catálogo de origen JSONC y genera declaraciones de TypeScript. La CLI envía ese archivo para su traducción y recupera el archivo de destino. Tu cargador convierte el archivo en el mapa de cadenas del proveedor. Extracción y carga de catálogos explica 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 comunica con un motor de localización ni incluye una clave de API. Mantén la traducción del lado del servidor en la integración de API; entrega los catálogos resultantes a la aplicación mediante su proceso habitual de compilación o de carga durante las solicitudes.
Escribe el mensaje que necesita quien lo lee #
Usa una oración 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 ir en otra parte de la oración.
| Qué necesita el mensaje | Usa |
|---|---|
| Texto sin formato con valores | l.text. |
| Enlaces, énfasis u otro elemento de React | l.rich, con funciones de retorno de renderizado con nombre. |
| Gramática según la cantidad o una elección entre categorías | l.plural y l.select. |
| Números, fechas, listas u operaciones de texto que tienen en cuenta el idioma | Métodos de formato, que usan 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 el 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 usas otra configuración, carga el idioma y los mensajes antes de renderizar y mantén ambos juntos durante el renderizado del lado del servidor y la hidratación.
Usa tipos generados para detectar errores en el texto de origen, el contexto y los valores mientras editas. Usa pruebas de renderizado para comprobar las plantillas que se cargan realmente. Si una traducción no aparece, la solución de problemas recorre la búsqueda desde el componente hasta el catálogo.
Exportaciones #
La 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.