Traduire des pages avec Google Translate dans BotBrowser

Lire une page web dans une autre langue devrait rester une tâche normale du navigateur. C'est aussi une décision qui doit être explicite. La traduction envoie le texte nécessaire vers un service externe, consomme un quota cloud et dépend de la session qui lance la requête. BotBrowser prend en charge ce parcours lorsque vous fournissez et gérez votre propre clé Cloud Translation API de Google.

Le résultat attendu est simple : ouvrir une page, utiliser la commande de traduction habituelle du navigateur, puis vérifier le contenu traduit. Le contrôle est tout aussi important : vous choisissez le projet qui paie les requêtes, les routes autorisées à utiliser la clé, les profils qui portent la session et les contenus pouvant être envoyés au service.

Ce que permet la traduction

Quand le texte principal d'une page n'est pas dans la langue cible, le navigateur peut demander une traduction et l'afficher dans la session courante. Cette fonction convient au support, à la recherche, à la revue de localisation, aux opérations de contenu et aux contrôles qualité autorisés.

La traduction est une capacité du navigateur qui dépend d'un service externe. Une page peut exposer un comportement lié à la traduction alors que le service complet reste indisponible. Ce sont deux résultats différents. Une vérification de capacité montre que le navigateur comprend la fonction, mais ne prouve pas qu'une requête cloud réussira. Il faut aussi une clé client valide, le service activé, la facturation, un quota disponible, un trafic autorisé, une route fonctionnelle et une page que le service peut traiter.

Cette distinction aide à décrire les échecs. Si la commande n'apparaît pas, vérifiez la langue de la page et les réglages du navigateur. Si elle apparaît mais que le résultat n'arrive pas, vérifiez le projet, les restrictions de clé, le quota, le proxy et le réseau. Une requête échouée n'est pas une page traduite et une commande visible ne prouve pas la disponibilité du service externe.

Préparez les prérequis

• Une version BotBrowser et un profil adaptés au parcours.
• Un projet Google Cloud détenu ou administré par votre organisation.
• Cloud Translation API activée dans ce projet.
• Un compte de facturation associé selon les exigences actuelles du service.
• Une politique de quota adaptée aux pages et utilisateurs prévus.
• Une clé API limitée à Cloud Translation API et à l'environnement qui en a besoin.
• Une route réseau permettant au navigateur d'atteindre les services requis.

Utilisez un projet séparé pour les essais lorsque les dépenses et les accès doivent être isolés. Cela simplifie aussi la révocation d'une clé de test sans toucher à une autre charge de travail. Documentez le profil, le répertoire de données, le proxy et le mode de lancement comme une unité de déploiement. La traduction est plus reproductible quand ces choix restent stables.

Créez un projet sous votre contrôle

Dans Google Cloud Console, créez ou sélectionnez un projet de traduction, activez Cloud Translation API, associez la facturation et consultez les tarifs et quotas actuels. Créez ensuite une clé API dans APIs & Services et Credentials. Limitez-la à Cloud Translation API et ajoutez une restriction d'application qui correspond au lieu réel d'exécution du navigateur. Une restriction IP peut convenir à une sortie serveur stable ; d'autres déploiements demanderont une autre option. Choisissez la limite la plus étroite qui fonctionne et testez-la depuis la route réelle.

Ne collez jamais une clé réelle dans un article, un fichier source, un profil, une capture, un enregistrement de terminal, un fichier d'environnement versionné ou un journal partagé. Les exemples de cet article utilisent volontairement des marqueurs. Conservez la vraie clé dans le gestionnaire de secrets du déploiement ou saisissez-la dans un shell protégé au lancement de BotBrowser. Si elle est exposée, faites-la tourner ou révoquez-la dans Google Cloud.

BotBrowser ne fournit pas de clé de traduction partagée. Cette séparation vous laisse contrôler les coûts, les quotas, la revue des accès, la conservation des données et la réponse aux incidents. Elle signifie aussi que l'état du service Google Cloud et la configuration du compte relèvent du déploiement.

Lancez BotBrowser avec la clé

La variable doit être présente au démarrage du processus BotBrowser. Définissez-la dans le même environnement que celui qui lance le navigateur, avec les arguments de profil et de données habituels :

GOOGLE_API_KEY='YOUR_API_KEY' \
chromium-browser \
  --bot-profile='/absolute/path/to/profile.enc' \
  --user-data-dir='/absolute/path/to/user-data' \
  about:blank

La valeur est un marqueur inutilisable. Remplacez-la uniquement dans votre environnement local ou de déploiement protégé. Redémarrez BotBrowser après toute modification. Modifier un client HTTP externe, un script de page ou un processus enfant ne configure pas le processus du navigateur.

Sur macOS ou Linux, exportez-la depuis le même shell que celui qui démarre le navigateur :

export GOOGLE_API_KEY='YOUR_API_KEY'
chromium-browser \
  --bot-profile='/absolute/path/to/profile.enc' \
  --user-data-dir='/absolute/path/to/user-data'

Dans PowerShell, définissez l'environnement du processus avant le lancement :

$env:GOOGLE_API_KEY = 'YOUR_API_KEY'
& 'C:\path\to\chromium.exe' `
  '--bot-profile=C:\path\to\profile.enc' `
  '--user-data-dir=C:\path\to\user-data'

Avec Playwright ou Puppeteer, le processus qui lance le navigateur possède l'environnement. Faites passer la valeur protégée par cette frontière et gardez les arguments du profil au lancement. Ne placez jamais la clé dans le JavaScript de la page ni dans un fichier .env versionné.

Gardez le profil cohérent

La traduction ne justifie pas de mélanger des identités de navigateur ou des politiques d'état. Chargez le profil avant la navigation et définissez clairement la politique du répertoire de données. Un répertoire persistant conserve l'historique de session attendu ; un nouveau répertoire convient à une relation de site nouvelle. Ne partagez pas un répertoire persistant entre des identités sans rapport.

Le profil, la version du navigateur, l'hôte et la route réseau doivent décrire une même session. Si le profil correspond à une famille de navigateur ou à un contexte de plateforme, gardez ces choix stables pendant la vérification. Des paramètres de lancement incohérents rendent le résultat difficile à reproduire et peuvent exposer un état inattendu à la page.

Dans un parcours à plusieurs profils, affectez le profil avant de démarrer la session et gardez les réglages liés à l'identité stables pendant sa durée. Consultez Per-Context Fingerprint pour la séquence actuelle. La traduction doit s'exécuter dans une session déjà définie, sans la modifier après navigation.

La cohérence rend explicables la famille du navigateur, les préférences de langue, l'état stocké et la route réseau. Un profil contrôle le comportement et la continuité du navigateur. Il n'accorde pas d'accès et ne remplace pas les règles du site.

Vérifiez le parcours visible par l'utilisateur

Utilisez la même version, le même profil, le même proxy, le même mode de lancement et la même langue cible que le déploiement :

1. Confirmez que le processus a été redémarré après la configuration de la clé.
2. Ouvrez une page dont le texte principal n'est pas dans la langue cible.
3. Utilisez la commande normale du menu ou du menu contextuel.
4. Confirmez que le texte change visiblement et que le résultat est lisible.
5. Vérifiez l'utilisation attendue dans le projet Google Cloud.
6. Notez profil, route, langues et résultat sans enregistrer le texte privé ni les secrets.

Testez une page qui doit être traduite et une page qui doit rester inchangée. Pour les formulaires, comptes, dossiers clients ou textes générés par les utilisateurs, utilisez une page représentative sûre, sauf autorisation explicite de votre politique de données.

Une vérification de capacité du navigateur seule ne prouve pas que le service externe est disponible. Un succès dans un environnement ne garantit pas le même résultat avec un autre proxy, quota, profil ou projet de facturation. Reliez chaque preuve à l'environnement réel.

Dépannez dans un ordre contrôlé

La traduction est indisponible. Vérifiez que la clé était présente avant le démarrage, que le navigateur a été redémarré, que Cloud Translation API est activée et que la facturation est configurée. Vérifiez aussi que les langues sont adaptées.

Accès refusé. Contrôlez les restrictions API et application. Confirmez que la requête passe par une route autorisée et que le projet contient bien la clé et la facturation.

Quota ou limite de débit. Consultez l'utilisation, les limites quotidiennes et par minute. Définissez des limites qui empêchent les dépenses accidentelles sans supprimer la capacité prévue. Ne copiez pas une clé d'un autre projet pour contourner une limite.

Échec avec proxy. Confirmez que le proxy est configuré au niveau du navigateur et autorise les services Google requis. Comparez la route de test à celle du déploiement et gardez les responsabilités réseau et identité distinctes.

Clé exposée. Révoquez-la ou faites-la tourner immédiatement, mettez à jour l'environnement protégé et retirez les copies des canaux de distribution. N'utilisez plus une clé dont la limite d'accès est incertaine.

Résultats variables. Comparez version, profil, répertoire de données, langues, proxy, hôte, projet, quota et moment de lancement. Ne changez qu'une variable à la fois. Les métadonnées opérationnelles valent mieux que des captures contenant du texte privé.

Confidentialité et protection

La traduction envoie à Google le texte nécessaire au service. Cela peut inclure titres, paragraphes, libellés et autres textes sélectionnés par le navigateur. Ce texte peut être personnel, confidentiel, réglementé ou commercialement sensible. Vérifiez votre politique de traitement avant de traduire une page.

Utilisez des pages de test approuvées. Excluez secrets, récupération de compte, paiements, santé, données client et textes professionnels confidentiels, sauf autorisation explicite. Une fonction de langue ne doit pas étendre discrètement le nombre de systèmes qui reçoivent des informations.

Documentez le projet qui reçoit les requêtes, les personnes pouvant changer la clé, la gestion des alertes de quota et la rotation en cas d'exposition. Appliquez le moindre privilège et ne gardez que les métadonnées opérationnelles. Si traduction réussie ou quota refusé suffit, ne copiez pas le texte de page dans un ticket.

Confidentialité et cohérence se renforcent. Un profil et une route stables indiquent quelles données quittent la session et où un échec se produit. Une politique claire indique quand traduire. Aucune ne remplace l'autre : un profil ne sécurise pas automatiquement un texte sensible et un réseau privé ne rend pas toute requête externe acceptable.

Maîtrisez coût et disponibilité

Google Cloud contrôle les tarifs et quotas. Configurez une alerte budgétaire, examinez l'utilisation et définissez un maximum de requêtes par parcours. Une longue page peut consommer bien plus de caractères qu'une courte, et les nouvelles tentatives peuvent augmenter la consommation pendant un incident.

Pour des budgets d'équipe différents, séparez les projets ou les limites de service. Donnez à chaque responsable un quota et une procédure d'escalade. La préparation production inclut un plafond de coût connu, une route fonctionnelle, une clé renouvelable et une réponse aux échecs de facturation ou de quota.

La disponibilité est conditionnelle. Google Cloud, le réseau, le profil, la page source et la session contribuent au résultat. Si une dépendance est indisponible, conservez la page originale et indiquez que la traduction est indisponible. Ne marquez pas une page comme traduite parce que la commande est visible.

Liste pratique

Avant l'activation :

• Choisissez une politique de données et une page de vérification sûre.
• Sélectionnez un projet Google Cloud géré par le client.
• Activez API, facturation, limites de quota et alertes.
• Limitez la clé à l'API et à la route nécessaires.
• Gardez la clé hors du code, des profils, captures et journaux partagés.
• Choisissez un profil, une version, une politique de données et un proxy cohérents.

Pendant l'exécution :

• Lancez BotBrowser avec la clé déjà présente dans son environnement.
• Utilisez la commande normale de traduction.
• Confirmez le résultat visible et conservez l'original en cas d'échec.
• Surveillez les erreurs d'accès, quota, facturation et réseau.
• Notez les métadonnées sans copier contenu privé ni identifiants.

Après l'exécution :

• Vérifiez l'utilisation attendue dans Google Cloud.
• Contrôlez la langue et l'état de la page.
• Faites tourner la clé en cas d'exposition suspectée ou de changement de responsable.
• Réexaminez confidentialité et quota si le parcours, le profil ou l'audience changent.

Documentation associée

• Google Translate Page Translation pour la configuration.
• Profile Management pour choisir un profil adapté.
• Proxy Configuration pour la route réseau du navigateur.
• First Verification pour une vérification contrôlée.
• Per-Context Fingerprint pour les profils par contexte.

La traduction fonctionne mieux comme une capacité explicite avec une frontière externe explicite. La clé, le projet, le profil, la route, le quota et la politique de données doivent être visibles pour les responsables de la session. Vous obtenez ainsi un outil linguistique utile tout en préservant confidentialité, cohérence et contrôle opérationnel.