ترجمه محتوای ساختاریافته از جاوا با استفاده از PolyLingo SDK

PolyLingo Java SDK اکنون در Maven Central در دسترس است. این SDK کل API پلی‌لینگو را پوشش می‌دهد: ترجمه همزمان، درخواست‌های دسته‌ای، کارهای ناهمزمان با نظرسنجی، و تمام نقاط انتهایی کمکی. نیازمند جاوا 11 یا بالاتر است، از کلاینت HTTP کتابخانه استاندارد استفاده می‌کند و دقیقاً یک وابستگی زمان اجرا دارد: 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 در کتابخانه استاندارد جاوا 11 استفاده می‌کند.

---

راه‌اندازی کلاینت

import com.usepolylingo.polylingo.PolyLingo;

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

دو پارامتر اختیاری برای builder موجود است:

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!

builder TranslateParams فیلدهای content و targets را به عنوان فیلدهای اجباری می‌پذیرد. پارامترهای اختیاری شامل format (plain، markdown، json یا html — در صورت حذف به صورت خودکار تشخیص داده می‌شود)، source به عنوان نشانه زبان و model به صورت standard (پیش‌فرض) یا advanced است.

حفظ قالب‌بندی همانند بقیه API پلی‌لینگو کار می‌کند. برای محتوای json فقط مقادیر رشته‌ای ترجمه می‌شوند و کلیدها، تو در تو بودن و انواع غیررشته‌ای دست نخورده باقی می‌مانند. برای markdown، سرفصل‌ها به عنوان سرفصل باقی می‌مانند و بلوک‌های کد به صورت عیناً حفظ می‌شوند. برای html، تگ‌ها و ویژگی‌ها حفظ می‌شوند و فقط گره‌های متنی ترجمه می‌شوند.

ترجمه یک فایل 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);
    }
});

یک درخواست همه سه 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 کارها درخواست را می‌پذیرد، بلافاصله با یک شناسه کار بازمی‌گردد و به شما اجازه می‌دهد برای نتیجه نظرسنجی کنید. 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) + "...")
);

callback onProgress در هر نظرسنجی با موقعیت فعلی صف به صورت عدد صحیح فراخوانی می‌شود، یا null اگر API چنین مقداری بازنگرداند. از آن برای ثبت پیشرفت یا به‌روزرسانی رابط کاربری استفاده کنید.

صف‌بندی و نظرسنجی دستی

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، بدون زنجیره استثناهای checked برای باز کردن:

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() شناسه کار شکست خورده را برای ثبت یا منطق تلاش مجدد می‌دهد.

---

نکات طراحی

چند تصمیم که ارزش دانستن دارد اگر در حال ارزیابی SDK هستید:

API همزمان. هر متد مسدود می‌شود و مستقیماً نتیجه را برمی‌گرداند. بدون Future، بدون CompletableFuture، بدون جریان‌های واکنشی. نظرسنجی کارها داستان ناهمزمان SDK برای بارهای کاری سنگین است — کار را ارسال کنید، SDK در رشته شما نظرسنجی می‌کند و callback onProgress شما را هنگام به‌روزرسانی موقعیت صف فراخوانی می‌کند.

الگوی builder در سراسر. هر شیء پارامتر از builder استفاده می‌کند. نبود سازنده موقعیتی یعنی حدس زدن ترتیب آرگومان‌ها نیست، جابجایی تصادفی فیلدها نیست و کد واضح در محل فراخوانی.

یک وابستگی زمان اجرا. Jackson برای سریال‌سازی JSON. بقیه کتابخانه استاندارد است. بدون OkHttp، بدون Apache HttpClient، بدون Guava.

جاوا 11+. از java.net.http.HttpClient که در جاوا 11 معرفی شد استفاده می‌کند. اگر پروژه شما جاوا 8 یا قدیمی‌تر هدف است، SDK سازگار نیست.

---

مرجع سریع

متد	Endpoint	نیاز به احراز هویت
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 خود را دریافت کنید