Mensajes y contexto

Escribe mensajes de origen completos, explica su significado e inserta valores variables sin cambiar su identidad.

Un mensaje traducido necesita suficiente información para conservar la acción o el significado que expresan las palabras. Escribe el texto de origen completo y explica cómo se usa en context. Proporciona nombres, cantidades y otros datos variables mediante values.

tsx
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 acepta values?: Record<string, string | number>. El catálogo contiene la plantilla de la oración; la traducción puede ubicar {name} donde lo requiera la gramática.

Explica el significado de un mensaje ambiguo #

“Guardar” puede significar enviar un formulario o marcar un artículo como favorito. El contexto los convierte en mensajes distintos, aunque el texto de origen en inglés sea idéntico:

ts
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. Quien traduce puede elegir el verbo adecuado para cada acción. Un contexto como “Texto que se muestra a un usuario” no resuelve esa ambigüedad; describe la acción, el público o la restricción que podría cambiar la redacción.

El extractor escribe esta información en el comentario @context del catálogo. Sirve como guía para traducir, no como texto visible de la interfaz. Coloca la terminología recurrente, las instrucciones y los requisitos de voz en el contexto de traducción del motor de localización, y conserva 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 el contexto. Une un contexto no vacío al texto de origen con 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 nueva. Los valores no intervienen en el 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 con la nueva clave sin comprobar su significado puede conservar precisamente la redacción que el cambio en el texto de origen buscaba reemplazar. Los hashes tienen un conjunto finito de valores posibles; el extractor detecta colisiones entre los mensajes que recopila.

Mantén las llamadas en un formato que permita extraerlas #

Usa cadenas de origen y contexto 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 el programa podría construir. Mantén el receptor como l o como 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 puede extraerse, traducirse una vez por cada significado y reutilizarse para cada valor.

Interpolación e ICU #

Los marcadores de posición simples usan nombres como {name}. Los valores proporcionados se convierten en texto. Los valores simples que faltan permanecen visibles, y si omites 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:

ts
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 patrones ICU complejos, el entorno de ejecución devuelve esa plantilla y reporta un error de desarrollo sin duplicados; no reemplaza una traducción mal formada por el texto de origen formateado de nuevo.

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.