Menerjemahkan konten terstruktur dari Java dengan PolyLingo SDK

PolyLingo Java SDK sekarang tersedia di Maven Central. SDK ini mencakup seluruh API PolyLingo: terjemahan sinkron, permintaan batch, pekerjaan async dengan polling, dan semua endpoint utilitas. SDK ini membutuhkan Java 11 atau lebih baru, menggunakan klien HTTP dari pustaka standar, dan memiliki tepat satu dependensi runtime: Jackson untuk JSON.

Instalasi

Maven

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

Gradle

implementation 'com.usepolylingo:polylingo:0.1.0'

Tidak diperlukan dependensi klien HTTP tambahan. SDK menggunakan java.net.http.HttpClient dari pustaka standar Java 11.

Menyiapkan klien

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

Dua parameter builder opsional tersedia:

PolyLingo client = PolyLingo.builder()
    .apiKey(System.getenv("POLYLINGO_API_KEY"))
    .baseUrl("https://api.usepolylingo.com/v1") // default, ganti untuk instance self-hosted
    .timeout(Duration.ofSeconds(30))            // default adalah 120 detik
    .build();

Simpan kunci API Anda di variabel lingkungan. Jangan pernah menuliskannya secara langsung atau meng-commit ke kontrol versi.

SDK menggunakan pola builder secara menyeluruh. Tidak ada konstruktor posisi, tidak ada urutan field yang wajib. Semua field opsional memiliki nilai default yang masuk akal sehingga Anda hanya mengonfigurasi apa yang benar-benar perlu diubah.

Menerjemahkan konten

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!

Builder TranslateParams menerima content dan targets sebagai field wajib. Parameter opsional termasuk format (plain, markdown, json, atau html — terdeteksi otomatis jika dihilangkan), source sebagai petunjuk bahasa, dan model sebagai standard (default) atau advanced.

Preservasi format bekerja sama seperti API PolyLingo lainnya. Untuk konten json, hanya nilai string yang diterjemahkan dan kunci, penempatan, serta tipe non-string dibiarkan tidak berubah. Untuk markdown, heading tetap heading dan blok kode dibiarkan verbatim. Untuk html, tag dan atribut dipertahankan dan hanya node teks yang diterjemahkan.

Menerjemahkan file 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 menangani ketiga locale sekaligus. Kunci identik dengan sumber di setiap file output.

Permintaan batch

Kirim hingga 100 item konten dalam satu permintaan, masing-masing dengan id dan format opsional:

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 berbagi daftar targets yang sama. id yang Anda tetapkan dipertahankan dalam respons sehingga Anda dapat memetakan hasil kembali ke data sumber tanpa bergantung pada urutan.

Pekerjaan Async

Untuk dokumen panjang atau beban kerja terjemahan besar, API pekerjaan menerima permintaan, mengembalikan segera dengan ID pekerjaan, dan memungkinkan Anda melakukan polling untuk hasilnya. SDK menangani ini dengan dua cara.

Satu panggilan yang melakukan polling sampai 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) + "...")
);

Callback onProgress dipanggil pada setiap polling dengan posisi antrean saat ini sebagai integer, atau null jika API tidak mengembalikannya. Gunakan untuk mencatat kemajuan atau memperbarui UI.

Mengantri 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

Endpoint utilitas

// Periksa kesehatan API (tidak perlu kunci API)
HealthResponse health = client.health();
System.out.println(health.getStatus()); // "ok"
 
// Daftar bahasa yang didukung (tidak perlu kunci API)
LanguagesResponse langs = client.languages();
langs.getLanguages().forEach(l ->
    System.out.println(l.getCode() + " — " + l.getName())
);
 
// Periksa penggunaan token untuk bulan tagihan saat ini
UsageResponse usage = client.usage();
System.out.println("Tokens used: " + usage.getUsage().getTokensUsed());
System.out.println("Tokens remaining: " + usage.getUsage().getTokensRemaining());

Penanganan error

Semua pengecualian tidak diperiksa. Tidak ada deklarasi throws yang dipaksa, tidak ada rantai pengecualian yang harus diurai:

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 valid, hilang, atau dicabut
    System.out.println("Auth failed: " + e.getError());
} catch (RateLimitException e) {
    // HTTP 429 — batas per menit tercapai
    e.getRetryAfter().ifPresent(s ->
        System.out.println("Retry after: " + s + "s")
    );
} catch (JobFailedException e) {
    // Pekerjaan async mencapai status terminal gagal atau polling timeout
    System.out.println("Job " + e.getJobId() + " failed: " + e.getError());
} catch (PolyLingoException e) {
    // Semua error API lainnya
    System.out.println(e.getStatus() + ": " + e.getMessage());
}

RateLimitException.getRetryAfter() mengembalikan Optional<Integer> — ada dengan jumlah detik untuk menunggu jika API menyertakan nilai tersebut, kosong jika tidak. JobFailedException.getJobId() memberi Anda ID pekerjaan yang gagal untuk pencatatan atau logika retry.

Catatan desain

Beberapa keputusan penting yang perlu diketahui jika Anda mengevaluasi SDK:

API sinkron. Setiap metode memblokir dan mengembalikan hasil langsung. Tidak ada Future, CompletableFuture, atau reactive streams. Polling pekerjaan adalah cerita async SDK untuk beban kerja berat — kirim pekerjaan, SDK melakukan polling di thread Anda dan memanggil callback onProgress saat posisi antrean diperbarui.

Pola builder secara menyeluruh. Setiap objek params menggunakan builder. Tidak ada konstruktor posisi berarti tidak perlu menebak urutan argumen, tidak ada pertukaran field tidak sengaja, dan kode jelas di tempat pemanggilan.

Satu dependensi runtime. Jackson untuk serialisasi JSON. Semua lainnya dari pustaka standar. Tidak ada OkHttp, Apache HttpClient, atau Guava.

Java 11+. Menggunakan java.net.http.HttpClient yang diperkenalkan di Java 11. Jika proyek Anda menargetkan Java 8 atau lebih lama, SDK tidak kompatibel.

Referensi cepat

Metode	Endpoint	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

Memulai

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

Tingkat gratis mencakup 50.000 token per bulan. Tidak perlu kartu kredit.

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

Dapatkan kunci API Anda

Terjemahkan konten terstruktur dari Java dengan PolyLingo SDK