แปลเนื้อหาแบบมีโครงสร้างจาก Java ด้วย PolyLingo SDK

PolyLingo Java SDK พร้อมให้ใช้งานบน Maven Central แล้ว ครอบคลุม PolyLingo API ทั้งหมด: การแปลแบบซิงโครนัส, คำขอแบบกลุ่ม, งานแบบอะซิงโครนัสพร้อมการตรวจสอบสถานะ และจุดเชื่อมต่อยูทิลิตี้ทั้งหมด ต้องการ Java 11 หรือใหม่กว่า ใช้ไคลเอนต์ HTTP จากไลบรารีมาตรฐาน และมีการพึ่งพา runtime เพียงตัวเดียวคือ Jackson สำหรับ JSON

---

การติดตั้ง

Maven

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

Gradle

implementation 'com.usepolylingo:polylingo:0.1.0'

ไม่ต้องการการพึ่งพาไคลเอนต์ HTTP เพิ่มเติม SDK ใช้ java.net.http.HttpClient จากไลบรารีมาตรฐาน Java 11

---

การตั้งค่าไคลเอนต์

import com.usepolylingo.polylingo.PolyLingo;

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

มีพารามิเตอร์ตัวสร้างแบบเลือกได้สองตัว:

PolyLingo client = PolyLingo.builder()
    .apiKey(System.getenv("POLYLINGO_API_KEY"))
    .baseUrl("https://api.usepolylingo.com/v1") // ค่าเริ่มต้น, เปลี่ยนสำหรับอินสแตนซ์ที่โฮสต์เอง
    .timeout(Duration.ofSeconds(30))            // ค่าเริ่มต้นคือ 120 วินาที
    .build();

เก็บคีย์ API ของคุณในตัวแปรแวดล้อม ห้ามเขียนคีย์ลงในโค้ดโดยตรงหรือคอมมิตลงในระบบควบคุมเวอร์ชัน

SDK ใช้รูปแบบ builder ตลอด ไม่มีตัวสร้างตำแหน่ง ไม่มีลำดับฟิลด์ที่ต้องกำหนด ฟิลด์เลือกทั้งหมดมีค่าเริ่มต้นที่เหมาะสม ดังนั้นคุณจึงกำหนดค่าเฉพาะสิ่งที่ต้องการเปลี่ยนแปลงจริงๆ

---

การแปลเนื้อหา

คำขอเดียว

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!

ตัวสร้าง TranslateParams รับ content และ targets เป็นฟิลด์ที่ต้องระบุ พารามิเตอร์เลือกได้รวมถึง format (plain, markdown, json หรือ html — ตรวจจับอัตโนมัติถ้าไม่ระบุ), source เป็นคำใบ้ภาษา และ model เป็น standard (ค่าเริ่มต้น) หรือ advanced

การรักษารูปแบบทำงานเหมือนกับ API PolyLingo อื่นๆ สำหรับเนื้อหา json จะแปลเฉพาะค่าข้อความเท่านั้น ส่วนคีย์, การซ้อน, และชนิดข้อมูลที่ไม่ใช่ข้อความจะไม่ถูกแตะต้อง สำหรับ markdown หัวข้อยังคงเป็นหัวข้อและบล็อกโค้ดยังคงเหมือนเดิม สำหรับ html แท็กและแอตทริบิวต์จะถูกเก็บไว้และแปลเฉพาะโหนดข้อความ

การแปลไฟล์ JSON locale

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

คำขอเดียวจัดการ locale ทั้งสามไฟล์ คีย์เหมือนกับต้นฉบับในทุกไฟล์ผลลัพธ์

---

คำขอแบบกลุ่ม

ส่งเนื้อหาสูงสุด 100 รายการในคำขอเดียว แต่ละรายการมี id ของตัวเองและ 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());
}

รายการทั้งหมดใช้รายการ targets เดียวกัน id ที่คุณกำหนดจะถูกเก็บไว้ในคำตอบเพื่อให้คุณแมปผลลัพธ์กลับไปยังข้อมูลต้นทางโดยไม่ต้องพึ่งพาลำดับ

---

งานแบบอะซิงโครนัส

สำหรับเอกสารยาวหรือภาระงานแปลขนาดใหญ่ API งานรับคำขอ, ส่งกลับทันทีพร้อม ID งาน และให้คุณตรวจสอบผลลัพธ์ได้ SDK จัดการสองวิธี

การเรียกครั้งเดียวที่ตรวจสอบจนเสร็จ

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 จะถูกเรียกในแต่ละรอบตรวจสอบพร้อมตำแหน่งคิวปัจจุบันเป็นจำนวนเต็ม หรือ null หาก API ไม่ส่งกลับ ใช้เพื่อล็อกความคืบหน้าหรืออัปเดต UI

การเข้าคิวและตรวจสอบด้วยตนเอง

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

// ตรวจสอบสถานะด้วยตัวเอง
Job status = client.jobs().get(job.getJobId());
System.out.println(status.getStatus()); // pending / processing / completed / failed

---

จุดเชื่อมต่อยูทิลิตี้

// ตรวจสอบสถานะ API (ไม่ต้องใช้คีย์ API)
HealthResponse health = client.health();
System.out.println(health.getStatus()); // "ok"

// แสดงรายการภาษาที่รองรับ (ไม่ต้องใช้คีย์ API)
LanguagesResponse langs = client.languages();
langs.getLanguages().forEach(l ->
    System.out.println(l.getCode() + " — " + l.getName())
);

// ตรวจสอบการใช้โทเค็นสำหรับเดือนเรียกเก็บเงินปัจจุบัน
UsageResponse usage = client.usage();
System.out.println("Tokens used: " + usage.getUsage().getTokensUsed());
System.out.println("Tokens remaining: " + usage.getUsage().getTokensRemaining());

---

การจัดการข้อผิดพลาด

ข้อยกเว้นทั้งหมดเป็นแบบ unchecked ไม่มีการประกาศ throws บังคับ ไม่มีโซ่ข้อยกเว้นที่ต้องจัดการ:

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 — คีย์ API ไม่ถูกต้อง, ขาด หรือถูกเพิกถอน
    System.out.println("Auth failed: " + e.getError());
} catch (RateLimitException e) {
    // HTTP 429 — ถึงขีดจำกัดต่อหนึ่งนาที
    e.getRetryAfter().ifPresent(s ->
        System.out.println("Retry after: " + s + "s")
    );
} catch (JobFailedException e) {
    // งานอะซิงโครนัสถึงสถานะล้มเหลวหรือหมดเวลาตรวจสอบ
    System.out.println("Job " + e.getJobId() + " failed: " + e.getError());
} catch (PolyLingoException e) {
    // ข้อผิดพลาด API อื่นๆ ทั้งหมด
    System.out.println(e.getStatus() + ": " + e.getMessage());
}

RateLimitException.getRetryAfter() คืนค่า Optional<Integer> — มีค่าเป็นจำนวนวินาทีที่ต้องรอถ้า API ส่งค่ามา, ว่างถ้าไม่มี JobFailedException.getJobId() ให้ ID ของงานที่ล้มเหลวสำหรับการบันทึกหรือการลองใหม่

---

หมายเหตุการออกแบบ

มีการตัดสินใจบางอย่างที่ควรรู้ถ้าคุณกำลังประเมิน SDK:

API แบบซิงโครนัส. ทุกเมธอดบล็อกและคืนค่าผลลัพธ์โดยตรง ไม่มี Future, ไม่มี CompletableFuture, ไม่มี reactive streams การตรวจสอบงานเป็นเรื่องอะซิงโครนัสของ SDK สำหรับภาระงานหนัก — ส่งงาน, SDK ตรวจสอบบนเธรดของคุณและเรียกคอลแบ็ก onProgress เมื่อมีการอัปเดตตำแหน่งคิว

รูปแบบ builder ตลอด. ทุกอ็อบเจ็กต์พารามิเตอร์ใช้ builder ไม่มีตัวสร้างตำแหน่ง หมายความว่าไม่ต้องเดาลำดับอาร์กิวเมนต์ ไม่มีการสลับฟิลด์โดยไม่ตั้งใจ และโค้ดชัดเจนที่จุดเรียกใช้

การพึ่งพา runtime เพียงตัวเดียว. Jackson สำหรับการซีเรียลไลซ์ JSON ทุกอย่างอื่นเป็นไลบรารีมาตรฐาน ไม่มี OkHttp, ไม่มี Apache HttpClient, ไม่มี Guava

Java 11+. ใช้ java.net.http.HttpClient ที่เพิ่มเข้ามาใน Java 11 ถ้าโปรเจกต์ของคุณเป้าหมาย Java 8 หรือต่ำกว่า SDK จะไม่เข้ากัน

---

อ้างอิงด่วน

วิธีการ	จุดเชื่อมต่อ	ต้องใช้การยืนยันตัวตน
client.health()	GET /health	ไม่
client.languages()	GET /languages	ไม่
client.translate(...)	POST /translate	ใช่
client.batch(...)	POST /translate/batch	ใช่
client.usage()	GET /usage	ใช่
client.jobs().create(...)	POST /jobs	ใช่
client.jobs().get(jobId)	GET /jobs/:id	ใช่
client.jobs().translate(...)	POST /jobs + polling	ใช่

---

เริ่มต้น

SDK อยู่บน Maven Central ที่ central.sonatype.com/artifact/com.usepolylingo/polylingo โค้ดต้นฉบับและ Javadoc อยู่ที่ github.com/UsePolyLingo/polylingo-Java เอกสาร API เต็มรูปแบบอยู่ที่ usepolylingo.com/docs/sdk/java

ระดับฟรีรวม 50,000 โทเค็นต่อเดือน ไม่ต้องใช้บัตรเครดิต

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

รับคีย์ API ของคุณ