Terjemah kandungan berstruktur dari Java dengan PolyLingo SDK

PolyLingo Java SDK kini tersedia di Maven Central. Ia merangkumi keseluruhan API PolyLingo: terjemahan segerak, permintaan kelompok, kerja async dengan polling, dan semua titik akhir utiliti. Ia memerlukan Java 11 atau lebih baru, menggunakan klien HTTP perpustakaan standard, dan mempunyai tepat satu kebergantungan runtime: Jackson untuk JSON.

---

Pemasangan

Maven

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

Gradle

implementation 'com.usepolylingo:polylingo:0.1.0'

Tiada kebergantungan klien HTTP tambahan diperlukan. SDK menggunakan java.net.http.HttpClient dari perpustakaan standard Java 11.

---

Menyediakan klien

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

Dua parameter pembina pilihan tersedia:

PolyLingo client = PolyLingo.builder()
    .apiKey(System.getenv("POLYLINGO_API_KEY"))
    .baseUrl("https://api.usepolylingo.com/v1") // lalai, ganti untuk instans sendiri
    .timeout(Duration.ofSeconds(30))            // lalai ialah 120 saat
    .build();

Simpan kunci API anda dalam pembolehubah persekitaran. Jangan sekali-kali menulis keras atau komit ke kawalan versi.

SDK menggunakan corak pembina sepanjang masa. Tiada konstruktor posisi, tiada susunan medan wajib. Semua medan pilihan mempunyai nilai lalai yang munasabah supaya anda hanya mengkonfigurasi apa yang anda benar-benar perlu ubah.

---

Menterjemah kandungan

Permintaan tunggal

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!

Pembina TranslateParams menerima content dan targets sebagai medan wajib. Parameter pilihan termasuk format (plain, markdown, json, atau html — dikesan automatik jika diabaikan), source sebagai petunjuk bahasa, dan model sama ada standard (lalai) atau advanced.

Pemeliharaan format berfungsi sama seperti API PolyLingo yang lain. Untuk kandungan json, hanya nilai rentetan diterjemah dan kunci, penempatan, dan jenis bukan rentetan dibiarkan tidak disentuh. Untuk markdown, tajuk kekal sebagai tajuk dan blok kod dibiarkan secara verbatim. Untuk html, tag dan atribut dipelihara dan hanya nod teks diterjemah.

Menterjemah fail locale JSON

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

Satu permintaan mengendalikan ketiga-tiga locale. Kunci adalah sama dengan sumber dalam setiap fail output.

---

Permintaan kelompok

Hantar sehingga 100 item kandungan dalam satu permintaan, setiap satu dengan id sendiri dan format pilihan:

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

Semua item berkongsi senarai targets yang sama. id yang anda tetapkan dipelihara dalam respons supaya anda boleh memetakan hasil kembali ke data sumber anda tanpa bergantung pada susunan.

---

Kerja async

Untuk dokumen panjang atau beban kerja terjemahan besar, API kerja menerima permintaan, kembali segera dengan ID kerja, dan membolehkan anda melakukan polling untuk hasil. SDK mengendalikan ini dengan dua cara.

Satu panggilan yang melakukan polling sehingga selesai

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

Panggilan balik onProgress dipanggil pada setiap polling dengan kedudukan antrian semasa sebagai integer, atau null jika API tidak mengembalikannya. Gunakan untuk merekod kemajuan atau mengemas kini UI.

Antrikan dan polling secara manual

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

---

Titik akhir utiliti

// Semak kesihatan API (tiada kunci API diperlukan)
HealthResponse health = client.health();
System.out.println(health.getStatus()); // "ok"
 
// Senaraikan bahasa yang disokong (tiada kunci API diperlukan)
LanguagesResponse langs = client.languages();
langs.getLanguages().forEach(l ->
    System.out.println(l.getCode() + " — " + l.getName())
);
 
// Semak penggunaan token untuk bulan bil semasa
UsageResponse usage = client.usage();
System.out.println("Tokens used: " + usage.getUsage().getTokensUsed());
System.out.println("Tokens remaining: " + usage.getUsage().getTokensRemaining());

---

Pengendalian ralat

Semua pengecualian tidak diperiksa. Tiada deklarasi throws dipaksa, tiada rantai pengecualian diperiksa untuk dibongkar:

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 — kunci API tidak sah, hilang, atau dibatalkan
    System.out.println("Auth failed: " + e.getError());
} catch (RateLimitException e) {
    // HTTP 429 — had per minit dicapai
    e.getRetryAfter().ifPresent(s ->
        System.out.println("Retry after: " + s + "s")
    );
} catch (JobFailedException e) {
    // Kerja async mencapai status terminal gagal atau polling tamat masa
    System.out.println("Job " + e.getJobId() + " failed: " + e.getError());
} catch (PolyLingoException e) {
    // Semua ralat API lain
    System.out.println(e.getStatus() + ": " + e.getMessage());
}

RateLimitException.getRetryAfter() mengembalikan Optional<Integer> — hadir dengan bilangan saat untuk menunggu jika API menyertakan nilai itu, kosong jika tidak. JobFailedException.getJobId() memberi anda ID kerja yang gagal untuk log atau logik cuba semula.

---

Nota reka bentuk

Beberapa keputusan yang patut diketahui jika anda menilai SDK:

API segerak. Setiap kaedah menyekat dan mengembalikan hasil secara langsung. Tiada Future, tiada CompletableFuture, tiada aliran reaktif. Polling kerja adalah cerita async SDK untuk beban kerja berat — hantar kerja, SDK melakukan polling pada thread anda dan memanggil panggilan balik onProgress anda apabila kedudukan antrian dikemas kini.

Corak pembina sepanjang masa. Setiap objek params menggunakan pembina. Tiada konstruktor posisi bermakna tiada tekaan susunan argumen, tiada pertukaran medan tidak sengaja, dan kod jelas di tapak panggilan.

Satu kebergantungan runtime. Jackson untuk serialisasi JSON. Semua yang lain adalah perpustakaan standard. Tiada OkHttp, tiada Apache HttpClient, tiada Guava.

Java 11+. Menggunakan java.net.http.HttpClient yang diperkenalkan dalam Java 11. Jika projek anda mensasarkan Java 8 atau lebih awal, SDK tidak serasi.

---

Rujukan pantas

Kaedah	Titik akhir	Perlu Auth
client.health()	GET /health	Tidak
client.languages()	GET /languages	Tidak
client.translate(...)	POST /translate	Ya
client.batch(...)	POST /translate/batch	Ya
client.usage()	GET /usage	Ya
client.jobs().create(...)	POST /jobs	Ya
client.jobs().get(jobId)	GET /jobs/:id	Ya
client.jobs().translate(...)	POST /jobs + polling	Ya

---

Mula

SDK ada di Maven Central di central.sonatype.com/artifact/com.usepolylingo/polylingo. Kod sumber dan Javadoc ada di github.com/UsePolyLingo/polylingo-Java. Dokumentasi API penuh ada di usepolylingo.com/docs/sdk/java.

Tier percuma termasuk 50,000 token sebulan. Tiada kad kredit diperlukan.

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

Dapatkan kunci API anda