Papermark es una plataforma de intercambio de documentos de código abierto. Cuando el equipo decidió localizar su documentación, se encontró con el problema que frena a la mayoría de los equipos de herramientas para desarrolladores: hacer que i18n funcione correctamente en una aplicación Next.js es más difícil que la propia traducción.

El problema de la configuración#

«Probé todos los paquetes de automatización y herramientas caseras que hay», recuerda Iuliia Shnai, fundadora de Papermark. «El mayor quebradero de cabeza ni siquiera era la traducción: era conseguir que i18n funcionara bien con la estructura de nuestra aplicación».

Es un patrón habitual. La mayoría de las herramientas de localización dan por hecho que la infraestructura de i18n ya está montada. Se ocupan de traducir, pero no de la configuración, la estructura de archivos, el procesamiento de MDX ni de los casos límite que cambian según el framework. Para un proyecto de código abierto con un equipo pequeño, dedicar tiempo de ingeniería a preparar la localización tiene un coste directo para el producto.

Los archivos MDX —documentación escrita en Markdown con componentes React integrados— añaden otra capa de complejidad. Las herramientas de i18n estándar trabajan con archivos JSON de idioma y cadenas simples. El contenido MDX con interpolaciones de componentes, frontmatter y etiquetas personalizadas requiere otro enfoque.

Qué cambió#

Max, fundador de Lingo.dev, se puso en contacto directamente y ayudó a configurar el proyecto Next.js de Papermark. La implementación resolvió los casos límite que tenían bloqueado al equipo: el procesamiento de archivos MDX, la interacción entre next-intl y la estructura de archivos de la aplicación, y la extracción de cadenas traducibles de una documentación con un uso intensivo de componentes.

«La implementación resolvió muchísimos casos límite que ni siquiera habíamos tenido en cuenta», afirma Shnai. «Quedó claro que habían pensado en toda la complejidad de la localización, especialmente en los archivos MDX, que para nosotros eran un punto especialmente problemático».

Desde el primer día: 80 páginas de documentación traducidas. El motor de localización —configurado con la terminología de producto de Papermark y conectado a su repositorio— se encargó automáticamente de toda la documentación.

Cómo funciona ahora#

El motor de localización de Papermark se ejecuta con cada push de código. Cuando se añade nueva documentación o se actualiza contenido existente, el motor traduce los cambios automáticamente. Los ingenieros redactan la documentación en inglés; las versiones localizadas aparecen sin ningún paso adicional.

Aquí es donde importa que conserve el estado. Como el motor de localización mantiene la terminología de producto de Papermark en cada solicitud, términos específicos del producto como "Data Room", "Link tracking" y "NDA flow" se traducen de forma coherente en todos los idiomas. Tanto la primera página de documentación que pasa por el motor como la número cien aplican el mismo vocabulario de producto.

«Cero esfuerzo de ingeniería continuo para las traducciones» es el resultado medible, pero la razón de fondo es que la localización pasó de ser una tarea recurrente a convertirse en infraestructura.

Resultados#

• 80 páginas de documentación traducidas el primer día
• Cero esfuerzo de ingeniería continuo para la localización
• Gestión automática de documentación MDX compleja
• Traducción continua con cada push, tanto para contenido nuevo como actualizado
• Terminología coherente en todos los idiomas

En un proyecto de código abierto, la economía importa. Cada hora que no se dedica al mantenimiento de la localización es una hora que puede invertirse en el producto. Papermark sigue ampliando su motor de localización para abarcar también la optimización SEO en distintos idiomas.