Java SDK (polylingo)

Official Java client for the PolyLingo REST API. Uses java.net.http.HttpClient (Java 11+) plus Jackson for JSON (jackson-databind, the only runtime dependency).

• Maven coordinates: com.usepolylingo:polylingo
• Source: UsePolyLingo/polylingo-Java

For raw HTTP details, see API reference.

Installation

Maven

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

Gradle

implementation 'com.usepolylingo:polylingo:0.1.0'

Java: >= 11

Constructor

import com.usepolylingo.polylingo.PolyLingo;
import java.time.Duration;

PolyLingo client = PolyLingo.builder()
    .apiKey(System.getenv("POLYLINGO_API_KEY"))                    // required
    .baseUrl("https://api.usepolylingo.com/v1")                    // optional; default shown
    .timeout(Duration.ofSeconds(120))                              // optional; per-request HTTP timeout (default 120s)
    .build();

All API calls are synchronous (blocking). Use jobs().translate(...) for long-running translations that poll in the background on the server.

Methods

client.health()

GET /health

var h = client.health();
// h.getStatus(), h.getTimestamp()

client.languages()

GET /languages

var data = client.languages();
// data.getLanguages()

client.translate(params)

POST /translate

import com.usepolylingo.polylingo.types.TranslateParams;

var r = client.translate(
    TranslateParams.builder()
        .content("# Hello")
        .targets(java.util.List.of("es", "fr"))
        .format("markdown")   // optional; omit to auto-detect
        .source("en")         // optional
        .model("standard")    // optional: "standard" | "advanced"
        .build());
// r.getTranslations().get("es"), r.getUsage().getTotalTokens(), ...

client.batch(params)

POST /translate/batch

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

var b = client.batch(
    BatchParams.builder()
        .addItem(BatchItem.builder().id("a").content("Hello").build())
        .addItem(BatchItem.builder().id("b").content("## Title").format("markdown").build())
        .targets(java.util.List.of("de"))
        .build());
// b.getResults().get(0).getTranslations().get("de"), b.getUsage().getTotalTokens()

client.usage()

GET /usage

var u = client.usage();
// u.getUsage().getTokensUsed(), u.getUsage().getTokensLimit(), ...

Jobs (client.jobs())

client.jobs().create(params)

POST /jobs. Returns the 202 body (job_id, status, …).

import com.usepolylingo.polylingo.types.CreateJobParams;

var job = client.jobs().create(
    CreateJobParams.builder()
        .content(longMarkdown)
        .targets(java.util.List.of("de", "fr"))
        .format("markdown")
        .build());
// job.getJobId()

client.jobs().get(jobId)

GET /jobs/:id. When status is "completed", the response includes translations and usage at the top level.

var status = client.jobs().get(job.getJobId());

client.jobs().translate(params) (convenience)

Submits a job, then polls until completed or failed, or until the timeout is reached.

Polling options use java.time.Duration:

import com.usepolylingo.polylingo.types.JobsTranslateParams;
import java.time.Duration;

var done = client.jobs().translate(
    JobsTranslateParams.builder()
        .content(longMarkdown)
        .targets(java.util.List.of("de", "fr", "es"))
        .format("markdown")
        .pollInterval(Duration.ofSeconds(5))   // default 5s if omitted
        .timeout(Duration.ofMinutes(20))        // default 20m if omitted
        .onProgress(queuePosition ->
            System.out.println("Queue: " + queuePosition))
        .build());
// done.getTranslations(), done.getUsage()

Job lifecycle statuses: pending, processing, completed, failed.

Error handling

All failures throw unchecked subclasses of PolyLingoException:

import com.usepolylingo.polylingo.errors.*;

try {
    client.translate(
        TranslateParams.builder().content("x").targets(java.util.List.of("es")).build());
} catch (AuthException e) {
    // invalid key
} catch (RateLimitException e) {
    e.getRetryAfter().ifPresent(seconds -> { });
} catch (JobFailedException e) {
    // e.getJobId()
} catch (PolyLingoException e) {
    // e.getStatus(), e.getError()
}

Async jobs pattern (summary)

1. Manual: jobs().create → loop jobs().get until a terminal state.
2. Helper: jobs().translate with pollInterval, timeout, and optional onProgress.

Prefer jobs for very large content where synchronous translate might hit client or server timeouts.

Changelog

0.1.0

• Initial release: health, languages, translate, batch, usage, jobs().create, jobs().get, jobs().translate.