Maintenir les intégrations du SDK v0
Comprenez les fonctions utilitaires de LingoDotDevEngine et préservez leur gestion des entrées, des sorties, du traitement par lots et de l’annulation lors d’une migration.
Une application utilisant LingoDotDevEngine peut faire appel à bien plus que la traduction d’objets : elle peut découper les requêtes en blocs, reconstruire des tableaux ou analyser du HTML. Lors d’une migration, veillez à préserver explicitement ces comportements. Changer l’import ne suffit pas à les remplacer.
Cette référence porte sur lingo.dev 0.138.10, dont le point d’entrée lingo.dev/sdk réexporte @lingo.dev/_sdk 0.17.3. Conservez la version enregistrée dans le Lockfile de l’application pendant que vous vérifiez les endroits où ces fonctions sont appelées. Pour un nouveau workflow côté serveur, consultez le guide de l’API JavaScript.
Appels existants de traduction d’objets #
Les appels côté serveur prenaient historiquement cette forme :
import { LingoDotDevEngine } from "lingo.dev/sdk";
const apiKey = process.env.LINGO_API_KEY;
const engineId = process.env.LINGO_ENGINE_ID;
if (!apiKey || !engineId) throw new Error("Configure a key and localization engine ID");
const client = new LingoDotDevEngine({ apiKey, engineId });
const translated = await client.localizeObject(
{ greeting: "Welcome back" },
{ sourceLocale: "en", targetLocale: "es" },
);La fonction utilitaire renvoie directement l’objet traduit. Gardez les identifiants d’authentification côté serveur. Une tâche de traitement de document suit un cycle distinct de création, de démarrage et de téléchargement ; la réponse à sa création n’est pas l’objet traduit que renvoie cette fonction utilitaire.
Constructeur et paramètres de traitement par lots #
| Option | Comportement historique |
|---|---|
apiKey | Chaîne obligatoire, validée par le constructeur. |
apiUrl | Remplacement de l’URL de base de l’API. |
engineId | Choix facultatif du moteur de localisation, envoyé avec la traduction. |
batchSize | 25 par défaut, 250 au maximum. |
idealBatchItemSize | 250 par défaut, 2500 au maximum. |
maxRetries | 3 par défaut. |
retryDelayMs | 500 millisecondes par défaut. |
Les options de traitement par lots déterminent la façon dont le client construit les blocs, et non le nombre d’opérations simultanées à l’échelle de l’application. Sa fonction utilitaire de nouvelle tentative relance les requêtes en cas d’erreur réseau ou 5xx, avec un délai exponentiel assorti d’une variation aléatoire. Elle ne relance ni les requêtes annulées volontairement ni celles ayant reçu une réponse 4xx ordinaire. D’autres opérations, comme la reconnaissance et la recherche de compte, suivent leurs propres circuits de requête ; ne supposez pas qu’une même politique de nouvelle tentative s’applique à toutes les méthodes.
Entrées et valeurs de retour des fonctions utilitaires #
| Fonction utilitaire | Contrat |
|---|---|
localizeObject(object, params, progressCallback?, signal?) | Un objet en entrée, un objet traduit en sortie. |
localizeText(text, params, progressCallback?, signal?) | Place le texte dans un champ et renvoie la chaîne traduite. |
batchLocalizeText(text, { sourceLocale, targetLocales, fast? }, signal?) | Exécute une requête de traduction de texte pour chaque langue et renvoie les chaînes dans l’ordre des langues demandées. |
localizeStringArray(strings, params) | Utilise des clés temporaires et reconstruit un tableau de chaînes ; n’expose aucun paramètre de signal public. |
localizeChat(messages, params, progressCallback?, signal?) | Traduit text dans les messages { name, text } et conserve leurs noms. |
localizeHtml(html, params, progressCallback?, signal?) | Analyse le HTML avec jsdom, traduit le contenu sélectionné et sérialise le résultat. |
recognizeLocale(text, signal?) | Renvoie la valeur de langue issue de la reconnaissance. |
estimate(items, signal?) | Accepte des éléments { targetLocale, sourceChars } et renvoie des totaux approximatifs ainsi que les coûts par langue. |
whoami(signal?) | Renvoie { email, id } ou null pour les réponses de compte ordinaires indiquant un échec ; les erreurs serveur peuvent déclencher une exception. |
Les paramètres de traduction courants sont sourceLocale (peut être nul pour permettre la détection), targetLocale, fast facultatif, des données de référence par langue, des tableaux d’indications par clé, filePath et triggerType (cli ou ci). Les langues sont normalisées avant utilisation. Préservez le sens de chaque entrée lorsque vous la faites correspondre à un schéma de requête plus récent.
Les fonctions de rappel de progression signalent les blocs terminés côté client, avec le pourcentage d’avancement et les blocs sources et traités. Il ne s’agit pas de notifications persistantes de tâches en arrière-plan. Un AbortSignal arrête le travail côté client, mais ne peut pas annuler le traitement déjà accepté par le serveur.
Préserver explicitement le comportement HTML #
La fonction utilitaire HTML traduit les nœuds de texte situés en dehors de script et style, ainsi que meta.content, img.alt, input.placeholder et a.title. Elle définit la langue cible comme langue du document et sérialise le DOM. Elle ne traduit pas tous les attributs et ne conserve pas les octets d’origine.
Testez cette fonction utilitaire dans l’environnement d’exécution réel du serveur, en vérifiant notamment la résolution de son import dynamique jsdom. Comparez les liens, le balisage structurel, les attributs sélectionnés et la sortie sérialisée avant de remplacer un appel HTML par une autre transformation. Une requête JSON structurée ne réalise pas, à elle seule, ces étapes de traitement HTML.
ReplexicaEngine et LingoEngine étendent LingoDotDevEngine en tant qu’alias de compatibilité et émettent des avertissements d’obsolescence. Faire disparaître un avertissement lié à un alias ne constitue qu’un changement de nom ; cela ne suffit pas à migrer le comportement.
Migrer une application vers les tâches de traitement de documents #
Pour une nouvelle intégration, suivez le cycle de vie des tâches de l’API. Placez le contenu de l’objet dans un document JSON intégré à la requête, démarrez la tâche et téléchargez chaque cible terminée. Conservez l’ID de la tâche avec la révision source jusqu’à ce que l’application accepte son résultat.
Préservez tous les comportements de l’application qui dépendent actuellement du placement du texte dans un champ, de l’ordre des tableaux, de l’analyse HTML, du traitement par lots ou des fonctions de rappel de progression. Pour la traduction de fichiers, vous pouvez utiliser le format de document correspondant. Changer de mode de transport ne recrée pas automatiquement les transformations ni les nouvelles tentatives côté client.
Comparez les données obtenues et la gestion des échecs avant de basculer le stockage de l’application vers le nouveau workflow. Le guide des workflows aborde les résultats partiels et les tâches qui se terminent dans un ordre différent de celui de leur lancement.