Oversett strukturert innhold fra Java med PolyLingo SDK

PolyLingo Java SDK er nå tilgjengelig på Maven Central. Den dekker hele PolyLingo API: synkron oversettelse, batch-forespørsler, asynkrone jobber med polling, og alle hjelpeendepunkter. Den krever Java 11 eller nyere, bruker standardbibliotekets HTTP-klient, og har nøyaktig én runtime-avhengighet: Jackson for JSON.

---

Installasjon

Maven

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

Gradle

implementation 'com.usepolylingo:polylingo:0.1.0'

Ingen ekstra HTTP-klientavhengighet kreves. SDK-en bruker java.net.http.HttpClient fra Java 11 standardbibliotek.

---

Sette opp klienten

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

To valgfrie builder-parametere er tilgjengelige:

PolyLingo client = PolyLingo.builder()
    .apiKey(System.getenv("POLYLINGO_API_KEY"))
    .baseUrl("https://api.usepolylingo.com/v1") // standard, overskriv for selvhostede instanser
    .timeout(Duration.ofSeconds(30))            // standard er 120 sekunder
    .build();

Hold API-nøkkelen din i en miljøvariabel. Aldri hardkod den eller legg den i versjonskontroll.

SDK-en bruker builder-mønsteret gjennomgående. Ingen posisjonelle konstruktører, ingen påkrevd rekkefølge på felt. Alle valgfrie felt har fornuftige standardverdier slik at du bare konfigurerer det du faktisk trenger å endre.

---

Oversette innhold

Enkelt forespørsel

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!

TranslateParams-builderen aksepterer content og targets som påkrevde felt. Valgfrie parametere inkluderer format (plain, markdown, json, eller html — oppdages automatisk hvis utelatt), source som språktips, og model som enten standard (standard) eller advanced.

Formatbevaring fungerer på samme måte som resten av PolyLingo API. For json-innhold oversettes bare strengverdier, og nøkler, nesting og ikke-streng-typer forblir urørt. For markdown forblir overskrifter overskrifter og kodeblokker blir stående ordrett. For html bevares tagger og attributter, og bare tekstnoder oversettes.

Oversette en JSON locale-fil

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

Én forespørsel håndterer alle tre locale. Nøklene er identiske med kilden i hver utdatafil.

---

Batch-forespørsler

Send opptil 100 innholdselementer i én enkelt forespørsel, hver med sin egen id og valgfri format:

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

Alle elementer deler samme targets-liste. id du tildeler bevares i responsen slik at du kan mappe resultater tilbake til kildedata uten å stole på rekkefølge.

---

Async jobber

For lange dokumenter eller store oversettelsesarbeidsmengder aksepterer jobs-API-et en forespørsel, returnerer umiddelbart med en jobb-ID, og lar deg poll for resultatet. SDK-en håndterer dette på to måter.

Én kall som poller til ferdig

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

onProgress callbacken kalles ved hver polling med gjeldende køposisjon som et heltall, eller null hvis API-et ikke returnerer en. Bruk den til å logge fremdrift eller oppdatere et brukergrensesnitt.

Kjø inn i kø og poll manuelt

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

---

Hjelpeendepunkter

// Sjekk API-helse (ingen API-nøkkel kreves)
HealthResponse health = client.health();
System.out.println(health.getStatus()); // "ok"
 
// List støttede språk (ingen API-nøkkel kreves)
LanguagesResponse langs = client.languages();
langs.getLanguages().forEach(l ->
    System.out.println(l.getCode() + " — " + l.getName())
);
 
// Sjekk tokenbruk for gjeldende faktureringsmåned
UsageResponse usage = client.usage();
System.out.println("Tokens used: " + usage.getUsage().getTokensUsed());
System.out.println("Tokens remaining: " + usage.getUsage().getTokensRemaining());

---

Feilhåndtering

Alle unntak er unchecked. Ingen tvungne throws-deklarasjoner, ingen sjekket unntakskjeder å pakke ut:

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 — ugyldig, manglende eller tilbakekalt API-nøkkel
    System.out.println("Auth failed: " + e.getError());
} catch (RateLimitException e) {
    // HTTP 429 — per-minutt grense nådd
    e.getRetryAfter().ifPresent(s ->
        System.out.println("Retry after: " + s + "s")
    );
} catch (JobFailedException e) {
    // Async jobb nådde en mislykket terminal status eller polling tidsavbrudd
    System.out.println("Job " + e.getJobId() + " failed: " + e.getError());
} catch (PolyLingoException e) {
    // Alle andre API-feil
    System.out.println(e.getStatus() + ": " + e.getMessage());
}

RateLimitException.getRetryAfter() returnerer en Optional<Integer> — tilstede med antall sekunder å vente hvis API-et inkluderer den verdien, tom ellers. JobFailedException.getJobId() gir deg ID-en til den mislykkede jobben for logging eller retry-logikk.

---

Designnotater

Noen beslutninger verdt å vite om hvis du evaluerer SDK-en:

Synkron API. Hver metode blokkerer og returnerer et resultat direkte. Ingen Future, ingen CompletableFuture, ingen reaktive strømmer. Jobb-pollingen er SDK-ens async-historie for tunge arbeidsmengder — send inn jobben, SDK poller på din tråd og kaller din onProgress callback når køposisjonen oppdateres.

Builder-mønster gjennomgående. Hvert params-objekt bruker en builder. Ingen posisjonelle konstruktører betyr ingen gjetting på argumentrekkefølge, ingen utilsiktede feltbytter, og klar kode på kallstedet.

Én runtime-avhengighet. Jackson for JSON-serialisering. Alt annet er standardbibliotek. Ingen OkHttp, ingen Apache HttpClient, ingen Guava.

Java 11+. Bruker java.net.http.HttpClient introdusert i Java 11. Hvis prosjektet ditt målretter Java 8 eller tidligere, er SDK-en ikke kompatibel.

---

Rask referanse

Metode	Endepunkt	Auth kreves
client.health()	GET /health	Nei
client.languages()	GET /languages	Nei
client.translate(...)	POST /translate	Ja
client.batch(...)	POST /translate/batch	Ja
client.usage()	GET /usage	Ja
client.jobs().create(...)	POST /jobs	Ja
client.jobs().get(jobId)	GET /jobs/:id	Ja
client.jobs().translate(...)	POST /jobs + polling	Ja

---

Kom i gang

SDK-en er på Maven Central på central.sonatype.com/artifact/com.usepolylingo/polylingo. Kildekode og Javadoc er på github.com/UsePolyLingo/polylingo-Java. Full API-dokumentasjon er på usepolylingo.com/docs/sdk/java.

Gratisnivået inkluderer 50 000 tokens per måned. Ingen kredittkort kreves.

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

Få din API-nøkkel