Översätt strukturerat innehåll från Java med PolyLingo SDK

PolyLingo Java SDK finns nu tillgängligt på Maven Central. Det täcker hela PolyLingo API: synkron översättning, batchförfrågningar, asynkrona jobb med polling och alla hjälpfunktioner. Det kräver Java 11 eller senare, använder standardbibliotekets HTTP-klient och har exakt ett runtimeberoende: Jackson för 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 ytterligare HTTP-klientberoende krävs. SDK använder java.net.http.HttpClient från Java 11:s standardbibliotek.

---

Ställa in klienten

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

Två valfria builder-parametrar finns tillgängliga:

PolyLingo client = PolyLingo.builder()
    .apiKey(System.getenv("POLYLINGO_API_KEY"))
    .baseUrl("https://api.usepolylingo.com/v1") // standard, skriv över för självhostade instanser
    .timeout(Duration.ofSeconds(30))            // standard är 120 sekunder
    .build();

Håll din API-nyckel i en miljövariabel. Aldrig hårdkoda den eller checka in den i versionskontroll.

SDK använder builder-mönstret överallt. Inga positionella konstruktörer, ingen obligatorisk fältordning. Alla valfria fält har vettiga standardvärden så att du bara konfigurerar det du faktiskt behöver ändra.

---

Översätta innehåll

Enskild förfrågan

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!

Buildern TranslateParams accepterar content och targets som obligatoriska fält. Valfria parametrar inkluderar format (plain, markdown, json eller html — autodekterat om utelämnat), source som språktips och model som antingen standard (standard) eller advanced.

Formatbevarande fungerar på samma sätt som resten av PolyLingo API. För json-innehåll översätts endast strängvärden och nycklar, nästling och icke-strängtyper lämnas orörda. För markdown förblir rubriker rubriker och kodblock lämnas verbatim. För html bevaras taggar och attribut och endast textnoder översätts.

Översätta en JSON-lokaliseringsfil

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

En förfrågan hanterar alla tre lokaler. Nycklarna är identiska med källan i varje utdatafil.

---

Batchförfrågningar

Skicka upp till 100 innehållsobjekt i en enda förfrågan, varje med sitt eget id och valfritt 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());
}

Alla objekt delar samma targets-lista. Det id du tilldelar bevaras i svaret så att du kan mappa resultaten tillbaka till din källdata utan att förlita dig på ordning.

---

Asynkrona jobb

För långa dokument eller stora översättningsbelastningar accepterar jobs-API:n en förfrågan, returnerar omedelbart ett jobb-ID och låter dig poll:a efter resultatet. SDK hanterar detta på två sätt.

Ett anrop som pollar tills klart

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 triggas vid varje polling med aktuell köposition som ett heltal, eller null om API inte returnerar en sådan. Använd den för att logga framsteg eller uppdatera ett UI.

Köa och poll:a manuellt

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

---

Hjälpändpunkter

// Kontrollera API-hälsa (ingen API-nyckel krävs)
HealthResponse health = client.health();
System.out.println(health.getStatus()); // "ok"
 
// Lista stödda språk (ingen API-nyckel krävs)
LanguagesResponse langs = client.languages();
langs.getLanguages().forEach(l ->
    System.out.println(l.getCode() + " — " + l.getName())
);
 
// Kontrollera tokenanvändning för aktuell faktureringsmånad
UsageResponse usage = client.usage();
System.out.println("Tokens used: " + usage.getUsage().getTokensUsed());
System.out.println("Tokens remaining: " + usage.getUsage().getTokensRemaining());

---

Felhantering

Alla undantag är unchecked. Inga tvingande throws-deklarationer, inga kontrollerade undantagskedjor att hantera:

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 — ogiltig, saknad eller återkallad API-nyckel
    System.out.println("Auth failed: " + e.getError());
} catch (RateLimitException e) {
    // HTTP 429 — minutgräns nådd
    e.getRetryAfter().ifPresent(s ->
        System.out.println("Retry after: " + s + "s")
    );
} catch (JobFailedException e) {
    // Async-jobb nådde ett misslyckat terminalt status eller polling timeout
    System.out.println("Job " + e.getJobId() + " failed: " + e.getError());
} catch (PolyLingoException e) {
    // Alla andra API-fel
    System.out.println(e.getStatus() + ": " + e.getMessage());
}

RateLimitException.getRetryAfter() returnerar en Optional<Integer> — närvarande med antal sekunder att vänta om API inkluderar det värdet, annars tom. JobFailedException.getJobId() ger dig ID för det misslyckade jobbet för loggning eller retry-logik.

---

Designnoteringar

Några beslut värda att känna till om du utvärderar SDK:

Synkront API. Varje metod blockerar och returnerar ett resultat direkt. Ingen Future, ingen CompletableFuture, inga reaktiva strömmar. Jobb-polling är SDK:ns asynkrona lösning för tunga arbetsbelastningar — skicka in jobbet, SDK pollar i din tråd och anropar din onProgress callback när köpositionen uppdateras.

Builder-mönster överallt. Varje params-objekt använder en builder. Inga positionella konstruktörer betyder ingen gissning av argumentordning, inga oavsiktliga fältbyten och tydlig kod vid anropsplatsen.

En runtime-beroende. Jackson för JSON-serialisering. Allt annat är standardbibliotek. Ingen OkHttp, ingen Apache HttpClient, ingen Guava.

Java 11+. Använder java.net.http.HttpClient som introducerades i Java 11. Om ditt projekt riktar sig mot Java 8 eller tidigare är SDK inte kompatibelt.

---

Snabbreferens

Metod	Endpoint	Kräver autentisering
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 igång

SDK finns på Maven Central på central.sonatype.com/artifact/com.usepolylingo/polylingo. Källkod och Javadoc finns på github.com/UsePolyLingo/polylingo-Java. Fullständig API-dokumentation finns på usepolylingo.com/docs/sdk/java.

Gratisnivån inkluderar 50 000 tokens per månad. Ingen kreditkort krävs.

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

Få din API-nyckel