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 reúne esas llamadas en un archivo que se puede traducir. La carga vuelve a vincular los valores traducidos con las claves del componente. Esta guía recorre ese flujo de trabajo con archivos a partir del primer saludo y genera el mapa Messages que necesita un proveedor.
Extraer el origen #
Instala las dependencias de la CLI y del cargador en la aplicación:
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 enLa extracción se ejecuta localmente y no requiere una clave de API. De forma predeterminada, escribe locales/en.jsonc y lingo.d.ts. Las opciones explícitas --out y --types tienen prioridad sobre los valores configurados en i18n.messagesPath y i18n.typesPath, que a su vez tienen prioridad sobre los valores predeterminados. Una aplicación de Pages con llamadas fuera de src usa el directorio donde se encuentran, como --src pages.
Inspecciona 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 la preceden registran @context para el significado, @src para la ubicación en el código de origen y @orphan cuando una entrada extraída anteriormente ya no está activa. Revisa esos cambios antes de solicitar traducciones.
Traducir el catálogo seleccionado #
Para una aplicación sin configuración de Lingo.dev, inicializa exactamente este archivo y define el español como idioma de destino; luego autentícate y vincula un motor de localización:
npx lingo init --source en --targets es --files 'locales/en.jsonc' --yes
npx lingo login
npx lingo linkNecesitas acceso a un motor de localización habilitado y suficiente cuota de uso en tu cuenta. Autenticación de la CLI explica las credenciales para ejecuciones sin supervisión.
Si .lingo/config.json ya existe, conserva su vinculación y las demás entradas de archivos. Agrega o actualiza la entrada que selecciona locales/en.jsonc y confirma que el idioma de origen del proyecto sea en. Si ya cuentas con una versión de referencia, completa las actualizaciones habituales de los idiomas de destino existentes con npx lingo push --wait, resuelve cualquier revisión pendiente o error e inspecciona los cambios recuperados antes de agregar es a targetLocales. Mantén fija la revisión del origen durante la posterior carga retroactiva. Agregar 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.
Para un proyecto nuevo, o después de completar esa preparación en un proyecto existente, solicita los archivos de destino faltantes y espera a que se recuperen. No modifiques los archivos de destino mientras el comando espera, porque su proceso de descarga puede sobrescribir los cambios locales:
npx lingo push --backfill-missing --waitCuando termine la ejecución, inspecciona locales/es.jsonc. Resuelve cualquier estado de revisión o error informado antes de dar el resultado por completo. Para cambios posteriores en el origen, vuelve a extraer y usa npx lingo push --wait; la carga de archivos faltantes sirve para recuperar archivos que no existen, no para realizar 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. El destino por sí solo no puede indicarle a un cargador 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. Esto excluye los mensajes eliminados y mantiene la posibilidad de seleccionar por ruta de origen. Las claves de destino faltantes permanecen ausentes, lo que permite que el entorno de ejecución recurra al origen como alternativa.
Analizar un catálogo sin procesar #
Crea src/catalog.ts con este cargador propio de la aplicación:
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 arreglos y valores que no son cadenas a pesar del tipo de entrada declarado, y no devuelve entradas cuando la 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 de Vite, carga los archivos como texto sin procesar en el módulo que suministra los datos al proveedor:
import source from "../locales/en.jsonc?raw";
import target from "../locales/es.jsonc?raw";
import { loadMatchedMessages } from "./catalog";
export const spanishMessages = loadMatchedMessages(source, target);Esto supone que el módulo está directamente dentro de src y que se incluyen los tipos de cliente de Vite. Pasa spanishMessages como messages con locale="es". Ahora el saludo debería usar la plantilla en español recuperada y seguir reemplazando {name} por Ana. Revisa la redacción y prueba qué ocurre cuando faltan entradas; cargar un archivo y evaluar su calidad lingüística son tareas distintas.
Seleccionar solo las entradas de origen que necesita una ruta #
El predicado opcional include se ejecuta sobre las entradas activas del origen antes de la vinculación. 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 use claves de otra revisión.
La guía de Next Pages proporciona un predicado de ruta completo. La guía de TanStack usa este cargador para el catálogo de cada solicitud. Sus cargadores integrados pueden filtrar archivos con metadatos, pero ninguno vincula automáticamente los destinos sin comentarios con los metadatos de origen.
Referencia de funciones auxiliares de especificación #
| Exportación | Contrato |
|---|---|
readLocaleFile(content): LocaleFile | Analiza JSONC, incluidas las comas finales y los comentarios de bloque con metadatos que preceden a las entradas; los errores de sintaxis generan excepciones. |
getActiveEntries(entries): LocaleEntry[] | Conserva las entradas cuyo valor metadata.orphan no se evalúa como verdadero. |
LocaleFile | { entries: LocaleEntry[] }. |
LocaleEntry | { key: string; value: string; metadata: EntryMetadata }. |
EntryMetadata | context, src y orphan opcionales. |
computeKey(source, context?) | Identidad normalizada y compartida de origen/contexto, también exportada por React. |
buildIcuPlural(forms) | Genera las categorías cardinales conocidas en orden canónico. |
buildIcuSelect(forms) | Genera alternativas con claves ordenadas. |
Los constructores de ICU aceptan registros de cadenas; los tipos plural y select de React agregan su forma other obligatoria. 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 usan sus propios controladores de formato en lugar de esta guía de extracción. Los proyectos de ejemplo muestran esas estructuras junto con aplicaciones de React.