Configuración y glosario

Carga la configuraciónCopiar enlace a esta sección

loadConfigCopiar enlace a esta sección

Encuentra, carga y valida la configuración del proyecto, devolviendo una VerbatraConfig. configOverride (validar un objeto en memoria) gana a configPath (cargar un archivo explícito), que gana a una búsqueda desde cwd en el orden de descubrimiento. Un glossary dado como ruta de archivo se lee y valida aquí, así que el código posterior siempre ve un glosario en memoria: un mapa de versión 1 de término de origen a traducción, o una definición de versión 2.

function loadConfig(
  options?: LoadConfigOptions,
): Promise<VerbatraConfig>;

Devuelve: VerbatraConfig

Lanza: CONFIG_NOT_FOUND, CONFIG_INVALID

Ejemplo: Una configuración sin archivo

Consulta el Archivo de configuración para ver el esquema. fs es el puerto del sistema de archivos a través del cual se lee un archivo de glosario, como se describe en El punto de inyección de dependencias.

loadConfigWithMeta Disponible a partir de 0.5.0Copiar enlace a esta sección

La misma carga, más la procedencia: devuelve { config, source, glossary }, donde source dice si la configuración vino de un acierto de búsqueda, de una ruta explícita o de una anulación en memoria (con el filepath absoluto cuando lo hay), y glossary registra si el glosario estaba ausente, en línea o resuelto desde un archivo. Úsalo cuando necesites mostrar de dónde salió la configuración.

function loadConfigWithMeta(
  options?: LoadConfigOptions,
): Promise<LoadedConfig>;

Devuelve: LoadedConfig

Lanza: CONFIG_NOT_FOUND, CONFIG_INVALID

Ambas aceptan fresh: true para volver a evaluar un archivo de configuración en JavaScript o TypeScript en lugar de reutilizar lo que evaluó una carga anterior en el mismo proceso; un proceso de larga duración que recarga la configuración tras una edición lo activa. Las configuraciones JSON, YAML y de package.json siempre se leen de nuevo. Disponible a partir de 0.12.0

configCandidatePaths Disponible a partir de 0.12.0Copiar enlace a esta sección

Lista cada archivo del que loadConfigWithMeta podría leer una configuración con los mismos { cwd?, configPath? }: solo el archivo explícito cuando se indica configPath, y si no, cada lugar de búsqueda en cada directorio de la cadena de búsqueda, el más cercano primero, exista o no. Vigílalas, por ejemplo por fecha de modificación, para notar que una configuración se crea, se edita o se elimina sin cargarla en cada petición. El archivo de glosario no se incluye; loadConfigWithMeta lo nombra en glossary.

function configCandidatePaths(
  options?: ConfigCandidateOptions,
): readonly string[];

Devuelve: readonly string[]

resolveProjectRoot Disponible a partir de 0.12.0Copiar enlace a esta sección

Devuelve la raíz del proyecto contra la que los flujos resuelven rutas relativas: el directorio del archivo de configuración encontrado, así que un proceso iniciado en un subdirectorio trabaja con los archivos de locale, el archivo de bloqueo y .verbatra-local/ del proyecto, o cwd para una configuración de configPath. Un flujo que recibe la configuración que devolvió loadConfig o loadConfigWithMeta ya usa esa raíz como cwd por defecto. Pasa resolveProjectRoot(loaded.source, cwd) como cwd cuando copias o reconstruyes la configuración, y a loadLockFile, loadProvenance y runStatus, que no reciben configuración.

function resolveProjectRoot(
  source: ConfigSource,
  cwd: string,
): string;

Devuelve: string

GlosarioCopiar enlace a esta sección

readGlossaryFile Disponible a partir de 0.9.0Copiar enlace a esta sección

Lee un glosario respaldado por archivo directamente del disco y lo devuelve como un Glossary normalizado: { version, terms, doNotTranslate }, donde version es 1 para un mapa plano de términos y 2 para un glosario por locale, y cada término lleva source, un target opcional, targets, forbidden, caseSensitive y, de forma opcional, note y partOfSpeech. Su entrada glossary es la GlossaryProvenance de loadConfigWithMeta, de modo que el archivo que lee siempre es el que nombra la configuración; no hay ningún argumento de ruta. Úsalo en una herramienta de larga duración que muestre el glosario como está ahora, no como al cargarlo.

function readGlossaryFile(
  input: GlossaryFileInput,
  deps?: GlossaryFileDeps,
): Promise<Glossary>;

Devuelve: Glossary

Lanza: GLOSSARY_NOT_FILE_BACKED, CONFIG_INVALID

Lanza GLOSSARY_NOT_FILE_BACKED cuando el glosario está en línea o ausente, y CONFIG_INVALID cuando el archivo incumple las reglas del archivo de glosario o declara otra versión.

Hasta la 0.11 devolvía el propio mapa plano de términos.

updateGlossaryTerm Disponible a partir de 0.9.0Copiar enlace a esta sección

Añade, cambia o elimina exactamente un término de un glosario respaldado por archivo y devuelve el glosario normalizado tal como queda. translation es el texto nuevo o null para eliminar el término. El resto del archivo conserva su orden de claves y su sangría, la escritura es atómica y todo el ciclo de leer, modificar y escribir se mantiene bajo un bloqueo de glosario para todo el proyecto, así que dos ediciones simultáneas se serializan en vez de entrelazarse.

function updateGlossaryTerm(
  input: UpdateGlossaryTermInput,
  deps?: GlossaryFileDeps,
): Promise<Glossary>;

Devuelve: Glossary

Lanza: GLOSSARY_NOT_FILE_BACKED, CONFIG_INVALID, LOCK_TIMEOUT_INVALID, LOCK_CONTENDED, RUN_CANCELLED, GLOSSARY_UNWRITABLE

También recibe locale (entonces translation es la traducción propia de ese locale y null solo elimina esa), forbidden (las traducciones que locale nunca debe usar; null o [] las elimina), note, partOfSpeech (cada uno null para eliminarlo), caseSensitive y doNotTranslate (true añade el término a los que no se traducen, false lo quita; no se puede combinar con los campos del término). Un archivo de la versión 1 sigue siendo versión 1 mientras la edición solo fije o elimine una traducción para todos los locales; cualquier otra edición lo reescribe como versión 2, y cada término existente conserva su traducción como target. translation: null sin locale ahora elimina solo la traducción compartida; el término en sí se elimina cuando ya no le queda ninguna traducción ni traducción prohibida, lo que en un término de la versión 1 ocurre de inmediato.

Un glosario en línea se rechaza con GLOSSARY_NOT_FILE_BACKED en lugar de convertirse: vive dentro de un módulo de configuración ejecutable. Un campo vacío, una edición que no fija ningún campo o que mezcla doNotTranslate con los campos del término, traducciones prohibidas sin locale, un locale no válido, una edición que dejaría un glosario no válido y una edición cuyo resultado superaría el límite de 1 MiB del glosario se rechazan con CONFIG_INVALID; una escritura fallida, incluido un bloqueo de escritura del glosario que no se puede crear en un proyecto de solo lectura o liberar tras una edición guardada, es GLOSSARY_UNWRITABLE, con el error del sistema de archivos como cause. Una edición que deja el glosario tal como ya está tiene éxito y no escribe nada.

También acepta lockAcquireTimeoutMs, que limita la espera del bloqueo del glosario antes de que la llamada falle con LOCK_CONTENDED (diez minutos por defecto); un límite no válido falla con LOCK_TIMEOUT_INVALID antes de leer nada.

glossaryForLocale Disponible a partir de 0.12.0Copiar enlace a esta sección

Resuelve la parte de un glosario que se aplica a un locale de destino: glossaryForLocale(config.glossary, "de") devuelve { terms, doNotTranslate }, cada término con el target del locale (su propia entrada, luego la de su idioma base, luego la compartida), sus traducciones forbidden, caseSensitive, y su note y partOfSpeech, o undefined cuando nada del glosario se aplica allí. Es exactamente lo que una petición de traducción a ese locale lleva como TranslateRequest.glossary, y lo que ven las comprobaciones de revisión y la huella de caché de ese locale.

function glossaryForLocale(
  glossary: GlossaryInput | Glossary | undefined,
  locale: string,
): LocaleGlossary | undefined;

Devuelve: LocaleGlossary | undefined

glossaryHits Disponible a partir de 0.12.0Copiar enlace a esta sección

glossaryHits({ glossary, locale, sourceLocale, source }) devuelve las entradas del glosario que se aplican a un texto de origen en un locale de destino, como { terms, doNotTranslate } con la forma que devuelve glossaryForLocale: cada término cuyo origen aparece en source como término completo, con la traducción y las traducciones prohibidas a las que está sujeto ese locale, y cada término que se mantiene sin traducir y aparece en él. Un término coincide con o sin mayúsculas según indique, normalizando para sourceLocale. Usa la misma coincidencia que aplica una ejecución de traducción al marcar un término de glosario omitido, y no lee nada.

function glossaryHits(
  input: GlossaryHitsInput,
): LocaleGlossary;

Devuelve: LocaleGlossary

glossaryDraftCheck Disponible a partir de 0.12.0Copiar enlace a esta sección

glossaryDraftCheck({ glossary, locale, sourceLocale, source, draft }) comprueba un borrador de traducción contra las entradas del glosario que glossaryHits encuentra en el texto de origen, antes de que lo escribas. Cada término vuelve con targetUsed (si el borrador lleva la traducción obligatoria; ausente en un término que solo prohíbe traducciones) y forbiddenUsed (las traducciones prohibidas que usa el borrador y no el origen), y cada término que se mantiene sin traducir con kept. Son las reglas con las que una ejecución de traducción marca GLOSSARY_TERM_MISSED y GLOSSARY_FORBIDDEN_TERM. No lee nada.

function glossaryDraftCheck(
  input: GlossaryDraftCheckInput,
): GlossaryDraftCheck;

Devuelve: GlossaryDraftCheck

normalizeGlossary Disponible a partir de 0.12.0Copiar enlace a esta sección

Convierte un glosario en cualquiera de sus formas, un mapa plano de la versión 1 o una definición de la versión 2, al Glossary normalizado que devuelve readGlossaryFile, con todos los valores por defecto rellenados. Úsalo para mostrar un glosario en línea igual que uno respaldado por archivo. No vuelve a validar; loadConfig ya lo hizo.

function normalizeGlossary(
  glossary: GlossaryInput | Glossary,
): Glossary;

Devuelve: Glossary

sharedGlossaryTranslations Disponible a partir de 0.12.0Copiar enlace a esta sección

Proyecta un Glossary normalizado sobre un mapa plano de cada término que tiene un target compartido a esa traducción, en el orden del glosario. Las traducciones por locale, las traducciones prohibidas y los términos de doNotTranslate quedan fuera, así que úsalo solo donde un consumidor no pueda mostrar más que un mapa plano de términos. Un término llamado __proto__ sigue siendo una clave propia.

function sharedGlossaryTranslations(
  glossary: Glossary,
): Readonly<Record<string, string>>;

Devuelve: Readonly<Record<string, string>>

redactGlossary Disponible a partir de 0.12.0Copiar enlace a esta sección

Pasa cada término de origen, traducción, traducción prohibida, nota, categoría gramatical y término de doNotTranslate de un Glossary normalizado por redact y devuelve { glossary, redactedTerms }, donde redactedTerms nombra cada término al que se le sustituyó un valor, un término de origen redactado como [REDACTED], para que la lista nunca repita un secreto. El servidor MCP y Studio lo usan antes de que un glosario salga del proceso; úsalo igual en tu propia herramienta.

function redactGlossary(glossary: Glossary): RedactedGlossary;

Devuelve: RedactedGlossary

readCurrentGlossary Disponible a partir de 0.12.0Copiar enlace a esta sección

Lee el glosario que nombra una configuración cargada tal como está ahora: readCurrentGlossary({ loaded }), donde loaded es lo que devuelve loadConfigWithMeta. Un glosario respaldado por archivo se lee directamente del disco, uno en línea sale de la configuración, y en ambos casos el resultado es el Glossary normalizado, o undefined cuando la configuración no declara ninguno. Para ver a qué está sujeto un locale de destino, pasa el resultado a glossaryForLocale.

function readCurrentGlossary(
  input: ReadCurrentGlossaryInput,
  deps?: GlossaryFileDeps,
): Promise<Glossary | undefined>;

Devuelve: Glossary | undefined

Lanza: CONFIG_INVALID

editConfiguredGlossaryTerm Disponible a partir de 0.12.0Copiar enlace a esta sección

updateGlossaryTerm para una herramienta que tiene una configuración cargada: recibe loaded en lugar de glossary con los mismos campos de edición, trata un campo dejado en undefined como ausente y comprueba primero locale contra los locales de destino configurados; si no es uno de ellos, falla con UNKNOWN_LOCALE y no escribe nada. El servidor MCP y Studio escriben el glosario a través de ella.

function editConfiguredGlossaryTerm(
  input: EditConfiguredGlossaryTermInput,
  deps?: GlossaryFileDeps,
): Promise<Glossary>;

Devuelve: Glossary

Lanza: UNKNOWN_LOCALE, GLOSSARY_NOT_FILE_BACKED, CONFIG_INVALID, LOCK_TIMEOUT_INVALID, LOCK_CONTENDED, RUN_CANCELLED, GLOSSARY_UNWRITABLE

Escritura, detección y modo solo humanoCopiar enlace a esta sección

defineConfigCopiar enlace a esta sección

Un ayudante de identidad para un verbatra.config.ts tipado: devuelve su argumento sin cambios, para la inferencia de tipos y el autocompletado del editor, incluidos los IDs de modelo conocidos del proveedor seleccionado (solo al escribir; en tiempo de ejecución pasa cualquier cadena no vacía). Cada proveedor salvo opencode, openai-compatible, libretranslate y none tiene además una sobrecarga que recibe AuthoringConfigFor<"<id>">, como AuthoringConfigFor<"anthropic">, que restringe el bloque provider a las opciones de ese proveedor; esos cuatro usan la alternativa con AuthoringConfig de abajo.

function defineConfig(config: AuthoringConfigFor<"anthropic">): VerbatraConfigInput;
function defineConfig(config: AuthoringConfigFor<"openai">): VerbatraConfigInput;
function defineConfig(config: AuthoringConfigFor<"gemini">): VerbatraConfigInput;
function defineConfig(config: AuthoringConfigFor<"deepl">): VerbatraConfigInput;
function defineConfig(config: AuthoringConfigFor<"google-translate">): VerbatraConfigInput;
function defineConfig(config: AuthoringConfig): VerbatraConfigInput;

Devuelve: VerbatraConfigInput

Ejemplo: Añade un archivo fuente y una configuración

verbatraConfigSchemaCopiar enlace a esta sección

El esquema zod con el que valida loadConfig, exportado para que tu propia herramienta pueda validar un objeto de configuración igual que lo hace el SDK. Las claves desconocidas de nivel superior se rechazan, así que un secreto extraviado no puede esconderse en la configuración, salvo $schema: una cadena opcional, ignorada en tiempo de ejecución, con la que una configuración JSON o YAML apunta un editor al @verbatra/sdk/config-schema.json del paquete.

const verbatraConfigSchema: z.ZodObject<{ ... }, z.core.$strict>;

Su bloque rates es una RateCard, la lista de precios que convierte una estimación en dinero:

scaffoldingMetadata Disponible a partir de 0.4.0Copiar enlace a esta sección

Metadatos de solo lectura de los que el comando init de la CLI deriva sus preguntas: providerEnv (de id de proveedor a la variable de entorno de la que se lee su clave), scaffoldModels (un modelo de scaffold por defecto por proveedor LLM), providerTokenLimitKeys (la clave de opción bajo la que cada proveedor LLM recibe su límite de tokens de salida) y supportedFormats (el conjunto cerrado de ids de formato). Lee la clave del límite de tokens de providerTokenLimitKeys en lugar de suponer una, porque las claves difieren (proveedores); DeepL y Google Cloud Translation no tienen entrada porque no reciben límite de tokens. El tipo ScaffoldableProviderId es Exclude<ProviderId, "openai-compatible" | "libretranslate" | "none">: todos los proveedores que solo necesitan su id. openai-compatible y libretranslate necesitan cada uno una baseUrl que solo tú conoces y no tienen variable de entorno obligatoria, y none no llama a ningún proveedor.

const scaffoldingMetadata: {
  readonly providerEnv: { ... };
  readonly scaffoldModels: { ... };
  readonly providerTokenLimitKeys: { ... };
  readonly supportedFormats: readonly [...];
  readonly humanOnlyProviderId: "none";
  readonly openAiCompatibleKeyEnv: "OPENAI_COMPATIBLE_API_KEY";
  readonly libreTranslateKeyEnv: "LIBRETRANSLATE_API_KEY";
  readonly configSearchPlaces: readonly string[];
};

scaffoldingMetadata.humanOnlyProviderId es "none", el id que desactiva la traducción automática. No tiene entrada en providerEnv, porque no lee ninguna clave.

scaffoldingMetadata.libreTranslateKeyEnv es "LIBRETRANSLATE_API_KEY", la variable de la que un proveedor libretranslate lee su clave. Es opcional: un servidor iniciado sin --api-keys no necesita ninguna, así que un generador debería dejarla sin definir.

scaffoldingMetadata.openAiCompatibleKeyEnv es "OPENAI_COMPATIBLE_API_KEY", la variable que lee un proveedor openai-compatible cuando sus opciones no nombran ningún apiKeyEnvVar. scaffoldingMetadata.configSearchPlaces lista cada nombre de archivo que loadConfig busca como configuración, en el orden en que los comprueba; un generador que escribe verbatra.config.ts debería negarse cuando ya existe otro de ellos, porque gana el primero que se encuentra.

detectProject Disponible a partir de 0.12.0Copiar enlace a esta sección

Detecta el formato de los archivos de locale de un proyecto y su estructura a partir de sus archivos, igual que hace verbatra init antes de escribir una configuración. No escribe nada y no llama a ningún proveedor. Recorre el directorio (saltándose los directorios ocultos, node_modules y la salida de compilación, dentro de una profundidad y un número de entradas acotados) en busca de archivos que reclame un adaptador registrado, encuentra en cada uno el segmento de la ruta que escribe un locale, y se queda con el patrón de archivo que cubre más locales. El formato es aquel cuyo adaptador reclama con canHandle cada archivo encontrado según su contenido; para JSON, donde todos los adaptadores JSON lo hacen, decide una única biblioteca de i18n coincidente en package.json.

function detectProject(
  input?: DetectProjectInput,
  deps?: DetectProjectDeps,
): Promise<ProjectDetection>;

Devuelve: ProjectDetection

import { detectProject } from "@verbatra/sdk";

const detection = await detectProject({ cwd: "/path/to/project" });
if (detection.ambiguities.length > 0) {
  // several formats or file patterns fit: choose one of detection.ambiguities[0].candidates
}
const format = detection.format?.id;          // for example "yaml"
const pattern = detection.layout?.pattern;    // for example "config/locales/{locale}.yml"

El resultado lleva format (con from: input, files o dependencies), layout (pattern, localeStyle, locales, sourceLocale, files, unqualifiedSourceFile), ambiguities (cada una con un subject de format o layout y sus candidates), una confidence de high, medium, low o none, y reasons, una frase por decisión. Los empates se informan como ambigüedades, nunca se adivinan. Las entradas opcionales format, pattern y sourceLocale acotan la búsqueda, y deps.fs y deps.adapterRegistry sustituyen el sistema de archivos y los adaptadores, así que también se detectan los archivos de un adaptador de terceros. Un archivo ausente, ilegible o malformado nunca lanza; solo deja el informe más escueto. layout.unqualifiedSourceFile nombra un archivo junto al layout con cadenas sin nombre de locale, como messages.properties o una plantilla .pot de gettext; entonces el locale de origen queda abierto, ya que el origen se lee del archivo que el patrón nombra para él.

isMachineTranslationEnabled Disponible a partir de 0.12.0Copiar enlace a esta sección

Devuelve false exactamente cuando la configuración fija provider: { id: "none" }, el modo solo humano en el que nunca se construye un proveedor ni se lee una clave de API. Una interfaz que ofrece acciones que gastan en el proveedor lo lee para omitirlas por completo; así es como Studio y el servidor MCP retienen el gasto incluso con --allow-spend.

function isMachineTranslationEnabled(
  config: Pick<VerbatraConfig, "provider">,
): boolean;

Devuelve: boolean

assertMachineTranslationEnabled Disponible a partir de 0.12.0Copiar enlace a esta sección

Recibe la configuración y una frase corta que nombra la acción, y lanza un SdkError MACHINE_TRANSLATION_DISABLED con provider: { id: "none" }. Llámalo antes de envolver translate en una acción explícita de "traducir todo lo pendiente", para que la acción falle igual que retranslateEntry en lugar de rellenar en silencio solo desde la memoria de traducción.

function assertMachineTranslationEnabled(
  config: Pick<VerbatraConfig, "provider">,
  action: string,
): void;

Devuelve: void

Lanza: MACHINE_TRANSLATION_DISABLED

assertTargetLocale Disponible a partir de 0.12.0Copiar enlace a esta sección

Recibe la configuración y un locale, y lanza un SdkError UNKNOWN_LOCALE cuando el locale no está entre los targetLocales configurados, con el mismo mensaje que usa cada función del SDK que acepta un filtro locales. Llámalo en una superficie que recibe un único locale propio, como hace glossary.get del servidor MCP, para que un locale incorrecto falle igual que en el SDK.

function assertTargetLocale(
  config: Pick<VerbatraConfig, "targetLocales">,
  locale: string,
): void;

Devuelve: void

Lanza: UNKNOWN_LOCALE