Mensajes y contexto
Escribe mensajes de origen completos, explica su significado e inserta valores variables sin alterar su identidad.
Para conservar la acción o el significado de las palabras, un mensaje traducido necesita suficiente información. Escribe el texto de origen completo y explica cómo se usa en context. Proporciona nombres, cantidades y otros datos variables mediante values.
import { useLingo } from "@lingo.dev/react";
export function Greeting({ name }: { name: string }) {
const l = useLingo();
return (
<h1>
{l.text("Welcome back, {name}.", {
context: "Greeting at the top of the account dashboard",
values: { name },
})}
</h1>
);
}El resultado es una cadena. TextOptions requiere context: string y admite values?: Record<string, string | number>. El catálogo contiene la plantilla de la frase; la traducción puede colocar {name} donde lo exija la gramática.
Explica el significado de los mensajes ambiguos #
«Guardar» puede significar enviar un formulario o marcar un artículo como favorito. El contexto permite distinguir esos mensajes, aunque el texto de origen en inglés sea idéntico:
import { computeKey } from "@lingo.dev/react";
const submitKey = computeKey("Save", "Submit changes to account settings");
const bookmarkKey = computeKey("Save", "Bookmark this article for later reading");Las claves son distintas, por lo que quien traduce puede elegir el verbo adecuado para cada acción. Un contexto como «Texto que se muestra al usuario» no resuelve esa ambigüedad; describe la acción, el público o la restricción que podría influir en la redacción.
El extractor escribe esta información en el comentario @context del catálogo. Es una orientación para la traducción, no un texto visible en la interfaz. Incluye la terminología recurrente, las instrucciones y los requisitos de voz en el contexto de traducción del motor de localización, y mantén el significado específico de cada mensaje junto a la llamada.
Identidad del mensaje #
computeKey(source: string, context?: string): string genera una clave de ocho caracteres a partir del texto de origen y del contexto. Une el contexto, si no está vacío, al texto de origen mediante un separador nulo, normaliza la entrada combinada a Unicode NFC y calcula el hash de sus bytes UTF-8.
Las representaciones Unicode canónicamente equivalentes comparten una clave. Cambiar la redacción, la puntuación, las mayúsculas y minúsculas, los espacios en blanco o el contexto puede generar una clave nueva. Los valores no intervienen en el cálculo del hash, por lo que todos los nombres del saludo usan la misma entrada de mensaje.
Después de cambiar el texto de origen o el contexto, vuelve a ejecutar la extracción y revisa las entradas nuevas y huérfanas. Copiar una traducción bajo la nueva clave sin comprobar su significado puede conservar precisamente la redacción que el cambio del texto de origen pretendía sustituir. Los hashes son finitos; el extractor detecta colisiones entre los mensajes que recopila.
Escribe llamadas que puedan extraerse #
Usa cadenas de origen y contextos literales en llamadas como l.text(...). El entorno de ejecución puede recibir una cadena calculada, pero el extractor no puede inferir todas las cadenas que podría construir el programa. Mantén l como receptor o usa una variable compatible creada a partir de useLingo o createLingo. La referencia de extracción describe las formas reconocidas.
Usa marcadores de posición para los datos variables en lugar de generar cadenas de origen como "Welcome, " + name. Una plantilla estable se puede extraer, traducir una vez por cada significado y reutilizar para cada valor.
Interpolación e ICU #
Los marcadores de posición simples usan nombres como {name}. Los valores proporcionados se convierten en texto. Si falta un valor simple, su marcador permanece visible; si se omite el objeto values, se devuelve la plantilla seleccionada sin interpolación.
Cuando la gramática depende de una cantidad o categoría, el formateador de texto admite patrones ICU complejos mediante intl-messageformat:
import { createLingo } from "@lingo.dev/react";
const l = createLingo("en");
const label = l.text("{count, plural, =0 {No files} one {# file} other {# files}}", {
context: "Number of files attached to a message",
values: { count: 0 },
});Esto devuelve No files. La rama explícita =0 distingue el cero de las categorías de plural habituales del idioma. Proporciona todos los argumentos que necesite la plantilla seleccionada. Si falla el análisis o el formateo de un patrón ICU complejo, el entorno de ejecución devuelve esa plantilla y notifica un error de desarrollo sin duplicados; no sustituye una traducción mal formada por una nueva versión formateada del texto de origen.
Plurales y selecciones ofrece funciones auxiliares para alternativas completas. Texto enriquecido inserta elementos de React mediante un analizador independiente de etiquetas con nombre. Usa la forma adecuada en lugar de mezclar expresiones ICU complejas en plantillas de texto enriquecido.