TCDEV Blog

Deje que su LLM piense en inglés

2026-04-27T00:00:00Z

Usted envía un chatbot para su equipo alemán. La interfaz de usuario es alemana. Los documentos fuente son en parte alemanes y en parte ingleses. Las herramientas detrás del asistente esperan valores enum en inglés, descripciones de funciones en inglés, nombres de productos en inglés, todo en inglés.

Entonces alguien hace una pregunta perfectamente normal en alemán, el modelo elige la herramienta adecuada, pasa un argumento en alemán en lugar de en inglés, y todo se viene abajo silenciosamente.

Ya he visto versiones de esto suficientes veces como para dejar de considerarlo un problema de traducción. Es un problema de ejecución.

Mi predeterminación actual es simple: dejar que los usuarios hablen el idioma que quieran, pero que el LLM haga su trabajo de recuperación, razonamiento y herramientas en inglés siempre que la fiabilidad realmente importe. A continuación, localice la respuesta fuera de ese bucle.

Eso suena ligeramente herético al principio. También es, en mi opinión, lo más práctico que puede hacer ahora mismo.

La investigación está empezando a decir esto en voz alta

Las cifras ya no son sutiles.

En el MASSIVE-Agents benchmark, los investigadores evaluaron la llamada a funciones multilingües en 52 idiomas, 47.020 muestras y 21 modelos. La mejor puntuación media en todos los idiomas fue de sólo el 34,05%. El inglés alcanzó el 57,37%. El amárico cayó hasta el 6,81%.

Eso no es un pequeño bamboleo de calidad. Es un precipicio de fiabilidad.

Luego está Lost in Execution, que se acerca aún más al problema real de los sistemas. El documento muestra que muchos fallos en la llamada a herramientas multilingües se producen después de que el modelo ya haya comprendido la intención y seleccionado la herramienta correcta. El problema dominante era el desajuste lingüístico del valor de los parámetros. En pocas palabras, el modelo sabía lo que tenía que hacer, pero expresaba los bits ejecutables en el idioma del usuario en lugar del idioma de la interfaz, por lo que la llamada fallaba de todos modos.

Y esto no se limita a la llamada a herramientas. En ¿Piensan mejor en inglés los modelos lingüísticos multilingües?, Etxaniz y sus colegas descubrieron que la autotraducción al inglés superaba sistemáticamente a la inferencia directa no inglesa en cinco tareas. Su formulación es refrescantemente contundente: los modelos son "incapaces de aprovechar todo su potencial multilingüe cuando se les pregunta en lenguas distintas del inglés".

Así que sí, los modelos multilingües son impresionantes. Pero si su listón no es "suena bastante bien" y es en cambio "debe comportarse correctamente en producción", el inglés sigue pareciendo el idioma operativo más seguro con notable frecuencia.

Por qué la RAG se rompe en el mismo sitio

La gente suele oír este argumento y pensar primero en los agentes. Llamadas a funciones, salida estructurada, ejecución de API, ese tipo de cosas.

RAG tiene la misma debilidad, sólo que una capa antes.

Si su capa de recuperación tiene que hacer coincidir el fraseo local de un usuario con el contenido escrito en idiomas mezclados, con terminología incoherente, nombres de productos traducidos y etiquetas de taxonomía medio localizadas, crea más posibilidades de que el sistema se desvíe antes incluso de que empiece la generación. Sinceramente, de ahí vienen muchas de las quejas de "el modelo no es fiable". El modelo puede estar bien. La interfaz de contenidos no lo está.

Yo preferiría normalizar pronto.

Traducir la pregunta al inglés. Recuperar contra un corpus canónico inglés. Deje que el modelo razone sobre una capa terminológica estable. Genere un borrador de respuesta en inglés si es necesario. A continuación, traduzca o localice la respuesta final para el usuario.

Así dispondrá de un lugar en el que la nomenclatura se mantiene estable:

un título de documento canónico
un vocabulario de producto canónico
un esquema de herramientas canónico
un conjunto canónico de etiquetas de recuperación

Puede seguir soportando todos los idiomas de los usuarios en el exterior. Sólo tiene que dejar de pedir al núcleo de la ruta de ejecución que sea perfectamente multilingüe en cada paso.

Esto no es antilocalización

Todo lo contrario.

Una mala arquitectura de IA multilingüe suele perjudicar primero a los usuarios locales. Consiguen la bonita interfaz localizada, luego el sistema oculto centrado en el inglés que hay debajo se comporta de forma incoherente y les hace pagar el precio.

Una localización adecuada significa ser honesto sobre dónde debe flexionar el idioma y dónde no.

Para mí, la división tiene este aspecto:

Localice la interfaz de usuario, los avisos, el texto de ayuda, la incorporación y las respuestas finales.
Localizar el contenido fuente que la gente lee directamente cuando ese contenido tiene que existir en el mercado.
Mantenga las definiciones internas de las herramientas, los identificadores canónicos, las etiquetas de recuperación y los pivotes de razonamiento en inglés si esa es la capa más estable.
Añada un posprocesamiento explícito o una revisión humana cuando un resultado localizado tenga peso legal, normativo o contractual.

Este último punto importa más de lo que a los equipos les gusta admitir. Si el modelo está hablando con un humano, la localización es una decisión de experiencia de usuario. Si el modelo está hablando con otro sistema, la lengua es un contrato de interfaz.

No son la misma cosa.

La arquitectura en la que más confío ahora mismo

Esta es la versión por la que apostaría hoy para los productos de IA multilingüe:

El usuario pregunta en su idioma.
El sistema traduce o normaliza la petición al inglés.
La recuperación, el razonamiento, la clasificación y las llamadas a las herramientas se producen contra los datos canónicos en inglés.
La respuesta final se localiza al idioma del usuario.
Las salidas de alto riesgo reciben un paso de validación adicional antes de abandonar el sistema.

No es filosóficamente puro. Es operativamente sano.

Lo bueno es que investigaciones recientes apuntan en la misma dirección. Lost in Execution descubrió que la pretraducción de las consultas de los usuarios reducía en general los errores de desajuste lingüístico mejor que las correcciones post-hoc, aunque seguía sin recuperar totalmente el rendimiento a nivel inglés. Eso coincide con lo que muchos constructores ya sospechan en la práctica. Si espera hasta el final para limpiar la incoherencia multilingüe, suele llegar demasiado tarde.

Y sí, hay excepciones. Si está construyendo para lenguas de escasos recursos, lenguaje específico del dominio o fraseo culturalmente dependiente, traducirlo todo al inglés puede introducir desviaciones. El documento anterior advierte explícitamente de ello. Así que no convierta esto en un dogma.

Pero como norma por defecto para copilotos de empresa, asistentes internos, GAR multilingües y agentes que utilizan herramientas, creo que la regla se mantiene sorprendentemente bien.

Lo que esto significa para Rasepi

Esta es exactamente la razón por la que me preocupo tanto por la estructura canónica del contenido.

Si su base de conocimientos tiene una capa de origen limpia, una terminología estable y una localización controlada en la parte superior, es más fácil confiar en la IA. Si cada versión lingüística deriva de forma independiente dentro de la ruta de ejecución, está pidiendo al modelo que improvise donde su sistema debería ser preciso.

Todo el enfoque de Rasepi se basa en separar limpiamente esas preocupaciones. Mantenga un núcleo canónico. Localice deliberadamente. Rastree dónde existen variantes. No pretenda que todas las capas de la pila sean igualmente multilingües sólo porque la interfaz de usuario lo sea.

Solía pensar que la mejor experiencia de IA multilingüe significaba "hacerlo todo en el idioma del usuario". Ya no pienso lo mismo. No para los sistemas que tienen que recuperar el párrafo correcto, elegir la herramienta adecuada y devolver algo en lo que se pueda confiar.

La regla práctica es simple: los usuarios deben permanecer locales, pero la ruta de ejecución del LLM debe permanecer estable. Ahora mismo, eso suele significar inglés en el centro y localización en los bordes.

Eso cambiará con el tiempo. Espero que cambie rápidamente. Pero si está haciendo envíos hoy y la fiabilidad importa más que la estética, yo dejaría que el modelo pensara en inglés y que su producto hablara el idioma del usuario.

Claude Design y la agencia creativa unipersonal

2026-04-18T00:00:00Z

Ayer Anthropic lanzó Claude Design, un nuevo producto de su equipo de Anthropic Labs que le permite crear diseños, prototipos, presentaciones y material de marketing hablando con Claude. Y me quedé sentado mirando el anuncio pensando: vale, así que ahora una persona con una suscripción a Claude tiene realmente la mayor parte de lo que ofrece una pequeña agencia creativa. Diseñar. Código. Automatización. Presentaciones. Coherencia de marca. Todo dentro del mismo ecosistema.

Es una frase descabellada para escribirla en 2026. Pero no creo que sea una exageración.

Lo que Claude Design hace en realidad

La versión corta: usted describe lo que necesita, y Claude construye una primera versión. Luego usted refina a través de conversaciones, comentarios en línea, ediciones directas o deslizadores personalizados que Claude genera para usted. Funciona con Opus 4.7 y es sorprendentemente bueno a la hora de mantener la coherencia visual.

Pero la característica que más me llamó la atención es el onboarding. Durante la configuración, Claude lee su código base y los archivos de diseño existentes para construir un sistema de diseño para su equipo. Colores, tipografía, componentes. Cada proyecto posterior sigue automáticamente su marca. Puede importar imágenes, documentos (DOCX, PPTX, XLSX) o apuntarlo directamente a su base de código. Hay una herramienta de captura web que toma elementos de su sitio web en vivo para que los prototipos se parezcan al producto real.

¿Tiene una maqueta Figma sobre la que desea iterar? Expórtelo, suéltelo en Claude Design e inicie una conversación sobre qué cambiar. O simplemente capture su sitio web existente y diga "haga la sección hero más grande y añada un carrusel de testimonios". Ese tipo de cosas.

Los testimonios del anuncio son reveladores. El Diseñador de Producto Senior de Brilliant dijo que sus páginas más complejas, que necesitaban más de 20 indicaciones para recrearlas en otras herramientas, sólo requerían 2 indicaciones en Claude Design. El director de producto de Datadog describió cómo se pasa de una idea aproximada a un prototipo funcional antes de que nadie abandone la sala, y dijo que lo que solía llevar una semana de briefs, maquetas y rondas de revisión ahora sucede en una sola conversación.

Una semana de idas y venidas, colapsada en una sola conversación. Piense en ello durante un segundo.

La pila que lo cambia todo

Aquí es donde la cosa se pone interesante. Claude Design no existe de forma aislada. Anthropic cuenta ahora con tres productos que, combinados, cubren una cantidad absurda de terreno:

Código Claude: Escribir, revisar y enviar software real. (https://www.anthropic.com/news/anthropic-raises-30-billion-series-g-funding-380-billion-post-money-valuation) en febrero, responsable de un 4% estimado de todos los commits públicos de GitHub en todo el mundo.
Claude Cowork: Automatice el trabajo del conocimiento. Investigación, análisis, procesamiento de documentos, tareas recurrentes desde su escritorio.
Claude Design: Cree trabajo visual. Prototipos, presentaciones, material de marketing, activos coherentes con la marca.

Y se entregan unos a otros. Cuando un diseño está listo para construirse, Claude lo empaqueta todo en un paquete de traspaso que puede pasar a Claude Code con una sola instrucción. Del diseño a la producción en un solo flujo. Sin ticket de Jira. Sin reunión de traspaso. Nada de "¿puedes enviarme las especificaciones en Slack?".

Sigo pensando en la predicción de Sam Altman de principios de 2024 sobre la empresa unipersonal de mil millones de dólares. En aquel momento sonaba aspiracional, quizá un poco hiperbólico. Las herramientas aún no estaban ahí. Se podía generar texto e imágenes, claro, pero la distancia entre generar cosas y enviar productos reales era enorme.

Esa brecha se está reduciendo rápidamente.

Lo que habría dado por esto hace dos meses

Cuando construí Rasepi, el sitio de marketing era una de las partes más tediosas. No el código. El código estaba bien, Claude maneja HTML y CSS como un campeón. ¿Pero las decisiones de diseño visual? ¿La disposición del héroe, las tarjetas de la página de precios, las tablas de comparación de características? Yo describía las cosas con palabras, Claude producía algo, y luego me pasaba horas yendo y viniendo intentando ajustar el espaciado, los colores, la tipografía. Todo mediante indicaciones de texto. No había bucle de retroalimentación visual.

Con Claude Design, ese flujo de trabajo se convierte en: "aquí está mi sitio web" (captura web), "rediseñar la sección de precios para enfatizar el plan de equipo" (conversación), retocar el color verde de acento con un deslizador, aprobar, pasar a Claude Code para la implementación. Calculo que eso me habría ahorrado todo un fin de semana.

(Sinceramente, me molesta un poco que no se lanzara dos meses antes).

Y la exportación a Canva es inteligente. Canva tiene 220 millones de usuarios activos y 3.000 millones de dólares de ingresos anualizados. Anthropic no intenta sustituir a Canva. Están intentando ser el lugar donde empiezan las ideas antes de aterrizar en Canva para su pulido final y distribución. Se trata de una jugada de posicionamiento inteligente. Usted genera la creatividad en Claude Design, luego la exporta a Canva donde su equipo de marketing la recoge. O exporte a PPTX para ese mazo de inversores. O exporte como HTML independiente para una página de aterrizaje.

El multiplicador "sólo añadir herramientas

Este es el patrón que sigo viendo en todo el espacio de la IA en 2026. El modelo base se hace más inteligente, seguro, pero el verdadero salto de productividad viene de conectar herramientas entre sí. Claude por sí mismo es un generador de texto muy inteligente. Claude con Code es un ingeniero de software. Claude con Cowork es un analista de investigación. Claude con Design es un director creativo. ¿Claude con las tres? Es una agencia pequeña.

Y las conexiones siguen creciendo. Anthropic afirma que añadirá más integraciones en las próximas semanas. Los servidores MCP ya permiten conectar Claude a herramientas y fuentes de datos externas. El ecosistema se está construyendo solo.

Para los fundadores en solitario, los autónomos y los equipos pequeños, esto cambia el cálculo por completo. Usted no necesita un diseñador contratado para producir cubiertas y prototipos de aspecto profesional. No necesita un desarrollador frontend independiente para convertir las maquetas en código. No necesita un gestor de proyectos para coordinar el traspaso entre el diseño y la ingeniería porque no hay traspaso. Es una conversación continua.

No estoy diciendo que los diseñadores estén obsoletos. Ni mucho menos. Tanto Brilliant como Datadog describen a sus diseñadores utilizando Claude Design. La herramienta hace que los buenos diseñadores sean más rápidos y da a todos los demás acceso a un resultado visual competente. Eso es una cosa diferente a sustituir a las personas.

Qué significa esto para los productos de documentación

Esto lo observo de cerca. En Rasepi, estamos construyendo una plataforma de documentación donde la calidad visual importa. Las páginas de entrada tienen que tener buen aspecto. Las guías de inicio rápido necesitan diagramas claros. Los documentos de marketing necesitan coherencia de marca en todos los idiomas y equipos.

¿Un mundo en el que cada miembro del equipo pueda generar documentación visual acorde con la marca, entregarla al motor de traducción y distribuirla en siete idiomas sin tocar Figma ni Photoshop ni InDesign? Ese es exactamente el problema que estamos resolviendo desde un ángulo diferente. (Y sí, este es exactamente el tipo de flujo de trabajo que Rasepi está construido para soportar).

La parte en la que se pone extrañamente caro

He aquí la parte de la que nadie habla todavía. Creé una cuenta Anthropic completamente nueva específicamente para probar Claude Design. Cuenta nueva, sin historial, sin uso previo. Importé un pequeño archivo Figma y generé un único activo. Eso fue todo. Dos operaciones. Y me quedé sin créditos.

En una cuenta nueva. Con una nueva asignación.

No sé cómo son las matemáticas de las fichas por parte de Anthropic cuando Opus 4.7 está haciendo la generación visual, pero sea lo que sea, quema los créditos a un ritmo que hace que el argumento de "agencia creativa unipersonal" parezca mucho más caro de lo esperado. Si importar una pequeña maqueta de Figma y producir una imagen se come todo su presupuesto, la economía de usar esto como su herramienta de diseño diaria no funciona todavía.

Para ser justos, esto es una vista previa de investigación y los precios probablemente cambiarán. Pero ahora mismo hay una brecha significativa entre la promesa (sustituir su flujo de trabajo de diseño) y la realidad (puede que se quede sin créditos antes de comer). Las ganancias de productividad son reales. Si la relación créditos-producción lo hace práctico para un uso regular es una cuestión totalmente diferente.

La advertencia sincera

El diseño Claude está en fase de investigación previa. Tendrá bordes ásperos. Los testimonios son de equipos de diseño de empresas bien financiadas con sistemas de diseño establecidos. Su kilometraje variará, especialmente si usted está comenzando desde cero sin directrices de marca para alimentarlo.

Pero la trayectoria está clara. Hace dieciocho meses se necesitaba un diseñador, un desarrollador y un gestor de proyectos para pasar del concepto a la página de aterrizaje enviada. Hoy en día, una sola persona con una suscripción a Claude puede hacer una versión sorprendentemente creíble de ese mismo flujo de trabajo en una tarde.

Todavía no hemos llegado a la empresa de mil millones de dólares de una sola persona. ¿Pero la agencia creativa de una sola persona? Creo que acabamos de llegar.

Una clave API, muchos inquilinos: Cómo aislamos DeepL Traducciones entre clientes

2026-04-18T00:00:00Z

Hay una pregunta que surge cada vez que explico la arquitectura de traducción de Rasepi a otro desarrollador: "Espere, ¿así que todos sus inquilinos comparten una clave API DeepL? ¿Cómo evita que sus glosarios y reglas de estilo se filtren unos a otros?".

Es una pregunta justa. Y la respuesta implica más trabajo de diseño del que cabría esperar.

Ya tratamos el proceso de traducción completo en un post anterior, el hash a nivel de bloque, el orquestador, todo el flujo desde que se guarda el documento hasta que se traduce. Este post se centra en el problema específico de la multitenencia. Cómo se toma una API de terceros que no tiene el concepto de inquilinos y se construye el aislamiento de inquilinos sobre ella.

El problema: DeepL no conoce a sus clientes

La API de DeepL se autentica con una única clave de API. Todo lo que se crea con esa clave, glosarios, listas de reglas de estilo, historial de traducciones, pertenece a la misma cuenta. No existe el concepto de "este glosario pertenece al arrendatario A" por parte de DeepL.

Cuando llama a GET /v2/glossaries, obtiene todos los glosarios de todos los inquilinos. Cuando crea una lista de reglas de estilo, ésta vive en el mismo espacio de nombres que las reglas de estilo de todos los demás arrendatarios. La API es plana.

Para un producto autoalojado en el que cada cliente ejecuta su propia instancia con su propia clave DeepL, esto está bien. ¿Para un SaaS multiarrendatario en el que gestionamos la infraestructura? Necesita una capa de aislamiento.

La base de datos es la fuente de la verdad

Nuestra principal decisión de diseño: la base de datos es la propietaria de todo el contenido del glosario y de la configuración de las reglas de estilo. DeepL es un objetivo de ejecución en tiempo de ejecución, nada más.

Cada entidad TenantGlossary y TenantStyleRuleList implementa ITenantScoped, lo que significa que los filtros de consulta global del núcleo de EF amplían automáticamente todas las lecturas al inquilino actual. Una consulta de glosarios en el contexto de solicitud del arrendatario A nunca devolverá las entradas del arrendatario B. Este es el mismo patrón de aislamiento que utilizamos en todas partes en Rasepi, aplicado a nivel ORM.

Esto es lo que lo hace interesante. Cuando un arrendatario edita un término del glosario, no llamamos inmediatamente a DeepL. Actualizamos la fila de la base de datos y establecemos IsDirty = true. Y ya está. El glosario DeepL real se crea (o se vuelve a crear) perezosamente, justo antes de que la siguiente traducción lo necesite.

public async Task<string?> GetOrSyncDeepLGlossaryIdAsync(
    string sourceLanguage, string targetLanguage)
{
    var glossary = await _db.TenantGlossaries
        .Include(g => g.Entries)
        .FirstOrDefaultAsync(g =>
            g.SourceLanguage == sourceLanguage &&
            g.TargetLanguage == targetLanguage);

    if (glossary?.Entries.Count == 0) return null;

    if (!glossary.IsDirty && glossary.DeepLGlossaryId is not null)
        return glossary.DeepLGlossaryId;

    // Dirty: delete old, create new
    if (glossary.DeepLGlossaryId is not null)
        await _deepL.DeleteGlossaryAsync(glossary.DeepLGlossaryId);

    var entries = glossary.Entries
        .ToDictionary(e => e.SourceTerm, e => e.TargetTerm);

    var created = await _deepL.CreateGlossaryAsync(
        $"rasepi-{glossary.Id}",
        glossary.SourceLanguage,
        glossary.TargetLanguage,
        entries);

    glossary.DeepLGlossaryId = created.GlossaryId;
    glossary.IsDirty = false;
    glossary.LastSyncedAt = DateTime.UtcNow;
    await _db.SaveChangesAsync();

    return glossary.DeepLGlossaryId;
}

El filtro de consulta en TenantGlossaries se encarga del aislamiento. La bandera IsDirty hace la sincronización perezosa. Y la convención de nomenclatura (rasepi-{glossary.Id}) es sólo para depuración en el tablero DeepL, no tiene ningún propósito funcional.

¿Por qué perezosa? Porque los glosarios de DeepL v2 son inmutables. No se pueden editar. Cualquier cambio significa borrar y volver a crear. Si un equipo importa un CSV con 200 términos y luego corrige una errata en una entrada, no queremos borrar y volver a crear el glosario DeepL dos veces. Simplemente establecemos IsDirty las dos veces y la única recreación se produce cuando se ejecuta la siguiente traducción.

Reglas de estilo: mismo patrón, diferente API

Las reglas de estilo de DeepL son más nuevas (API v3) y realmente mutables, lo que es más agradable. Puede actualizar las reglas configuradas in situ con PUT /v3/style_rules/{style_id}/configured_rules, y las instrucciones personalizadas pueden añadirse o eliminarse individualmente.

Sin embargo, seguimos utilizando el mismo patrón IsDirty. Un TenantStyleRuleList tiene un DeepLStyleId que mapea al identificador de tiempo de ejecución de DeepL, además de ConfiguredRulesJson para las reglas de formato y una colección de entradas TenantCustomInstruction para las directivas de traducción de texto libre.

El verdadero poder está en esas instrucciones personalizadas. Cada una es una directiva de texto libre, de hasta 300 caracteres, que da forma a cómo traduce DeepL. Ejemplos reales de nuestros inquilinos:

"Utilice siempre la forma 'Sie', nunca 'du'" para un bufete de abogados alemán
"Traduzca 'deployment' como 'Bereitstellung', nunca 'Deployment'" para términos dependientes del contexto que van más allá de las simples correspondencias del glosario
"Utilice la ortografía del inglés británico (color, organización, licencia)" para una empresa del Reino Unido que traduce entre variantes del inglés
"Ponga símbolos de moneda después del importe numérico" para las convenciones europeas

Cada arrendatario puede tener instrucciones completamente diferentes por idioma de destino, todas detrás de la misma clave API. El aislamiento proviene del hecho de que cada llamada de traducción incluye únicamente el glossary_id y el style_id pertenecientes al tenant solicitante. Nunca se hace referencia a los recursos DeepL de otros arrendatarios.

La llamada de traducción: todo compone

Cuando el orquestador traduce un bloque, ensambla todos los ajustes específicos del inquilino en una única solicitud:

var glossaryId = await _glossaryService
    .GetOrSyncDeepLGlossaryIdAsync(sourceLang, targetLang);
var styleId = await _styleRuleService
    .GetOrSyncStyleIdAsync(targetLang);
var formality = langConfig.Formality ?? "default";

var options = new TranslationOptions
{
    GlossaryId = glossaryId,
    StyleId = styleId,
    Formality = formality,
    Context = documentContext,
    ModelType = styleId != null ? "quality_optimized" : null
};

Aquí todos los parámetros son específicos del inquilino. El glossaryId se resolvió mediante una consulta filtrada por el inquilino. El styleId se resolvió de la misma manera. El formality proviene del TenantLanguageConfig, también tenant-scoped. Incluso el context (párrafos circundantes enviados para mejorar la calidad de la traducción, no facturados) procede del propio documento del arrendatario.

Una cosa que quiero destacar: cuando se establece style_id, DeepL utiliza automáticamente su modelo quality_optimized. No puede combinar reglas de estilo con latency_optimized. Es una restricción de DeepL, pero sinceramente razonable. Si está invirtiendo en reglas de estilo personalizadas, probablemente querrá la mejor calidad de salida.

Almacenamiento en caché a nivel de bloque: la base de datos como memoria de traducción

No llamamos a DeepL para los bloques que no han cambiado. El mecanismo de almacenamiento en caché es la propia tabla TranslationBlock.

Cada EntryBlock fuente tiene un ContentHash, un SHA256 de su contenido semántico (con atributos de metadatos como blockId y deleted despojados). Cada TranslationBlock almacena el SourceContentHash que estaba vigente cuando se hizo la traducción. Cuando cambia el bloque fuente, cambia su hash. El orquestador compara los hashes y sólo pone en cola los bloques que no coinciden.

El árbol de decisión para cada bloque tiene el siguiente aspecto:

Hash coincide, traducción existe = omitir (en caché, actualizado)
Hash cambiado, traducción automática, no bloqueada = retraducir automáticamente
Hash cambiado, editado por humanos o bloqueado = marcar como Stale, no sobrescribir

El tercer caso es crucial. Si su traductor de alemán refinó manualmente un párrafo, no lo sobrescribimos sólo porque la fuente inglesa cambió. Lo marcamos como rancio para que sepan que necesita revisión, pero el texto traducido permanece intacto.

El resultado práctico: la edición de un párrafo en un documento de 30 párrafos desencadena exactamente una llamada a la API DeepL (bueno, un lote que incluye un bloque). Los otros 29 párrafos, en todos los idiomas, ya están almacenados en caché y no cuestan nada.

¿Por qué no utilizar una clave distinta por inquilino?

Lo he considerado seriamente. Dé a cada inquilino su propia clave API DeepL y elimine por completo el problema del aislamiento.

Tres razones por las que no lo hicimos:

Complejidad de facturación. Cada arrendatario necesitaría su propia suscripción a DeepL o una forma de aprovisionar subcuentas. DeepL no ofrece gestión de claves multiarrendatario de forma nativa.
Eficiencia de costes. Una infraestructura compartida significa límites de tarifas y descuentos por volumen compartidos. Nuestro uso agregado obtiene mejores precios.
Simplicidad operativa. Una llave que rotar, una cuota que supervisar, una integración que mantener.

La contrapartida es que necesitamos la capa de aislamiento que he descrito. Pero dado que ya tenemos consultas EF Core de ámbito tenant para todo lo demás en el sistema, añadirlo a los glosarios y a las reglas de estilo fue sencillo. El patrón ya estaba ahí.

Lo que realmente le protege

Para resumir las garantías de aislamiento:

Las entradas del glosario se almacenan en TenantGlossary (implementa ITenantScoped), filtradas por los filtros de consulta globales de EF Core. DeepL Los ID de glosario son referencias opacas que sólo se resuelven dentro del contexto del inquilino.
Las reglas de estilo y las instrucciones personalizadas siguen el mismo patrón a través de TenantStyleRuleList.
El contenido traducido** se encuentra en TranslationBlock, con alcance a través de su cadena padre Entry → Hub, que también tiene alcance de inquilino.
La guardia SaveChanges** establece TenantId automáticamente en nuevas entidades y lanza en escrituras cruzadas entre inquilinos.
No hay IgnoreQueryFilters()** en el código de producción. Nunca.

El principio de diseño es simple: DeepL ve IDs de recursos. Rasepi ve entidades tenant-scoped. El mapeo entre ellos nunca cruza los límites de los tenants porque la consulta que resuelve el mapeo es físicamente incapaz de devolver los datos de otro tenant.

Si está construyendo un SaaS multi-tenant que se integra con APIs de terceros sin soporte nativo tenant, este patrón funciona bien. Trate la API externa como un motor de ejecución sin estado, mantenga toda la configuración en su propia base de datos de ámbito de inquilino, sincronice perezosamente y nunca confíe en los listados de recursos externos para el aislamiento.

Los tokens quemados son las nuevas líneas de código

2026-04-13T00:00:00Z

Mi feed de LinkedIn está lleno de ello desde hace semanas. Mi línea de tiempo X también. Gente publicando capturas de pantalla de gastos de tokens como si fueran informes de progreso. Fundadores de startups alardeando de que gastaron 16.000 dólares en Claude Code el mes pasado y que aspiran a 60.000 dólares el próximo. Tablas de clasificación. Clasificaciones. Títulos como "Token Legend" y "AI God".

Y entonces, la semana pasada, alcanzó la masa crítica. Forbes informó sobre el movimiento "tokenmaxxing" que arrasa en Silicon Valley, donde las empresas compiten para ver quién quema más tokens de IA. Jensen Huang acudió al podcast All-In y dijo: "A ese ingeniero de 500.000 dólares, al final del año, le voy a preguntar: '¿Cuánto gastaste en tokens? Si esa persona dice '5.000 dólares' me pondré como un mono. Si ese ingeniero de 500.000 dólares no consumió al menos 250.000 dólares en fichas, me voy a alarmar profundamente".

Entonces Fortune informó de que un empleado de Meta había construido una tabla de clasificación interna llamada "Claudeonomics" que rastreaba el consumo de tokens entre los más de 85.000 empleados de la empresa. Los mejores usuarios recibían títulos. En un periodo de 30 días, el uso total alcanzó los 60 billones de tokens. El mejor usuario individual alcanzó una media de 281.000 millones. Mark Zuckerberg ni siquiera se coló entre los 250 primeros. Mientras tanto, Andrew Bosworth, director de tecnología de Meta, decía públicamente que su mejor ingeniero gastaba su salario equivalente en tokens pero era "entre 5 y 10 veces más productivo". "Es como, esto es dinero fácil", dijo Bosworth. "Sin límite".

Llevo en el mundo del software el tiempo suficiente para reconocer lo que está pasando aquí. Esto son "líneas de código" con un precio mucho más alto.

Hemos estado aquí antes

En 2003, Martin Fowler escribió un breve artículo sobre por qué no se puede medir la productividad del software que probablemente debería ser de lectura obligatoria para todo ejecutivo técnico. Su argumento sobre las líneas de código era preciso:

"Una de mis mayores irritaciones son los estudios de productividad basados en líneas de código. Cualquier buen desarrollador sabe que puede codificar lo mismo con enormes variaciones en líneas de código".

El problema es obvio una vez que se dice en voz alta. El LOC mide la actividad, no la producción. Dos desarrolladores pueden construir la misma función: uno escribe 1.200 líneas, el otro escribe 80. El más conciso probablemente construyó un sistema mejor. En un régimen de LOC, el verborreico parece más productivo.

Los equipos evaluados en función de la LOC respondieron racionalmente. Escribieron más líneas. Copiaron y pegaron en lugar de abstraer. Evitaron la refactorización porque borrar código perjudicaría sus cifras. La métrica moldeó el comportamiento, pero no hacia un software mejor. Más código. Sistemas peores.

Entonces, en 2023, McKinsey publicó un artículo en el que afirmaba haber descifrado la medición objetiva de la productividad de los desarrolladores. La exhaustiva respuesta de Gergely Orosz y Kent Beck señalaba el mismo fallo: casi todas las métricas de McKinsey medían el esfuerzo y la producción, no los resultados. Kent Beck relató cómo las encuestas internas de Facebook sobre el sentimiento de los desarrolladores pasaron de ser una retroalimentación útil a convertirse en negociaciones de los directivos con los ingenieros para obtener puntuaciones más altas. Eso es lo que ocurre cuando se incentiva una métrica indirecta. La cifra mejora. Lo que realmente importa no lo hace.

Se podría pensar que hemos aprendido. No lo hemos hecho.

Mismo error, diferente unidad

La seductora lógica del tokenmaxxing funciona así. Consumo de fichas = uso de IA. Más uso de IA = los equipos están utilizando IA. Por lo tanto, alto consumo de tokens = alta adopción de IA = bueno.

Es precisamente tan erróneo como medir las líneas de código, sólo que con un panel de facturación en lugar de un gráfico de commit. Y para ser justos con el artículo de Forbes, el consejero delegado de Sendbird, John Kim, básicamente dijo exactamente eso: "Ya hemos visto esta película antes". Se refería a la cultura del LOC de los años 90 y 2000. El verdadero indicador, señaló, es cuánto código generado por IA llega realmente a la producción. El gasto en fichas "es más bien un iniciador de conversación". Estoy de acuerdo. Se convierte en un problema cuando el iniciador de la conversación se convierte en el KPI principal.

La encuesta de desarrolladores 2024 de GitHub descubrió que el 97% de los desarrolladores empresariales habían utilizado herramientas de codificación de IA en el trabajo en algún momento. Sin embargo, una adopción organizativa significativa requiere políticas claras, flujos de trabajo y resultados medibles vinculados a resultados empresariales reales. No sólo uso. No sólo consumo.

Boris Cherny, el ingeniero detrás de Claude Code, compartió públicamente que no abrió un IDE en absoluto durante un mes de trabajo, con Opus 4.5 escribiendo alrededor de 200 PRs. Eso es impresionante. Pero lo que lo hace impresionante no son los tokens que consumieron esos 200 PRs. Es que fueron 200 contribuciones fusionadas reales con software funcional en el otro extremo.

El valor está en el resultado. Los tokens son la energía que te ha llevado hasta ahí, nada más.

Cuando la métrica se convierte en el objetivo

Existe un principio llamado Ley de Goodhart: cuando una medida se convierte en un objetivo, deja de ser una buena medida. La historia del desarrollo de software es básicamente un museo de la Ley de Goodhart en acción.

El seguimiento de los tokens como KPI de adopción de la IA establece exactamente la misma dinámica. Los equipos de ingeniería que se midan por el consumo de tokens consumirán más tokens. Así es como funcionan los incentivos. ¿Quiere parecer más productivo? Ejecute algunos bucles agénticos más. Deje que el modelo razone largamente antes de generar la salida. Envuelva cada tarea en una capa de orquestación que llame a cuatro herramientas donde bastaría con una. El gasto en fichas aumenta. El valor entregado no.

En realidad, la historia de Claudeonomics lo demostró casi de inmediato. Fortune señaló que "algunos empleados han puesto a trabajar durante horas a agentes de IA para maximizar el uso de tokens". Ahí está. La Ley de Goodhart ejecutándose en tiempo real, dentro de una empresa que se supone que está en la frontera de la productividad impulsada por la IA. La tabla de clasificación llevaba en funcionamiento unas pocas semanas antes de que se cerrara, y los empleados ya estaban jugándosela ejecutando agentes en bucle. La métrica tenía tres semanas y ya había dejado de medir lo que se suponía que debía medir.

Cualquier desarrollador que lea esto probablemente pueda pensar en cinco formas de inflar las métricas de uso de tokens sin beneficiar a nadie. No voy a enumerarlas. Pero si yo puedo pensar en cinco, también pueden hacerlo los ingenieros que están siendo medidos en esto.

Andrej Karpathy describió el momento actual de la ingeniería de software como un "terremoto de magnitud 9" para la profesión. Tiene razón. Pero los terremotos no se miden en la electricidad consumida. Se miden en lo que se ha movido.

La versión documental de este problema

Esto no es sólo un problema para los equipos de ingeniería. Veo la misma dinámica en la gestión del conocimiento, que está mucho más cerca de casa para nosotros en Rasepi.

"Hemos publicado 400 documentos este trimestre" es una cifra que suena bien en una presentación de diapositivas. No tiene nada que decir sobre si esos documentos son precisos, si alguien los leyó o si la información que contienen sigue siendo cierta seis meses después. Se puede alcanzar esa cifra con IA y sin pensar en absoluto. Ruido asistido por tokens publicado a escala.

La métrica honesta es más difícil de recopilar pero mucho más útil: ¿qué porcentaje de su base de conocimientos refleja realmente el funcionamiento actual de sus sistemas? ¿Cuántas personas llegaron a una respuesta correcta utilizando su documentación? ¿Cuántos lo intentaron, fracasaron y acabaron preguntando a alguien en Slack en su lugar?

Esas preguntas aún no tienen bonitos cuadros de mando. Requieren una reflexión real sobre lo que quiere que la documentación haga por su organización. (Esto es, no por casualidad, exactamente el problema en torno al cual se construye Rasepi. Las fechas de caducidad forzadas existen precisamente para que los equipos tengan que calcular si el contenido sigue siendo válido, en lugar de dejar que decaiga silenciosamente detrás de una métrica de alto número de páginas).

Qué rastrear en su lugar

La respuesta honesta a "¿está dando frutos nuestra inversión en IA?" no puede leerse en un cuadro de mandos de facturación.

Puede aproximarla con mejores preguntas: ¿están mejorando los tiempos de ciclo? ¿La proporción entre las características enviadas y los errores notificados tiende en la dirección correcta? ¿Informan los ingenieros de que dedican más tiempo al trabajo de juicio y menos al mecanografiado? ¿Se mantiene actualizada su documentación en lugar de acumularse como un sedimento?

Estos datos son más difíciles de extraer de una API. Requieren pensar qué resultados quiere realmente de sus equipos, lo cual, hay que reconocerlo, es el trabajo más duro. Pero son las preguntas que importan, porque se refieren a los resultados más que a las entradas.

El gasto en fichas le dice cuánto cálculo ha comprado. Si ese cómputo se convirtió en algo útil es una cuestión totalmente distinta. Las empresas que no mantengan esa distinción van a construir cuadros de mando muy caros que no les mostrarán casi nada.

Pasamos años optimizando la métrica equivocada para la productividad de los desarrolladores. Tenemos quizá un trimestre antes de que el mismo error se cuele en todos los informes de adopción de la IA en la empresa. La ventana para evitarlo está abierta, pero no se quedará así.

La división de la IA está dividiendo a su equipo por la mitad

2026-04-10T00:00:00Z

La semana pasada estuve en una llamada con un amigo que me habló de uno de sus clientes, una empresa de logística. Un jefe de equipo de allí tenía una reunión de planificación en la que dos de sus personas habían construido todo un modelo de escenarios utilizando IA antes incluso de que empezara la reunión. Previsiones, desgloses de riesgos, tres enfoques alternativos. Las otras cuatro personas del equipo se presentaron con el mismo formato de cubierta de diapositivas que habían estado utilizando durante dos años. La misma estructura, el mismo proceso manual, las mismas estimaciones de plazos.

La reunión se torció rápidamente. La pareja asistida por la IA no entendía por qué los demás no habían hecho una preparación básica que "ahora lleva cinco minutos". Los demás se sintieron emboscados, como si las reglas del juego hubieran cambiado y nadie se lo hubiera dicho. El líder del equipo pasó el resto del día haciendo control de daños.

Esa historia ya no me sorprende. Llevo meses oyendo versiones de ella.

Ahora la brecha es medible

No se trata sólo de vibraciones. El [Índice de Tendencias Laborales 2025] de Microsoft (https://www.microsoft.com/en-us/worklab/work-trend-index/2025-the-year-the-frontier-firm-is-born), una encuesta realizada a 31.000 trabajadores de 31 países, reveló que el 67% de los líderes están familiarizados con los agentes de la IA, frente a sólo el 40% de los empleados. Los líderes son mucho más propensos a ver la IA como un acelerador de carrera (79% frente al 67% de los empleados), y también están ahorrando más tiempo con ella. Casi un tercio de los líderes afirman que la IA les ahorra más de una hora cada día.

Pero aquí está la parte que realmente se me quedó grabada: cuando se les preguntó cómo ven la IA, el 52% de los encuestados dijeron que la tratan como una herramienta basada en órdenes. Dale una instrucción, obtén un resultado. Sólo el 46% la describió como un compañero de pensamiento, algo con lo que se tiene un ida y vuelta.

No es una diferencia pequeña. Son dos relaciones fundamentalmente diferentes con la misma tecnología. Y esos dos grupos están sentados en las mismas reuniones, trabajando en los mismos proyectos, supuestamente avanzando en la misma dirección.

Dos velocidades, un equipo

La consecuencia práctica es que los equipos funcionan ahora a dos velocidades completamente distintas. Las personas que han integrado la IA en su trabajo diario no sólo producen más rápido. Piensan de forma diferente. Abordan los problemas de forma diferente. Llegan a las reuniones con el trabajo que antes les llevaba una semana hecho en una tarde.

Y las personas que no han adoptado la IA (o que la han probado una vez, la encontraron poco satisfactoria y siguieron adelante) están haciendo un trabajo realmente sólido. Quiero ser claro al respecto. No es que sean malos en su trabajo. Es que el techo de lo que es posible se ha movido, y ellos están trabajando bajo el antiguo.

Un estudio de Harvard sobre IA generativa en equipos descubrió algo notable: un solo individuo con IA supera a todo un equipo sin ella. Pero un equipo en el que todos utilizan IA supera a todos. La implicación es brutal. La adopción mixta no te da un término medio. Le da fricción.

Lo vi de primera mano en un taller que dirigí el mes pasado. Los participantes que utilizaban la IA con regularidad terminaban los ejercicios en la mitad de tiempo y se frustraban esperando el resto. Los participantes que no utilizaban la IA se sentían apurados y, sinceramente, un poco humillados. Nadie pretendía ese resultado. Simplemente ocurrió porque la diferencia de velocidad es así de grande ahora.

La ventaja competitiva de la que nadie habla

Aquí es donde se pone realmente consecuente. La [encuesta sobre el estado de la IA en 2025] de McKinsey (https://www.mckinsey.com/capabilities/quantumblack/our-insights/the-state-of-ai) reveló que el 88% de las organizaciones utilizan la IA en al menos una función. Suena genial, ¿verdad? Pero casi dos tercios siguen estancados en fases de experimentación y piloto. Sólo alrededor de un tercio han comenzado a escalar la IA en toda su empresa. ¿Y las empresas que han escalado, las que McKinsey denomina "de alto rendimiento"? Representan aproximadamente el 6% de los encuestados.

Ese 6% se está alejando de todos los demás a una velocidad que creo que la mayoría de la gente subestima.

Los de alto rendimiento tienen tres veces más probabilidades de haber rediseñado fundamentalmente sus flujos de trabajo en torno a la IA. Tienen tres veces más probabilidades de contar con líderes sénior que defienden y modelan activamente el uso de la IA. Tres cuartas partes de ellos están ampliando o ya han ampliado la IA en toda su organización, en comparación con un tercio de todos los demás.

Los datos de Microsoft cuentan una historia similar. Las empresas que ellos denominan "Frontier Firms" (aquellas con un despliegue de la IA en toda la organización y una madurez avanzada) informan de resultados drásticamente diferentes. El 71% de los líderes de Frontier Firm afirman que su empresa está prosperando, en comparación con el 39% de los trabajadores a nivel global. El 55% afirma que puede asumir más trabajo, frente al 25% global. Y tienen menos miedo de que la IA les quite el trabajo, no más.

La brecha entre estas empresas y el resto no se está estrechando. Se está acelerando.

Es un problema de personas disfrazado de problema tecnológico.

La tentación es resolverlo con herramientas. Despliegue Copilot, compre algunas licencias, envíe un correo electrónico a toda la empresa sobre los recursos de IA. Hecho.

Pero el verdadero reto es cultural. Es el jefe de equipo en esa llamada intentando mantener unido a un grupo en el que la mitad de la gente se siente sobrecargada y la otra mitad se siente dejada de lado. Es el directivo que tiene que explicar a un veterano de 20 años que su flujo de trabajo, el que perfeccionaron durante una década, puede que ya no sea el mejor enfoque. Es el empleado subalterno que está utilizando silenciosamente la IA para producir trabajo de nivel superior y no sabe si sentirse orgulloso o preocupado por las consecuencias políticas.

Microsoft descubrió que el 47% de los líderes enumeran la mejora de las competencias de los empleados existentes como una de las principales estrategias de personal. Supongo que eso es alentador. Pero la mejora de las competencias sólo funciona si la gente realmente quiere aprender. Y ahora mismo, una parte significativa de la mano de obra ha decidido que la IA no es relevante para ellos, no es fiable o no merece la pena el esfuerzo. Puede que algunos de ellos tengan razón sobre herramientas concretas. Pero la trayectoria más amplia no es opcional (lo digo como alguien que se ha mostrado escéptico ante muchos ciclos de exageración tecnológica a lo largo de los años, y éste parece diferente).

Hacia dónde se dirige

No creo que la división desaparezca. Creo que se amplía. Las personas que adopten la IA seguirán siendo más rápidas, seguirán produciendo más, seguirán subiendo el listón de lo que es un "rendimiento normal". Las personas que no lo hagan sentirán una presión cada vez mayor, ya sea por parte de la dirección, de los compañeros o simplemente por la realidad ambiental de que sus colegas están haciendo cosas que ellos no pueden.

Las empresas que averigüen cómo atraer a todo su equipo, no sólo a los entusiastas, tendrán una auténtica ventaja. Y esa ventaja se acumula. Cada mes de fluidez organizativa en IA es un mes que sus competidores pasan discutiendo sobre si comprar licencias de ChatGPT.

La mayor ventaja competitiva en la era de la IA no será qué modelo utiliza. Será si todo su equipo lo utiliza realmente.

¿Ese equipo de logística que he mencionado? Mi amigo me dijo que el jefe del equipo reservó un taller interno de dos días. No "así es como se hace". Más bien "así es como esto cambia la forma en que planificamos juntos". Los escépticos necesitaban ver lo que era posible en el contexto de su trabajo, no en una demostración genérica con un escenario inventado. Y los entusiastas necesitaban aprender a tener paciencia. A llevar a la gente con ellos en lugar de correr delante.

Ese parece ser el trabajo ahora mismo. No sólo adoptar la IA. Cerrar la brecha. Antes de que ella te cierre a ti.

Build vs Buy Reimagined: Lo que realmente significa en 2026

2026-04-07T00:00:00Z

La semana pasada vi a un desarrollador junior de nuestro equipo poner en marcha una aplicación CRUD funcional con autenticación, migraciones de bases de datos y una interfaz de usuario medianamente decente en unos 90 minutos. Con Copilot. Desde cero.

Hace cinco años, esa misma tarea habría llevado una semana. Tal vez dos si se cuenta el yak-shaving alrededor de las configuraciones de despliegue y los flujos de OAuth. Y ese cambio, esa compresión del tiempo de construcción de días a horas, está desmantelando silenciosamente una de las cuestiones más antiguas del software: ¿debemos construir o debemos comprar?

El viejo marco está muerto

Durante décadas, "construir frente a comprar" era un cálculo de costes. Se estimaba cuántos meses-desarrollador se necesitarían para construir una cosa, se multiplicaba por el salario cargado, se añadía algún amortiguador para el mantenimiento, y se comparaba con la cuota de licencia anual de cualquier producto SaaS que hiciera más o menos lo mismo. Si el SaaS era más barato, usted compraba. Si sus requisitos eran lo suficientemente extraños, usted construía.

Ese marco suponía que construir era caro. Y lo era. Pero según los datos de Octoverse 2025 de GitHub, el desarrollo asistido por IA produce ahora un aumento del rendimiento del 20 al 30 por ciento. El 80% de los nuevos desarrolladores en GitHub utilizan Copilot en su primera semana. Más de 1,1 millones de repositorios públicos ya integran los SDK de LLM. Construir se ha abaratado drásticamente, casi de la noche a la mañana.

Así que la pregunta ya no es realmente "construir vs comprar". Es algo más como: ¿qué está pagando realmente cuando compra SaaS?

El nuevo cálculo

Esto es lo que creo que la mayoría de los fundadores de SaaS (yo incluido, sinceramente) no quieren oír: si toda su propuesta de valor es "le evitamos construirlo", tiene problemas. Porque ese foso acaba de hacerse mucho menos profundo.

Cuando un equipo puede crear un prototipo de una herramienta interna funcional en un día, el listón de lo que justifica una suscripción mensual sube mucho. Usted no sólo necesita ser mejor que lo que ellos podrían construir. Tiene que ser mejor que lo que ellos podrían construir con la ayuda de la IA.

Gartner predijo en abril de 2026 que para 2028, más de la mitad de las empresas dejarán de pagar por la inteligencia asistida y favorecerán las plataformas que se comprometan con los resultados del flujo de trabajo. Aún más crudo: prevén que para 2030, las empresas de software que superpongan IA sobre aplicaciones heredadas en lugar de rediseñarlas para la ejecución agéntica se enfrentarán a una compresión de márgenes de hasta el 80%.

Ochenta por ciento. No se trata de un error de redondeo.

Entonces, ¿qué es lo que realmente sobrevive?

He estado pensando mucho en esto, en parte porque estamos construyendo Rasepi y necesito ser honesto conmigo mismo sobre dónde se encuentra nuestro valor. Y creo que la respuesta se reduce a tres cosas que son realmente difíciles de replicar con un sprint de codificación de fin de semana, por muy bueno que sea su asistente de IA.

**Cualquiera puede construir un editor de texto. ¿Construir un sistema de traducción que rastree los cambios de contenido a nivel de párrafo, detecte las traducciones obsoletas mediante hash de contenido y gestione la adaptación estructural entre idiomas? Eso lleva años de conocimiento del dominio incorporado en la arquitectura. La IA puede ayudarle a escribir el código más rápido, pero no puede decirle qué construir.

Alguien todavía tiene que ejecutarlo y mantenerlo. Esto es lo que pasa con la construcción: es divertida. ¿Mantener? Nada divertido. Manejar casos extremos en sistemas de permisos multiusuario, mantenerse al día con las peculiaridades de los navegadores, gestionar migraciones de bases de datos entre versiones, parchear CVE a las 2 de la madrugada, lidiar con ese error de exportación de PDF que sólo aparece en Safari. La IA hace que la compilación inicial sea más rápida, seguro. Pero la investigación de Forrester de abril de 2026 muestra que la mayoría de las empresas aún no pueden convertir la adopción de la IA en un impacto medible, en parte porque la parte difícil nunca fue escribir código. Es mantenerlo en funcionamiento, actualizado y funcionando correctamente durante años. La construcción es la parte fácil. Es el tiempo de actividad, las rotaciones de guardia y las correcciones incrementales lo que realmente le cuesta.

Confianza, seguridad y privacidad de los datos. Este aspecto está infravalorado. Cuando construye algo usted mismo, usted es el dueño de la seguridad. Usted es responsable de la encriptación en reposo, el registro de auditoría, las pruebas de penetración, el cumplimiento del GDPR, SOC 2, y la próxima regulación de la que nadie ha oído hablar todavía. Un buen proveedor de SaaS tiene un equipo entero cuyo único trabajo es asegurarse de que sus datos no terminan en algún lugar donde no deberían estar. Para la mayoría de las empresas, ése no es un coste que quieran asumir internamente. Y, sinceramente, la mayoría de las herramientas internas que he visto ni siquiera tienen controles de acceso adecuados, por no hablar de una pista de auditoría de seguridad.

El término medio componible

Lo interesante es que la respuesta cada vez más no es "construir" o "comprar". Es componer. Elija las herramientas SaaS que hacen bien las cosas difíciles, exponen buenas API y le permiten construir a su alrededor.

Esta es la razón por la que las arquitecturas de plugins importan tanto ahora mismo (y sí, esto es exactamente en lo que hemos estado invirtiendo con el sistema de plugins de Rasepi). Los productos SaaS que prosperarán son los que digan: "Nosotros nos encargamos del núcleo duro y específico del dominio. Usted personaliza todo lo demás". No "aquí está nuestro monolito, tómelo o déjelo".

El informe de Forrester de abril de 2026 descubrió que la mayoría de las empresas siguen luchando por convertir la adopción de la IA en un impacto empresarial medible. Las empresas que más la adoptan tienen un 47% más de probabilidades de trabajar con socios consultores para preparar sus datos y sistemas. El mensaje es claro: la capacidad bruta de construcción no es el cuello de botella. Saber qué construir y disponer de la infraestructura que lo respalde es la verdadera limitación.

Lo que esto significa para SaaS

Si usted dirige una empresa SaaS en 2026, creo que hay algunas verdades incómodas:

Su argumento "le ahorraremos tiempo" es más débil que nunca. El ahorro de tiempo era la venta clásica de SaaS. Pero cuando la IA comprime el tiempo de construcción en un 20-30%, la cifra de "tiempo ahorrado" en su hoja de cálculo de ROI se reduce proporcionalmente. Necesita una historia diferente.
Las características son apuestas de mesa, los resultados son el producto. A nadie le importa que tenga 47 integraciones. Les importa que su documentación se mantenga actualizada, que sus traducciones sean precisas, que su equipo utilice realmente la herramienta. El lenguaje de Gartner sobre el "flujo de trabajo centrado en los resultados" no es sólo jerga de analistas. Es hacia donde se dirige el mercado.
La apertura gana al cierre. El instinto de cerrar su plataforma y dificultar el cambio es comprensible. Pero Gartner advirtió explícitamente de que "los proveedores de SaaS heredados que intenten cerrar los sistemas de registro corren el riesgo de ser eludidos por las capas de orquestación en las que confían más las empresas." Ouch.

La versión honesta

Seré franco sobre dónde aterrizo en esto. Construir frente a comprar nunca fue realmente una cuestión de tecnología. Siempre se trató de la confianza. ¿Confío en que este proveedor entienda mi problema con la suficiente profundidad como para que su solución sea mejor que la que yo pueda improvisar?

En 2026, "improvisar" recibió una actualización masiva. Así que el listón de la confianza también subió.

Para nosotros en Rasepi, eso significa que no podemos ser simplemente una herramienta de documentación que casualmente soporta traducciones. Tenemos que ser tan buenos en los problemas difíciles, el seguimiento de la traducción a nivel de bloque, la aplicación de la frescura del contenido, la complejidad multi-inquilino, que construir un sustituto sería realmente doloroso incluso con las mejores herramientas de IA del mundo.

Ese es el nuevo "construir vs comprar". No "¿puede construirlo?", sino "¿debería gastar su energía en construirlo cuando otro ya ha resuelto las partes difíciles?".

La cuestión nunca fue realmente el coste. Se trataba de dónde quiere gastar su atención. Y en un mundo en el que construir es barato, la atención es el único recurso escaso que queda.

Deje de despedir a gente porque existe la IA

2026-04-04T00:00:00Z

Un amigo mío dirige los contenidos de una empresa mediana de SaaS. El año pasado, su equipo estaba formado por ocho personas. Redactores, editores, un especialista en localización, alguien que se encargaba de la base de conocimientos. Un buen equipo, una producción sólida. Entonces el director general asistió a una conferencia, volvió entusiasmado con la IA y en tres meses el equipo se había reducido a tres. ¿El razonamiento? "Con las herramientas de IA, tres personas pueden producir lo que antes producían ocho".

Y técnicamente, es cierto. Las tres personas restantes están produciendo aproximadamente el mismo volumen. Entradas de blog, documentos de ayuda, actualizaciones de productos, comunicaciones internas. Las cifras se ven bien en un cuadro de mandos.

Pero mi amiga no ha dormido bien en meses. Está alternando entre la redacción, la edición, la ingeniería de avisos, el control de calidad de los resultados de la IA, la gestión de las traducciones y todo el trabajo estratégico que solía compartirse entre todo el equipo. Sus dos colegas restantes están en el mismo barco. Uno de ellos ya está buscando otro trabajo.

La empresa se ha ahorrado cinco salarios. También está perdiendo poco a poco a las tres personas que realmente saben cómo funcionan las cosas.

Las matemáticas que parecen correctas pero no lo son

Este es el argumento que ha estado dando vueltas en las salas de juntas desde que ChatGPT se generalizó: una persona con IA puede hacer ahora el trabajo de diez. Y si es así, ¿por qué mantener a diez?

Es un argumento convincente. Sencillo. Limpio. Cabe en una diapositiva.

También es peligrosamente incompleto.

Sí, la IA puede comprimir tareas. Según el Índice de Tendencias Laborales 2024 de Microsoft, el 90% de los usuarios de IA en el trabajo afirman que las herramientas les ayudan a ahorrar tiempo. Los usuarios más intensivos de Microsoft Teams resumieron ocho horas de reuniones utilizando Copilot en un solo mes. Eso es una jornada laboral completa recuperada sólo con los resúmenes de reuniones. Y el 85% afirma que la IA les ayuda a centrarse en su trabajo más importante.

Son cifras reales. Los aumentos de productividad no son imaginarios.

Pero he aquí de lo que nunca hablan los partidarios de "despedir a nueve personas": la persona que se queda no sólo absorbe el rendimiento. Absorbe la carga cognitiva, el contexto, la toma de decisiones, la coordinación, la garantía de calidad y cada pizca de conocimiento institucional que salió por la puerta con esos nueve antiguos colegas.

La carga mental no es una hoja de cálculo

Existe un concepto en psicología llamado teoría de la carga cognitiva. Describe la cantidad total de esfuerzo mental que se utiliza en la memoria de trabajo en un momento dado. Y cada vez que pide a una persona que haga el trabajo mental que antes compartían cinco personas, no está ahorrando esfuerzo. Lo está concentrando.

Pienso mucho en esto cuando la gente me dice que la IA hace a los trabajadores "10 veces más productivos". ¿Productivos en qué? ¿Produciendo más palabras? ¿Enviar más billetes? ¿Generando más presentaciones de diapositivas? Claro. Pero la parte realmente difícil del trabajo del conocimiento nunca ha sido el producir. Es el pensar. Decidir qué producir. Comprender el contexto. Hacer juicios de valor. Saber cuándo algo está mal incluso cuando parece correcto en la superficie.

La IA no hace eso por usted. La IA le da un primer borrador, y ahora usted tiene que ser lo suficientemente inteligente como para evaluarlo, lo suficientemente experimentado como para detectar los errores sutiles y lo suficientemente presente como para darse cuenta de cuándo el resultado es ciertamente erróneo. (Si alguna vez ha visto a alguien enviar un documento interno generado por la IA sin leerlo, sabrá exactamente a qué me refiero).

El informe [Estado del lugar de trabajo en el mundo 2025] de Gallup (https://www.gallup.com/workplace/659279/global-engagement-falls-second-time-2009.aspx) reveló que el compromiso global de los empleados cayó hasta el 21% en 2024, frente al 23% del año anterior. Esa caída costó a la economía mundial unos 438.000 millones de dólares en pérdida de productividad. El compromiso de los directivos cayó aún más, del 30% al 27%. Las mujeres directivas experimentaron un descenso de siete puntos. Los directivos menores de 35 años cayeron cinco puntos.

Estas son las personas que se supone que deben liderar la adopción de la IA. Y se están quemando.

El argumento de la amplificación

Permítame ofrecerle una forma diferente de pensar sobre esto.

Si una persona con IA puede hacer el trabajo de diez, entonces diez personas con IA pueden hacer el trabajo de cien.

Léalo otra vez. Porque esta es la parte de la que casi nadie habla, y es la parte que debería quitar el sueño a todo director general. No porque dé miedo, sino porque es una enorme oportunidad que la mayoría de las empresas están desperdiciando.

Las empresas que despiden a la mitad de su plantilla porque "la IA puede con todo" no están siendo eficientes. Están siendo miopes. Están optimizando una cifra trimestral de plantilla mientras sus competidores descubren lo que ocurre cuando das herramientas potentes a un equipo completo de personas motivadas y con experiencia.

Vi cómo se desarrollaba esta situación en un evento de startups en Zúrich el mes pasado. Dos empresas en el mismo espacio. Aproximadamente del mismo tamaño, el mismo mercado. La empresa A había reducido su equipo de contenidos de doce a cuatro. La empresa B había mantenido a los doce y les había dado herramientas de IA además de formación. ¿Adivine cuál de las dos estaba produciendo contenidos multilingües en seis idiomas, realizando experimentos con nuevos formatos y enviando actualizaciones semanales de productos a su base de conocimientos? (No era la empresa A.)

Lo que ocurre realmente cuando se corta

Permítame repasar lo que ocurre en la práctica cuando sustituye un equipo de diez personas por uno o dos supertrabajadores "mejorados por la IA".

La primera semana sienta muy bien. Las personas restantes están llenas de energía. Tienen nuevas herramientas. Están produciendo mucho. La dirección está encantada. Las cifras del cuadro de mando parecen increíbles en relación con los efectivos.

El segundo mes, aparecen las grietas. La única persona responsable de la documentación descubre que el contenido generado por IA necesita una revisión seria. No una edición ligera. Una revisión profunda. Porque la IA no conoce los matices de su producto, el contexto de sus clientes ni las tres cosas que cambió la semana pasada y que invalidan la mitad de lo escrito. Sólo el trabajo de revisión se come el tiempo que se "ahorró" generando contenidos más rápidamente.

Cuarto mes, surgen las lagunas de conocimiento institucional. ¿Recuerda a esas ocho personas que despidió? No se limitaban a escribir contenidos. Tenían relaciones con los jefes de producto. Conocían los puntos de dolor de los clientes gracias a años de patrones de tickets de soporte. Sabían qué temas de la documentación generaban más preguntas. Ese conocimiento ha desaparecido. La IA, desde luego, no lo tiene.

Al sexto mes, usted está contratando a contratistas. Porque las personas que quedan están abrumadas, la calidad ha bajado y alguien por fin se ha dado cuenta de que la base de conocimientos no se ha actualizado correctamente en semanas. Pero los contratistas tampoco tienen contexto, así que usted está pagando más por hora por peores resultados.

No me lo estoy inventando. He visto cómo se repetía este patrón en tres empresas diferentes sólo en el último año.

Los datos dicen que conserve a su gente (y fórmela)

El Informe sobre el futuro del empleo 2025 del Foro Económico Mundial preguntó a más de 1.000 empresarios de todo el mundo sobre sus planes de personal. Las cifras cuentan una historia interesante. Sí, el 40% de los empleadores tiene previsto reducir personal cuando la IA automatice tareas. Pero el 85% planea mejorar las cualificaciones de su plantilla actual. Y el 70% espera contratar a personas con nuevas habilidades, no a menos gente.

El informe prevé un crecimiento neto del empleo de 78 millones para 2030. Eso después de contabilizar los 92 millones de puestos desplazados. El mundo no se está moviendo hacia menos trabajadores. Se está moviendo hacia trabajadores con habilidades diferentes.

Y aquí está el dato que debería hacer reflexionar a todos los directores generales de "vamos a recortar plantilla": El 64% de los empresarios identificaron el apoyo a la salud y el bienestar de los empleados como una estrategia clave para la disponibilidad de talento. No "reducir costes". No "automatizarlo todo". Apoyar el bienestar. Porque las empresas que queman a su gente no consiguen contratar después a los buenos.

Mientras tanto, un estudio de BCG y Harvard Business School descubrió que cuando los equipos utilizaban la IA para tareas creativas, alrededor del 90% mejoraba su rendimiento, y la calidad de la producción aumentaba un 40% por encima de los grupos de control. Pero el estudio también descubrió algo que debería incomodar a todo líder: la diversidad de ideas entre los grupos asistidos por IA descendió un 41%.

Piense en lo que eso significa. Usted despide a siete personas de su equipo de diez. Los tres que quedan utilizan la IA para producir el mismo volumen. Pero la gama de ideas, perspectivas y enfoques se reduce casi a la mitad. Su producción parece productiva, pero poco a poco se vuelve homogénea. Y nadie se da cuenta hasta que un competidor lanza algo genuinamente creativo y usted no puede entender por qué su equipo no está haciendo lo mismo.

La carga mental que nadie presupuesta

La encuesta de Microsoft reveló que el 68% de la gente tiene dificultades con el ritmo y el volumen de trabajo, y el 46% se siente quemado. Y este era el estado de las cosas antes de que usted les dijera que ahora están haciendo los trabajos de sus tres antiguos compañeros de equipo.

He aquí algo que no aparece en los cuadros de mando de productividad: el coste cognitivo de ser la última línea de defensa. Cuando usted es la única persona que revisa los resultados de la IA, no puede tener un día libre. Cuando es el único propietario de la base de conocimientos, todas las preguntas de soporte aterrizan en su mesa. Cuando no hay nadie a quien rebotar ideas porque el equipo fue "bien dimensionado", cada decisión es sólo suya.

He estado construyendo Rasepi en parte porque he visto este problema de cerca. Cuando los equipos de documentación se reducen, los conocimientos no se reducen con ellos. La cantidad de contenido que debe existir, mantenerse actualizado y ser preciso en todos los idiomas no disminuye sólo porque haya menos personas manteniéndolo. En todo caso, crece (por cierto, este es exactamente el problema que estamos construyendo en Rasepi para resolver, con características como las fechas de caducidad forzadas y las traducciones a nivel de bloque que hacen que los equipos más pequeños sean realmente más eficaces en lugar de estar más abrumados).

Pero ni siquiera las mejores herramientas arreglan una decisión de personal fundamentalmente rota. No se puede automatizar la necesidad del juicio humano, el contexto y la atención. Sólo puede hacer que esos humanos sean más eficaces.

Lo que hacen realmente las empresas inteligentes

Lo más impresionante de los datos de Microsoft es el aspecto de los "usuarios avanzados de IA". Se trata de personas que utilizan la IA varias veces al día y ahorran más de 30 minutos. Tienen un 68% más de probabilidades de experimentar con distintas formas de utilizar la IA. No se limitan a generar más rendimiento. Rediseñan cómo se realiza el trabajo.

Y aquí está el truco: existen dentro de las organizaciones que invierten en ellos. Los usuarios avanzados de IA tienen un 61% más de probabilidades de que su director general les hable de la importancia de la IA en el trabajo. Tienen un 53% más de probabilidades de recibir ánimos de la dirección para replantearse toda su función. Reciben formación a medida, no sólo un acceso a ChatGPT.

En otras palabras, los trabajadores más productivos en IA no son supervivientes solitarios de un despido. Son miembros de equipos apoyados y en los que se ha invertido.

Permítanme contrastar esto con lo que veo en las empresas que tomaron la ruta de "recortar plantilla". Los empleados que quedan no son usuarios avanzados. Son generalistas abrumados que intentan desesperadamente que las cosas sigan funcionando. No tienen tiempo para experimentar con la IA porque están demasiado ocupados utilizándola para sobrevivir. No se replantean la función porque la función son... ellos solos, haciéndolo todo.

El problema del conocimiento que nadie menciona

Hay una cosa más. Y no oigo a nadie hablar de ello, lo que es extraño porque debería ser obvio.

Cuando se despide a trabajadores experimentados del conocimiento, el conocimiento se va con ellos. No se queda en el edificio. No está en la wiki. No está en la IA. Está en las cabezas de las personas que construyeron los procesos, comprendieron los casos límite y sabían qué clientes se preocupaban por qué detalles.

¿Sabe lo que ocurre cuando se tienen grandes herramientas de IA y ningún conocimiento institucional? Obtienes información bellamente formateada, entregada con confianza y completamente errónea. A escala.

El mes pasado hablé con una jefa de documentación de una empresa de tecnología financiera (no quiso ser nombrada, lo cual le dice algo). Después de que su equipo se redujera de seis a dos, empezaron a depender en gran medida de la IA para mantener sus documentos para desarrolladores. En cuatro meses, notaron un repunte en las solicitudes de asistencia. Los documentos parecían estar bien. Estaban bien escritos, actualizados en apariencia. Pero contenían errores sutiles que sólo alguien con un profundo conocimiento del producto habría detectado. Una descripción de los parámetros de la API que era técnicamente correcta pero prácticamente engañosa. Una guía de migración que omitía un paso que todo el mundo en el antiguo equipo conocía. Pequeñas cosas que la IA no puede saber porque la IA no asiste a sus standups, no lee sus hilos de Slack, no oye el frustrado "oh, ese documento está mal otra vez" del ingeniero de soporte en la máquina de café.

La verdadera cuestión

Así que esto es de lo que creo que debería tratarse realmente la conversación.

No: "¿Cuánta gente podemos recortar ahora que tenemos IA?"_.

Sino de: "¿Qué será posible cuando demos IA a todos los que ya tenemos?".

Su equipo de documentación de diez personas con herramientas de IA no se vuelve redundante. Se convierte en un equipo que puede mantener el contenido en doce idiomas en lugar de dos. Que puede mantener actualizados todos los contenidos con comprobaciones automáticas de frescura. Que puede experimentar con nuevos formatos, realizar pruebas A/B sobre el contenido de ayuda, crear guías interactivas y aún así tener tiempo para pensar estratégicamente sobre lo que los clientes realmente necesitan.

Su equipo de marketing de diez personas con IA no se convierte en cinco personas haciendo el mismo trabajo con más estrés. Se convierte en diez personas que pueden personalizar las campañas a una escala que antes era imposible, probar más variaciones creativas, responder más rápidamente a los cambios del mercado y seguir teniendo el ancho de banda cognitivo para aportar ideas realmente originales que la IA nunca habría generado.

Eso no es un coste. Es una inversión con un rendimiento que se compone.

En qué acaba esto

Las empresas que ganen los próximos cinco años no serán las que corten más cabezas. Serán las que hayan descubierto cómo hacer que sus equipos existentes sean realmente más capaces.

La cuestión no es si una persona puede hacer el trabajo de diez. La cuestión es qué ocurre cuando las diez pueden hacer el trabajo de cien.

Si usted es un líder que lee esto, le pido una cosa. Antes de aprobar esa próxima ronda de "reestructuración basada en la IA", hable con las personas que se quedaron después de la última. Pregúnteles cómo les va. Pregúnteles qué han dejado de hacer porque no hay tiempo. Pregúnteles qué se les está escapando.

Y luego imagine lo que podrían conseguir si, en lugar de llevar la carga ellos solos, contaran con un equipo completo y las mejores herramientas disponibles.

Eso no es una fantasía. Para las empresas dispuestas a invertir en su gente en lugar de sustituirla, eso son los próximos doce meses.

Los lectores y los escritores están en diferentes modos mentales. ¿Por qué todas las herramientas les ofrecen la misma interfaz de usuario?

2026-04-03T00:00:00Z

Abra Confluence ahora mismo y busque un documento que necesite leer. ¿Qué ve?

Una barra de herramientas. Botones de edición. Cuadros de comentarios. Enlaces al historial de la página. Una barra lateral llena de navegación que no necesita. Migas de pan. Campos de metadatos. Indicadores de permiso. Toda una interfaz de autoría envuelta alrededor del texto que ha venido a leer.

Ahora piense en lo que realmente quería: la respuesta a una pregunta, o los tres pasos siguientes de un proceso, o una política que necesita consultar antes de una reunión dentro de diez minutos.

Usted vino a consumir. La interfaz supuso que usted había venido a crear.

Esto es lo predeterminado en casi todas las plataformas de documentación. Confluence, Notion, SharePoint, GitBook, Nuclino, Slite. Todas ellas presentan el mismo entorno a lectores y escritores. La página es la página. Todo el mundo tiene la misma vista, más o menos unos cuantos botones con permisos.

Parece normal porque nunca hemos tenido otra cosa. Pero es una decisión de diseño, no una ley de la naturaleza. Y es la equivocada.

La misma interfaz para leer y escribir crea una sobrecarga cognitiva](/es/blog/img/readers-writers-ui.svg)

Leer y escribir no son la misma tarea cognitiva

No se trata de una preferencia de interfaz de usuario. Es una diferencia fundamental en el funcionamiento del cerebro.

Cuando escribe, está en modo generativo. Está construyendo, organizando, decidiendo qué incluir y qué omitir. Necesita herramientas: opciones de formato, controles de estructura, incrustación de medios, campos de metadatos, historial de versiones, funciones de colaboración. La interfaz debe proporcionarle potencia y flexibilidad.

Cuando lee, está en modo receptivo. Está escaneando, filtrando, extrayendo lo que es relevante y tratando de seguir adelante. Necesita claridad: tipografía limpia, diseño centrado, distracciones mínimas. La interfaz debe apartarse de su camino.

La psicología cognitiva tiene un marco claro para esto. La Teoría de la carga cognitiva, desarrollada por John Sweller a finales de la década de 1980, distingue entre carga intrínseca (la dificultad del material en sí), carga germana (el esfuerzo de aprender e integrar) y carga extraña (todo lo que el entorno añade que no ayuda). Cada barra de herramientas, barra lateral y botón de edición visible para un lector es carga extraña. No les ayuda a comprender el contenido. Compite activamente por la atención.

Las investigaciones de Mayer y Moreno (2003) sobre el aprendizaje multimedia demostraron que la reducción de los elementos extraños mejora tanto la comprensión como la retención. Su principio de coherencia es directo: la gente aprende mejor cuando se excluye el material extraño en lugar de incluirlo. Una interfaz de documentación que muestre controles de autoría a los lectores está violando este principio en cada carga de página.

El lector no necesita ver las herramientas del escritor. Mostrarlas de todos modos no es neutral. Es activamente perjudicial para la comprensión.

Cómo manejan esto las plataformas actuales (en su mayoría no lo hacen)

Veamos lo que existe.

Confluence tiene un modo de lectura y un modo de edición, pero el modo de lectura sigue rodeado por la navegación, los metadatos y el árbol de páginas de la plataforma. La barra de herramientas de edición desaparece cuando no se está editando, pero el marco mental de "esta es una página wiki editable" nunca desaparece del todo. Todos los lectores ven el botón "Editar". La página susurra: puedes cambiar esto.

Notion es peor en este sentido. Su filosofía central de diseño es que todo es siempre editable. Haga clic en cualquier sitio y estará escribiendo. Eso es brillante para los escritores. Es terrible para los lectores que sólo quieren absorber el contenido sin la ansiedad de modificar algo accidentalmente. La propia [galería de plantillas] de Notion (https://www.notion.com/templates) lo demuestra: cada plantilla es un espacio de trabajo, no una publicación.

SharePoint admite técnicamente distintos diseños de página para la visualización y la edición, pero la experiencia general sigue siendo la de una intranet corporativa. Los lectores se sienten como si estuvieran dentro de una herramienta empresarial, no leyendo un documento optimizado para su comprensión.

GitBook es lo que más se acerca a una experiencia de lectura en primer lugar, con su salida limpia al estilo de la documentación. Pero incluso allí, la experiencia del lector sirve a la suposición de que el lector es un desarrollador mirando documentos técnicos. No está diseñado para el consumidor de conocimientos generales.

Ninguna de estas plataformas trata la lectura como una actividad fundamentalmente diferente de la escritura. La tratan como escribir con la barra de herramientas oculta.

Herramientas actuales: una interfaz, todos los públicos](/es/blog/img/readers-writers-current-tools.svg)

El coste de una interfaz única

No se trata sólo de un problema estético. Tiene consecuencias cuantificables.

La sobrecarga de información reduce la comprensión

Un estudio publicado en el Journal of Consumer Research descubrió que la sobrecarga de información conduce a una peor calidad de la decisión, y que el efecto aumenta a medida que crece la proporción entre información irrelevante y relevante. Una página de documentación con controles de autor visibles, árboles de navegación y campos de metadatos aumenta esa proporción para cada lector que no está allí para escribir.

El cambio de contexto tiene un coste real

Cuando una señal de la interfaz dice "puede editar esto", activa un marco cognitivo diferente al de "lea esto". La investigación de Gloria Mark en la UC Irvine sobre la atención y la multitarea descubrió que se tarda una media de 23 minutos y 15 segundos en volver a centrarse completamente tras un cambio de contexto. Un lector que se plantea momentáneamente editar (aunque sea para corregir una errata) ha sido sacado del modo lectura. No es una hipótesis. Cualquiera que haya utilizado Notion conoce la experiencia de hacer clic para seleccionar texto y empezar a escribir accidentalmente.

Los lectores y los escritores tienen necesidades diferentes ante el mismo contenido

Un escritor necesita ver la estructura, los marcadores de formato, los tipos de bloque, los metadatos y las señales de colaboración. Necesitan toda la maquinaria.

Un lector necesita ver un texto limpio, una jerarquía clara y el camino más rápido hacia la información que busca. Necesitan el contenido, no la maquinaria.

Servir a ambos desde la misma interfaz significa que ninguno obtiene una experiencia optimizada para lo que realmente está haciendo.

Y luego está el tercer público: AI

Aquí es donde la cosa se complica, y donde las plataformas existentes no están en absoluto preparadas.

La documentación en 2026 tiene tres consumidores distintos, no dos:

Escritores que crean y mantienen el contenido
Lectores que consumen contenidos visualmente
Sistemas de inteligencia artificial que recuperan, analizan y sintetizan contenidos mediante programación

Cada uno de estos públicos necesita una interfaz fundamentalmente diferente para el mismo contenido subyacente.

Los escritores necesitan herramientas de edición enriquecidas, funciones de colaboración y controles estructurales. Los lectores necesitan una presentación limpia y centrada con un mínimo de distracciones. La IA necesita una salida estructurada y legible por máquina con metadatos explícitos: señales de frescura, etiquetas de clasificación, direccionamiento a nivel de bloque y un marcado semántico limpio.

Como ya comentamos en Builders, Not Developers, los intermediarios de la IA ya son el consumidor dominante de documentación para una parte cada vez mayor de los trabajadores del conocimiento. La encuesta de desarrolladores 2024 de GitHub descubrió que el 97% de los desarrolladores empresariales han utilizado herramientas de codificación de IA. Para 2026, el 84% de los desarrolladores utilizarán herramientas de IA con regularidad, y el 41% de todo el código será generado por IA.

A estos sistemas de IA no les importa su barra lateral ni su barra de herramientas. Necesitan datos limpios. Y una plataforma que confunde la vista del lector con la del escritor también está confundiendo la superficie consumible por la IA con la superficie de autoría humana. Son tres desajustes en una sola interfaz.

Cómo separa Rasepi las experiencias

Rasepi se basa en el principio de que crear contenidos y consumirlos son actividades distintas que merecen interfaces diferentes.

El entorno del escritor

Cuando escribe en Rasepi, dispone de un entorno de autor completo. Edición de texto enriquecido con TipTap, controles a nivel de bloque, indicadores de estado de traducción, gestión de vencimientos, herramientas de colaboración, vistas de estructura de contenidos y todo lo que un escritor necesita para crear y mantener una documentación de alta calidad.

El redactor ve la maquinaria porque necesita la maquinaria.

El entorno del lector

Cuando alguien consume un documento Rasepi, ve una experiencia de lectura limpia y centrada. Sin cromo de edición. Sin barras de herramientas. Sin señales de "usted podría modificar esto". Sólo el contenido, presentado en un diseño optimizado para la comprensión y el escaneado.

El lector no ve el botón de edición porque no está aquí para editar. Están aquí para aprender algo, seguir un proceso o encontrar una respuesta. La interfaz respeta esa intención.

La superficie AI

Para los consumidores de IA, Rasepi expone el contenido a través de API estructuradas con metadatos completos. Cada bloque lleva su puntuación de frescura, estado de traducción, hash del contenido y etiquetas de clasificación. Los sistemas de IA pueden consultar el contenido a nivel de bloque, filtrar por frescura, excluir el material obsoleto o borrador y recuperar exactamente los datos estructurados que necesitan.

Nada de raspar una página wiki y esperar lo mejor. La IA dispone de una interfaz especialmente diseñada, al igual que el lector y el escritor.

Una capa de contenido, tres interfaces

Lo importante es que no estamos manteniendo tres copias del contenido. Este no es el problema de las cinco copias del mismo documento que comentamos en Deje de mantener cinco copias del mismo documento.

Se trata de una capa de contenido, almacenada como bloques estructurados, servida a través de tres vistas diferentes optimizadas para tres públicos distintos.

El escritor edita bloques. El lector ve el contenido ensamblado y estilizado. La IA consulta datos estructurados con metadatos. Los mismos bloques. La misma fuente de verdad. Diferente capa de presentación para cada consumidor.

Esto sólo es posible gracias a la arquitectura a nivel de bloque. Cada pieza de contenido es una unidad direccionable individualmente con sus propios metadatos. Puede presentar esos bloques de forma diferente en función de quién los solicite:

Audiencia	Necesidades	Obtiene
Escritor	Formateo, estructura, colaboración, metadatos	Entorno de autor completo con controles a nivel de bloque
Lector	Texto limpio, jerarquía clara, escaneo rápido	Vista de lectura centrada, sin cromo de edición
AI	Datos estructurados, puntuaciones de frescura, clasificación	API a nivel de bloque con metadatos completos

Por qué esto importa más de lo que parece

Puede que lea esto y piense: "Es sólo interfaz de usuario. Diferentes vistas de la misma cosa. ¿Qué importancia puede tener?"

Resulta que es muy importante.

Confianza de los lectores

La gente confía en los contenidos que parecen publicados. Cuando una página parece un wiki que cualquiera puede editar, los lectores la descartan inconscientemente. Cuando el mismo contenido se presenta en una vista de lectura limpia y con calidad de publicación, conlleva más autoridad. Esto no es irracional. Es una señal de que alguien se tomó en serio la presentación, lo que implica que también se tomó en serio el contenido.

El Grupo Nielsen Norman ha estudiado este tema en profundidad. Su investigación sobre la credibilidad del contenido muestra que la calidad del diseño y la presentación se encuentran entre las señales más fuertes en las que se basan los usuarios para evaluar la fiabilidad del contenido. Una vista de editor desordenada socava activamente la credibilidad del contenido que muestra.

Productividad del redactor

Los escritores que trabajan en un entorno de autor dedicado no tienen que cambiar de contexto entre "¿estoy leyendo o estoy escribiendo?". Las herramientas están ahí porque se supone que tienen que estar ahí, no porque la interfaz no pueda decidir quién la está mirando.

Fiabilidad de la IA

Cuando los sistemas de IA disponen de una superficie construida a propósito con metadatos estructurados, pueden tomar mejores decisiones sobre qué recuperar y qué excluir. Pueden comprobar las puntuaciones de frescura antes de incluir un bloque en una respuesta. Pueden respetar las etiquetas de clasificación. Pueden filtrar por idioma, estado o audiencia. Nada de eso es posible cuando la IA está raspando la misma página HTML que se diseñó para lectores humanos.

El cambio de modelo mental

El supuesto fundamental de la mayoría de las plataformas de documentación es: la página es la unidad, y todo el mundo interactúa con la página.

La suposición de Rasepi es diferente: el bloque es la unidad, y distintos públicos interactúan con los bloques a través de superficies creadas a tal efecto.

Parece una pequeña distinción arquitectónica. No lo es. Es la diferencia entre una herramienta que accidentalmente muestra contenidos a los sistemas de inteligencia artificial y otra que deliberadamente les sirve. Entre un entorno de escritura que resulta ser legible y una experiencia de lectura diseñada desde cero. Entre una interfaz suficientemente buena y tres excelentes.

La documentación ya no sólo se escribe y se lee. Se escribe, se lee, se consulta, se traduce, se puntúa, se clasifica y se sirve a sistemas de IA a escala. Una única interfaz no puede optimizar todo eso, y fingir que puede es la forma en que acabamos con wikis que nadie quiere leer y asistentes de IA que extraen respuestas de páginas que nunca fueron diseñadas para ser consumidas por máquinas.

Los lectores y los escritores están en modos mentales diferentes. La IA está en un modo completamente diferente. La interfaz debería reflejarlo.

El estado de los documentos en 2026: cinco tendencias que definirán la próxima era

2026-04-03T00:00:00Z

Cada pocos meses dedico una mañana a leer. Ni código Rasepi, ni temas de GitHub. Blogs de la competencia, informes del sector, anuncios de keynote, encuestas a desarrolladores. Cualquier cosa que haya salido en el último trimestre que tenga que ver con la documentación, la gestión del conocimiento o los flujos de trabajo asistidos por IA.

Lo hice la semana pasada y la imagen que surgió fue más nítida de lo que esperaba. No porque un solo anuncio fuera innovador, sino porque convergen cinco tendencias distintas que, al alinearlas, dibujan un panorama muy claro de lo que las plataformas de documentación deberán hacer en los próximos dos años.

Esto es lo que descubrí

1. La IA es ahora el lector principal. No los humanos.

GitBook publicó una cifra sorprendente en su AI docs data report: La lectura de documentación por parte de la IA aumentó más de un 500% en 2025. Quinientos por ciento. Eso no es un error de redondeo.

Mientras tanto, la Encuesta a desarrolladores 2024 de Stack Overflow mostró que el 61% de los desarrolladores pasan más de 30 minutos al día buscando respuestas. Pero la forma en que buscan ha cambiado. La propia encuesta de GitHub descubrió que el 97% de los desarrolladores empresariales han utilizado herramientas de codificación con IA. En 2026, el 84% de los desarrolladores utilizarán herramientas de IA a diario, y el 41% del código estará generado ahora por IA. Estas personas no están navegando por la barra lateral de su wiki. Están preguntando a Claude o Copilot, y la IA está leyendo sus documentos en su nombre.

La implicación es difícil de exagerar. Su consumidor de documentación más frecuente ya no es una persona con una pestaña del navegador abierta. Es un modelo lingüístico haciendo llamadas de recuperación. Y ese modelo no tiene capacidad para entrecerrar los ojos ante una página y pensar "hmm, esto parece anticuado".

GitBook se dio cuenta de esto pronto y respondió con su informe State of Docs 2026 y un impulso hacia los formatos legibles por máquinas. También lanzaron skill.md, una convención para estructurar la información del producto específicamente para agentes de IA. Google fue más allá con su Gemini API Docs MCP, que conecta a los agentes de codificación con la documentación actual a través del Protocolo de Contexto de Modelo. Su razonamiento era explícito: los agentes generan código obsoleto porque sus datos de entrenamiento tienen una fecha límite. La corrección del MCP elevó su tasa de aprobados en la evaluación al 96,3%.

Así que la primera tendencia está asentada. La IA es el lector principal. Las plataformas que traten esto como una restricción central de diseño, no como una característica a añadir más tarde, tendrán una ventaja estructural.

2. La frescura y los metadatos de confianza se están convirtiendo en obligatorios

Anthropic entrevistó a 81.000 usuarios de Claude en diciembre de 2025 y publicó los resultados en marzo de 2026. Se trata del mayor estudio cualitativo de usuarios de IA jamás realizado (159 países, 70 idiomas). ¿La preocupación más citada? La falta de fiabilidad. El 27% de los encuestados la mencionó como su principal preocupación, y el 79% de esas personas la habían experimentado de primera mano.

Esa cifra debería quitar el sueño a todos los equipos de documentación.

Cuando las respuestas de la IA no son fiables, el problema no siempre es el modelo. A menudo, el modelo está reproduciendo fielmente lo que encontró en un documento obsoleto. El modelo no alucinó. Simplemente, sus documentos estaban mal y nadie los señaló.

Los datos de Stack Overflow refuerzan esto desde un ángulo diferente: El 81% de los desarrolladores esperan que la IA esté más integrada en su forma de documentar el código el año que viene. Si el 81% de sus usuarios están alimentando a la IA con documentación, y el 27% de los usuarios de IA dicen que la falta de fiabilidad es el mayor problema, usted tiene un problema de confianza que ninguna cantidad de ingeniería rápida soluciona. La solución está en la fuente.

Por eso importan los metadatos de frescura. No las marcas de tiempo de "última edición" (esas le dicen cuándo alguien tocó el archivo, no si el contenido sigue siendo exacto). Frescura real: estado de las revisiones, salud de los enlaces, alineación de las traducciones, señales de lectura, detección de la deriva del contenido. Metadatos que una máquina pueda leer y utilizar para decidir si es seguro citar un documento.

Sigo volviendo a un simple encuadre. Su documentación necesita una puntuación de crédito. No una marca de tiempo. Una puntuación de crédito. (Hemos estado construyendo exactamente esto con el [sistema de puntuación de frescura] de Rasepi (/características/frescura) y, sinceramente, ver los datos de la industria sólo me hace estar más convencido de que es la decisión correcta).

3. La traducción pasa de "proyecto" a "pipeline".

DeepL publicó en febrero un artículo titulado "The 6 Translation Transformations Global Businesses Can't Afford to Miss". Su argumento: la traducción se está convirtiendo en un reto operativo continuo, no en un proyecto por lotes que se realiza trimestralmente.

Eso concuerda con todo lo que veo.

El antiguo modelo era sencillo. Escriba en inglés. Cuando tenga presupuesto, contrate a un traductor o hágalo pasar por un servicio. Reciba las traducciones. Cárguelas. Hecho hasta la próxima vez. El problema es que "la próxima vez" llega cada vez más rápido cuando su producto se envía semanalmente y sus documentos se actualizan constantemente. Para cuando la versión alemana está de vuelta de la revisión, la fuente inglesa ya ha cambiado dos veces.

El propio [Centro de personalización] de DeepL (https://www.deepl.com/customization-hub) ofrece ahora glosarios, reglas de estilo y ajustes de formalidad, lo cual es estupendo. Pero si esas herramientas viven fuera de su plataforma de documentación, estará gestionando una cadena de herramientas de traducción: editor, exportar, traducir, revisar, reimportar, repetir. Cada paso es una oportunidad para la deriva.

Notion no tiene soporte multilingüe nativo en absoluto. Confluence lo ofrece a través de plugins del mercado. GitBook añadió la traducción automática en agosto de 2025, que es un paso, pero funciona a nivel de página.

El verdadero cambio es del nivel de página al nivel de bloque. Cuando se hace un seguimiento de las traducciones a nivel de párrafo, sólo se retraduce lo que realmente ha cambiado. Una edición típica toca quizá dos párrafos de cuarenta. Eso supone un 94% menos de trabajo de traducción. (Esta es la arquitectura central de traducción de Rasepi y, sinceramente, de lo que más orgulloso estoy del producto. Pero incluso dejándonos de lado, la dirección de la industria es clara: la traducción continua, incremental e integrada es hacia donde se dirige esto).

4. Los agentes de IA necesitan contenidos estructurados, no páginas wiki

Ésta cristalizó para mí cuando Notion anunció Custom Agents en febrero. 21.000 agentes construidos durante el acceso anticipado. Agentes que responden a preguntas de las bases de conocimientos, enrutan tareas, compilan informes de estado. Sólo la rampa tiene más de 300 agentes.

Atlassian fue en una dirección similar. Rovo AI in Confluence extrae el contexto de todas las aplicaciones de Atlassian y de terceros para generar contenido. Su discurso: "contenido rico en contexto y de alta calidad basado en el trabajo existente de su equipo".

Y luego Anthropic lanzó equipos de agentes en Claude Code, donde múltiples agentes de IA se coordinan de forma autónoma en tareas complejas. Opus 4.6 obtiene una puntuación del 76% en la prueba de 8 agujas 1M MRCR (frente al 18,5% del modelo anterior), lo que significa que realmente puede recuperar información enterrada en lo más profundo de conjuntos masivos de documentos sin perder el rastro.

Las tres empresas están construyendo agentes que consumen documentación. Ninguna de ellas ha resuelto el problema de la calidad de la fuente.

La documentación de los agentes personalizados de Notion reconoce explícitamente el riesgo de inyección rápida cuando los agentes leen contenido que no es de confianza. Rovo de Atlassian coge todo lo que encuentra en su Confluence. Si ese contenido tiene tres meses de antigüedad, Rovo no lo sabe. Construye sobre él de todos modos.

Para que los agentes funcionen de forma fiable, necesitan algo más que páginas de texto. Necesitan contenidos estructurados con identificadores estables, señales explícitas de frescura, metadatos de clasificación claros y la capacidad de distinguir "esto es actual y está revisado" de "esto existe pero nadie lo ha tocado en un año". Las páginas wiki no proporcionan eso. El contenido estructurado a nivel de bloque con metadatos de confianza sí lo hace.

5. El código abierto y el autoalojamiento están resurgiendo

Esto último es más una corazonada respaldada por datos que un simple anuncio.

GitBook open-sourced their published documentation a finales de 2024 y lanzó un fondo OSS. Su razonamiento: los proyectos de código abierto merecen herramientas de documentación gratuitas y de alta calidad. Pero el movimiento también señala algo más amplio.

Notion es sólo en la nube. No hay opción de autoalojamiento. Confluence Data Center existe pero requiere una licencia. Cuando su plataforma de documentación alberga sus conocimientos operativos más sensibles (libros de jugadas de incidentes, procedimientos de cumplimiento, decisiones de arquitectura), la pregunta de "¿quién controla estos datos?" no es abstracta.

El post de Anthropic "Claude es un espacio para pensar" de febrero planteaba un argumento interesante sobre la confianza y los modelos de negocio. Su afirmación central: los incentivos publicitarios son incompatibles con un asistente de IA realmente útil. Optaron por mantenerse sin publicidad para que los usuarios confíen en la herramienta.

Creo que existe un paralelismo para las plataformas de documentación. Si su sistema de documentación es de código cerrado y sólo en la nube, no puede verificar lo que alimenta a la IA. No puede auditar los cálculos de frescura. No puede asegurarse de que sus datos permanezcan bajo su control. Para los equipos que están desplegando asistentes de IA en la parte superior de su base de conocimientos (y cada vez más, todo el mundo está haciendo esto), la auditabilidad importa.

No se trata de una polémica sobre si el código abierto es moralmente superior. Los productos de código cerrado pueden ser absolutamente dignos de confianza. Pero cuando está construyendo flujos de trabajo impulsados por IA sobre su documentación interna, la capacidad de inspeccionar y verificar el sistema es una ventaja práctica. Para nosotros, la licencia MIT de Rasepi no fue una idea de última hora. Fue una decisión de diseño arraigada en la misma lógica: la infraestructura de documentación debe ser auditable.

Lo que significan estas cinco tendencias juntas

Individualmente, cada una de estas tendencias es manejable. ¿La IA lee sus documentos? Bien, añada metadatos legibles por máquina. ¿La frescura importa? Bien, añada fechas de revisión. ¿La traducción debe ser continua? Claro, integre DeepL. ¿Los agentes necesitan estructura? Justo, mejore su modelo de contenidos. ¿La soberanía importa? Estupendo, ofrezca una opción de autoalojamiento.

Pero tomados en conjunto, describen una plataforma que parece fundamentalmente diferente de lo que la mayoría de los equipos utilizan hoy en día.

La brecha es arquitectónica. No se trata de cinco características que se puedan añadir. Son cinco supuestos que deben incorporarse a los cimientos. Cómo se almacena el contenido (a nivel de bloque, no de página). Cómo se modela la confianza (puntuaciones de frescura, no marcas de tiempo). Cómo funciona la traducción (incremental, incrustada, por párrafo). Cómo acceden los agentes de IA a los contenidos (API estructuradas con metadatos, no raspado de páginas). Cómo se controlan los datos (abiertos, auditables, autoalojables).

Ninguna plataforma establecida se ha diseñado en torno a estos cinco aspectos simultáneamente. Algunas las están añadiendo poco a poco. GitBook se está moviendo más rápido en el frente de la legibilidad de la IA. Notion está construyendo una infraestructura de agentes. Atlassian tiene distribución empresarial.

¿Pero diseñar para los cinco desde el primer día? Esa es la ventaja de empezar de cero cuando el terreno se mueve.

Soy consciente de que aquí soy parcial. Construimos Rasepi específicamente porque vimos que estas tendencias convergían y queríamos una plataforma que las asumiera todas desde el principio. Traducción a nivel de bloque, caducidad forzosa, puntuación de frescura, contenidos estructurados listos para la IA, código abierto. Es la tesis de todo el proyecto.

Pero aunque no existiéramos, creo que cualquier lectura honesta de lo ocurrido en el primer trimestre de 2026 apunta en la misma dirección. La documentación se está convirtiendo en infraestructura. Y la infraestructura tiene requisitos diferentes a los de las páginas wiki.

Los equipos que descubran esto primero no sólo tendrán mejores documentos. Tendrán agentes de IA más fiables, menores costes de traducción, menos sorpresas de cumplimiento y bases de conocimientos que realmente sigan siendo fiables con el paso del tiempo.

Ese será el estado de los documentos en 2026. La cuestión no es si estas tendencias son reales. Es si su plataforma ha sido diseñada para ellas.

Cinco tendencias. Una pregunta arquitectónica: ¿su plataforma de documentación se diseñó para 2026 o sigue sirviendo supuestos de 2016?

Fuentes: GitBook AI docs data report, GitBook State of Docs 2026, GitBook skill.md, Google Gemini API Docs MCP, Stack Overflow 2024 Developer Survey, GitHub 2024 developer survey, Index.dev developer productivity statistics, Anthropic "What 81,000 People Want from AI", Anthropic "Claude es un espacio para pensar", Claude Opus 4.6, Agentes personalizados de Notion, Atlassian Rovo en Confluence, DeepL "6 transformaciones de traducción", DeepL Customization Hub, Documentación de código abierto de GitBook, Traducción automática de GitBook.

Constructores, no desarrolladores: Cómo Claude cambió para quién son sus documentos

2026-04-02T00:00:00Z

Hay una persona ahora mismo, en algún lugar, integrando su API. No están en su sitio de documentación. No han abierto su guía de inicio. No han visto su zona de juegos interactiva ni su cuidada barra lateral de navegación.

Están sentados en Claude. O Copiloto. O Cursor. Han tecleado algo como "integrar la API de facturación de Stripe con mi aplicación Next.js utilizando el enrutador de aplicaciones" y han esperado a que les devolviera el código funcional. La IA leyó sus documentos en su nombre. Encontró los puntos finales relevantes, entendió el flujo de autenticación, eligió los métodos SDK correctos y produjo una implementación.

Hace dos semanas, en el Start Summit Hackathon de St. Gallen, vi cómo ocurría esto en tiempo real. Estaba hablando con un grupo de estudiantes de CS y un par de fundadores de startups en fase inicial sobre cómo abordan las nuevas API, y todos y cada uno de ellos describieron el mismo flujo de trabajo: pegar el problema en una IA, obtener código de vuelta, iterar a partir de ahí. Una de las estudiantes se rió cuando le pregunté si había leído los documentos. "¿Por qué iba a hacerlo? Claude los lee por mí".

La persona nunca visitó su sitio. Puede que nunca visiten su sitio. Y así es como se construye cada vez más el software.

El cambio fundamental

La documentación tiene ahora dos consumidores fundamentalmente diferentes: los humanos que la leen y los asistentes de IA que la leen en nombre de los constructores. La mayor parte de la documentación está optimizada exclusivamente para los humanos. La IA es ya el lector dominante.

Esto lo cambia todo aguas abajo:

La frescura es ahora un problema de fiabilidad. Cuando una IA sirve contenido rancio, el constructor no tiene forma de detectar el problema. El daño escala silenciosamente.
"Desarrollador" es una palabra demasiado estrecha. Los jefes de producto, diseñadores y analistas están distribuyendo software a través de asistentes de IA, a menudo sin haber leído ellos mismos ni una línea de documentación.
Una estructura legible por la máquina es más importante que el diseño visual.** Un markdown limpio, bloques autocontenidos y metadatos explícitos son lo que permite a la IA representar su producto con precisión.
Los requisitos de formato se han dividido. Los lectores humanos necesitan narrativa. Los intermediarios de la IA necesitan especificaciones estructuradas y parseables. Usted necesita servir a ambos.

El resto de este artículo explica cómo hemos llegado hasta aquí, qué significa esto para DevRel y qué puede hacer al respecto ahora mismo.

El viaje que nadie planeó

Durante mucho tiempo, las relaciones con los desarrolladores siguieron un camino bien entendido. Usted redactó una documentación exhaustiva. Publicó guías de inicio rápido. Usted dio charlas en conferencias. Usted mantuvo una presencia en Stack Overflow. Usted hizo que la referencia de su API fuera buscable, sus SDK idiomáticos, sus mensajes de error útiles.

Ese camino suponía que el desarrollador leería su contenido. Navegaría por tu estructura. Seguiría sus pasos.

La encuesta de desarrolladores 2024 de GitHub reveló que el 97% de los desarrolladores empresariales han utilizado herramientas de codificación de IA en algún momento. La encuesta anual de Stack Overflow mostró que el 76% de todos los desarrolladores utilizan o tienen previsto utilizar herramientas de IA, y que el 62% de los profesionales las utilizan activamente en su día a día. Para 2026, esa cifra subía al 84%, con el 41% de todo el código generado ahora por IA y el 51% de los desarrolladores profesionales utilizando herramientas de IA a diario. Esas cifras no se están ralentizando.

El nuevo viaje tiene un aspecto diferente. Alguien describe lo que quiere en lenguaje natural. Un asistente de IA lee la documentación, encuentra las secciones relevantes y genera la integración. El constructor revisa el resultado, tal vez refina la solicitud, tal vez pide un seguimiento. Minutos, no horas.

¿El embudo de puesta en marcha que los equipos de DevRel pasaron años perfeccionando? Se está obviando. No porque fuera malo. Simplemente, el punto de entrada se ha desplazado.

Dos consumidores, un conjunto de documentos

La documentación tiene ahora dos públicos fundamentalmente diferentes.

El primero es el lector humano. Esta persona sigue existiendo. Aparecen para tomar decisiones de arquitectura, depurar casos límite, revisar la conformidad y comprender conceptos. Quieren explicaciones narrativas, material de referencia bien organizado y un razonamiento claro sobre las compensaciones.

El segundo es el intermediario de la IA. Lee su documentación en nombre de un constructor. No le importa su barra lateral. No aprecia su diseño visual. Necesita un contenido estructurado y comprensible para la máquina: un markdown limpio, un formato coherente, especificaciones explícitas sobre las que pueda razonar sin ambigüedades.

Hoy en día, casi todos los sitios de documentación están optimizados exclusivamente para el primer público. El segundo público es ya el consumidor dominante.

Jeremy Howard identificó esta tensión cuando propuso la norma /llms.txt en 2024. Su observación fue precisa: "Los grandes modelos lingüísticos dependen cada vez más de la información de los sitios web, pero se enfrentan a una limitación crítica: las ventanas de contexto son demasiado pequeñas para manejar la mayoría de los sitios web en su totalidad." La propuesta es sencilla. Un archivo markdown curado en /llms.txt que proporcione a los modelos de IA una visión general estructurada de su producto y enlaces a los recursos más importantes. FastHTML, los propios documentos de Anthropic y un directorio creciente de proyectos ya incluyen uno.

Es una convención útil. Pero también es un síntoma de un problema más profundo. El verdadero problema no es el formato. Es que la mayor parte de la documentación nunca se diseñó pensando en el consumo por parte de las máquinas.

El constructor no recorta gastos

Existe la tentación de mirar a la persona que pregunta a Claude en lugar de leer la documentación y concluir que está tomando atajos. Que no entienden realmente lo que ocurre en el código. Que de alguna manera son un tipo de desarrollador inferior.

Ya he tenido esta conversación suficientes veces como para saber que eso suele ser erróneo.

Muchos de estos constructores son ingenieros experimentados que toman decisiones deliberadas sobre la eficiencia. Entienden el código, simplemente no quieren navegar por cuatro páginas de documentación para encontrar las tres líneas que realmente necesitan. Han aprendido que un asistente de IA puede extraer esas líneas más rápido de lo que ellos pueden escanearlas, así que delegan la lectura. (Sinceramente, yo mismo hago esto. No recuerdo la última vez que leí una guía de inicio de arriba abajo).

Anthropic reconoció este patrón cuando construyó el Protocolo de Contexto Modelo. El MCP está ahora soportado por Claude, ChatGPT, VS Code, Cursor y otros. Está diseñado explícitamente para que los asistentes de IA puedan llegar a sistemas externos, extraer contexto y actuar en consecuencia. La especificación lo describe como un "acceso a un ecosistema de fuentes de datos, herramientas y aplicaciones que aumentarán las capacidades y mejorarán la experiencia del usuario final".

Léalo con atención. Es lenguaje de infraestructura, no de conveniencia. Los constructores que utilizan estas herramientas no están evitando el trabajo. Están trabajando a través de una nueva capa, y su documentación forma parte de esa capa, tanto si usted la diseñó para ello como si no.

Las cifras respaldan esto. Sólo Claude gestiona en la actualidad 25.000 millones de llamadas API al mes, con 30 millones de usuarios activos mensuales en 159 países. El 70% de las empresas de la lista Fortune 100 utilizan Claude. Según un estudio de Menlo Ventures, Anthropic posee el 32% de la cuota de mercado de la IA empresarial por uso de modelos, por delante de OpenAI con un 25%. Un informe de investigación de HSBC lo sitúa incluso por encima: 40% por gasto total en IA. No se trata de herramientas experimentales. Son infraestructuras primarias.

Las relaciones con los desarrolladores se construyeron para otra época

Si su estrategia DevRel se diseñó antes de 2023, se diseñó para un mundo en el que los desarrolladores leían los documentos directamente. Ese mundo no ha desaparecido, pero ya no es el patrón de interacción dominante para una parte cada vez mayor de los desarrolladores.

Esto cambia el cálculo de varias actividades de DevRel de larga data.

Conferencias. Una presentación de 45 minutos en una conferencia de desarrolladores llega a una sala de unos cientos de personas. Un archivo /llms.txt bien estructurado y una documentación limpia y legible por máquina llegan a todos los constructores que preguntan a cualquier asistente de IA sobre su producto, continuamente, en cualquier momento. La charla es un acontecimiento único. La documentación legible por máquina se acumula. No digo que las conferencias no valgan nada (literalmente acabo de volver de una), pero la ecuación de apalancamiento ha cambiado.

Guías de inicio. El clásico tutorial de inicio rápido en cinco pasos es cada vez más una formalidad. El constructor no sigue pasos. Describen lo que quieren y esperan que la IA produzca la integración. Si la API está bien documentada en un formato apto para las máquinas, la IA se encarga de la experiencia de puesta en marcha de forma más eficiente de lo que podría hacerlo cualquier tutorial. En su lugar, los tutoriales deberían convertirse en material conceptual: explicar por qué elegir el enfoque A en lugar del B. La IA puede generar la implementación. Es mucho menos fiable a la hora de explicar las compensaciones.

Stack Overflow. Los datos de su propia encuesta muestran que el 84% de los desarrolladores utilizan la documentación técnica directamente, y el 90% de ellos confían en la documentación de los paquetes de API y SDK. Pero la forma en que acceden a esos documentos es cada vez más a través de una capa de IA, no de una pestaña del navegador. Las preguntas que todavía llegan a Stack Overflow tienden a ser las difíciles. Casos límite, depuración de producción, cosas que requieren matices. Valiosas, seguro. Pero ya no es donde está el volumen.

Cuando la IA lee sus documentos, la frescura se vuelve crítica

Esta es la parte en la que la mayoría de los equipos no han pensado.

Cuando un humano lee una página de documentación, puede aplicar su juicio. Pueden notar que las capturas de pantalla parecen antiguas, o que un comentario al final dice que el proceso ha cambiado. Pueden entrecerrar los ojos y pensar "esto parece anticuado".

Un asistente de IA no puede hacer nada de eso. Lee el texto, lo procesa como un hecho y genera una respuesta con total confianza. Si la documentación describe un punto final obsoleto, la IA recomendará alegremente integrarse con él. Si la documentación hace referencia a una infraestructura que fue sustituida hace seis meses, la IA describirá la antigua configuración como actual. Sin titubeos.

Y aquí está lo que hace que esto sea peor de lo que parece: El 66% de los desarrolladores ya dicen que el mayor problema con las herramientas de IA es que dan resultados que son "casi correctos pero no del todo". La documentación obsoleta alimenta directamente ese problema. La IA no está alucinando. Está reproduciendo fielmente contenido obsoleto, y no hay forma de que el constructor note la diferencia.

El constructor confía en la IA. La IA confía en la documentación. Si la documentación está anticuada, esa cadena de confianza ofrece una respuesta errónea con toda seguridad.

Esto siempre ha sido un problema, obviamente. El contenido obsoleto siempre ha confundido a la gente. Pero el daño se contenía porque los lectores humanos a veces podían detectarlo. Los intermediarios de la IA no pueden. Amplifican el contenido rancio sirviéndolo a escala, con autoridad, a personas que no tienen motivos para dudar de él.

La frescura ya no es una cuestión de calidad del contenido. Es una cuestión de fiabilidad para cada flujo de trabajo impulsado por IA que toque sus documentos.

La palabra "desarrollador" es demasiado estrecha

Las personas que construyan software en 2026 no se identificarán todas como desarrolladores. Algunos son diseñadores que incitan a Claude a construir un prototipo funcional. Algunos son jefes de producto que utilizan Cursor para enviar herramientas internas. Algunos son analistas de datos que describen una canalización de datos en lenguaje natural y dejan que un agente la ensamble. En la Cumbre Start, la mitad de los equipos del hackathon contaban con miembros sin conocimientos de programación que, al final del fin de semana, ya estaban distribuyendo software operativo.

Ramp es un ejemplo útil. Esta empresa de tecnología financiera pasó de una valoración de 5.800 millones de dólares en 2023 a 32.000 millones de dólares a finales de 2025, superando los 1.000 millones de dólares de ingresos anualizados por el camino. Es una de las startups de más rápido crecimiento de la historia. Una parte muy discutida de su enfoque: los jefes de producto construyen características directamente con herramientas de IA en lugar de esperar en un backlog de ingeniería. Los PM de Ramp no se limitan a escribir especificaciones. Envían código. La IA se encarga de la implementación. El PM se encarga de la intención.

No es un atajo. Un nuevo modelo operativo, y está funcionando a una escala que hace muy difícil descartarlo como experimento.

El propio estudio interno de Anthropic es revelador aquí. Cuando encuestaron a 132 de sus propios ingenieros sobre cómo utilizan Claude, los ingenieros informaron de que lo utilizaban para cerca del 60% de sus tareas laborales. ¿Los usos más comunes? Depurar el código existente, comprender qué hacían algunas partes de la base de código e implementar nuevas funciones. Los ingenieros dijeron que tienden a entregar a Claude tareas "no complejas, repetitivas, en las que la calidad del código no es crítica". Y el 27% del trabajo que hacen ahora con Claude simplemente no lo habrían hecho antes.

Es el propio equipo de Anthropic. Las personas que construyeron el modelo lo están utilizando como lector de documentación, navegador de base de código y generador de primeros borradores. Todos los demás están haciendo lo mismo, sólo que con su documentación en lugar de la de ellos.

Anthropic ha sido deliberado a la hora de llamar a este personaje "constructor". Sus herramientas están diseñadas no sólo para ingenieros de software profesionales, sino para cualquiera que pueda describir lo que quiere construir. Cuando Claude puede crear una aplicación completa a partir de un diseño Figma mediante MCP, la línea tradicional entre "desarrollador" y "no desarrollador" se disuelve.

Esto tiene implicaciones reales para cualquiera que mantenga documentación o se preocupe por la experiencia de los desarrolladores. Su público ya no se limita a las personas que saben lo que es un punto final REST. Incluye a cualquiera cuyo asistente de IA pueda interactuar con su producto. ¿El PM de Ramp que lanza una función utilizando su API? Probablemente nunca lea directamente su documentación. Su agente de IA sí que lo hará.

Lo que esto significa para la documentación

Si la documentación sirve ahora a dos públicos, los lectores humanos y los intermediarios de la IA, tiene que funcionar para ambos. Suena obvio. En la práctica, casi nadie lo hace.

Esto es lo que creo que realmente importa:

**Si la documentación de su API es una bonita página HTML que un LLM tiene que raspar y analizar, la IA está trabajando más de lo que debería. Envíe la especificación OpenAPI sin procesar junto con la versión renderizada. Envíe un markdown limpio. Haga que las especificaciones sean accesibles sin necesidad de que la IA interprete el diseño de la página.

Estructura a nivel de bloque en lugar de narrativa a nivel de página. Los asistentes de IA no consumen la documentación página por página. Extraen las secciones relevantes. Un documento con encabezados claros, párrafos autocontenidos y una semántica explícita a nivel de bloque es mucho más útil para una IA que una narración fluida que requiera leer toda la página para conocer el contexto.

Confíe en las señales de que las máquinas saben leer. ¿Cuándo se revisó este documento por última vez? ¿Sigue siendo actual? ¿Se ha marcado el contenido? Estas señales deben existir de forma que la IA pueda acceder a ellas, no sólo como señales visuales en una página web. Una puntuación de frescura, un estado de caducidad, una fecha de revisión, estos son los metadatos que permiten a una IA decidir si un documento es seguro para utilizarlo como fuente.

La frescura como prerrequisito, no como característica. Cuando un asistente de IA sirve a un constructor una respuesta segura basada en un punto final obsoleto, el daño es peor que un 404. El constructor construye sobre él. El constructor construye sobre ella. Lo lanza al mercado. Luego se rompe en producción, y nadie sabe por qué hasta que alguien lo rastrea hasta la documentación que debería haber sido actualizada hace meses. Cada documento al que una IA pueda hacer referencia necesita un mecanismo que demuestre que sigue siendo actual. (Este es, con toda sinceridad, exactamente el problema que estamos construyendo Rasepi para resolver. Forzar la caducidad de los bloques de documentación para que el contenido obsoleto no pueda esconderse).

Para empezar: audite su documentación actual

Si ha leído hasta aquí y está pensando "vale, pero ¿qué hago realmente el lunes?", aquí tiene cuatro cosas concretas que puede comprobar esta semana.

1. Pruebe sus documentos a través de una IA. Abra Claude o ChatGPT y pídale que integre su producto en un escenario realista. No utilice sus conocimientos internos. Fíjese sólo en lo que produce la IA. ¿Es correcto? ¿Es actual? ¿Está utilizando los puntos finales correctos, la versión correcta del SDK, el flujo de autenticación correcto? Si la IA se equivoca, eso es lo que los constructores están obteniendo en este momento.

**2. Elija las cinco páginas de documentación más visitadas y pregúntese: ¿cuándo se revisó por última vez? ¿Sigue describiendo el estado actual del producto? Si no puede responder con seguridad, tampoco podrá hacerlo una IA. Esta es la única solución de alto rendimiento para la mayoría de los equipos.

**3. Si no tiene un archivo /llms.txt, cree uno. Si su referencia API sólo está disponible como HTML renderizado, exporte la especificación OpenAPI sin procesar y hágala accesible. Si sus documentos están en un CMS que no produce un markdown limpio, ese es un problema que vale la pena resolver ahora.

4. Añada fechas de revisión y metadatos de frescura. Incluso algo sencillo, un campo last-reviewed en su sistema de gestión de contenidos, un ciclo de revisión obligatorio para las páginas de alto tráfico. Esto da tanto a los humanos como a la IA una señal sobre si el contenido es digno de confianza. Herramientas como Rasepi pueden automatizar esto con la caducidad forzosa a nivel de bloque, pero incluso un proceso manual es mejor que nada.

El cambio silencioso en la representación de los productos

Hay una consecuencia más amplia de todo esto que merece la pena exponer directamente.

Su documentación ya no es sólo un manual de referencia para desarrolladores. Es el material de partida que los asistentes de IA utilizan para representar su producto ante el mundo. Cuando un constructor pregunta a Claude cómo utilizar su producto, la respuesta de Claude está moldeada por lo que pueda encontrar y analizar de su documentación.

Buena documentación, buena respuesta. ¿Anticuados, ambiguos, encerrados en HTML difícil de analizar para un modelo? Peor respuesta, o una respuesta incorrecta. Así de sencillo.

La calidad de la respuesta de la IA sobre su producto es ahora un indicador directo de su experiencia como desarrollador. La mayoría de las empresas aún no lo tratan así.

Los equipos que van por delante en esto, Stripe, Vercel, Cloudflare, el propio Anthropic, tratan la legibilidad de la IA como una preocupación de primera clase. Un requisito fundamental que da forma a cómo se escribe, estructura y mantiene la documentación. No es un tema pendiente para el próximo trimestre.

El constructor que está sentado en Claude ahora mismo, describiendo lo que quiere construir, espera un código que funcione en cuestión de minutos. Puede que nunca vuelvan a visitar un sitio de documentación. Pero la IA que les atiende sí lo hará. Constantemente.

Esa IA es ahora su lector más frecuente. La cuestión es si su documentación está preparada para ello.

La mejor estrategia de experiencia del desarrollador en 2026 no es una charla en una conferencia o una guía rápida. Es asegurarse de que la IA lo hace bien.

Este post hace referencia a investigaciones y documentación de productos disponibles públicamente. Las estadísticas se han extraído de GitHub's 2024 developer survey, la Stack Overflow 2024 Developer Survey, Index.dev's 2026 developer productivity report, Incremys Claude statistics, y Fortune's reporting on Anthropic. La especificación /llms.txt se mantiene en llmstxt.org. El protocolo de contexto de modelo está documentado en modelcontextprotocol.io.

Dentro del motor de traducción: Glosarios, reglas de estilo y retraducción inteligente

2026-03-31T00:00:00Z

Nuestro post anterior sobre arquitectura cubría los plugins, los guardianes de acción y el sistema de canalización. Éste profundiza en el motor de traducción, la parte que creo que hace que Rasepi sea fundamentalmente diferente de cualquier otra plataforma de documentación.

No el discurso de marketing sobre traducir párrafos en lugar de páginas. El código real. Cómo se resuelven los glosarios por inquilino, cómo las reglas de estilo de DeepL y las instrucciones personalizadas dan forma a cada traducción, cómo el hashing de contenidos impulsa la detección de documentos obsoletos y cómo el orquestador decide qué bloques hay que retraducir.

El proceso de traducción

Cuando un usuario guarda un documento, el sistema no se limita a retraducirlo todo. Ejecuta una secuencia bastante específica:

Analiza el JSON de TipTap en bloques individuales
Compara los hashes de contenido para detectar qué bloques cambiaron realmente
Para los bloques cambiados, resuelva el glosario del inquilino y la lista de reglas de estilo para el par de idiomas
Aplique las reglas de estilo, las instrucciones personalizadas y la formalidad de la configuración del arrendatario
Envíe sólo los bloques modificados a DeepL
Actualice los bloques de traducción y sincronice los hashes de contenido

Cada paso es su propio servicio con su propia interfaz. Esto es importante porque cualquier paso puede cambiarse por otra cosa, un proveedor de traducción diferente, un algoritmo hash diferente, una fuente de glosario diferente.

Resolución del glosario: tenant-scoped, DeepL-synced

DeepL glosarios tienen una limitación que la mayoría de la gente desconoce: son inmutables. No se puede editar un glosario DeepL. Cualquier cambio supone borrar el antiguo y crear uno nuevo.

Rasepi maneja esto tratando la base de datos como la fuente de la verdad y los glosarios de DeepL como artefactos desechables en tiempo de ejecución. La entidad TenantGlossary almacena todo localmente:

public class TenantGlossary : ITenantScoped
{
    public Guid Id { get; set; }
    public Guid TenantId { get; set; }
    public string Name { get; set; }
    public string SourceLanguage { get; set; }     // e.g. "en"
    public string TargetLanguage { get; set; }     // e.g. "de"
    public string? DeepLGlossaryId { get; set; }   // Runtime DeepL ID
    public DateTime? LastSyncedAt { get; set; }
    public bool IsDirty { get; set; } = true;      // Triggers re-sync
    public ICollection<TenantGlossaryEntry> Entries { get; set; }
}

Cuando un usuario añade una entrada al glosario, por ejemplo, asignando "Sprint Review" a "Sprint-Überprüfung" para EN→DE, el registro de la base de datos se actualiza inmediatamente y IsDirty se establece en true. El glosario DeepL no se recrea en ese momento. Se recrea perezosamente, la próxima vez que una traducción lo necesite realmente.

El flujo de sincronización

Antes de cada llamada a traducción, el sistema resuelve el glosario:

public async Task<string?> GetOrSyncDeepLGlossaryIdAsync(
    string sourceLanguage, string targetLanguage,
    CancellationToken ct = default)
{
    var glossary = await _db.TenantGlossaries
        .Include(g => g.Entries)
        .FirstOrDefaultAsync(g =>
            g.SourceLanguage == sourceLanguage &&
            g.TargetLanguage == targetLanguage, ct);

    if (glossary is null || glossary.Entries.Count == 0)
        return null;

    if (!glossary.IsDirty && glossary.DeepLGlossaryId is not null)
        return glossary.DeepLGlossaryId;

    // Dirty - delete old, create new
    if (glossary.DeepLGlossaryId is not null)
        await _deepL.DeleteGlossaryAsync(glossary.DeepLGlossaryId);

    var entries = glossary.Entries
        .ToDictionary(e => e.SourceTerm, e => e.TargetTerm);

    var deepLGlossary = await _deepL.CreateGlossaryAsync(
        $"rasepi-{glossary.Id}",
        glossary.SourceLanguage,
        glossary.TargetLanguage,
        entries);

    glossary.DeepLGlossaryId = deepLGlossary.GlossaryId;
    glossary.IsDirty = false;
    glossary.LastSyncedAt = DateTime.UtcNow;
    await _db.SaveChangesAsync(ct);

    return glossary.DeepLGlossaryId;
}

Aquí hay tres cosas que merece la pena destacar:

Sincronización perezosa. Sólo llamamos a la API DeepL cuando realmente se necesita una traducción. La edición masiva de entradas del glosario no desencadena docenas de llamadas a la API.
**La consulta se ejecuta a través de los filtros de consulta globales de EF, por lo que TenantGlossaries se delimita automáticamente. Las entradas del glosario del arrendatario A nunca se filtran a las traducciones del arrendatario B.
Un glosario por par de idiomas. DeepL impone esto de todos modos. Un glosario EN→DE, un glosario EN→FR, y así sucesivamente. El par (SourceLanguage, TargetLanguage) es único por arrendatario.

Entradas del glosario

Las entradas individuales son sólo mapeos de términos:

public class TenantGlossaryEntry
{
    public Guid Id { get; set; }
    public Guid GlossaryId { get; set; }
    public string SourceTerm { get; set; }   // e.g. "Sprint Review"
    public string TargetTerm { get; set; }   // e.g. "Sprint-Überprüfung"
}

La API le ofrece CRUD completo además de importación/exportación CSV para la gestión en bloque:

POST   /admin/glossaries                       Create glossary
POST   /admin/glossaries/{id}/entries           Add term
PUT    /admin/glossaries/{id}/entries/{entryId}  Update term
DELETE /admin/glossaries/{id}/entries/{entryId}  Remove term
POST   /admin/glossaries/{id}/import            Import CSV
GET    /admin/glossaries/{id}/export            Export CSV
POST   /admin/glossaries/{id}/sync              Force DeepL sync

La importación CSV es súper útil para los equipos que migran desde sistemas de memorias de traducción existentes. Exporte sus términos, límpielos, impórtelos en Rasepi y la siguiente ejecución de traducción utilizará el nuevo glosario automáticamente.

Reglas de estilo, instrucciones personalizadas y formalidad

Los glosarios se ocupan de la terminología. Pero la terminología es sólo la mitad. Una traducción puede utilizar todas las palabras correctas y aun así sonar mal. Un tono incorrecto, un formato de fecha incorrecto, convenciones de puntuación incorrectas.

La API de reglas de estilo (v3) de DeepL lo soluciona. Puede crear listas de reglas de estilo reutilizables que combinan dos tipos de controles:

Reglas configuradas, convenciones de formato predefinidas para fechas, horas, puntuación, números, etc.
Instrucciones personalizadas, directivas de texto libre que dan forma al tono, la redacción y las convenciones específicas del dominio.

Rasepi las crea y gestiona por inquilino, por idioma de destino. La entidad TenantStyleRuleList almacena el DeepL style_id junto con las reglas configuradas y las instrucciones personalizadas del inquilino:

public class TenantStyleRuleList : ITenantScoped
{
    public Guid Id { get; set; }
    public Guid TenantId { get; set; }
    public string Name { get; set; }
    public string TargetLanguage { get; set; }      // e.g. "de"
    public string? DeepLStyleId { get; set; }       // Runtime DeepL style_id
    public string ConfiguredRulesJson { get; set; }  // Serialized configured rules
    public bool IsDirty { get; set; } = true;
    public DateTime? LastSyncedAt { get; set; }
    public ICollection<TenantCustomInstruction> CustomInstructions { get; set; }
}

Creación de listas de reglas de estilo

Cuando un administrador configura reglas de traducción para el alemán, Rasepi llama a la API v3 de DeepL para crear la lista de reglas de estilo. Esto es lo que parece:

public async Task<string> CreateOrSyncStyleRuleListAsync(
    TenantStyleRuleList ruleList, CancellationToken ct = default)
{
    if (!ruleList.IsDirty && ruleList.DeepLStyleId is not null)
        return ruleList.DeepLStyleId;

    // DeepL style rule lists are mutable - we can update in place
    if (ruleList.DeepLStyleId is not null)
    {
        // Replace configured rules on existing list
        await _httpClient.PutAsJsonAsync(
            $"v3/style_rules/{ruleList.DeepLStyleId}/configured_rules",
            JsonSerializer.Deserialize<JsonElement>(ruleList.ConfiguredRulesJson),
            ct);

        // Sync custom instructions
        await SyncCustomInstructionsAsync(ruleList, ct);

        ruleList.IsDirty = false;
        ruleList.LastSyncedAt = DateTime.UtcNow;
        return ruleList.DeepLStyleId;
    }

    // Create new style rule list
    var payload = new
    {
        name = $"rasepi-{ruleList.TenantId}-{ruleList.TargetLanguage}",
        language = ruleList.TargetLanguage,
        configured_rules = JsonSerializer.Deserialize<JsonElement>(
            ruleList.ConfiguredRulesJson),
        custom_instructions = ruleList.CustomInstructions.Select(ci => new
        {
            label = ci.Label,
            prompt = ci.Prompt,
            source_language = ci.SourceLanguage
        })
    };

    var response = await _httpClient.PostAsJsonAsync("v3/style_rules", payload, ct);
    var result = await response.Content.ReadFromJsonAsync<StyleRuleResponse>(ct);

    ruleList.DeepLStyleId = result.StyleId;
    ruleList.IsDirty = false;
    ruleList.LastSyncedAt = DateTime.UtcNow;
    await _db.SaveChangesAsync(ct);

    return ruleList.DeepLStyleId;
}

A diferencia de los glosarios, las listas de reglas de estilo de DeepL son mutables. Puede reemplazar las reglas configuradas en su lugar con PUT /v3/style_rules/{style_id}/configured_rules, y las instrucciones personalizadas pueden añadirse, actualizarse o eliminarse individualmente. Mucho más amigable para el refinamiento iterativo.

Qué aspecto tienen las reglas configuradas

Las reglas configuradas cubren convenciones de formato que varían según el idioma o las preferencias de la empresa. Cosas como

{
  "dates_and_times": {
    "time_format": "use_24_hour_clock",
    "calendar_era": "use_bc_and_ad"
  },
  "punctuation": {
    "periods_in_academic_degrees": "do_not_use"
  },
  "numbers": {
    "decimal_separator": "use_comma"
  }
}

Parecen triviales, pero se complican rápidamente. Un documento alemán que utiliza el formato de hora AM/PM y decimales separados por puntos sólo se lee como "traducido del inglés" para un lector alemán. Establecer use_24_hour_clock y use_comma para los separadores decimales en todas las traducciones al alemán elimina eso inmediatamente.

Instrucciones personalizadas: éste es el verdadero poder

Las instrucciones personalizadas son directivas de texto libre, hasta 200 por lista de reglas de estilo, cada una de hasta 300 caracteres. Básicamente le dicen a DeepL cómo dar forma a la traducción en lenguaje llano:

public class TenantCustomInstruction
{
    public Guid Id { get; set; }
    public Guid StyleRuleListId { get; set; }
    public string Label { get; set; }              // e.g. "Tone instruction"
    public string Prompt { get; set; }             // e.g. "Use a friendly, diplomatic tone"
    public string? SourceLanguage { get; set; }    // Optional source lang filter
}

Ejemplos reales de nuestros inquilinos:

"Use a friendly, diplomatic tone" para una startup que quiere documentos accesibles
"Always use 'Sie' form, never 'du'" para un bufete de abogados alemán
"Translate 'deployment' as 'Bereitstellung', never 'Deployment'" para términos que necesitan un tratamiento dependiente del contexto más allá del simple mapeo del glosario
"Use British English spelling (colour, organisation, licence)" para empresas con sede en el Reino Unido que traducen entre variantes del inglés
"Put currency symbols after the numeric amount" para adaptarse a las convenciones europeas

Las instrucciones personalizadas son realmente potentes para las convenciones específicas de un dominio que no caben en las entradas de un glosario. Un glosario asigna un término a otro. Una instrucción personalizada puede decir "cuando traduzca documentos de la API, utilice el modo imperativo en lugar de la voz pasiva". Ese es un tipo de control completamente diferente.

Formalidad

El parámetro formality de DeepL (default, more, less, prefer_more, prefer_less) sigue estando disponible como control independiente junto con las reglas de estilo. El "du" alemán frente al "Sie", el "tu" francés frente al "vous", los niveles de cortesía japoneses. Estos se establecen por idioma del inquilino a través de TenantLanguageConfig:

public class TenantLanguageConfig : ITenantScoped
{
    public string LanguageCode { get; set; }
    public string DisplayName { get; set; }
    public bool IsEnabled { get; set; }
    public TranslationTrigger Trigger { get; set; }
    public string? Formality { get; set; }         // "more", "less", "prefer_more", etc.
    public string? StyleRuleListId { get; set; }   // Links to TenantStyleRuleList
    public string? TranslationProvider { get; set; }
    public int SortOrder { get; set; }
    public bool IsDefault { get; set; }
}

La formalidad, las normas de estilo y los glosarios se componen. Una sola llamada de traducción puede llevar los tres:

var glossaryId = await GetOrSyncDeepLGlossaryIdAsync(sourceLang, targetLang, ct);
var styleId = await GetOrSyncStyleRuleListAsync(targetLang, ct);
var formality = tenantLanguageConfig.Formality ?? "default";

// Build the v2/translate request payload
var payload = new
{
    text = new[] { blockContent },
    source_lang = NormalizeLanguageCode(sourceLang),
    target_lang = NormalizeLanguageCode(targetLang),
    glossary_id = glossaryId,
    style_id = styleId,
    formality = formality,
    preserve_formatting = true,
    context = surroundingContext,  // Adjacent blocks, not billed
    model_type = "quality_optimized"
};

Aquí hay que señalar dos cosas:

El parámetro context. Pasamos bloques adyacentes como contexto para mejorar la calidad de la traducción. DeepL lo utiliza para resolver ambigüedades, pero no traduce ni factura por ello. Un párrafo sobre "celdas" se traduce de forma diferente cuando el contexto circundante es un documento de biología frente a un manual de hojas de cálculo.
Selección del modelo. Cualquier solicitud con style_id o custom_instructions utiliza automáticamente el modelo quality_optimized de DeepL. Este es el nivel de calidad más alto. No puede combinarlos con latency_optimized, y es una restricción deliberada de DeepL. La personalización del estilo necesita el modelo completo.

Por qué esto importa más de lo que cree

Imagine una empresa que escribe documentos internos en alemán con un "du" informal que de repente cambia a un "Sie" formal en una sección traducida. Parece incoherente en el mejor de los casos, poco profesional en el peor. La formalidad se encarga de eso. Pero la formalidad por sí sola no detectará un documento que utiliza marcas de tiempo AM/PM cuando su oficina alemana utiliza el formato de 24 horas, o que pone el símbolo de la moneda antes del número en lugar de después.

Todas estas capas juntas (reglas de estilo, instrucciones personalizadas, formalidad, glosarios) producen traducciones que se leen como si alguien de su equipo las hubiera escrito. No como salidas de una máquina que no sabe que su empresa existe.

La capa de servicio DeepL

Toda la comunicación de DeepL pasa por IDeepLService. Envuelve el SDK .NET oficial de DeepL y gestiona las llamadas a la API v3 para las reglas de estilo:

public interface IDeepLService
{
    // Text translation (v2)
    Task<TextResult> TranslateTextAsync(
        string text, string sourceLanguage, string targetLanguage,
        string? options = null);

    Task<TextResult[]> TranslateTextBatchAsync(
        IEnumerable<string> texts, string sourceLanguage,
        string targetLanguage, string? options = null);

    // Glossary management (v2)
    Task<GlossaryInfo> CreateGlossaryAsync(
        string name, string sourceLang, string targetLang,
        Dictionary<string, string> entries);
    Task DeleteGlossaryAsync(string glossaryId);
    Task<GlossaryInfo> GetGlossaryAsync(string glossaryId);
    Task<GlossaryInfo[]> ListGlossariesAsync();
    Task<Dictionary<string, string>> GetGlossaryEntriesAsync(
        string glossaryId);

    // Style rules (v3)
    Task<StyleRuleResponse> CreateStyleRuleListAsync(
        string name, string language,
        JsonElement configuredRules,
        IEnumerable<CustomInstructionRequest> customInstructions);
    Task ReplaceConfiguredRulesAsync(
        string styleId, JsonElement configuredRules);
    Task<CustomInstructionResponse> AddCustomInstructionAsync(
        string styleId, string label, string prompt,
        string? sourceLanguage = null);
    Task DeleteCustomInstructionAsync(
        string styleId, string instructionId);
    Task DeleteStyleRuleListAsync(string styleId);

    // Usage tracking
    Task<Usage> GetUsageAsync();
    Task<Language[]> GetSourceLanguagesAsync();
    Task<Language[]> GetTargetLanguagesAsync();
}

La implementación gestiona la normalización del código del lenguaje. DeepL requiere EN-US o EN-GB en lugar de en desnudo, y PT-PT o PT-BR en lugar de pt:

private static string NormalizeLanguageCode(string code)
    => code.ToLower() switch
    {
        "en" => "EN-US",
        "pt" => "PT-PT",
        _ => code.ToUpper()
    };

La traducción por lotes utiliza el troceado de 50 elementos para mantenerse dentro de los límites de la API de DeepL al tiempo que se maximiza el rendimiento:

public async Task<TranslationBatchResult> TranslateBatchAsync(
    Dictionary<string, string> texts,
    string sourceLanguage, string targetLanguage)
{
    var translations = new Dictionary<string, string>();
    long totalChars = 0;

    foreach (var chunk in texts.Chunk(50))
    {
        var results = await _deepL.TranslateTextBatchAsync(
            chunk.Select(kv => kv.Value),
            sourceLanguage, targetLanguage);

        for (int i = 0; i < chunk.Length; i++)
        {
            translations[chunk[i].Key] = results[i].Text;
            totalChars += chunk[i].Value.Length;
        }
    }

    return new TranslationBatchResult
    {
        Translations = translations,
        BilledCharacters = totalChars
    };
}

Dado que sólo enviamos bloques anticuados, no documentos enteros, un lote de traducción típico para una sola edición contiene de 1 a 3 bloques en lugar de más de 40. De ahí procede la reducción de costes del 94%.

El orquestador de traducción

El TranslationOrchestrator decide qué hacer con cada bloque cuando cambia el documento fuente. Recorramos el árbol de decisiones:

public async Task OrchestrateTranslationAsync(
    Guid entryId, List<Guid> changedBlockIds,
    CancellationToken ct = default)
{
    var entry = await _db.Entries
        .FirstOrDefaultAsync(e => e.Id == entryId, ct);

    var translations = await _db.EntryTranslations
        .Where(t => t.EntryId == entryId)
        .ToListAsync(ct);

    foreach (var translation in translations)
    {
        var langConfig = await GetLanguageConfigAsync(
            translation.Language, ct);

        var translationBlocks = await _db.TranslationBlocks
            .Where(tb => changedBlockIds.Contains(tb.SourceBlockId)
                      && tb.Language == translation.Language)
            .ToListAsync(ct);

        foreach (var block in translationBlocks)
        {
            if (block.IsLocked || block.TranslatedById is not null)
            {
                // Human-edited or locked - mark stale, don't overwrite
                block.Status = TranslationStatus.Stale;
            }
            else if (langConfig.Trigger == TranslationTrigger.AlwaysTranslate)
            {
                // Machine-translated, auto mode - retranslate now
                await RetranslateBlockAsync(block, translation.Language, ct);
            }
            else
            {
                // TranslateOnFirstVisit - mark stale, translate later
                block.Status = TranslationStatus.Stale;
            }
        }
    }

    await _db.SaveChangesAsync(ct);
}

El bit clave: Los bloques editados por humanos nunca se sobrescriben automáticamente. Si un traductor ajustó manualmente un bloque, quizá añadiendo contexto cultural o reformulando la redacción para mayor claridad, el sistema respeta ese trabajo. Marca el bloque como obsoleto para que el traductor sepa que la fuente ha cambiado, pero no reemplazará silenciosamente sus ediciones.

Los bloques traducidos automáticamente con AlwaysTranslate activado se retraducen inmediatamente. Los bloques traducidos automáticamente con TranslateOnFirstVisit se marcan como obsoletos y se traducen cuando alguien abre el documento en ese idioma.

Activadores de traducción: cuándo se producen las traducciones

Cada idioma tiene un TranslationTrigger que controla los tiempos:

public enum TranslationTrigger
{
    AlwaysTranslate,         // Translate on every save
    TranslateOnFirstVisit    // Translate when first opened in that language
}

AlwaysTranslate es útil para los idiomas de alta prioridad en los que desea que las traducciones estén inmediatamente actualizadas. Francés para una empresa con una gran oficina en París. Alemán para una empresa con sede en Múnich.

TranslateOnFirstVisit es útil para idiomas que se necesitan ocasionalmente pero no merece la pena el coste API de mantener perfectamente actualizados en todo momento. Cuando alguien abre el documento en ese idioma, los bloques obsoletos se traducen sobre la marcha.

Ambos modos utilizan la misma resolución de glosario, los mismos ajustes de formalidad y el mismo hashing de contenido. La única diferencia es el tiempo.

Adaptación única del contenido y la estructura

Aquí es donde la arquitectura realmente vale la pena más allá de la mera traducción.

Cuando un traductor alemán añade una sección de cumplimiento de la DSGVO que no existe en inglés, la añade como un nuevo bloque en la versión alemana. Ese bloque no tiene SourceBlockId, está marcado como contenido único. El sistema nunca lo envía para retraducción porque no hay fuente de la que traducir. Sólo existe en alemán.

Cuando un traductor japonés cambia una lista con viñetas por una lista numerada (una convención común en la escritura técnica japonesa), la bandera IsStructureAdapted del bloque lo conserva en futuros ciclos de retraducción:

var translation = new TranslationBlock
{
    SourceBlockId = sourceBlockId,
    Language = targetLanguage,
    BlockType = translatedBlockType,
    SourceBlockType = sourceBlock.BlockType,
    IsStructureAdapted = translatedBlockType != sourceBlock.BlockType,
    StructureAdaptationNotes = "Numbered list preferred in JP technical docs",
    SourceContentHash = sourceBlock.ContentHash,
    Status = TranslationStatus.UpToDate,
};

La bandera IsNoTranslate se ocupa del contenido que debe copiarse textualmente: bloques de código, URL, nombres de productos, notación matemática. El proveedor de traducción se los salta por completo.

Ponerlo todo junto

Recorramos el flujo completo. Un usuario en Londres edita un párrafo en el documento fuente en inglés, y su oficina de Múnich tiene el alemán configurado en AlwaysTranslate:

El usuario guarda. TipTap envía JSON a la API.
Extracción de bloques y detección de cambios. CreateBlocksFromDocumentAsync analiza JSON, recalcula los hashes de contenido y compara los hashes antiguos y nuevos para identificar qué bloques cambiaron realmente.
El orquestador se ejecuta. Encuentra el EntryTranslation alemán, comprueba el bloque alemán. Está traducido por máquina, no está bloqueado y no ha sido editado por humanos, por lo que es apto para la retraducción.
Configuración de traducción cargada. ID del glosario resuelto mediante GetOrSyncDeepLGlossaryIdAsync("en", "de"), reglas de estilo mediante GetOrSyncStyleRuleListAsync("de"), formalidad establecida en "más" (formal "Sie"), bloques adyacentes pasados como contexto para desambiguación.
Llamada DeepL. Se envía un único bloque con el ID del glosario, el ID del estilo, la formalidad y el contexto.
Bloque actualizado. Contenido traducido almacenado, SourceContentHash sincronizado, estado establecido en UpToDate. Un bloque traducido en lugar de los más de 40. ¿Los 39 bloques restantes? Intactos.

Mientras tanto, su oficina de Tokio tiene el japonés fijado en TranslateOnFirstVisit. La misma edición marca el bloque de traducción japonés como Stale. Cuando alguien en Tokio abre el documento, los pasos 5-9 suceden sobre la marcha. La adaptación de su estructura (lista numerada) se conserva. Sus bloques únicos permanecen exactamente donde están.

Creo que el motor de traducción es la parte de Rasepi que aporta el valor más visible. Traducciones que utilizan su terminología, siguen sus convenciones de formato, obedecen sus instrucciones personalizadas, coinciden con su tono, respetan el trabajo de sus traductores y cuestan una fracción de lo que costaría la retraducción de un documento completo. La arquitectura hace que todo eso sea automático, y se mantiene al margen cuando los humanos quieren tomar el relevo.

El mismo motor DeepL que impulsa las traducciones escritas también impulsa Talk to Docs, nuestra interfaz de documentación conversacional, con DeepL Voice encargándose de la interacción hablada. Los mismos glosarios, las mismas normas de estilo, la misma formalidad, la misma coherencia. Tanto si su equipo lee la documentación como si habla con ella, la calidad lingüística es idéntica.

Explore la API de traducción →

Hablar con los documentos es mejor que leerlos

2026-03-10T00:00:00Z

Hay una razón por la que la gente dice "hablemos de ello" cuando algo es complejo.

Cuando intentamos comprender una idea nueva, resolver un problema o recordar un proceso bajo presión, la conversación suele resultar más fácil que la lectura. No porque leer sea malo. La lectura es una de las herramientas más poderosas que ha desarrollado el ser humano. Pero la lectura es una habilidad aprendida que se superpone a algo mucho más antiguo: el habla.

Somos habladores mucho antes que lectores.

Eso importa más de lo que la gente cree, sobre todo ahora que la mayor parte del conocimiento del mundo vive dentro de documentos, wikis, PDF y largas páginas internas que nadie quiere abrir a menos que sea absolutamente necesario.

La lectura se aprende. La conversación es nativa.

Los seres humanos hablaron durante mucho tiempo antes de escribir nada. Los niños aprenden a comprender el lenguaje hablado de forma natural. La lectura requiere instrucción explícita, repetición y años de práctica.

Incluso para los adultos altamente alfabetizados, la lectura sigue siendo un acto más deliberado que escuchar o hablar. Requiere concentración visual, atención continua, memoria de trabajo e interpretación de la estructura de la página. Se descodifican símbolos, se analizan frases, se construye el contexto y se decide lo que importa.

La conversación funciona de forma diferente. Cuando la información se transmite de forma hablada e interactiva, el cerebro vive una experiencia diferente:

Se siente secuencial en lugar de visualmente abrumadora.
Proporciona información y aclaraciones inmediatas
Reduce la necesidad de escanear y filtrar grandes bloques de texto
Refleja la forma en que la gente pide ayuda en la vida real.

Este último punto es muy importante. Ante la incertidumbre, la mayoría de la gente no quiere leer instintivamente 1.500 palabras. Quieren preguntar: _"¿Qué hago ahora?

Hablar reduce la fricción cognitiva

Un documento es estático. Lo contiene todo a la vez.

Parece útil, y a menudo lo es. Pero también crea fricción. Una página llena de encabezamientos, llamadas, enlaces, notas, ejemplos y casos extremos obliga al lector a decidir qué ignorar. Eso es cognitivamente costoso.

Cuando se habla con un sistema de información, se suele obtener la experiencia opuesta: la relevancia primero, el detalle después.

Usted hace una pregunta. Obtiene una respuesta. Luego hace una pregunta de seguimiento.

Ese patrón de interacción reduce la sobrecarga mental de varias formas importantes:

1. Reduce el espacio del problema

Un documento completo presenta todo el panorama. Una conversación presenta el siguiente paso útil.

Cuando alguien pregunta: "¿Cómo incorporo a un nuevo ingeniero?", normalmente no quieren todo el manual inmediatamente. Quieren orientación. La conversación les permite empezar poco a poco y ampliar sólo cuando sea necesario.

2. Preserva la memoria de trabajo

Leer le obliga a retener varias cosas en la cabeza mientras busca la parte relevante. La interacción oral o conversacional externaliza ese esfuerzo. El sistema hace más del filtrado por usted.

3. Le resulta socialmente familiar

Los humanos estamos profundamente adaptados al intercambio de ida y vuelta. Preguntamos. Alguien responde. Afinamos. Ellos aclaran. Ese bucle es una de las formas de aprendizaje más antiguas que tenemos.

Incluso cuando el "alguien" es un sistema, la estructura sigue pareciendo natural.

Leer no es pasivo. Esa es exactamente la cuestión.

Una de las razones por las que hablar puede parecer más fácil es que leer no es tan fácil como la gente supone. Los lectores expertos hacen que parezca que no requiere esfuerzo, pero el proceso es muy activo.

Para leer bien, tiene que hacerlo:

identificar la estructura
deducir la importancia
resolver la ambigüedad
mantener el contexto en la memoria
conectar una sección con otra
decidir cuándo hojear y cuándo ir más despacio

Eso es verdadero trabajo cognitivo.

En muchas situaciones, ese trabajo merece la pena. La lectura profunda ayuda con los matices, la precisión y la comprensión a largo plazo. Pero en otras situaciones, especialmente cuando alguien está cansado, estresado, sobrecargado o simplemente intenta desatascarse, hablar es a menudo la opción mentalmente más ligera.

Esto es especialmente cierto en el lugar de trabajo, donde la gente no suele acercarse a la documentación en condiciones ideales. Lo están:

a mitad de tarea
interrumpida
cambiando de contexto
intentando resolver algo rápidamente
a menudo ya ligeramente frustrado

En ese estado, el acceso conversacional a la información puede sentirse mucho mejor que el acceso a través de una página.

Hablar cambia la relación con la información

Aquí también hay una dimensión emocional.

Los documentos pueden parecer formales y distantes. Implican: lea todo esto, entiéndalo bien y no se pierda nada importante. Eso puede ser útil como material de referencia, pero también puede crear dudas.

La conversación se siente permisiva. Se puede ser vago. Puede preguntar mal. Puede admitir confusión. Puede decir: "En realidad no sé lo que estoy buscando, pero necesito lo de las solicitudes de acceso".

Eso importa porque la gente suele evitar la documentación no porque no les guste la información, sino porque les disgusta el esfuerzo y la incertidumbre que supone encontrar la parte adecuada.

Hablar reduce esa barrera.

Por qué esto importa ahora

Durante mucho tiempo, había que leer los documentos porque no existía una alternativa práctica. La búsqueda ayudó a la gente a encontrar páginas, pero no cambió el modelo de interacción. Aún había que abrir la página, escanearla y extraer lo que se necesitaba.

Eso está cambiando.

A medida que las interfaces se vuelven más conversacionales, la gente espera cada vez más que la información responda en lugar de simplemente existir. Quieren pedir lo que necesitan en un lenguaje sencillo y recibir algo adaptado al momento.

Esto no hace que la lectura sea obsoleta. Cambia su función.

La lectura se convierte en la capa profunda. La conversación se convierte en la capa de acceso.

Los mejores sistemas soportarán ambas:

hablar cuando necesite orientación o rapidez
leer cuando necesite profundidad, verificación o contexto completo

El riesgo de simplificar en exceso

Hay una advertencia importante: hablar con información sólo sienta mejor si las respuestas son fiables.

Si una interfaz conversacional da respuestas parciales, engañosas o demasiado seguras, la experiencia se vuelve peor que la lectura porque elimina la capacidad del usuario de inspeccionar directamente el material fuente.

Así que el futuro no es "sustituir todos los documentos por la voz". El futuro es dar a la gente una forma más humana de acceder a los documentos sin perder la profundidad y la precisión que proporciona el conocimiento escrito.

Ese equilibrio es importante. Conversar es más fácil, pero los documentos siguen teniendo la estructura duradera, el detalle y la responsabilidad que necesitan las organizaciones.

Una interfaz más humana para el conocimiento

El punto más profundo es sencillo: las personas no piensan de forma natural en páginas. Piensan en preguntas, historias, fragmentos y diálogo.

Nosotros preguntamos:

¿Qué significa esto?
¿Qué hago primero?
¿Cuál es la parte importante?
¿Puede explicarlo de otra manera?
¿Qué ha cambiado?

Son movimientos de conversación, no de lectura.

Así que cuando hablar con la información resulta mentalmente más fácil que leerla, no es un signo de pereza intelectual. Suele ser una señal de que la interfaz coincide con la forma en que el cerebro prefiere abordar la incertidumbre.

La lectura sigue siendo esencial. Pero como punto de entrada al conocimiento, la conversación a menudo se siente mejor porque está más cerca de lo que somos por naturaleza.

Primero no somos lectores. Primero somos habladores. Los sistemas de conocimiento más intuitivos lo recordarán.

Plataformas de documentación creadas para otra época

2026-03-08T00:00:00Z

Confluence y Notion no son malos productos. Eso hay que decirlo claramente desde el principio.

Tuvieron éxito por buenas razones. Confluence se convirtió en el hogar por defecto de la documentación interna en muchas empresas porque ofrecía a los equipos un lugar central para escribir, organizar y compartir conocimientos. Notion se ganó a la gente con flexibilidad, experiencias de escritura más limpias y una superficie de producto de sensación más moderna.

Ambas plataformas resolvieron problemas reales en la época para la que fueron construidas.

El problema ahora es que el mundo que las rodea ha cambiado más rápido que sus fundamentos.

Ya no estamos en un mundo en el que la documentación sólo necesita escribirse, almacenarse y buscarse. Estamos en un mundo en el que cada vez se espera más de la documentación:

legible por máquina
consciente de la frescura
segura para la recuperación mediante IA
lo suficientemente estructurada para la automatización
dinámico en todos los idiomas y para todos los públicos
continuamente fiable, no sólo disponible

Se trata de un listón diferente.

Se construyeron para un modelo de conocimiento anterior a la IA

Las plataformas de documentación tradicionales se diseñaron en torno a un supuesto simple: si la página existe y se puede buscar en ella, el problema está resuelto en su mayor parte.

Eso era suficientemente bueno cuando el usuario principal era un humano que abría un wiki, hojeaba la página y aplicaba su criterio. En ese modelo, el trabajo de la plataforma consistía en facilitar la autoría y la navegación.

La IA cambia la descripción del trabajo.

Ahora la plataforma no se limita a almacenar conocimientos para las personas. Está produciendo material fuente para sistemas que recuperan, clasifican, resumen y responden preguntas automáticamente.

Eso introduce nuevos requisitos que las arquitecturas anteriores no priorizaban:

¿Qué contenidos son fiables en este momento?
¿Qué páginas están obsoletas pero aún se pueden buscar?
¿Qué secciones han cambiado recientemente?
¿Qué versión lingüística es la actual?
¿Qué contenidos son borradores, están archivados, son específicos de una región o son poco fiables?
¿Qué documentos deberían excluirse por completo de las respuestas AI?

Una plataforma que no se haya construido en torno a estas preguntas tiene que adaptarlas. Eso siempre es más difícil que diseñar para ellas desde el principio.

La fuerza heredada se convierte en un lastre heredado

Los productos establecidos tienen ventajas: distribución, ecosistema, marca, familiaridad con el cliente, integraciones y equipos que saben cómo hacer envíos. Pero esas mismas fortalezas pueden ralentizar el cambio estructural.

¿Por qué? Porque las plataformas maduras conllevan compromisos.

Los tienen:

años de decisiones acumuladas sobre productos
enormes bases instaladas con flujos de trabajo existentes
expectativas en torno a la compatibilidad con versiones anteriores
plugins y extensiones que dependen de comportamientos antiguos
modelos de datos optimizados para los casos de uso de ayer

Cuando una plataforma como Confluence o Notion quiere añadir una capacidad realmente nueva, a menudo tiene que encajar esa capacidad alrededor del sistema existente en lugar de a través de él.

Ése es el reto de la incumbencia: no sólo está construyendo el futuro, sino que está arrastrando el pasado consigo.

Añadir funciones de IA no es lo mismo que convertirse en nativo de IA

Muchas plataformas establecidas están ahora superponiendo la IA. Resúmenes. Ayuda a la escritura. Mejoras en la búsqueda. Interfaces de preguntas y respuestas. Confluence cuenta con Atlassian Intelligence, Notion ha incorporado Notion AI y GitBook ha añadido AI-powered search. Se trata de funciones útiles. Algunas de ellas son buenas.

Pero hay una diferencia significativa entre:

añadir características de IA a un producto de documentación
construir un producto de documentación cuya arquitectura central asuma el consumo de IA desde el primer día

El primer enfoque suele dar lugar a funciones de asistencia en los bordes. El segundo cambia los cimientos.

Una plataforma de conocimiento nativa de la IA plantea preguntas de diseño diferentes desde el principio:

¿cómo deben estructurarse los documentos para que los sistemas puedan razonar sobre ellos con seguridad?
¿cómo debe representarse la confianza?
¿qué metadatos deben ser de primera clase y no opcionales?
¿cómo debe degradarse la visibilidad de los contenidos obsoletos?
¿cómo deben restringirse las respuestas cuando las fuentes subyacentes son débiles?

Se trata de cuestiones de arquitectura, no de características.

Las plataformas frescas tienen una ventaja temporal

Aquí es donde las plataformas más nuevas pueden ganar, al menos durante un tiempo.

Una plataforma nueva tiene la libertad de diseñar en torno a las limitaciones de hoy en lugar de los hábitos de ayer. No tiene que conservar una década de suposiciones sobre lo que es un documento o cómo debe comportarse un wiki. Puede tomar decisiones diferentes desde el principio:

tratar la frescura como un concepto de primera clase
hacer que la confianza en la fuente sea visible tanto para los humanos como para las máquinas
almacenar metadatos más ricos sobre el estado del contenido
integrar los flujos de trabajo multilingües en el modelo básico en lugar de añadirlos por añadidura
Decidir que la búsqueda y la recuperación mediante inteligencia artificial se clasifiquen en función de la confianza y no sólo de la relevancia.

Que la libertad importa.

En tecnología, los operadores tradicionales suelen ser más fuertes durante los periodos estables. Los nuevos competidores suelen ser más fuertes cuando el propio modelo está cambiando.

La era de la IA es uno de esos cambios.

Por qué esto es especialmente duro para Confluence

Confluence es potente, pero procede de una visión del mundo más antigua. Se construyó en torno a espacios de equipo, páginas, navegación jerárquica, y un modelo de empresa rico en plugins. Esas opciones tenían sentido. Siguen teniendo sentido para muchas organizaciones.

Pero también significan que el producto arrastra mucha complejidad. Las plataformas empresariales rara vez consiguen reinventarse limpiamente. Tienen que negociar con su propia historia.

Eso hace que la modernización sea más lenta. No imposible. Sólo más lenta.

Cuando los requisitos de la era de la inteligencia artificial exigen metadatos más limpios, un modelado de confianza más explícito o una gobernanza de contenidos más orientada a las opiniones, un sistema construido para ofrecer la máxima flexibilidad a través de años de ampliaciones puede tener dificultades para moverse de forma cohesionada.

Por qué esto es especialmente delicado para Notion

Notion tiene un problema diferente. Parece más nuevo, más ligero y más flexible. Pero la flexibilidad también puede jugar en su contra.

El punto fuerte de Notion es que casi cualquier cosa puede convertirse en una página, una base de datos, una nota, un documento ligero o un espacio de colaboración. Esa flexibilidad es estupenda para los equipos. Es menos genial cuando se necesitan garantías sólidas sobre el significado del contenido, el estado en que se encuentra y si debe ser utilizado como fuente de confianza por un sistema de IA.

Cuanto más libre sea una plataforma, más difícil será imponer una semántica fiable más adelante.

Los sistemas de IA prosperan con estructura, metadatos explícitos y señales de confianza. Los espacios de trabajo flexibles de uso general a menudo necesitan mucha interpretación antes de que su contenido sea seguro para ese tipo de uso.

Nada de esto significa que estén condenados

Sería un análisis perezoso decir que Confluence y Notion no pueden adaptarse. Por supuesto que pueden.

Cuentan con equipos inteligentes, importantes recursos y fuertes incentivos. Lanzarán más capacidades de IA. Mejorarán la recuperación, la ayuda a la autoría, los resúmenes, la gobernanza y los flujos de trabajo estructurados. Con el tiempo, es posible que acorten muchas distancias.

Pero el momento es importante.

Cuando se produce un cambio como éste, la ventaja suele pertenecer a quien esté dispuesto a reconstruir los supuestos más rápidamente. Las plataformas más nuevas pueden moverse con más coherencia porque no se están adaptando tanto. Eso les da una ventana.

Puede que no sea una ventana permanente. Pero es real.

La siguiente fase de las plataformas de documentación

Es probable que la próxima generación de herramientas de documentación se juzgue menos por lo bien que permiten a la gente escribir páginas y más por lo bien que gestionan el conocimiento como un sistema de confianza.

Eso significa que los ganadores probablemente harán bien cinco cosas:

Modelarán la confianza de forma explícita.
Distinguirán el conocimiento actual del conocimiento obsoleto.
Manejarán la recuperación de la IA como una superficie central del producto, no como un añadido.
Soportarán el conocimiento multilingüe y específico de la audiencia sin fragmentación.
Proporcionarán a los equipos un mayor control sobre qué información se muestra, a quién y en qué condiciones.

Se trata de una categoría diferente a la del wiki clásico.

Por qué importan los nuevos comienzos

Hay momentos en el software en los que un producto de hoja en blanco tiene ventaja no porque los titulares sean incompetentes, sino porque la historia es cara.

Este es uno de esos momentos.

Una nueva plataforma puede decidir, desde el primer día, que los documentos no son sólo páginas. Son fuentes activas para humanos, agentes, sistemas de búsqueda y asistentes de IA. Esa asunción lo cambia todo aguas abajo.

Confluence y Notion pueden llegar hasta ahí. Pero el camino es más largo porque tienen que transformar sistemas que estaban optimizados para otra época.

Esa transformación lleva tiempo. Mientras tanto, las plataformas más nuevas tienen margen para definir cómo debe ser una infraestructura del conocimiento moderna.

La mayor ventaja de una plataforma nueva no es la novedad. Es liberarse de las viejas suposiciones justo en el momento en que esas suposiciones dejan de funcionar.

Este es un artículo de perspectiva. Las afirmaciones sobre los productos de la competencia se basan en la documentación y los anuncios de productos disponibles públicamente en marzo de 2026. Respetamos sinceramente tanto a Confluence como a Notion: son productos excelentes que prestan un buen servicio a millones de equipos.

Dentro de la arquitectura Rasepi: Plugins, Action Guards y Pipelines

2026-03-06T00:00:00Z

La mayoría de las plataformas de documentación hablan de "extensibilidad" como las aerolíneas hablan de "espacio para las piernas". Técnicamente presente, prácticamente decepcionante. Yo quería que la arquitectura de Rasepi fuera realmente extensible sin volverse impredecible, así que construimos tres sistemas interconectados: plugins para la capacidad, guardias de acción para el control, y pipelines para la ejecución determinista.

Este artículo explica cómo funciona cada uno de ellos en nuestra base de código real.

Arquitectura Rasepi: Plugins, guardias y tuberías trabajando juntos](/es/blog/img/architecture-pipeline.svg)

El sistema de plugins: modular por diseño

Cada plugin en Rasepi implementa IPluginModule, una única interfaz que declara qué es el plugin, qué servicios necesita y qué rutas expone:

public interface IPluginModule
{
    PluginManifest Manifest { get; }
    void RegisterServices(IServiceCollection services);
    void MapRoutes(IEndpointRouteBuilder routes);
}

El PluginManifest es puro dato. Describe el plugin sin ejecutar nada:

public sealed class PluginManifest
{
    public required string Id { get; init; }
    public required string Name { get; init; }
    public required string Version { get; init; }
    public string Description { get; init; }
    public string Category { get; init; }
    public IReadOnlyDictionary<string, string> UiContributions { get; init; }
    public bool HasSettings { get; init; }
    public bool HasEndpoints { get; init; }
    public IReadOnlyList<string> Dependencies { get; init; }
}

Fíjese en UiContributions. Ese diccionario mapea puntos de extensión del frontend a nombres de componentes, de modo que el frontend Vue sabe qué componentes de interfaz de usuario aporta cada plugin (un botón de la barra de herramientas, un panel de la barra lateral, una página de configuración).

El registro es una línea por plugin

Al inicio, registramos los plugins a través de una API fluida:

var pluginRegistry = new PluginRegistry();

pluginRegistry
    .AddPlugin<WorkflowPluginModule>(builder.Services)
    .AddPlugin<RulesPluginModule>(builder.Services)
    .AddPlugin<RetentionPluginModule>(builder.Services)
    .AddPlugin<ClassificationPluginModule>(builder.Services);

Cada llamada instancia el módulo, lo almacena en el registro y llama a RegisterServices() para cablear sus dependencias. Tras la compilación de la aplicación, una única línea asigna todas las rutas de los plugins:

app.MapPluginRoutes(pluginRegistry);

Bajo el capó, cada plugin obtiene un grupo de rutas con alcance en /plugins/{pluginId}/ con autorización aplicada automáticamente.

Ejemplo real: el plugin Workflow

He aquí el aspecto de un plugin real, el módulo Workflow & Approvals:

public sealed class WorkflowPluginModule : IPluginModule
{
    public const string PluginId = "workflow";

    public PluginManifest Manifest { get; } = new()
    {
        Id = PluginId,
        Name = "Workflow & Approvals",
        Version = "1.0.0",
        Description = "Adds approval workflows to entry publishing.",
        Category = "Workflow",
        HasSettings = true,
        HasEndpoints = true,
        UiContributions = new Dictionary<string, string>
        {
            ["entry.toolbar.publish"] = "WorkflowPublishButton",
            ["entry.sidebar.status"]  = "WorkflowStatusPanel",
            ["hub.admin.settings"]    = "WorkflowHubSettings",
        }
    };

    public void RegisterServices(IServiceCollection services)
    {
        services.AddScoped<IWorkflowService, WorkflowService>();
        services.AddScoped<IActionGuard, WorkflowPublishGuard>();
    }

    public void MapRoutes(IEndpointRouteBuilder routes)
    {
        WorkflowEndpoints.Map(routes);
    }
}

La plataforma central nunca hace referencia a WorkflowService o WorkflowPublishGuard directamente. Los descubre a través del contenedor DI. Esa es la clave del acoplamiento cero. La aplicación core nunca toca el código de los plugins.

Guardias de acción: la capa de control

Los plugins añaden capacidad. Los guardianes de acción deciden si esa capacidad, o cualquier acción del núcleo, tiene permiso para proceder. Son validadores síncronos que interceptan las operaciones antes de su ejecución.

Flujo de evaluación de guardias de acción](/es/blog/img/action-guard-flow.svg)

La interfaz es deliberadamente mínima:

public interface IActionGuard
{
    string PluginId { get; }
    string? ActionName { get; }  // null means guard ALL actions

    Task<ActionGuardResult> EvaluateAsync(
        ActionGuardContext context,
        IServiceProvider services,
        CancellationToken ct = default);
}

Cuando ActionName es null, la guardia se ejecuta para cada acción. Cuando se establece en algo como "Entry.Publish", sólo intercepta esa acción específica.

Los contratos de contexto y resultado

Cada guardia recibe un contexto tipificado con el nombre de la acción, el arrendatario, el usuario, la entidad y una bolsa de propiedades:

public sealed record ActionGuardContext(
    string ActionName,
    Guid TenantId,
    Guid UserId,
    Guid EntityId,
    IReadOnlyDictionary<string, object?> Properties)
{
    public T? Get<T>(string key) =>
        Properties.TryGetValue(key, out var v) && v is T typed
            ? typed : default;
}

Y cada guardia devuelve un resultado predecible: permitir, denegar o permitir-con-modificaciones:

public sealed record ActionGuardResult
{
    public bool IsAllowed { get; init; }
    public string? ReasonCode { get; init; }
    public string? Message { get; init; }
    public IReadOnlyDictionary<string, object?>? Modifications { get; init; }

    public static ActionGuardResult Allow() =>
        new() { IsAllowed = true };

    public static ActionGuardResult Deny(
        string reasonCode, string message) =>
        new() { IsAllowed = false, ReasonCode = reasonCode, Message = message };
}

El campo Modifications es importante. Un guardia puede aprobar una acción pero reescribir parte del contenido (por ejemplo, redactar secretos antes de publicarlos).

Nombres canónicos de las acciones

Definimos todas las acciones interceptables como constantes de cadena para que no haya ambigüedad sobre a qué puede apuntar un guardia:

public static class ActionNames
{
    public static class Entry
    {
        public const string Create  = "Entry.Create";
        public const string Save    = "Entry.Save";
        public const string Publish = "Entry.Publish";
        public const string Delete  = "Entry.Delete";
        public const string Archive = "Entry.Archive";
        public const string Renew   = "Entry.Renew";
    }

    public static class Hub
    {
        public const string Create = "Hub.Create";
        public const string Delete = "Hub.Delete";
        public const string TransferOwnership = "Hub.TransferOwnership";
    }

    public static class Translation
    {
        public const string Create  = "Translation.Create";
        public const string Publish = "Translation.Publish";
    }
}

Ejemplo real: bloquear la publicación sin aprobación

El complemento de flujo de trabajo registra un guardia que intercepta Entry.Publish:

public sealed class WorkflowPublishGuard : IActionGuard
{
    public string PluginId => WorkflowPluginModule.PluginId;
    public string? ActionName => ActionNames.Entry.Publish;

    public async Task<ActionGuardResult> EvaluateAsync(
        ActionGuardContext context,
        IServiceProvider services,
        CancellationToken ct = default)
    {
        var db = services.GetRequiredService<RasepiDbContext>();
        var entry = await db.Entries
            .AsNoTracking()
            .FirstOrDefaultAsync(e => e.Id == context.EntityId, ct);

        if (entry is null)
            return ActionGuardResult.Allow();

        var workflowService = services.GetRequiredService<IWorkflowService>();
        var check = await workflowService
            .CheckPublishAllowedAsync(entry.Id, entry.HubId);

        if (check.IsAllowed)
            return ActionGuardResult.Allow();

        return ActionGuardResult.Deny(
            "workflow.approval_required",
            check.Message ?? "Approval required before publishing.");
    }
}

La plataforma central no sabe nada acerca de los flujos de trabajo de aprobación. Simplemente llama a Entry.Publish a través de la tubería, y el guardia lo bloquea si el flujo de trabajo no se ha completado.

La canalización de acciones: donde todo converge

El ActionPipeline es la única ruta de ejecución para todas las operaciones protegidas. Resuelve qué guardias se aplican, las evalúa y bloquea o ejecuta la acción.

public sealed class ActionPipeline : IActionPipeline
{
    public async Task<ActionPipelineResult> ExecuteAsync(
        string actionName,
        ActionGuardContext context,
        Func<Task> action,
        CancellationToken ct = default)
    {
        var result = await EvaluateAsync(actionName, context, ct);
        if (!result.IsAllowed) return result;

        await action();  // All guards passed — execute

        return result;   // Return modifications for caller
    }
}

El método EvaluateAsync hace el trabajo pesado:

public async Task<ActionPipelineResult> EvaluateAsync(
    string actionName,
    ActionGuardContext context,
    CancellationToken ct = default)
{
    // 1. Which plugins are enabled for this tenant?
    var enabledPlugins = await _resolver.GetEnabledPluginIdsAsync();

    // 2. Which guards match this action?
    var applicable = _guards
        .Where(g => enabledPlugins.Contains(g.PluginId))
        .Where(g => g.ActionName == null || g.ActionName == actionName)
        .ToList();

    // 3. Evaluate each guard
    var denials = new List<ActionGuardResult>();
    var modifications = new List<ActionGuardResult>();

    foreach (var guard in applicable)
    {
        try
        {
            var guardResult = await guard.EvaluateAsync(context, _services, ct);
            if (!guardResult.IsAllowed)
                denials.Add(guardResult);
            else if (guardResult.Modifications?.Count > 0)
                modifications.Add(guardResult);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Guard threw. Treating as Allow.");
        }
    }

    // 4. Any denial blocks the whole action
    if (denials.Count > 0)
        return ActionPipelineResult.Blocked(denials);

    return modifications.Count > 0
        ? ActionPipelineResult.Allowed(modifications)
        : ActionPipelineResult.Allowed();
}

Tres importantes decisiones de diseño aquí:

Resolución por inquilino. El TenantPluginResolver comprueba qué plugins tiene instalados y habilitados cada inquilino. Una guardia para un plugin deshabilitado nunca se ejecuta.
Todo-debe-pasar. Si alguna guarda deniega, la acción se bloquea. Esta es una postura de seguridad deliberada.
Guard errors fail open. Si un guard lanza una excepción, se registra y se trata como Allow(). Esto evita que un plugin roto bloquee toda la plataforma.

Resolución de plugins por inquilino

La resolución consulta la tabla TenantPluginInstallations (automáticamente delimitada al inquilino actual por los filtros de consulta globales de EF):

public sealed class TenantPluginResolver : ITenantPluginResolver
{
    public async Task<IReadOnlySet<string>> GetEnabledPluginIdsAsync(
        CancellationToken ct = default)
    {
        if (_cache is not null) return _cache;

        var ids = await _db.TenantPluginInstallations
            .Where(i => i.IsEnabled)
            .Select(i => i.PluginId)
            .ToListAsync(ct);

        _cache = ids.ToHashSet();
        return _cache;
    }
}

Efectos secundarios basados en eventos

Las acciones son síncronas. Los efectos secundarios no lo son. Una vez completada una acción, el servicio publica un evento de dominio:

await _eventPublisher.PublishAsync(
    EventNames.Entry.Created, entry.Id, new { entry.OriginalLanguage });

Los eventos se ponen en cola en un canal en memoria y son procesados por un EventConsumerWorker en segundo plano. El trabajador enruta los eventos a múltiples sistemas:

Seguimiento de la actividad. Registra quién hizo qué, cuándo
Facturación de traducciones. Rastrea los costes por proveedor
Cualquier plugin puede suscribirse a los eventos del dominio.

Los manejadores de eventos del plugin implementan IPluginEventHandler:

public interface IPluginEventHandler
{
    string PluginId { get; }
    IReadOnlyList<string> SubscribedEvents { get; }

    Task HandleAsync(
        string eventName, Guid entityId,
        Guid? tenantId, Guid? userId,
        string payloadJson, IServiceProvider services,
        CancellationToken ct = default);
}

El trabajador sólo invoca manejadores cuyo plugin está habilitado para el tenant. Esto significa que los efectos secundarios del plugin A nunca se filtran a un tenant que sólo tenga instalado el plugin B.

El motor de traducción a nivel de bloque

Aquí es donde la arquitectura da sus frutos de forma más visible.

Traducción a nivel de bloque: sólo se retraducen los bloques modificados](/es/blog/img/block-translation.svg)

Las plataformas tradicionales traducen documentos enteros. Nosotros traducimos bloques individuales: párrafos, encabezados, elementos de listas. Cuando un usuario edita un párrafo en un documento de 50 bloques, sólo es necesario volver a traducir ese párrafo. Ésa es la fuente de nuestro 94% de ahorro de costes.

Cómo se crean los bloques a partir de TipTap JSON

Cuando un usuario guarda un documento, el editor TipTap envía JSON de la siguiente forma:

{
  "type": "doc",
  "content": [
    {
      "type": "paragraph",
      "attrs": { "blockId": "a1b2c3d4-..." },
      "content": [{ "type": "text", "text": "Hello world" }]
    }
  ]
}

El BlockTranslationService analiza este JSON y crea registros EntryBlock individuales:

public async Task<List<EntryBlock>> CreateBlocksFromDocumentAsync(
    Guid entryId, string language, string contentJson,
    int version, Guid userId)
{
    var doc = JsonDocument.Parse(contentJson);
    var content = doc.RootElement.GetProperty("content");

    int position = 0;
    foreach (var node in content.EnumerateArray())
    {
        var blockType = node.GetProperty("type").GetString();
        var blockJson = JsonSerializer.Serialize(node);

        // Strip metadata attrs before hashing
        var hashInput = StripBlockMetaAttrs(blockJson);

        var block = new EntryBlock
        {
            Id = ExtractOrGenerateBlockId(node),
            EntryId = entryId,
            Language = language,
            Position = position++,
            BlockType = blockType,
            ContentJson = blockJson,
            ContentHash = CalculateContentHash(hashInput),
            IsNoTranslate = ExtractNoTranslateFlag(node),
            Version = version,
        };

        _context.EntryBlocks.Add(block);
    }

    await _context.SaveChangesAsync();
    return blocks;
}

hash SHA256 para detección de caducidad

El hash del contenido es el núcleo de la detección de caducidad. Hacemos un hash del contenido del bloque (después de eliminar los atributos de metadatos como blockId y deleted) utilizando SHA256:

private string CalculateContentHash(string content)
{
    using var sha256 = SHA256.Create();
    var hashBytes = sha256.ComputeHash(Encoding.UTF8.GetBytes(content));
    return Convert.ToHexString(hashBytes);
}

Cuando cambia un bloque fuente, cambia su hash. El sistema compara entonces el SourceContentHash de cada bloque de traducción con el hash de origen actual, y las discrepancias se marcan como Stale:

public async Task MarkTranslationsAsStaleAsync(List<Guid> changedBlockIds)
{
    var affected = await _context.TranslationBlocks
        .Where(t => changedBlockIds.Contains(t.SourceBlockId))
        .ToListAsync();

    foreach (var translation in affected)
    {
        translation.Status = TranslationStatus.Stale;
        translation.UpdatedAt = DateTime.UtcNow;
    }

    await _context.SaveChangesAsync();
}

Adaptación de la estructura

Los traductores pueden cambiar los tipos de bloque de un idioma a otro. Una lista con viñetas en inglés puede convertirse en una lista numerada en alemán, una preferencia cultural. El sistema hace un seguimiento de esto:

var translation = new TranslationBlock
{
    SourceBlockId = sourceBlockId,
    Language = targetLanguage,
    BlockType = translatedBlockType,
    SourceBlockType = sourceBlock.BlockType,
    IsStructureAdapted = translatedBlockType != sourceBlock.BlockType,
    SourceContentHash = sourceBlock.ContentHash,
    Status = TranslationStatus.UpToDate,
};

Proveedores de traducción como plugins

Los servicios de traducción externos (DeepL, Google Translate, etc.) se conectan a través de ITranslationProviderPlugin:

public interface ITranslationProviderPlugin : IRasepiPlugin
{
    string[] GetSupportedLanguages();

    Task<string> TranslateAsync(
        string text, string sourceLanguage, string targetLanguage);

    Task<TranslationBatchResult> TranslateBatchAsync(
        Dictionary<string, string> texts,
        string sourceLanguage, string targetLanguage);
}

El método por lotes recibe un diccionario de identificadores de bloque a contenido, los traduce todos y devuelve las traducciones con un recuento de caracteres facturados. Como sólo enviamos los bloques antiguos, no todo el documento, los costes se mantienen al mínimo.

Aislamiento del inquilino: la red de seguridad invisible

Todos los sistemas descritos anteriormente funcionan dentro de un estricto aislamiento de inquilinos.

El TenantContextMiddleware resuelve el inquilino a partir del JWT en cada solicitud y verifica la pertenencia:

public async Task InvokeAsync(
    HttpContext context, TenantContext tenantContext, RasepiDbContext db)
{
    var tenantIdClaim = context.User.FindFirstValue("tenant_id");
    var userIdClaim = context.User.FindFirstValue(ClaimTypes.NameIdentifier);

    // Populate scoped context
    tenantContext.TenantId = Guid.Parse(tenantIdClaim);
    tenantContext.UserId = Guid.Parse(userIdClaim);

    // Verify membership — fail closed
    var membership = await db.TenantMemberships
        .Where(m => m.TenantId == tenantContext.TenantId
                  && m.UserId == tenantContext.UserId)
        .FirstOrDefaultAsync();

    if (membership == null)
    {
        context.Response.StatusCode = 401;
        return;  // No membership = no access
    }
}

Los filtros de consulta globales de Entity Framework garantizan que, incluso si un desarrollador se olvida de filtrar por inquilino, la capa de base de datos lo haga automáticamente:

modelBuilder.Entity<Hub>()
    .HasQueryFilter(h => h.TenantId == _tenantContext.TenantId);

El resultado: db.Hubs.ToListAsync() siempre devuelve sólo los centros del inquilino actual. Las fugas de datos requieren eludir activamente el filtro de consulta, lo que está prohibido en nuestra base de código.

La imagen completa

Cuando un usuario hace clic en "Publicar" en una entrada, esto es lo que ocurre:

La solicitud entra. La autenticación valida el JWT, TenantContextMiddleware resuelve y verifica el arrendatario.
El controlador llama a la tubería. IActionPipeline.ExecuteAsync("Entry.Publish", context, action)
Pipeline resuelve guardias. Consulta qué plugins tiene habilitados el inquilino, selecciona las guardias aplicables.
Las guardias evalúan. La guardia Workflow comprueba las aprobaciones, la guardia Retention comprueba la política, la guardia Rules valida el contenido. ¿Todos pasan? La entrada se publica.
**Se pone en cola el evento Entry.Published. Un trabajador en segundo plano registra la actividad, actualiza la facturación de la traducción y llama a los controladores de eventos del plugin.
**Se identifican los bloques obsoletos para su retraducción.

Cada capa hace su trabajo. Ninguna capa se mete en otra. Esa es la arquitectura.

No construimos esto porque la extensibilidad esté de moda. Lo construimos porque una plataforma de documentación que no pueda adaptarse al flujo de trabajo de cada equipo acabará siendo sustituida por otra que sí pueda hacerlo. Y una plataforma que se adapta sin guardarraíles acabará rompiendo algo que importa.