← ब्लॉग पर वापस जाएं
Maven coordinates for the PolyLingo Java SDK alongside a short Java client setup snippet.

PolyLingo SDK के साथ Java से संरचित सामग्री का अनुवाद करें

By Robert

PolyLingo SDK के साथ Java से संरचित सामग्री का अनुवाद करें

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 11 स्टैंडर्ड लाइब्रेरी से java.net.http.HttpClient का उपयोग करता है।

क्लाइंट सेटअप करना

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

एक अनुरोध सभी तीन लोकल को संभालता है। कुंजियाँ प्रत्येक आउटपुट फ़ाइल में स्रोत के समान होती हैं।

बैच अनुरोध

एकल अनुरोध में 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 असाइन करते हैं वह प्रतिक्रिया में संरक्षित रहता है ताकि आप परिणामों को अपने स्रोत डेटा से बिना क्रम पर निर्भर हुए मैप कर सकें।

असिंक्रोनस जॉब्स

लंबे दस्तावेज़ों या बड़े अनुवाद कार्यभार के लिए jobs 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());

त्रुटि हैंडलिंग

सभी अपवाद अनचेक्ड हैं। कोई मजबूर 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, कोई रिएक्टिव स्ट्रीम्स नहीं। जॉब्स पोलिंग 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 + पोलिंगहाँ

शुरू करें

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 कुंजी प्राप्त करें