Extraer y cargar catálogos de mensajes

Extrae los mensajes de origen, recupera un archivo JSONC traducido y crea un mapa para el entorno de ejecución con los metadatos de origen correspondientes.

Un componente contiene el mensaje de origen y su contexto. La extracción recopila esas llamadas en un archivo que se puede traducir. La carga vincula los valores traducidos con las claves del componente. Esta guía muestra cómo procesar el primer saludo mediante ese flujo de trabajo basado en archivos y generar el mapa Messages que necesita un proveedor.

Extraer el origen #

Instala la CLI y las dependencias del cargador en la aplicación:

sh
npm install --save-dev @lingo.dev/cli@latest
npm install @lingo.dev/spec@1.17.1 jsonc-parser
npx lingo extract --src src --source-locale en

La extracción se ejecuta en local y no necesita una clave de API. Por defecto, escribe locales/en.jsonc y lingo.d.ts. Los indicadores explícitos --out y --types tienen prioridad sobre los valores configurados de i18n.messagesPath y i18n.typesPath, que a su vez prevalecen sobre los valores predeterminados. Una aplicación Pages con llamadas fuera de src utiliza su directorio real, como --src pages.

Comprueba la entrada del saludo. Su valor es la plantilla completa en inglés; la clave se deriva del origen y del contexto. Los comentarios que preceden a la entrada registran @context para el significado, @src para la ubicación en el código fuente y @orphan cuando una entrada extraída anteriormente ya no está activa. Revisa esos cambios antes de solicitar traducciones.

Traducir el catálogo seleccionado #

Si la aplicación no tiene una configuración de Lingo.dev, inicializa este archivo concreto y el español como idioma de destino. Después, autentícate y vincula un motor de localización:

sh
npx lingo init --source en --targets es --files 'locales/en.jsonc' --yes
npx lingo login
npx lingo link

Necesitas acceso a un motor de localización habilitado y suficiente cuota de uso disponible en la cuenta. Autenticación de la CLI explica qué credenciales usar para las ejecuciones desatendidas.

Si .lingo/config.json ya existe, conserva su vinculación y las demás entradas de archivos. Añade o actualiza la entrada que selecciona locales/en.jsonc y confirma que el idioma de origen del proyecto es en. Si ya tienes una base de referencia, completa las actualizaciones habituales de los idiomas de destino existentes con npx lingo push --wait, resuelve cualquier revisión pendiente o fallo y comprueba los cambios recuperados antes de añadir es a targetLocales. Mantén fija la revisión del origen durante el proceso posterior de recuperación de los archivos que faltan. Añadir un idioma explica este orden. No uses init --force para editar la configuración: reconstruye las entradas de archivos y puede descartar opciones avanzadas. Configuración describe la estructura completa.

Si el proyecto es nuevo, o si ya has completado la preparación del proyecto existente, solicita los archivos de destino que faltan y espera a que se recuperen. No modifiques los archivos de destino mientras el comando espera, ya que el proceso de descarga puede sobrescribir los cambios locales:

sh
npx lingo push --backfill-missing --wait

Cuando termine la ejecución, comprueba locales/es.jsonc. Resuelve cualquier estado de revisión o fallo notificado antes de dar el resultado por completo. Para los cambios posteriores en el origen, vuelve a ejecutar la extracción y usa npx lingo push --wait; la recuperación de archivos que faltan no sirve para las actualizaciones habituales de un destino existente.

Conservar los metadatos de origen junto con la revisión de destino #

El flujo de trabajo general de traducción de JSONC conserva las marcas @orphan del origen en el destino, pero elimina sus comentarios @context y @src. Por sí solo, un archivo de destino no permite al cargador saber a qué página pertenecía un mensaje.

Conserva el archivo de origen extraído de la misma revisión que el destino. Selecciona las entradas activas de ese origen y vincula sus claves con los valores traducidos del destino. Así se excluyen los mensajes eliminados y se mantiene la posibilidad de seleccionar por ruta de origen. Las claves que faltan en el destino siguen ausentes, lo que permite recurrir al texto de origen en el entorno de ejecución.

Analizar un catálogo sin procesar #

Crea src/catalog.ts con este cargador propio de la aplicación:

ts
import { parse, type ParseError } from "jsonc-parser";
import { getActiveEntries, readLocaleFile, type LocaleEntry } from "@lingo.dev/spec";
import type { Messages } from "@lingo.dev/react";

function readStringCatalog(raw: string) {
  const errors: ParseError[] = [];
  const value: unknown = parse(raw, errors, { allowTrailingComma: true });
  if (
    errors.length > 0 ||
    value === null ||
    typeof value !== "object" ||
    Array.isArray(value) ||
    Object.values(value).some((entry) => typeof entry !== "string")
  ) {
    throw new Error("Expected a flat JSONC object with string values");
  }
  return readLocaleFile(raw);
}

export function loadMatchedMessages(
  sourceJsonc: string,
  targetJsonc: string,
  include: (entry: LocaleEntry) => boolean = () => true,
): Messages {
  const active = getActiveEntries(readStringCatalog(sourceJsonc).entries);
  const target = new Map(readStringCatalog(targetJsonc).entries.map((entry) => [entry.key, entry.value]));
  return Object.fromEntries(
    active.filter(include).flatMap((entry) => {
      const value = target.get(entry.key);
      return value === undefined ? [] : [[entry.key, value]];
    }),
  );
}

readLocaleFile analiza la sintaxis y los metadatos de JSONC, pero no valida la estructura en tiempo de ejecución. Acepta matrices y valores que no son cadenas pese al tipo de entrada declarado, y no devuelve entradas si el elemento raíz es un valor primitivo o nulo. La primera función mostrada arriba rechaza esas estructuras antes de que los valores lleguen al renderizador. Ambas funciones son locales y no realizan operaciones de E/S.

En una aplicación Vite, carga los archivos como texto sin procesar en el módulo que suministra los datos al proveedor:

ts
import source from "../locales/en.jsonc?raw";
import target from "../locales/es.jsonc?raw";
import { loadMatchedMessages } from "./catalog";

export const spanishMessages = loadMatchedMessages(source, target);

Se presupone que el módulo está directamente en src y que se incluyen los tipos de cliente de Vite. Pasa spanishMessages como messages con locale="es". El saludo debería usar ahora la plantilla en español recuperada y seguir sustituyendo {name} por Ana. Comprueba la redacción y prueba qué ocurre cuando faltan entradas; cargar un archivo no es lo mismo que evaluar su calidad lingüística.

Seleccionar solo las entradas de origen que necesita una ruta #

El predicado opcional include se ejecuta sobre las entradas activas del origen antes de vincularlas con el destino. Un cargador de página puede usar entry.metadata.src para incluir sus propias llamadas y los componentes compartidos. Haz esa selección en el origen, donde aún se conservan los metadatos. Mantén el origen y el destino juntos al desplegar para que la selección por ruta no utilice claves de otra revisión.

La guía de Next Pages proporciona un predicado de ruta completo. La guía de TanStack utiliza este cargador para su catálogo de solicitud. Sus cargadores integrados pueden filtrar archivos que contienen metadatos, pero ninguno vincula automáticamente los destinos sin comentarios con los metadatos de origen.

Referencia de las funciones auxiliares de la especificación #

ExportaciónContrato
readLocaleFile(content): LocaleFileAnaliza JSONC, incluidas las comas finales y los comentarios de bloque de metadatos que preceden a las entradas; los errores de sintaxis lanzan excepciones.
getActiveEntries(entries): LocaleEntry[]Conserva las entradas en las que metadata.orphan no se evalúa como verdadero.
LocaleFile{ entries: LocaleEntry[] }.
LocaleEntry{ key: string; value: string; metadata: EntryMetadata }.
EntryMetadatacontext, src y orphan opcionales.
computeKey(source, context?)Identidad normalizada compartida del origen y el contexto, también exportada por React.
buildIcuPlural(forms)Genera las categorías cardinales conocidas en orden canónico.
buildIcuSelect(forms)Genera alternativas con las claves ordenadas.

Los constructores ICU aceptan registros de cadenas; los tipos plural y select de React añaden su forma obligatoria other. El catálogo resultante para el entorno de ejecución es un mapa Messages simple, no un LocaleFile.

Los recursos existentes con claves, los documentos y los módulos estáticos de idiomas en TypeScript utilizan sus propios gestores de formato en lugar de esta guía de extracción. Los proyectos de ejemplo muestran esas estructuras junto con aplicaciones React.