Papermark est une plateforme open source de partage de documents. Lorsque l’équipe a décidé de localiser sa documentation, elle s’est heurtée au problème qui freine la plupart des équipes d’outils pour développeurs : faire fonctionner correctement l’i18n dans une application Next.js est plus difficile que la traduction elle-même.

Le défi de la mise en place#

« J’ai essayé tous les packages d’automatisation et tous les outils maison possibles », se souvient Iuliia Shnai, fondatrice de Papermark. « Le plus gros point de friction, ce n’était même pas la traduction : c’était de faire fonctionner correctement l’i18n avec la structure de notre application. »

C’est un scénario bien connu. La plupart des outils de localisation partent du principe que l’infrastructure i18n est déjà en place. Ils gèrent la traduction, mais pas la configuration, la structure des fichiers, l’analyse des fichiers MDX ni les cas complexes qui varient selon les frameworks. Pour un projet open source porté par une petite équipe, consacrer du temps d’ingénierie à la mise en place de la localisation a un coût direct pour le produit.

Les fichiers MDX — une documentation rédigée en Markdown avec des composants React intégrés — ajoutent une couche de complexité supplémentaire. Les outils i18n classiques gèrent les fichiers de langue JSON et les chaînes simples. Un contenu MDX avec interpolations de composants, frontmatter et balises personnalisées exige une approche différente.

Ce qui a changé#

Max, le fondateur de Lingo.dev, a pris contact directement et a aidé à configurer le projet Next.js de Papermark. L’implémentation a pris en charge les cas complexes qui bloquaient l’équipe : le traitement des fichiers MDX, l’interaction entre next-intl et la structure des fichiers de l’application, ainsi que l’extraction des chaînes à traduire dans une documentation riche en composants.

« L’implémentation a géré une quantité de cas complexes auxquels nous n’avions pas pensé », explique Shnai. « Il était clair qu’ils avaient anticipé toute la complexité de la localisation, en particulier pour les fichiers MDX, qui représentaient un vrai point de douleur pour nous. »

Dès le premier jour : 80 pages de documentation traduites. Le moteur de localisation — configuré avec la terminologie produit de Papermark et connecté à leur dépôt — a pris en charge automatiquement l’ensemble de la documentation.

Comment ça fonctionne aujourd’hui#

Le moteur de localisation de Papermark s’exécute à chaque push de code. Lorsqu’une nouvelle documentation est ajoutée ou qu’un contenu existant est mis à jour, le moteur traduit automatiquement les changements. Les ingénieurs rédigent la documentation en anglais ; les versions localisées apparaissent sans aucune étape supplémentaire.

Le fait que le système soit stateful est essentiel ici. Comme le moteur de localisation conserve la terminologie produit de Papermark d’une requête à l’autre, des termes propres au produit comme « Data Room », « Link tracking » et « NDA flow » sont traduits de façon cohérente dans toutes les langues. Qu’il s’agisse de la première page de documentation traitée par le moteur ou de la centième, le même vocabulaire produit est appliqué.

« Zéro effort d’ingénierie continu pour les traductions » : voilà le résultat mesurable. Mais la vraie raison derrière cela, c’est que la localisation est devenue une infrastructure, et non plus une tâche récurrente.

Résultats#

• 80 pages de documentation traduites dès le premier jour
• Zéro effort d’ingénierie continu pour la localisation
• Prise en charge automatique d’une documentation MDX complexe
• Traduction continue à chaque push, pour les nouveaux contenus comme pour les mises à jour
• Terminologie cohérente dans toutes les langues

Pour un projet open source, l’équation économique compte. Chaque heure non consacrée à la maintenance de la localisation est une heure rendue au produit. Papermark continue d’étendre son moteur de localisation afin d’y intégrer l’optimisation SEO dans toutes les langues.