← ব্লগে ফিরে যান
Maven coordinates for the PolyLingo Java SDK alongside a short Java client setup snippet.

PolyLingo SDK দিয়ে জাভা থেকে কাঠামোবদ্ধ সামগ্রী অনুবাদ করুন

By Robert

PolyLingo SDK দিয়ে জাভা থেকে কাঠামোবদ্ধ কনটেন্ট অনুবাদ করুন

PolyLingo Java SDK এখন Maven Central-এ উপলব্ধ। এটি সম্পূর্ণ PolyLingo API কভার করে: সিঙ্ক্রোনাস অনুবাদ, ব্যাচ অনুরোধ, পোলিং সহ অ্যাসিঙ্ক জব, এবং সব ইউটিলিটি এন্ডপয়েন্ট। এটি Java 11 বা তার পরবর্তী সংস্করণ প্রয়োজন, স্ট্যান্ডার্ড লাইব্রেরির HTTP ক্লায়েন্ট ব্যবহার করে, এবং একমাত্র রানটাইম ডিপেন্ডেন্সি: JSON এর জন্য Jackson।

ইনস্টলেশন

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 পুরোপুরি বিল্ডার প্যাটার্ন ব্যবহার করে। কোন পজিশনাল কনস্ট্রাক্টর নেই, কোন ফিল্ড অর্ডার বাধ্যতামূলক নয়। সব ঐচ্ছিক ফিল্ডের বোধগম্য ডিফল্ট আছে, তাই আপনি শুধু যা পরিবর্তন করতে চান তা কনফিগার করবেন।

কনটেন্ট অনুবাদ

একক অনুরোধ

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 API এর বাকি অংশের মতোই কাজ করে। 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);
    }
});

একটি অনুরোধে তিনটি লোকেলই হ্যান্ডেল হয়। প্রতিটি আউটপুট ফাইলে কী গুলো সোর্সের সাথে একই থাকে।

ব্যাচ অনুরোধ

একক অনুরোধে সর্বোচ্চ ১০০টি কনটেন্ট আইটেম পাঠান, প্রতিটির নিজস্ব 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) + "...")
);

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

এরর হ্যান্ডলিং

সব এক্সসেপশন আনচেকড। কোন বাধ্যতামূলক 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() ব্যর্থ জবের আইডি দেয় লগিং বা পুনরায় চেষ্টা করার জন্য।

ডিজাইন নোট

SDK মূল্যায়ন করার সময় কিছু সিদ্ধান্ত জানা ভালো:

সিঙ্ক্রোনাস API। প্রতিটি মেথড ব্লক করে এবং সরাসরি ফলাফল দেয়। কোন Future, CompletableFuture, বা রিয়েক্টিভ স্ট্রিম নেই। জব পোলিং SDK এর অ্যাসিঙ্ক গল্প ভারি কাজের জন্য — জব সাবমিট করুন, SDK আপনার থ্রেডে পোল করে এবং কিউ পজিশন আপডেট হলে onProgress কলব্যাক কল করে।

বিল্ডার প্যাটার্ন সর্বত্র। প্রতিটি প্যারাম অবজেক্ট বিল্ডার ব্যবহার করে। কোন পজিশনাল কনস্ট্রাক্টর নেই মানে আর্গুমেন্ট অর্ডার অনুমান নেই, ভুল ফিল্ড বিনিময় নেই, এবং কল সাইটে পরিষ্কার কোড।

একটি রানটাইম ডিপেন্ডেন্সি। JSON সিরিয়ালাইজেশনের জন্য Jackson। বাকিটা স্ট্যান্ডার্ড লাইব্রেরি। OkHttp, Apache HttpClient, Guava নেই।

Java 11+. Java 11 এ পরিচিত java.net.http.HttpClient ব্যবহার করে। আপনার প্রজেক্ট যদি 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।

ফ্রি টিয়ার প্রতি মাসে ৫০,০০০ টোকেন অন্তর্ভুক্ত করে। কোন ক্রেডিট কার্ড প্রয়োজন নেই।

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

আপনার API কী পান