Tradurre contenuti strutturati da Java con il PolyLingo SDK

Il PolyLingo Java SDK è ora disponibile su Maven Central. Copre l'intera API PolyLingo: traduzione sincrona, richieste batch, lavori asincroni con polling e tutti gli endpoint di utilità. Richiede Java 11 o superiore, utilizza il client HTTP della libreria standard e ha esattamente una dipendenza di runtime: Jackson per JSON.

Installazione

Maven

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

Gradle

implementation 'com.usepolylingo:polylingo:0.1.0'

Non è richiesta alcuna dipendenza aggiuntiva per il client HTTP. L'SDK utilizza java.net.http.HttpClient dalla libreria standard di Java 11.

Configurazione del client

import com.usepolylingo.polylingo.PolyLingo;
 
PolyLingo client = PolyLingo.builder()
    .apiKey(System.getenv("POLYLINGO_API_KEY"))
    .build();

Sono disponibili due parametri builder opzionali:

PolyLingo client = PolyLingo.builder()
    .apiKey(System.getenv("POLYLINGO_API_KEY"))
    .baseUrl("https://api.usepolylingo.com/v1") // default, sovrascrivi per istanze self-hosted
    .timeout(Duration.ofSeconds(30))            // default è 120 secondi
    .build();

Conserva la tua chiave API in una variabile d'ambiente. Non inserirla mai direttamente nel codice o committarla nel controllo versione.

L'SDK utilizza il pattern builder ovunque. Nessun costruttore posizionale, nessun ordine obbligatorio dei campi. Tutti i campi opzionali hanno valori predefiniti sensati, quindi configuri solo ciò che devi effettivamente modificare.

Traduzione dei contenuti

Richiesta singola

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!

Il builder TranslateParams accetta content e targets come campi obbligatori. I parametri opzionali includono format (plain, markdown, json o html — rilevato automaticamente se omesso), source come suggerimento di lingua e model come standard (default) o advanced.

La preservazione del formato funziona come nel resto dell'API PolyLingo. Per contenuti json, vengono tradotti solo i valori stringa e chiavi, nidificazione e tipi non stringa rimangono intatti. Per markdown, le intestazioni rimangono tali e i blocchi di codice sono lasciati verbatim. Per html, tag e attributi sono preservati e solo i nodi di testo sono tradotti.

Tradurre un file locale 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);
    }
});

Una singola richiesta gestisce tutte e tre le localizzazioni. Le chiavi sono identiche alla sorgente in ogni file di output.

Richieste batch

Invia fino a 100 elementi di contenuto in una singola richiesta, ciascuno con il proprio id e format opzionale:

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());
}

Tutti gli elementi condividono la stessa lista targets. L'id che assegni viene mantenuto nella risposta così puoi mappare i risultati ai dati sorgente senza affidarti all'ordine.

Lavori Async

Per documenti lunghi o carichi di lavoro di traduzione grandi, l'API lavori accetta una richiesta, restituisce immediatamente un ID lavoro e ti permette di fare polling per il risultato. L'SDK gestisce questo in due modi.

Una chiamata che fa polling fino al completamento

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) + "...")
);

La callback onProgress viene chiamata ad ogni polling con la posizione attuale in coda come intero, o null se l'API non la restituisce. Usala per registrare il progresso o aggiornare un'interfaccia utente.

Metti in coda e fai polling manualmente

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()
);
 
// Fai polling manualmente
Job status = client.jobs().get(job.getJobId());
System.out.println(status.getStatus()); // pending / processing / completed / failed

Endpoint di utilità

// Controlla lo stato dell'API (non serve chiave API)
HealthResponse health = client.health();
System.out.println(health.getStatus()); // "ok"
 
// Elenca le lingue supportate (non serve chiave API)
LanguagesResponse langs = client.languages();
langs.getLanguages().forEach(l ->
    System.out.println(l.getCode() + " — " + l.getName())
);
 
// Controlla l'uso dei token per il mese di fatturazione corrente
UsageResponse usage = client.usage();
System.out.println("Tokens used: " + usage.getUsage().getTokensUsed());
System.out.println("Tokens remaining: " + usage.getUsage().getTokensRemaining());

Gestione degli errori

Tutte le eccezioni sono unchecked. Nessuna dichiarazione throws obbligatoria, nessuna catena di eccezioni checked da gestire:

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 — chiave API non valida, mancante o revocata
    System.out.println("Auth failed: " + e.getError());
} catch (RateLimitException e) {
    // HTTP 429 — limite al minuto raggiunto
    e.getRetryAfter().ifPresent(s ->
        System.out.println("Retry after: " + s + "s")
    );
} catch (JobFailedException e) {
    // Lavoro async ha raggiunto uno stato terminale fallito o timeout polling
    System.out.println("Job " + e.getJobId() + " failed: " + e.getError());
} catch (PolyLingoException e) {
    // Tutti gli altri errori API
    System.out.println(e.getStatus() + ": " + e.getMessage());
}

RateLimitException.getRetryAfter() restituisce un Optional<Integer> — presente con il numero di secondi da attendere se l'API include quel valore, vuoto altrimenti. JobFailedException.getJobId() ti dà l'ID del lavoro fallito per logging o logica di retry.

Note di design

Alcune decisioni importanti da conoscere se stai valutando l'SDK:

API sincrona. Ogni metodo blocca e restituisce un risultato direttamente. Nessun Future, CompletableFuture o reactive streams. Il polling dei lavori è la storia async dell'SDK per carichi pesanti — invii il lavoro, l'SDK fa polling nel tuo thread e chiama la callback onProgress mentre la posizione in coda si aggiorna.

Pattern builder ovunque. Ogni oggetto params usa un builder. Nessun costruttore posizionale significa niente indovinelli sull'ordine degli argomenti, nessuno scambio accidentale di campi e codice chiaro nel punto di chiamata.

Una dipendenza di runtime. Jackson per la serializzazione JSON. Tutto il resto è libreria standard. Niente OkHttp, Apache HttpClient o Guava.

Java 11+. Usa java.net.http.HttpClient introdotto in Java 11. Se il tuo progetto punta a Java 8 o precedente, l'SDK non è compatibile.

Riferimento rapido

Metodo	Endpoint	Auth richiesta
`client.health()`	GET /health	No
`client.languages()`	GET /languages	No
`client.translate(...)`	POST /translate	Sì
`client.batch(...)`	POST /translate/batch	Sì
`client.usage()`	GET /usage	Sì
`client.jobs().create(...)`	POST /jobs	Sì
`client.jobs().get(jobId)`	GET /jobs/:id	Sì
`client.jobs().translate(...)`	POST /jobs + polling	Sì

Inizia

L'SDK è su Maven Central a central.sonatype.com/artifact/com.usepolylingo/polylingo. Il codice sorgente e Javadoc sono su github.com/UsePolyLingo/polylingo-Java. La documentazione completa dell'API è su usepolylingo.com/docs/sdk/java.

Il piano gratuito include 50.000 token al mese. Nessuna carta di credito richiesta.

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

Ottieni la tua chiave API

Traduci contenuti strutturati da Java con il SDK PolyLingo