ترجمة المحتوى المهيكل من جافا باستخدام PolyLingo SDK

تتوفر الآن مكتبة PolyLingo Java SDK على Maven Central. تغطي كامل واجهة برمجة تطبيقات PolyLingo: الترجمة المتزامنة، طلبات الدُفعات، الوظائف غير المتزامنة مع الاستطلاع، وجميع نقاط النهاية المساعدة. تتطلب جافا 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. تستخدم المكتبة java.net.http.HttpClient من مكتبة جافا 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 في متغير بيئة. لا تقم بكتابته مباشرة أو الالتزام به في نظام التحكم بالإصدارات.

تستخدم المكتبة نمط الباني في كل مكان. لا توجد منشئات موضعية، ولا ترتيب حقول مطلوب. جميع الحقول الاختيارية لها قيم افتراضية معقولة بحيث تقوم بتكوين ما تحتاج فقط.

---

ترجمة المحتوى

طلب واحد

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.

يحافظ التنسيق على نفس طريقة عمل باقي واجهة برمجة تطبيقات PolyLingo. بالنسبة لمحتوى json، تُترجم القيم النصية فقط وتُترك المفاتيح والتداخل والأنواع غير النصية دون تغيير. بالنسبة لـ markdown، تبقى العناوين كما هي وتُترك كتل الشيفرة كما هي. بالنسبة لـ html، تُحفظ العلامات والسمات ويُترجم فقط نص العقد.

ترجمة ملف لغة 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);
    }
});

يتعامل طلب واحد مع جميع اللغات الثلاث. المفاتيح متطابقة مع المصدر في كل ملف إخراج.

---

طلبات الدُفعات

أرسل حتى 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 الذي تعينه في الاستجابة بحيث يمكنك ربط النتائج ببيانات المصدر دون الاعتماد على الترتيب.

---

الوظائف غير المتزامنة

للمستندات الطويلة أو أحمال الترجمة الكبيرة، تقبل واجهة برمجة التطبيقات للوظائف طلبًا، وتُرجع فورًا معرف وظيفة، وتتيح لك الاستطلاع عن النتيجة. تتعامل المكتبة مع هذا بطريقتين.

مكالمة واحدة تستطلع حتى الانتهاء

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 إذا لم تُرجع الواجهة ذلك. استخدمه لتسجيل التقدم أو تحديث واجهة المستخدم.

الإضافة إلى الطابور والاستطلاع يدويًا

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

---

التعامل مع الأخطاء

جميع الاستثناءات غير مفحوصة. لا توجد إعلانات 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> — موجودة مع عدد الثواني للانتظار إذا شملتها الواجهة، فارغة خلاف ذلك. JobFailedException.getJobId() تعطيك معرف الوظيفة الفاشلة للتسجيل أو منطق إعادة المحاولة.

---

ملاحظات التصميم

بعض القرارات التي تستحق المعرفة إذا كنت تقيم المكتبة:

واجهة برمجة تطبيقات متزامنة. كل طريقة تحظر وتُرجع نتيجة مباشرة. لا Future، لا CompletableFuture، لا تدفقات تفاعلية. الاستطلاع للوظائف هو قصة المكتبة غير المتزامنة لأحمال العمل الثقيلة — قدم الوظيفة، تستطلع المكتبة على خيطك وتستدعي رد الاتصال onProgress مع تحديث موضع الطابور.

نمط الباني في كل مكان. كل كائن معلمات يستخدم باني. لا منشئات موضعية تعني لا تخمين لترتيب الوسائط، لا تبديل حقول عرضي، وكود واضح في موقع الاستدعاء.

اعتماد وقت تشغيل واحد. Jackson لتسلسل JSON. كل شيء آخر من المكتبة القياسية. لا OkHttp، لا Apache HttpClient، لا Guava.

جافا 11+. تستخدم java.net.http.HttpClient التي تم تقديمها في جافا 11. إذا كان مشروعك يستهدف جافا 8 أو أقدم، المكتبة غير متوافقة.

---

مرجع سريع

الطريقة	نقطة النهاية	يتطلب مصادقة
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	نعم

---

البدء

المكتبة متوفرة على Maven Central في central.sonatype.com/artifact/com.usepolylingo/polylingo. الشيفرة المصدرية وJavadoc على github.com/UsePolyLingo/polylingo-Java. التوثيق الكامل للواجهة على usepolylingo.com/docs/sdk/java.

الطبقة المجانية تشمل 50,000 رمز شهريًا. لا حاجة لبطاقة ائتمان.

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

احصل على مفتاح API الخاص بك