@trazum/core 1.8.0

package/src/host.ts

@@ -0,0 +1,90 @@
+/**
+ * Which tool Trazum is running inside.
+ *
+ * On the Node entry point rather than the browser-safe one, because it reads the
+ * process environment. Nothing about the optimisation changes with the answer —
+ * the same prompt optimises the same way everywhere, as it must, and that is a
+ * standing constraint rather than a coincidence.
+ *
+ * What the answer earns is the right to stop quoting a monthly dollar saving to
+ * somebody on a flat-rate plan. Inside Cursor or a Claude Code subscription the
+ * per-call saving is real arithmetic about tokens and **not money anybody gets
+ * back**, and "$184/month" is wrong in the direction that matters most.
+ */
+
+export interface HostEnvironment {
+  id: string;
+  displayName: string;
+  /**
+   * How the host bills.
+   *
+   * `unknown` is honest rather than lazy: a VS Code terminal says nothing about
+   * whether the prompts written in it go to a metered API or a subscription, and
+   * guessing either way would be worse than saying so.
+   */
+  billing: 'per-token' | 'subscription' | 'unknown';
+  /** The variable that gave it away, so the answer is checkable rather than magic. */
+  evidence: string | null;
+}
+
+/**
+ * Hosts recognised by an environment variable they set.
+ *
+ * A miss is harmless: it falls through to `terminal` and nothing changes. That
+ * asymmetry is why the list can include entries verified only by documentation
+ * rather than by running under them — the cost of a wrong row is a detection
+ * that never fires, not a wrong report.
+ *
+ * Ordered most-specific first. Cursor is a VS Code fork and sets
+ * `TERM_PROGRAM=vscode` as well, so a VS Code row above it would swallow every
+ * Cursor session.
+ */
+const HOSTS: Array<{
+  id: string;
+  displayName: string;
+  billing: HostEnvironment['billing'];
+  test: (env: NodeJS.ProcessEnv) => string | null;
+}> = [
+  {
+    id: 'claude-code',
+    displayName: 'Claude Code',
+    billing: 'subscription',
+    test: (e) => (e.CLAUDECODE ? 'CLAUDECODE' : null),
+  },
+  {
+    id: 'codex',
+    displayName: 'Codex',
+    billing: 'subscription',
+    test: (e) => (e.CODEX_SANDBOX ? 'CODEX_SANDBOX' : e.CODEX_HOME ? 'CODEX_HOME' : null),
+  },
+  {
+    id: 'cursor',
+    displayName: 'Cursor',
+    billing: 'subscription',
+    test: (e) => (e.CURSOR_TRACE_ID ? 'CURSOR_TRACE_ID' : null),
+  },
+  {
+    id: 'github-actions',
+    displayName: 'GitHub Actions',
+    billing: 'per-token',
+    test: (e) => (e.GITHUB_ACTIONS ? 'GITHUB_ACTIONS' : null),
+  },
+  { id: 'ci', displayName: 'CI', billing: 'per-token', test: (e) => (e.CI ? 'CI' : null) },
+  {
+    id: 'vscode',
+    displayName: 'VS Code',
+    billing: 'unknown',
+    test: (e) => (e.TERM_PROGRAM === 'vscode' ? 'TERM_PROGRAM' : null),
+  },
+];
+
+/** The host, or a plain terminal when nothing identifies itself. */
+export function detectHost(env: NodeJS.ProcessEnv = process.env): HostEnvironment {
+  for (const host of HOSTS) {
+    const evidence = host.test(env);
+    if (evidence !== null) {
+      return { id: host.id, displayName: host.displayName, billing: host.billing, evidence };
+    }
+  }
+  return { id: 'terminal', displayName: 'terminal', billing: 'unknown', evidence: null };
+}

package/src/i18n/en.ts

@@ -0,0 +1,236 @@
+import type { CoreMessages } from './types.js';
+
+const n = (value: number): string => value.toLocaleString('en-US');
+
+/** English catalogue. This is the source of truth every other locale mirrors. */
+export const en: CoreMessages = {
+  locale: 'en',
+  numberLocale: 'en-US',
+
+  rules: {
+    'duplicate-blocks': {
+      title: 'Repeated paragraphs',
+      rationale:
+        'Removes whole paragraphs that already appear earlier in the prompt. Common when prompts are assembled by concatenating templates: the same block of instructions goes in twice and is paid for twice.',
+    },
+    'near-duplicate-blocks': {
+      title: 'Near-identical paragraphs',
+      rationale:
+        'Removes paragraphs sharing 92% or more of their words with an earlier one, catching instructions reworded to say the same thing twice. Aggressive level: read the diff, because the 8% that differs may be exactly the nuance you cared about.',
+    },
+    'duplicate-lines': {
+      title: 'Repeated lines',
+      rationale:
+        'Removes lines identical to one that appeared earlier, ignoring case, accents and punctuation. Only touches lines of 25 characters or more, so bullets and legitimate separators survive.',
+    },
+    'verbose-phrases': {
+      title: 'Wordy phrasing',
+      rationale:
+        'Replaces long constructions with their short equivalent ("in order to" → "to", "con el fin de" → "para"). The meaning is identical; only the token count changes.',
+    },
+    politeness: {
+      title: 'Politeness formulas',
+      rationale:
+        'Strips "please", "thank you", "kindly", "por favor"... The model does not answer better for being asked nicely, and every formula is paid for on every call.',
+    },
+    filler: {
+      title: 'Filler and throat-clearing',
+      rationale:
+        'Removes empty openers such as "basically", "it is important to note that" or "cabe destacar que", which carry no instruction.',
+    },
+    hedges: {
+      title: 'Hedging',
+      rationale:
+        'Removes "I think", "in my opinion", "creo que". Inside an instruction they weaken the request without adding information.',
+    },
+    intensifiers: {
+      title: 'Intensifiers',
+      rationale:
+        'Strips "very", "really", "extremely", "muy"... They rarely change the task. Aggressive level because in a specific prompt the nuance can matter.',
+    },
+    'self-check': {
+      title: 'Self-verification instructions',
+      rationale:
+        'Removes "double-check your work", "verifica tu respuesta". Current models already verify their own output; asking explicitly triggers extra steps paid for in output tokens. Disable this rule if your workflow depends on that verification.',
+    },
+    emphasis: {
+      title: 'Shouted emphasis',
+      rationale:
+        'Lowercases shouted words (MUST, NEVER, CRITICAL) and drops prefixes like "IMPORTANT:". Uppercase splits into more tokens than lowercase, and on current models excessive emphasis makes the instruction over-trigger.',
+    },
+    decoration: {
+      title: 'Decorative separators',
+      rationale:
+        'Removes lines made only of repeated characters (====, ----, ****) and runs of exclamation marks. They add no structure the model uses and cost tokens on every call.',
+    },
+    whitespace: {
+      title: 'Stray whitespace',
+      rationale:
+        'Trims trailing spaces, collapses repeated spaces inside a line and reduces consecutive blank lines to one. Leading indentation is preserved so lists and nested markdown keep working.',
+    },
+  },
+
+  llm: {
+    emptyResponse: () => 'The model returned an empty response.',
+    protectedContentAltered: (count) =>
+      `The model altered ${count} protected fragment(s) (code, URL or template placeholder). Discarded so the prompt is not broken.`,
+    notShorter: (after, before) =>
+      `The result is not shorter (${after} vs ${before} tokens). Keeping the deterministic version.`,
+    suspiciousShrink: (retainedPct) =>
+      `The result keeps only ${retainedPct}% of the tokens. That looks like a summary rather than compression: review it by hand before using it.`,
+  },
+
+  suggest: {
+    'not-found': () =>
+      'the quoted phrase is not in the prompt — the model paraphrased what it was copying',
+    'touches-protected': () =>
+      'it would edit code, a URL, a placeholder or a tag, which are copied verbatim',
+    'introduces-protected': () => 'the replacement adds a placeholder or URL that was not there',
+    'no-saving': () => 'it is no shorter than what it replaces',
+    overlaps: () => 'it shares text with a suggestion already accepted',
+  },
+
+  advisories: {
+    contextOverflow: ({ tokens, modelName, contextWindow }) => ({
+      title: 'The prompt does not fit in the context window',
+      detail: `The optimised prompt is ~${n(tokens)} tokens and ${modelName} accepts ${n(contextWindow)}. The call will fail: split the content or move to a model with a larger window.`,
+    }),
+
+    promptCaching: ({
+      placeholder,
+      prefixTokens,
+      totalTokens,
+      minTokens,
+      modelName,
+      hitRatePct,
+      readPct,
+      writePct,
+      explicit,
+    }) => {
+      const scope = placeholder
+        ? `The stable prefix — everything before the first placeholder ${placeholder} — is ~${n(prefixTokens)} of the prompt's ${n(totalTokens)} tokens, and clears ${modelName}'s ${n(minTokens)}-token cacheable minimum.`
+        : `The prompt has no variable placeholders, so the whole thing is a cacheable prefix and it clears ${modelName}'s ${n(minTokens)}-token minimum.`;
+      const how = explicit
+        ? 'Put the cache marker at the end of the stable prefix: any byte that changes before the cut invalidates everything after it.'
+        : `${modelName} caches automatically above its minimum, so there is nothing to set — but the same rule applies: any byte that changes before the cut invalidates everything after it.`;
+      return {
+        title: 'Turn on prompt caching for the stable prefix',
+        detail: `${scope} At a ${hitRatePct}% hit rate, a cache read costs ${readPct}% of the input price and a write costs ${writePct}%. ${how}`,
+      };
+    },
+
+    promptCachingNotWorthIt: () => ({
+      title: 'At that hit rate, caching does not pay off',
+      detail:
+        'A cache write costs 125% of the input price and a read costs 10%. Below roughly a 28% hit rate you pay more than you save. Either raise prefix reuse or leave caching off.',
+    }),
+
+    belowCacheMinimum: ({
+      modelName,
+      minTokens,
+      placeholder,
+      prefixTokens,
+      totalTokens,
+      mentionLowerMinimum,
+    }) => {
+      const reason = placeholder
+        ? `here the first variable placeholder (${placeholder}) shows up at ~${n(prefixTokens)} tokens and only what precedes it can be cached`
+        : `this prompt has ~${n(totalTokens)}`;
+      return {
+        title: 'Below the cacheable minimum',
+        detail:
+          `${modelName} needs at least ${n(minTokens)} prefix tokens to cache; ${reason}. Setting cache_control will not error, it simply will not cache.` +
+          (mentionLowerMinimum
+            ? ' Claude Opus 5 lowers that minimum to 512 tokens, so short prompts that miss here would cache there.'
+            : ''),
+      };
+    },
+
+    cachePrefixReorder: ({ staticTokensAfter, sharePct, placeholder }) => ({
+      title: 'Move the stable instructions ahead of the first placeholder',
+      detail: `About ~${n(staticTokensAfter)} tokens of stable content (${sharePct}% of the prompt) sit after the first variable placeholder ${placeholder}, so today they never get cached. Reorder the template — fixed instructions and context first, placeholders last — and that content starts being read from cache at 10% of the price. Check that reordering does not change what the prompt asks for.`,
+    }),
+
+    batchApi: () => ({
+      title: 'If the work tolerates latency, use the Batch API',
+      detail:
+        'The Batch API applies a 50% discount on both input and output. Most batches finish in under an hour, with a 24-hour maximum. It fits bulk classification, data enrichment or evaluations: anything that is not answering a user in real time.',
+    }),
+
+    modelDowngrade: ({ modelName, tier, candidateName, currentUsd, candidateUsd }) => ({
+      title: `This task may not need ${modelName}`,
+      detail: `By length and vocabulary the prompt looks like "${tier}" complexity. On ${candidateName} you would go from ${currentUsd} to ${candidateUsd} per month. This is a keyword heuristic, not a judgement about answer quality: measure the difference with your own evaluations before switching in production.`,
+    }),
+
+    outputDominated: ({ outputUsd, inputUsd }) => ({
+      title: 'Your cost is in the output, not the prompt',
+      detail: `Output accounts for ${outputUsd} per month against ${inputUsd} of input. Shortening the prompt has a low ceiling here. The two controls that move the needle are the effort parameter (lower it when the task is not reasoning-heavy) and explicitly asking for concise answers.`,
+    }),
+
+    promoPricing: ({ modelName, promoInput, promoOutput, until, listInput, listOutput }) => ({
+      title: 'You are costing this with promotional pricing',
+      detail: `${modelName} has introductory pricing of ${promoInput}/${promoOutput} per million tokens until ${until}. After that date it moves to ${listInput}/${listOutput}: your bill goes up even if you change nothing.`,
+    }),
+
+    contradictoryInstructions: ({
+      axis,
+      firstValue,
+      firstSnippet,
+      secondValue,
+      secondSnippet,
+      otherCount,
+    }) => ({
+      title: `Two instructions disagree about ${axis}`,
+      detail:
+        `One says ${firstValue} ("${firstSnippet}") and another says ${secondValue} ("${secondSnippet}"). ` +
+        'The model has to pick one, and which one it picks can change between calls — so this is a correctness problem before it is a cost one. ' +
+        'Deleting the instruction you did not mean also shortens the prompt.' +
+        (otherCount > 0
+          ? ` ${otherCount} other ${otherCount === 1 ? 'pair' : 'pairs'} of instructions disagree too.`
+          : ''),
+    }),
+
+    redundantExamples: ({ redundantCount, totalCount, redundantTokens, topSimilarityPct }) => ({
+      title: `${redundantCount} of ${totalCount} examples repeat an earlier one`,
+      detail:
+        `They share ${topSimilarityPct}% or more of their wording with an example that comes before them, and account for about ${n(redundantTokens)} tokens paid for on every call. ` +
+        'Few-shot examples earn their cost by teaching something new; two that demonstrate the same pattern teach it once. ' +
+        'Read them before deleting: an example that looks redundant may be showing a boundary case on purpose.',
+    }),
+
+    movableSchema: ({ blocks, tokens, keyList, cue }) => ({
+      title: 'The output schema could travel in the request instead of the prompt',
+      detail:
+        `${blocks === 1 ? 'A schema block' : `${blocks} schema blocks`} introduced by "${cue}" defines ${keyList}, costing about ${n(tokens)} tokens on every call. ` +
+        'Every major API now takes a response schema as a request parameter — output_config.format, response_format, responseSchema — and moving it there is the rare change that is both cheaper and stricter: prose asks the model to comply, a parameter makes the decoder comply. ' +
+        'Trazum cannot make this edit, because it changes the call rather than the prompt, and it does not check whether your provider offers the parameter — if it does not, this is not available to you.',
+    }),
+
+    restatedOutputFormat: ({ restatedCount, totalCount, restatedTokens, keyList }) => ({
+      title: 'The output format is specified twice',
+      detail:
+        `The prose describes ${restatedCount} of the ${totalCount} fields your schema already defines (${keyList}), costing about ${n(restatedTokens)} tokens on every call. ` +
+        'The code block is the version worth keeping: it is unambiguous, and Trazum never edits it. ' +
+        'Check the two agree before deleting either — when a prompt says one thing in prose and another in its schema, the prose is usually the one that went stale.',
+    }),
+  },
+
+  contradictionAxes: {
+    'response-language': 'the language of the answer',
+    'output-format': 'the output format',
+    'response-length': 'how long the answer should be',
+    'reasoning-visibility': 'whether to show the reasoning',
+  },
+
+  contradictionValues: {
+    'fixed-language': 'always the same language',
+    'mirror-language': "the reader's own language",
+    'format-json': 'JSON',
+    'format-markdown': 'Markdown',
+    'format-plain-text': 'plain text',
+    'length-brief': 'keep it brief',
+    'length-detailed': 'go into detail',
+    'reasoning-shown': 'show the reasoning',
+    'reasoning-hidden': 'hide the reasoning',
+  },
+};

package/src/i18n/es.ts

@@ -0,0 +1,236 @@
+import type { CoreMessages } from './types.js';
+
+const n = (value: number): string => value.toLocaleString('es-ES');
+
+/** Spanish catalogue. Mirrors `en.ts`, which is the source of truth. */
+export const es: CoreMessages = {
+  locale: 'es',
+  numberLocale: 'es-ES',
+
+  rules: {
+    'duplicate-blocks': {
+      title: 'Párrafos repetidos',
+      rationale:
+        'Elimina párrafos enteros que ya aparecen antes en el prompt. Es habitual al montar prompts por concatenación de plantillas: el mismo bloque de instrucciones entra dos veces y se paga dos veces.',
+    },
+    'near-duplicate-blocks': {
+      title: 'Párrafos casi idénticos',
+      rationale:
+        'Elimina párrafos con un 92% o más de palabras en común con otro anterior. Detecta instrucciones reformuladas que dicen lo mismo dos veces. Nivel agresivo: revisa el diff, porque el 8% que difiere puede ser justo el matiz que te importa.',
+    },
+    'duplicate-lines': {
+      title: 'Líneas repetidas',
+      rationale:
+        'Elimina líneas que ya aparecen idénticas antes en el prompt, ignorando mayúsculas, acentos y puntuación. Solo actúa sobre líneas de 25 caracteres o más, para no tocar viñetas ni separadores legítimos.',
+    },
+    'verbose-phrases': {
+      title: 'Perífrasis largas',
+      rationale:
+        'Sustituye construcciones largas por su equivalente corto ("con el fin de" → "para", "in order to" → "to"). El significado es idéntico; solo cambia el número de tokens.',
+    },
+    politeness: {
+      title: 'Fórmulas de cortesía',
+      rationale:
+        'Quita "por favor", "gracias", "please", "kindly"... El modelo no responde mejor por pedírselo con cortesía, y cada fórmula se paga en todas las llamadas.',
+    },
+    filler: {
+      title: 'Muletillas y rodeos',
+      rationale:
+        'Elimina arranques vacíos como "básicamente", "cabe destacar que" o "it is important to note that", que no aportan instrucción.',
+    },
+    hedges: {
+      title: 'Coletillas de duda',
+      rationale:
+        'Elimina "creo que", "I think", "en mi opinión". En una instrucción debilitan la orden sin añadir información.',
+    },
+    intensifiers: {
+      title: 'Intensificadores',
+      rationale:
+        'Quita "muy", "realmente", "extremely"... Rara vez cambian la tarea. Nivel agresivo porque en algún prompt concreto el matiz sí importa.',
+    },
+    'self-check': {
+      title: 'Instrucciones de auto-verificación',
+      rationale:
+        'Quita "verifica tu respuesta", "double-check your work". Los modelos actuales ya verifican su trabajo; pedirlo explícitamente dispara pasos extra que se pagan en tokens de salida. Desactívala si tu flujo depende de esa verificación.',
+    },
+    emphasis: {
+      title: 'Énfasis en mayúsculas',
+      rationale:
+        'Pasa a minúscula palabras gritadas (MUST, NUNCA, CRITICAL) y quita prefijos tipo "IMPORTANTE:". Las mayúsculas se parten en más tokens que las minúsculas, y en los modelos actuales el énfasis excesivo hace que la instrucción se dispare de más.',
+    },
+    decoration: {
+      title: 'Separadores decorativos',
+      rationale:
+        'Elimina líneas hechas solo de caracteres repetidos (====, ----, ****) y las secuencias de signos de exclamación. No aportan estructura que el modelo aproveche y cuestan tokens en cada llamada.',
+    },
+    whitespace: {
+      title: 'Espacios y líneas en blanco sobrantes',
+      rationale:
+        'Quita espacios al final de línea, colapsa espacios repetidos dentro de la línea y reduce las líneas en blanco consecutivas a una. Respeta la sangría inicial para no romper listas ni markdown anidado.',
+    },
+  },
+
+  llm: {
+    emptyResponse: () => 'El modelo devolvió una respuesta vacía.',
+    protectedContentAltered: (count) =>
+      `El modelo alteró ${count} fragmento(s) protegido(s) (código, URL o marcador de plantilla). Descartado para no romper el prompt.`,
+    notShorter: (after, before) =>
+      `El resultado no es más corto (${after} vs ${before} tokens). Se mantiene la versión determinista.`,
+    suspiciousShrink: (retainedPct) =>
+      `El resultado conserva solo el ${retainedPct}% de los tokens. Eso parece un resumen, no una compresión: revísalo a mano antes de usarlo.`,
+  },
+
+  suggest: {
+    'not-found': () =>
+      'la frase citada no está en el prompt — el modelo parafraseó lo que estaba copiando',
+    'touches-protected': () =>
+      'editaría código, una URL, un marcador o una etiqueta, que se copian literalmente',
+    'introduces-protected': () => 'el reemplazo añade un marcador o una URL que no estaba',
+    'no-saving': () => 'no es más corto que lo que reemplaza',
+    overlaps: () => 'comparte texto con una sugerencia ya aceptada',
+  },
+
+  advisories: {
+    contextOverflow: ({ tokens, modelName, contextWindow }) => ({
+      title: 'El prompt no cabe en la ventana de contexto',
+      detail: `El prompt optimizado ocupa ~${n(tokens)} tokens y ${modelName} admite ${n(contextWindow)}. La llamada fallará: divide el contenido o cambia a un modelo con ventana mayor.`,
+    }),
+
+    promptCaching: ({
+      placeholder,
+      prefixTokens,
+      totalTokens,
+      minTokens,
+      modelName,
+      hitRatePct,
+      readPct,
+      writePct,
+      explicit,
+    }) => {
+      const scope = placeholder
+        ? `El prefijo estable —lo anterior al primer marcador ${placeholder}— son ~${n(prefixTokens)} de los ${n(totalTokens)} tokens del prompt, y supera el mínimo cacheable de ${n(minTokens)} de ${modelName}.`
+        : `El prompt no tiene marcadores variables, así que el prefijo cacheable es entero y supera el mínimo de ${n(minTokens)} tokens de ${modelName}.`;
+      const how = explicit
+        ? 'Coloca el marcador de caché al final del prefijo estable: cualquier byte que cambie antes del corte invalida todo lo que va detrás.'
+        : `${modelName} cachea automáticamente por encima de su mínimo, así que no hay nada que activar; pero la regla es la misma: cualquier byte que cambie antes del corte invalida todo lo que va detrás.`;
+      return {
+        title: 'Activa prompt caching en el prefijo estable',
+        detail: `${scope} Con una tasa de acierto del ${hitRatePct}%, la lectura de caché cuesta un ${readPct}% del precio de entrada y la escritura un ${writePct}%. ${how}`,
+      };
+    },
+
+    promptCachingNotWorthIt: () => ({
+      title: 'Con esa tasa de acierto, la caché no compensa',
+      detail:
+        'Escribir en caché cuesta un 125% del precio de entrada y leer un 10%. Por debajo de un ~28% de aciertos pagas más de lo que ahorras. Sube la reutilización del prefijo o deja la caché desactivada.',
+    }),
+
+    belowCacheMinimum: ({
+      modelName,
+      minTokens,
+      placeholder,
+      prefixTokens,
+      totalTokens,
+      mentionLowerMinimum,
+    }) => {
+      const reason = placeholder
+        ? `aquí el primer marcador variable (${placeholder}) aparece a los ~${n(prefixTokens)} tokens y solo lo anterior puede cachearse`
+        : `este prompt tiene ~${n(totalTokens)}`;
+      return {
+        title: 'Por debajo del mínimo cacheable',
+        detail:
+          `${modelName} necesita al menos ${n(minTokens)} tokens de prefijo para cachear; ${reason}. Marcar cache_control no dará error, simplemente no cacheará.` +
+          (mentionLowerMinimum
+            ? ' Claude Opus 5 baja ese mínimo a 512 tokens, así que prompts cortos que aquí no cachean, allí sí.'
+            : ''),
+      };
+    },
+
+    cachePrefixReorder: ({ staticTokensAfter, sharePct, placeholder }) => ({
+      title: 'Mueve las instrucciones estables antes del primer marcador',
+      detail: `Unos ~${n(staticTokensAfter)} tokens de contenido estable (el ${sharePct}% del prompt) están después del primer marcador variable ${placeholder}, así que hoy no se cachean nunca. Reordena la plantilla —instrucciones y contexto fijos primero, marcadores al final— y ese contenido pasa a leerse de caché al 10% del precio. Revisa que la reordenación no cambie el sentido del prompt.`,
+    }),
+
+    batchApi: () => ({
+      title: 'Si el trabajo tolera latencia, usa la Batch API',
+      detail:
+        'La Batch API aplica un 50% de descuento sobre entrada y salida. La mayoría de lotes terminan en menos de una hora, con un máximo de 24. Sirve para clasificación masiva, enriquecimiento de datos o evaluaciones: cualquier cosa que no responda a un usuario en tiempo real.',
+    }),
+
+    modelDowngrade: ({ modelName, tier, candidateName, currentUsd, candidateUsd }) => ({
+      title: `Esta tarea quizá no necesite ${modelName}`,
+      detail: `Por longitud y vocabulario, el prompt parece de complejidad "${tier}". Con ${candidateName} pasarías de ${currentUsd} a ${candidateUsd} al mes. Es una heurística por palabras clave, no un juicio de calidad: mide la diferencia con tus propias evaluaciones antes de cambiar en producción.`,
+    }),
+
+    outputDominated: ({ outputUsd, inputUsd }) => ({
+      title: 'Tu coste está en la salida, no en el prompt',
+      detail: `La salida supone ${outputUsd} al mes frente a ${inputUsd} de entrada. Acortar el prompt tiene un techo bajo aquí. Los dos controles que mueven la aguja son el parámetro effort (bájalo si la tarea no es intensiva en razonamiento) y pedir respuestas concisas de forma explícita.`,
+    }),
+
+    promoPricing: ({ modelName, promoInput, promoOutput, until, listInput, listOutput }) => ({
+      title: 'Estás calculando con precio promocional',
+      detail: `${modelName} tiene precio de lanzamiento ${promoInput}/${promoOutput} por millón de tokens hasta el ${until}. A partir de esa fecha pasa a ${listInput}/${listOutput}: tu factura subirá aunque no cambies nada.`,
+    }),
+
+    contradictoryInstructions: ({
+      axis,
+      firstValue,
+      firstSnippet,
+      secondValue,
+      secondSnippet,
+      otherCount,
+    }) => ({
+      title: `Dos instrucciones se contradicen sobre ${axis}`,
+      detail:
+        `Una dice ${firstValue} ("${firstSnippet}") y otra dice ${secondValue} ("${secondSnippet}"). ` +
+        'El modelo tiene que elegir una, y cuál elige puede cambiar entre llamadas: esto es un problema de corrección antes que de coste. ' +
+        'Borrar la instrucción que no querías además acorta el prompt.' +
+        (otherCount > 0
+          ? ` Hay ${otherCount} ${otherCount === 1 ? 'pareja más' : 'parejas más'} de instrucciones que se contradicen.`
+          : ''),
+    }),
+
+    redundantExamples: ({ redundantCount, totalCount, redundantTokens, topSimilarityPct }) => ({
+      title: `${redundantCount} de ${totalCount} ejemplos repiten uno anterior`,
+      detail:
+        `Comparten el ${topSimilarityPct}% o más de su redacción con un ejemplo previo y suponen unos ${n(redundantTokens)} tokens que pagas en cada llamada. ` +
+        'Un ejemplo few-shot se paga a sí mismo enseñando algo nuevo; dos que demuestran el mismo patrón lo enseñan una vez. ' +
+        'Léelos antes de borrar: un ejemplo que parece redundante puede estar mostrando un caso límite a propósito.',
+    }),
+
+    movableSchema: ({ blocks, tokens, keyList, cue }) => ({
+      title: 'El esquema de salida podría ir en la petición y no en el prompt',
+      detail:
+        `${blocks === 1 ? 'Un bloque de esquema' : `${blocks} bloques de esquema`} introducido por "${cue}" define ${keyList}, y cuesta unos ${n(tokens)} tokens en cada llamada. ` +
+        'Toda API relevante acepta ya un esquema de respuesta como parámetro de la petición — output_config.format, response_format, responseSchema — y moverlo allí es el cambio raro que sale más barato y además más estricto: la prosa le pide al modelo que cumpla, un parámetro obliga al decodificador. ' +
+        'Trazum no puede hacer esta edición, porque cambia la llamada y no el prompt, y no comprueba si tu proveedor ofrece el parámetro — si no lo ofrece, esto no está disponible para ti.',
+    }),
+
+    restatedOutputFormat: ({ restatedCount, totalCount, restatedTokens, keyList }) => ({
+      title: 'El formato de salida está especificado dos veces',
+      detail:
+        `La prosa describe ${restatedCount} de los ${totalCount} campos que tu esquema ya define (${keyList}), y cuesta unos ${n(restatedTokens)} tokens en cada llamada. ` +
+        'El bloque de código es la versión que merece la pena conservar: no es ambiguo y Trazum nunca lo toca. ' +
+        'Comprueba que ambos dicen lo mismo antes de borrar ninguno: cuando un prompt dice una cosa en prosa y otra en el esquema, lo que suele haberse quedado obsoleto es la prosa.',
+    }),
+  },
+
+  contradictionAxes: {
+    'response-language': 'el idioma de la respuesta',
+    'output-format': 'el formato de salida',
+    'response-length': 'la longitud de la respuesta',
+    'reasoning-visibility': 'si mostrar el razonamiento',
+  },
+
+  contradictionValues: {
+    'fixed-language': 'siempre el mismo idioma',
+    'mirror-language': 'el idioma de quien escribe',
+    'format-json': 'JSON',
+    'format-markdown': 'Markdown',
+    'format-plain-text': 'texto plano',
+    'length-brief': 'que sea breve',
+    'length-detailed': 'que entre en detalle',
+    'reasoning-shown': 'mostrar el razonamiento',
+    'reasoning-hidden': 'ocultar el razonamiento',
+  },
+};

package/src/i18n/index.ts

@@ -0,0 +1,68 @@
+import { en } from './en.js';
+import { es } from './es.js';
+import { DEFAULT_LOCALE, LOCALES } from './types.js';
+import type { CoreMessages, Locale } from './types.js';
+
+const CATALOGUES: Record<Locale, CoreMessages> = { en, es };
+
+/** Message catalogue for a locale. */
+export function getMessages(locale: Locale = DEFAULT_LOCALE): CoreMessages {
+  return CATALOGUES[locale] ?? CATALOGUES[DEFAULT_LOCALE];
+}
+
+/** Whether a string is a locale Trazum ships. */
+export function isLocale(value: unknown): value is Locale {
+  return typeof value === 'string' && (LOCALES as readonly string[]).includes(value);
+}
+
+/**
+ * Highest-priority locale in `input` that Trazum actually ships, or `null`
+ * when it lists none.
+ *
+ * Accepts a bare tag (`es`), a regional tag (`es-ES`, `en_GB`), a POSIX locale
+ * string (`es_ES.UTF-8`) or an Accept-Language list, so the same helper works
+ * for an HTTP header, a CLI flag and the LANG environment variable.
+ *
+ * The whole list is walked rather than just the first entry: a browser sending
+ * `fr-FR,es;q=0.9` prefers French, which we do not have, but it does read
+ * Spanish, which we do — falling straight back to English would ignore a
+ * preference the user actually expressed. Quality values are assumed to be in
+ * descending order, as every real client sends them.
+ *
+ * Returning `null` instead of a default is what lets callers tell "asked for
+ * something we don't have" from "asked for English", and so fall through to
+ * the next configuration source.
+ */
+export function matchLocale(input: string | null | undefined): Locale | null {
+  if (!input) return null;
+  for (const tag of input.split(',')) {
+    const base = tag.trim().split(/[-_.;]/)[0]?.toLowerCase() ?? '';
+    if (isLocale(base)) return base;
+  }
+  return null;
+}
+
+/**
+ * Same as `matchLocale`, but falls back to the default locale rather than
+ * returning `null`: a bad locale should never be the reason an optimisation
+ * fails.
+ */
+export function resolveLocale(input: string | null | undefined): Locale {
+  return matchLocale(input) ?? DEFAULT_LOCALE;
+}
+
+export { DEFAULT_LOCALE, LOCALES, en, es };
+export type {
+  BelowCacheMinimumParams,
+  CachePrefixReorderParams,
+  ContextOverflowParams,
+  CoreMessages,
+  Locale,
+  LocalizedMessage,
+  ModelDowngradeParams,
+  OutputDominatedParams,
+  PromoPricingParams,
+  PromptCachingParams,
+  RuleCopy,
+  RuleId,
+} from './types.js';