Překlad strukturovaného obsahu z Javy pomocí PolyLingo SDK

PolyLingo Java SDK je nyní dostupné na Maven Central. Pokrývá kompletní PolyLingo API: synchronní překlad, dávkové požadavky, asynchronní úlohy s pollingem a všechny pomocné koncové body. Vyžaduje Javu 11 nebo novější, používá standardního HTTP klienta z knihovny a má přesně jednu runtime závislost: Jackson pro JSON.

---

Instalace

Maven

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

Gradle

implementation 'com.usepolylingo:polylingo:0.1.0'

Není potřeba žádná další závislost HTTP klienta. SDK používá java.net.http.HttpClient ze standardní knihovny Javy 11.

---

Nastavení klienta

import com.usepolylingo.polylingo.PolyLingo;

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

Jsou dostupné dva volitelné parametry builderu:

PolyLingo client = PolyLingo.builder()
    .apiKey(System.getenv("POLYLINGO_API_KEY"))
    .baseUrl("https://api.usepolylingo.com/v1") // výchozí, přepište pro self-hosted instance
    .timeout(Duration.ofSeconds(30))            // výchozí je 120 sekund
    .build();

Uchovávejte svůj API klíč v proměnné prostředí. Nikdy ho nezapisujte přímo do kódu ani necommitujte do verzovacího systému.

SDK používá builder pattern všude. Žádné poziční konstruktory, žádné povinné pořadí polí. Všechna volitelná pole mají rozumné výchozí hodnoty, takže konfigurujete jen to, co skutečně potřebujete změnit.

---

Překlad obsahu

Jednotlivý požadavek

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!

Builder TranslateParams přijímá content a targets jako povinná pole. Volitelné parametry zahrnují format (plain, markdown, json nebo html — automaticky detekováno, pokud je vynecháno), source jako jazykovou nápovědu a model buď standard (výchozí) nebo advanced.

Zachování formátu funguje stejně jako u zbytku PolyLingo API. Pro obsah json se překládají pouze hodnoty typu string, klíče, vnoření a netextové typy zůstávají nedotčeny. Pro markdown zůstávají nadpisy nadpisy a bloky kódu jsou ponechány beze změny. Pro html jsou značky a atributy zachovány a překládají se pouze textové uzly.

Překlad JSON locale souboru

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

Jeden požadavek zpracuje všechny tři locale. Klíče jsou ve všech výstupních souborech shodné se zdrojem.

---

Dávkové požadavky

Pošlete až 100 obsahových položek v jednom požadavku, každou s vlastním id a volitelným 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());
}

Všechny položky sdílejí stejný seznam targets. Vámi přiřazené id je zachováno v odpovědi, takže můžete výsledky namapovat zpět na zdrojová data bez spoléhání se na pořadí.

---

Asynchronní úlohy

Pro dlouhé dokumenty nebo velké překladové úlohy API úloh přijme požadavek, okamžitě vrátí ID úlohy a umožní vám pollovat výsledek. SDK to řeší dvěma způsoby.

Jeden hovor, který polluje dokud není hotovo

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

Callback onProgress se volá při každém pollu s aktuální pozicí ve frontě jako integer, nebo null, pokud API žádnou nevrací. Použijte ho pro logování průběhu nebo aktualizaci UI.

Zařazení do fronty a manuální polling

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

// Pollujte sami
Job status = client.jobs().get(job.getJobId());
System.out.println(status.getStatus()); // pending / processing / completed / failed

---

Pomocné koncové body

// Kontrola zdraví API (není potřeba API klíč)
HealthResponse health = client.health();
System.out.println(health.getStatus()); // "ok"

// Seznam podporovaných jazyků (není potřeba API klíč)
LanguagesResponse langs = client.languages();
langs.getLanguages().forEach(l ->
    System.out.println(l.getCode() + " — " + l.getName())
);

// Kontrola využití tokenů za aktuální fakturační měsíc
UsageResponse usage = client.usage();
System.out.println("Tokens used: " + usage.getUsage().getTokensUsed());
System.out.println("Tokens remaining: " + usage.getUsage().getTokensRemaining());

---

Zpracování chyb

Všechny výjimky jsou unchecked. Žádné povinné throws deklarace, žádné kontrolované řetězce výjimek k rozmotání:

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 — neplatný, chybějící nebo odvolaný API klíč
    System.out.println("Auth failed: " + e.getError());
} catch (RateLimitException e) {
    // HTTP 429 — dosažen limit za minutu
    e.getRetryAfter().ifPresent(s ->
        System.out.println("Retry after: " + s + "s")
    );
} catch (JobFailedException e) {
    // Asynchronní úloha dosáhla chybového stavu nebo vypršel timeout pollingu
    System.out.println("Job " + e.getJobId() + " failed: " + e.getError());
} catch (PolyLingoException e) {
    // Všechny ostatní chyby API
    System.out.println(e.getStatus() + ": " + e.getMessage());
}

RateLimitException.getRetryAfter() vrací Optional<Integer> — je přítomný s počtem sekund čekání, pokud to API zahrnuje, jinak prázdný. JobFailedException.getJobId() vám dává ID neúspěšné úlohy pro logování nebo retry logiku.

---

Poznámky k designu

Několik rozhodnutí, která stojí za to znát, pokud hodnotíte SDK:

Synchronní API. Každá metoda blokuje a vrací výsledek přímo. Žádné Future, CompletableFuture ani reaktivní streamy. Polling úloh je asynchronní příběh SDK pro náročné úlohy — odešlete úlohu, SDK polluje na vašem vlákně a volá váš callback onProgress při aktualizaci pozice ve frontě.

Builder pattern všude. Každý parametrický objekt používá builder. Žádné poziční konstruktory znamenají žádné hádání pořadí argumentů, žádné náhodné prohození polí a čistý kód na místě volání.

Jedna runtime závislost. Jackson pro JSON serializaci. Vše ostatní je standardní knihovna. Žádné OkHttp, Apache HttpClient, Guava.

Java 11+. Používá java.net.http.HttpClient představený v Javě 11. Pokud váš projekt cílí na Javu 8 nebo starší, SDK není kompatibilní.

---

Rychlá reference

Metoda	Endpoint	Vyžaduje autentizaci
client.health()	GET /health	Ne
client.languages()	GET /languages	Ne
client.translate(...)	POST /translate	Ano
client.batch(...)	POST /translate/batch	Ano
client.usage()	GET /usage	Ano
client.jobs().create(...)	POST /jobs	Ano
client.jobs().get(jobId)	GET /jobs/:id	Ano
client.jobs().translate(...)	POST /jobs + polling	Ano

---

Začněte

SDK je na Maven Central na central.sonatype.com/artifact/com.usepolylingo/polylingo. Zdrojový kód a Javadoc jsou na github.com/UsePolyLingo/polylingo-Java. Kompletní dokumentace API je na usepolylingo.com/docs/sdk/java.

Bezplatný tarif zahrnuje 50 000 tokenů měsíčně. Kreditní karta není potřeba.

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

Získejte svůj API klíč