Paramètres de traduction

Cette page est l’interface de configuration : quelles langues existent, quel modèle les traduit, quand les passes sont exécutées, où les lecteurs changent de langue et à quoi ressemblent toutes les URL traduites. Le fonctionnement concret d’une passe est décrit dans Traductions par IA ; la qualité du résultat est abordée dans Qualité des traductions et SEO.

La traduction automatique et les contrôles du workflow de traduction font partie de l’offre payante — voir Tarifs. Un projet gratuit peut consulter tout le contenu de cette page, et sa langue source est toujours détectée automatiquement lorsque le projet se connecte. En revanche, il ne peut rien en modifier : les langues activées et la langue source constituent un même groupe soumis aux restrictions de l’offre, de sorte qu’un projet gratuit se voit refuser l’accès aux deux, ainsi qu’au mode de traduction et au démarrage d’une passe.

Ce qui peut être configuré#

Langue source de votre projet#

Docsbook détecte la langue dans laquelle votre documentation est rédigée au lieu de vous le demander. Lorsqu’un projet est connecté, il lit le fichier README du dépôt, en supprime les blocs de code, le code inline, les images, les liens et le HTML, puis exécute un identificateur de langue sur le contenu restant.

Les règles importantes sont les suivantes :

• Moins de 50 caractères de texte après suppression, ou l’absence de réponse fiable, entraîne un retour à en et est enregistré avec un faible niveau de confiance, afin que le panneau puisse l’indiquer comme meilleure estimation — veuillez confirmer plutôt que de présenter une supposition comme une détection. Une détection fiable est enregistrée avec un niveau de confiance élevé et indiquée comme détectée automatiquement. Si vous la définissez vous-même, elle est indiquée comme définie par vous et verrouillée.
• Le détecteur reconnaît exactement les quinze codes pris en charge par Docsbook. Un fichier README dans une langue qui ne figure pas dans cet ensemble utilise le repli en.
• La langue source ne peut jamais être activée comme langue cible de traduction. Elle est supprimée de enabled_languages si vous la transmettez, et une passe de traduction l’ignore explicitement — avant même de vérifier si la langue est activée — avec le motif is_source_language. Il s’agit d’une protection structurelle, et non d’une validation de l’interface : une ancienne ligne en base de données ou un appel direct à l’API ne peut pas faire payer à un projet la traduction de l’anglais vers l’anglais.
• L’anglais n’a rien de particulier. Un projet dont la documentation est rédigée en allemand obtient l’image miroir de tout ce qui précède.

Activer une langue#

1. Ouvrez votre site de documentation.
2. Ouvrez Float Widget → l’onglet Traduction.
3. Cochez la langue souhaitée.
4. Confirmez la boîte de dialogue. Le traitement démarre en arrière-plan.

Si le sélecteur de langue est déjà présent sur votre site, l’ouvrir et cliquer sur Activer les langues ouvre le même onglet. Ce point d’accès n’apparaît que pour vous en tant que propriétaire, ou dans l’aperçu administrateur — jamais pour les lecteurs.

Activer une langue ne traduit rien en soi au niveau de l’API : update_languages définit l’ensemble, et run_translation_pass (ou le déclencheur propre au mode) effectue le travail. Dans le panneau, les deux sont associés pour vous, donc cocher une case lance bien un traitement.

La boîte de dialogue affiche d’abord le devis de l’exécution#

Avant toute dépense, la boîte de dialogue de confirmation indique combien de pages ne sont pas encore traduites sur le total, le coût estimé et le solde restant. Si le traitement ne tient pas dans le solde, elle indique quelle part de la documentation celui-ci couvre et propose de recharger le compte — et Traduire ce qui peut l’être est une véritable option : les pages couvertes sont traduites immédiatement et le reste est pris en charge automatiquement lorsque le solde le permet.

L’estimation est calculée en fonction du modèle que vous avez sélectionné, de sorte que le devis et le montant facturé correspondent au même modèle. Il est important de le préciser explicitement, car cela n’a pas toujours été le cas : l’estimation était calculée pour un modèle tandis que l’exécution en utilisait un autre.

Choisir le modèle de traduction#

Paramètres ▸ Traductions ▸ Modèle de traduction permet de sélectionner le modèle, et il s’agit délibérément d’un paramètre différent de celui sur lequel fonctionne le chat de votre lecteur — traduire de la prose et répondre à une question avec des outils sont deux tâches différentes, et un réglage qui modifie l’une n’a aucune raison de modifier l’autre.

Si vous ne sélectionnez rien, le sélecteur utilise la valeur par défaut marquée (default), actuellement GPT-5.6 Luna. Chaque option indique son prix par million de jetons : un modèle moins cher permet de couvrir davantage de pages avec le même solde, tandis qu’un modèle plus performant est disponible en un clic lorsqu’une langue est mal rendue. Seuls les modèles du catalogue de Docsbook sont pris en compte en mode géré, car les dépenses sont facturées au prix publié du modèle et un modèle non reconnu serait facturé à un tarif qui ne vous a jamais été indiqué.

Si vous utilisez votre propre clé d’API de traduction, le modèle devient un champ de texte libre sur cette carte et l’exécution est facturée par votre propre fournisseur plutôt que sur le solde de votre projet. L’utilisation de votre propre clé ne débloque pas la traduction sur un projet gratuit : la restriction dépend du forfait, et non du coût.

Choisir quand les traductions sont exécutées#

En mode Automatique, Docsbook interroge votre dépôt au lieu de réagir à un webhook : un espace de travail est examiné environ toutes les 15 minutes, et seuls quatre espaces de travail sont examinés à chaque cycle. Attendez-vous donc à ce qu’un rattrapage commence dans ce délai environ, plutôt qu’immédiatement après votre push. Les pages qui ont pris du retard sont traduites avant celles qui n’ont jamais été traduites — une traduction obsolète indique activement à votre lecteur quelque chose que votre documentation ne dit plus, tandis qu’une traduction manquante revient à l’original et se contente de ne pas aider.

Les agents définissent le mode avec l’outil MCP set_translation_mode :

// auto: Docsbook follows new commits and re-translates the pages they changed
set_translation_mode({ workspace_id: 42, mode: "auto" })
 
// external: nothing runs here; your pipeline listens for translation.needed
set_translation_mode({ workspace_id: 42, mode: "external", external_webhook_url: "https://example.com/hooks/translate" })

En mode external, vous recevez un événement translation.needed, exécutez votre propre pipeline, puis publiez le résultat avec upload_translation. Définir external sans avoir fourni au préalable d’URL de webhook est refusé plutôt qu’accepté silencieusement.

Position du sélecteur de langue#

Le sélecteur peut apparaître dans la barre latérale, dans l’en-tête, ou dans les deux. L’emplacement dans l’en-tête est un indicateur d’espace de travail distinct ; la barre latérale peut en outre être configurée pour n’afficher le sélecteur que sur mobile, de sorte qu’un en-tête large sur ordinateur le propose sans que la mise en page étroite ne le répète.

Choisissez-en un. Afficher deux fois le même contrôle sur un même écran est superflu. Configurez-le dans les options de l’en-tête ou le contrôle de la barre latérale.

Un site ne disposant d’aucune langue activée n’affiche aucun sélecteur, plutôt qu’un contrôle ne contenant qu’une seule entrée.

L’URL d’une page traduite#

La langue est toujours un segment de chemin, jamais un sous-domaine. Il n’y a pas de https://fr.docsbook.io/…, et un sous-domaine de langue nu renvoie volontairement une 404 afin qu’il ne puisse pas devenir une seconde adresse pour le même contenu.

https://<user>.docsbook.io/<repo>/<path>          → your source language
https://<user>.docsbook.io/fr/<repo>/<path>       → French
https://<user>.docsbook.io/ja/<repo>/<path>       → Japanese

Sur un domaine personnalisé, le segment du dépôt disparaît et la langue conserve sa place au début :

https://docs.example.com/<path>                   → your source language
https://docs.example.com/fr/<path>                → French

Deux conséquences méritent d’être connues :

• Un espace de travail avec un domaine personnalisé est canonique sur ce domaine, et non sur son miroir docsbook.io — aussi bien pour les pages traduites que pour les pages originales. Mélanger les deux publierait une page dont les voisines hreflang pointeraient vers un emplacement différent de celui de sa propre URL canonique.
• /en/… existe, mais ne constitue pas une page distincte. L’anglais est servi à l’identique sur /<repo>/<path> et /en/<repo>/<path>, et la forme préfixée déclare la forme sans préfixe comme canonique ; la paire est donc regroupée en une seule page indexable au lieu d’entrer en concurrence avec elle-même.

Certains sites hébergés par Docsbook — la documentation du produit lui-même et les projets de démonstration — sont servis sur le domaine apex, avec la langue après le segment du dépôt (https://docsbook.io/<repo>/fr/<path>). Docsbook génère l’URL canonique et hreflang de ces sites à partir de la même fonction que celle qui les achemine ; l’URL annoncée est donc toujours celle qui répond avec un code 200 plutôt qu’avec une redirection.

Désactiver une langue#

Décochez-la dans l’onglet Traduction ou utilisez l’interrupteur sur la page dédiée à cette langue. Aucune confirmation n’est demandée, car rien n’est supprimé :

• Les traductions stockées sont conservées. Réactiver la langue ne génère pas de frais supplémentaires pour les pages qui n’ont pas changé : seules les pages nouvelles et modifiées sont traduites. Ainsi, réactiver une langue déjà utilisée est presque instantané et presque gratuit.
• La page de rapports de cette langue est également conservée, afin que la question « dois-je la réactiver ? » puisse être tranchée en fonction du nombre de lecteurs et du coût déjà engendré.
• Les lecteurs qui consultent l’URL de la langue désactivée sont redirigés vers votre version dans la langue source.

Limites#

• Quinze codes, sans variantes régionales. pt couvre le Brésil et le Portugal avec un seul ensemble de pages ; zh couvre les formes simplifiée et traditionnelle avec un seul ensemble. La colonne de langue stockée accepte cinq caractères, de sorte que des codes comme pt-BR peuvent être enregistrés, mais rien dans le produit ne les génère ni ne les propose.
• Le mode automatique effectue des sondages, ce n’est pas un webhook. Un push est pris en compte lors de l’analyse suivante et, lorsque la flotte est très sollicitée, l’attente entre deux analyses pour un espace de travail peut dépasser 15 minutes. Si rien n’a analysé votre projet depuis environ une heure, le panneau par langue signale que l’analyse est en retard plutôt que de prétendre qu’elle est effectuée comme prévu.
• Le sélecteur de langue est le seul contrôle de langue destiné aux lecteurs. Docsbook ne redirige pas les lecteurs en fonction de Accept-Language et n’effectue pas de routage géographique ; un lecteur n’ayant exprimé aucune préférence obtient la langue par défaut configurée pour le site.
• Le choix du modèle se fait par espace de travail, et non par langue. Vous ne pouvez pas traduire le japonais avec un modèle plus puissant que celui utilisé pour le polonais au sein d’un même projet.

Connexe#

• Traductions par IA — ce qu’une passe fait à une page et ce qui est protégé du modèle
• Qualité des traductions et SEO — couverture, fraîcheur, corrections, hreflang et URL canoniques
• Mise en page de l’en-tête et navigation — placer le sélecteur dans l’en-tête
• Mise en page et configuration de la barre latérale — le placer plutôt dans la barre latérale
• Rapport sur les pays des visiteurs — quelles régions vous apportent des visiteurs que vous ne traduisez pas encore