Oversæt struktureret indhold fra Java med PolyLingo SDK

PolyLingo Java SDK er nu tilgængelig på Maven Central. Den dækker hele PolyLingo API: synkron oversættelse, batch-forespørgsler, asynkrone jobs med polling og alle hjælpeendepunkter. Den kræver Java 11 eller nyere, bruger standardbibliotekets HTTP-klient og har præcis én runtime-afhængighed: Jackson til 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'

Ingen yderligere HTTP-klientafhængighed kræves. SDK bruger java.net.http.HttpClient fra Java 11 standardbiblioteket.

---

Opsætning af klienten

import com.usepolylingo.polylingo.PolyLingo;

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

To valgfrie builder-parametre er tilgængelige:

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

Opbevar din API-nøgle i en miljøvariabel. Hardcod den aldrig eller commit den til versionskontrol.

SDK bruger builder-mønsteret overalt. Ingen positionsbaserede konstruktører, ingen påkrævet feltorden. Alle valgfrie felter har fornuftige standardværdier, så du kun konfigurerer det, du faktisk har brug for at ændre.

---

Oversættelse af indhold

Enkelt forespørgsel

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 accepterer content og targets som påkrævede felter. Valgfrie parametre inkluderer format (plain, markdown, json eller html — automatisk opdaget, hvis udeladt), source som et sproghint, og model som enten standard (standard) eller advanced.

Formatbevarelse fungerer på samme måde som resten af PolyLingo API. For json-indhold oversættes kun strengværdier, og nøgler, indlejring og ikke-streng-typer forbliver uberørte. For markdown forbliver overskrifter overskrifter, og kodeblokke efterlades uændrede. For html bevares tags og attributter, og kun tekstnoder oversættes.

Oversættelse af 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ørgsel håndterer alle tre locales. Nøglerne er identiske med kilden i hver outputfil.

---

Batch-forespørgsler

Send op til 100 indholdselementer i en enkelt forespørgsel, hver med sit eget id og valgfrie 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 den samme targets-liste. Det id, du tildeler, bevares i svaret, så du kan mappe resultater tilbage til dine kildedata uden at stole på rækkefølgen.

---

Asynkrone jobs

For lange dokumenter eller store oversættelsesarbejder accepterer jobs-API'en en forespørgsel, returnerer straks et job-ID og lader dig poll'e efter resultatet. SDK håndterer dette på to måder.

Ét kald, der poller indtil færdigt

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 callback kaldes ved hver polling med den aktuelle køposition som et heltal, eller null hvis API'et ikke returnerer en. Brug det til at logge fremdrift eller opdatere en brugergrænseflade.

Sæt 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

---

Hjælpeendepunkter

// Tjek API sundhed (kræver ikke API-nøgle)
HealthResponse health = client.health();
System.out.println(health.getStatus()); // "ok"

// Liste over understøttede sprog (kræver ikke API-nøgle)
LanguagesResponse langs = client.languages();
langs.getLanguages().forEach(l ->
    System.out.println(l.getCode() + " — " + l.getName())
);

// Tjek tokenforbrug for den aktuelle faktureringsmåned
UsageResponse usage = client.usage();
System.out.println("Tokens used: " + usage.getUsage().getTokensUsed());
System.out.println("Tokens remaining: " + usage.getUsage().getTokensRemaining());

---

Fejlhåndtering

Alle undtagelser er unchecked. Ingen tvungne throws-deklarationer, ingen tjekkede undtagelseskæder at håndtere:

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 tilbagekaldt API-nøgle
    System.out.println("Auth failed: " + e.getError());
} catch (RateLimitException e) {
    // HTTP 429 — minutgrænse nået
    e.getRetryAfter().ifPresent(s ->
        System.out.println("Retry after: " + s + "s")
    );
} catch (JobFailedException e) {
    // Asynkront job nåede en fejlet terminal status eller polling timeout
    System.out.println("Job " + e.getJobId() + " failed: " + e.getError());
} catch (PolyLingoException e) {
    // Alle andre API-fejl
    System.out.println(e.getStatus() + ": " + e.getMessage());
}

RateLimitException.getRetryAfter() returnerer en Optional<Integer> — til stede med antal sekunder at vente, hvis API'et inkluderer denne værdi, ellers tom. JobFailedException.getJobId() giver dig ID'et på det fejlede job til logning eller retry-logik.

---

Designnoter

Nogle beslutninger værd at kende, hvis du evaluerer SDK'en:

Synkront API. Hver metode blokerer og returnerer et resultat direkte. Ingen Future, ingen CompletableFuture, ingen reaktive streams. Job-polling er SDK'ens asynkrone løsning til tunge arbejdsbelastninger — indsæt jobbet, SDK poller på din tråd og kalder din onProgress callback, når køpositionen opdateres.

Builder pattern overalt. Hvert parameterobjekt bruger en builder. Ingen positionsbaserede konstruktører betyder ingen gætteri om argumentrækkefølge, ingen utilsigtede feltbytter og klar kode ved kaldstedet.

Én runtime-afhængighed. Jackson til JSON-serialisering. Alt andet er standardbibliotek. Ingen OkHttp, ingen Apache HttpClient, ingen Guava.

Java 11+. Bruger java.net.http.HttpClient introduceret i Java 11. Hvis dit projekt sigter mod Java 8 eller tidligere, er SDK ikke kompatibel.

---

Hurtig reference

Metode	Endepunkt	Kræver auth
client.health()	GET /health	Nej
client.languages()	GET /languages	Nej
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 godt i gang

SDK'en findes på Maven Central på central.sonatype.com/artifact/com.usepolylingo/polylingo. Kildekode og Javadoc findes på github.com/UsePolyLingo/polylingo-Java. Fuld API-dokumentation findes på usepolylingo.com/docs/sdk/java.

Gratis niveau inkluderer 50.000 tokens pr. måned. Ingen kreditkort kræves.

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

Få din API-nøgle