Traduire du contenu structuré depuis Java avec le SDK PolyLingo

Le SDK PolyLingo Java est désormais disponible sur Maven Central. Il couvre l'intégralité de l'API PolyLingo : traduction synchrone, requêtes batch, travaux asynchrones avec polling, et tous les points d'utilité. Il nécessite Java 11 ou ultérieur, utilise le client HTTP de la bibliothèque standard, et a exactement une dépendance d'exécution : Jackson pour JSON.

---

Installation

Maven

<dependency>
  <groupId>com.usepolylingo</groupId>
  <artifactId>polylingo</artifactId>
  <version>0.1.0</version>
</dependency>

Gradle

implementation 'com.usepolylingo:polylingo:0.1.0'

Aucune dépendance supplémentaire pour le client HTTP requise. Le SDK utilise java.net.http.HttpClient de la bibliothèque standard Java 11.

---

Configuration du client

import com.usepolylingo.polylingo.PolyLingo;

PolyLingo client = PolyLingo.builder()
    .apiKey(System.getenv("POLYLINGO_API_KEY"))
    .build();

Deux paramètres optionnels du builder sont disponibles :

PolyLingo client = PolyLingo.builder()
    .apiKey(System.getenv("POLYLINGO_API_KEY"))
    .baseUrl("https://api.usepolylingo.com/v1") // par défaut, à surcharger pour les instances auto-hébergées
    .timeout(Duration.ofSeconds(30))            // par défaut 120 secondes
    .build();

Gardez votre clé API dans une variable d'environnement. Ne la codez jamais en dur ni ne la commettez dans le contrôle de version.

Le SDK utilise le pattern builder partout. Pas de constructeurs positionnels, pas d'ordre obligatoire des champs. Tous les champs optionnels ont des valeurs par défaut sensées, vous ne configurez que ce que vous devez réellement changer.

---

Traduction de contenu

Requête unique

import com.usepolylingo.polylingo.types.TranslateParams;
import com.usepolylingo.polylingo.types.TranslateResult;

TranslateResult result = client.translate(
    TranslateParams.builder()
        .content("Hello, world!")
        .targets(List.of("es", "fr", "de"))
        .build()
);

result.getTranslations().forEach((lang, text) ->
    System.out.println(lang + ": " + text)
);
// es: ¡Hola, mundo!
// fr: Bonjour le monde !
// de: Hallo Welt!

Le builder TranslateParams accepte content et targets comme champs requis. Les paramètres optionnels incluent format (plain, markdown, json ou html — détecté automatiquement si omis), source comme indice de langue, et model soit standard (par défaut) ou advanced.

La préservation du format fonctionne comme dans le reste de l'API PolyLingo. Pour le contenu json, seules les valeurs chaînes sont traduites, les clés, la structure et les types non-chaînes sont laissés intacts. Pour markdown, les titres restent des titres et les blocs de code sont laissés tels quels. Pour html, les balises et attributs sont préservés et seuls les nœuds de texte sont traduits.

Traduction d'un fichier de localisation JSON

import com.fasterxml.jackson.databind.ObjectMapper;
import java.nio.file.Files;
import java.nio.file.Path;

ObjectMapper mapper = new ObjectMapper();
String sourceJson = Files.readString(Path.of("messages/en.json"));

TranslateResult result = client.translate(
    TranslateParams.builder()
        .content(sourceJson)
        .format("json")
        .targets(List.of("fr", "de", "ja"))
        .build()
);

result.getTranslations().forEach((locale, translated) -> {
    try {
        Object parsed = mapper.readValue(translated, Object.class);
        String pretty = mapper.writerWithDefaultPrettyPrinter().writeValueAsString(parsed);
        Files.writeString(Path.of("messages/" + locale + ".json"), pretty);
        System.out.println("Wrote messages/" + locale + ".json");
    } catch (Exception e) {
        throw new RuntimeException(e);
    }
});

Une seule requête gère les trois locales. Les clés sont identiques à la source dans chaque fichier de sortie.

---

Requêtes batch

Envoyez jusqu'à 100 éléments de contenu dans une seule requête, chacun avec son propre id et un format optionnel :

import com.usepolylingo.polylingo.types.BatchParams;
import com.usepolylingo.polylingo.types.BatchItem;
import com.usepolylingo.polylingo.types.BatchResult;

BatchResult result = client.batch(
    BatchParams.builder()
        .targets(List.of("es", "ja"))
        .addItem(BatchItem.builder().id("title").content("Welcome").build())
        .addItem(BatchItem.builder().id("body").content("Get started today.").build())
        .build()
);

for (BatchItemResult item : result.getResults()) {
    System.out.println(item.getId() + ": " + item.getTranslations());
}

Tous les éléments partagent la même liste targets. L'id que vous assignez est conservé dans la réponse afin que vous puissiez mapper les résultats à vos données sources sans dépendre de l'ordre.

---

Travaux asynchrones

Pour les longs documents ou les lourdes charges de traduction, l'API jobs accepte une requête, retourne immédiatement un ID de travail, et vous permet de faire du polling pour le résultat. Le SDK gère cela de deux manières.

Un appel qui fait du polling jusqu'à la fin

import com.usepolylingo.polylingo.types.JobsTranslateParams;

TranslateResult result = client.jobs().translate(
    JobsTranslateParams.builder()
        .content(longArticleText)
        .targets(List.of("fr", "de", "ja", "zh"))
        .pollInterval(Duration.ofSeconds(3))
        .timeout(Duration.ofMinutes(10))
        .onProgress(queuePosition ->
            System.out.println("Queue position: " + queuePosition))
        .build()
);

result.getTranslations().forEach((lang, text) ->
    System.out.println(lang + ": " + text.substring(0, 100) + "...")
);

Le callback onProgress est appelé à chaque poll avec la position actuelle dans la file d'attente en entier, ou null si l'API ne la retourne pas. Utilisez-le pour journaliser la progression ou mettre à jour une interface utilisateur.

Enfilez et faites du polling manuellement

import com.usepolylingo.polylingo.types.CreateJobParams;
import com.usepolylingo.polylingo.types.Job;

Job job = client.jobs().create(
    CreateJobParams.builder()
        .content("Translate this.")
        .targets(List.of("es"))
        .build()
);

// Faites le polling vous-même
Job status = client.jobs().get(job.getJobId());
System.out.println(status.getStatus()); // pending / processing / completed / failed

---

Points d'utilité

// Vérifier la santé de l'API (pas de clé API requise)
HealthResponse health = client.health();
System.out.println(health.getStatus()); // "ok"

// Lister les langues supportées (pas de clé API requise)
LanguagesResponse langs = client.languages();
langs.getLanguages().forEach(l ->
    System.out.println(l.getCode() + " — " + l.getName())
);

// Vérifier l'utilisation des tokens pour le mois de facturation en cours
UsageResponse usage = client.usage();
System.out.println("Tokens used: " + usage.getUsage().getTokensUsed());
System.out.println("Tokens remaining: " + usage.getUsage().getTokensRemaining());

---

Gestion des erreurs

Toutes les exceptions sont unchecked. Pas de déclarations throws forcées, pas de chaînes d'exceptions checked à dénouer :

import com.usepolylingo.polylingo.errors.*;

try {
    TranslateResult result = client.translate(
        TranslateParams.builder()
            .content("# Hello")
            .targets(List.of("es", "fr"))
            .format("markdown")
            .build()
    );
} catch (AuthException e) {
    // HTTP 401 — clé API invalide, manquante ou révoquée
    System.out.println("Auth failed: " + e.getError());
} catch (RateLimitException e) {
    // HTTP 429 — limite par minute atteinte
    e.getRetryAfter().ifPresent(s ->
        System.out.println("Retry after: " + s + "s")
    );
} catch (JobFailedException e) {
    // Travail asynchrone arrivé à un statut terminal échoué ou timeout du polling
    System.out.println("Job " + e.getJobId() + " failed: " + e.getError());
} catch (PolyLingoException e) {
    // Toutes les autres erreurs API
    System.out.println(e.getStatus() + ": " + e.getMessage());
}

RateLimitException.getRetryAfter() retourne un Optional<Integer> — présent avec le nombre de secondes à attendre si l'API inclut cette valeur, vide sinon. JobFailedException.getJobId() vous donne l'ID du travail échoué pour la journalisation ou la logique de nouvelle tentative.

---

Notes de conception

Quelques décisions à connaître si vous évaluez le SDK :

API synchrone. Chaque méthode bloque et retourne un résultat directement. Pas de Future, pas de CompletableFuture, pas de flux réactifs. Le polling des jobs est la solution async du SDK pour les charges lourdes — soumettez le job, le SDK fait le polling sur votre thread et appelle votre callback onProgress à mesure que la position dans la file évolue.

Pattern builder partout. Chaque objet de paramètres utilise un builder. Pas de constructeurs positionnels signifie pas de devinettes sur l'ordre des arguments, pas d'échanges accidentels de champs, et un code clair au point d'appel.

Une dépendance d'exécution. Jackson pour la sérialisation JSON. Tout le reste est bibliothèque standard. Pas d'OkHttp, pas d'Apache HttpClient, pas de Guava.

Java 11+. Utilise java.net.http.HttpClient introduit en Java 11. Si votre projet cible Java 8 ou antérieur, le SDK n'est pas compatible.

---

Référence rapide

Méthode	Endpoint	Auth requise
client.health()	GET /health	Non
client.languages()	GET /languages	Non
client.translate(...)	POST /translate	Oui
client.batch(...)	POST /translate/batch	Oui
client.usage()	GET /usage	Oui
client.jobs().create(...)	POST /jobs	Oui
client.jobs().get(jobId)	GET /jobs/:id	Oui
client.jobs().translate(...)	POST /jobs + polling	Oui

---

Démarrer

Le SDK est sur Maven Central à central.sonatype.com/artifact/com.usepolylingo/polylingo. Le code source et la Javadoc sont sur github.com/UsePolyLingo/polylingo-Java. La documentation complète de l'API est sur usepolylingo.com/docs/sdk/java.

Le niveau gratuit inclut 50 000 tokens par mois. Pas de carte de crédit requise.

<dependency>
  <groupId>com.usepolylingo</groupId>
  <artifactId>polylingo</artifactId>
  <version>0.1.0</version>
</dependency>

Obtenez votre clé API