PolyLingo SDK ile Java'dan yapılandırılmış içeriği çevirme

PolyLingo Java SDK artık Maven Central'da mevcut. Tam PolyLingo API'sini kapsar: senkron çeviri, toplu istekler, anket ile asenkron işler ve tüm yardımcı uç noktalar. Java 11 veya daha yeni sürüm gerektirir, standart kütüphane HTTP istemcisini kullanır ve yalnızca bir çalışma zamanı bağımlılığı vardır: JSON için Jackson.

Kurulum

Maven

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

Gradle

implementation 'com.usepolylingo:polylingo:0.1.0'

Ek HTTP istemcisi bağımlılığı gerekmez. SDK, Java 11 standart kütüphanesinden java.net.http.HttpClient kullanır.

İstemciyi ayarlama

import com.usepolylingo.polylingo.PolyLingo;

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

İki isteğe bağlı builder parametresi mevcuttur:

PolyLingo client = PolyLingo.builder()
    .apiKey(System.getenv("POLYLINGO_API_KEY"))
    .baseUrl("https://api.usepolylingo.com/v1") // varsayılan, kendi barındırdığınız örnekler için geçersiz kılınabilir
    .timeout(Duration.ofSeconds(30))            // varsayılan 120 saniyedir
    .build();

API anahtarınızı bir ortam değişkeninde tutun. Asla sabit kodlamayın veya sürüm kontrolüne eklemeyin.

SDK, her yerde builder desenini kullanır. Pozisyonel yapıcı yok, zorunlu alan sırası yok. Tüm isteğe bağlı alanların mantıklı varsayılanları vardır, böylece yalnızca gerçekten değiştirmek istediğiniz şeyleri yapılandırırsınız.

İçerik çevirme

Tek istek

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 builder, content ve targets alanlarını zorunlu olarak kabul eder. İsteğe bağlı parametreler arasında format (plain, markdown, json veya html — atlanırsa otomatik algılanır), dil ipucu olarak source ve model olarak standard (varsayılan) veya advanced bulunur.

Format koruma, PolyLingo API'nin geri kalanıyla aynı şekilde çalışır. json içeriği için yalnızca string değerler çevrilir, anahtarlar, iç içe yapılar ve string olmayan türler dokunulmaz bırakılır. markdown için başlıklar başlık olarak kalır ve kod blokları olduğu gibi bırakılır. html için etiketler ve öznitelikler korunur ve yalnızca metin düğümleri çevrilir.

JSON locale dosyası çevirme

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

Tek bir istek üç locale'yi de işler. Anahtarlar her çıktı dosyasında kaynakla aynıdır.

Toplu istekler

Tek bir istekte en fazla 100 içerik öğesi gönderin, her biri kendi id ve isteğe bağlı format ile:

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

Tüm öğeler aynı targets listesini paylaşır. Atadığınız id yanıt içinde korunur, böylece sonuçları kaynak verinize sıraya bağlı kalmadan eşleyebilirsiniz.

Asenkron işler

Uzun belgeler veya büyük çeviri iş yükleri için işler API'si bir istek kabul eder, hemen bir iş kimliği döner ve sonucu sorgulamanıza izin verir. SDK bunu iki şekilde yönetir.

Tamamlanana kadar sorgulayan tek çağrı

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 geri çağrısı her sorgulamada mevcut kuyruk pozisyonu (tam sayı) ile tetiklenir veya API bunu döndürmezse null olur. İlerlemenin kaydını tutmak veya bir kullanıcı arayüzünü güncellemek için kullanın.

Elle kuyruğa alma ve sorgulama

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

// Kendiniz sorgulayın
Job status = client.jobs().get(job.getJobId());
System.out.println(status.getStatus()); // pending / processing / completed / failed

Yardımcı uç noktalar

// API sağlığını kontrol et (API anahtarı gerekmez)
HealthResponse health = client.health();
System.out.println(health.getStatus()); // "ok"

// Desteklenen dilleri listele (API anahtarı gerekmez)
LanguagesResponse langs = client.languages();
langs.getLanguages().forEach(l ->
    System.out.println(l.getCode() + " — " + l.getName())
);

// Geçerli faturalama ayı için token kullanımını kontrol et
UsageResponse usage = client.usage();
System.out.println("Tokens used: " + usage.getUsage().getTokensUsed());
System.out.println("Tokens remaining: " + usage.getUsage().getTokensRemaining());

Hata yönetimi

Tüm istisnalar unchecked'dir. Zorunlu throws bildirimi yok, çözülmesi gereken checked istisna zinciri yok:

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 — geçersiz, eksik veya iptal edilmiş API anahtarı
    System.out.println("Auth failed: " + e.getError());
} catch (RateLimitException e) {
    // HTTP 429 — dakikalık limit aşıldı
    e.getRetryAfter().ifPresent(s ->
        System.out.println("Retry after: " + s + "s")
    );
} catch (JobFailedException e) {
    // Asenkron iş başarısız terminal duruma ulaştı veya sorgulama zaman aşımına uğradı
    System.out.println("Job " + e.getJobId() + " failed: " + e.getError());
} catch (PolyLingoException e) {
    // Diğer tüm API hataları
    System.out.println(e.getStatus() + ": " + e.getMessage());
}

RateLimitException.getRetryAfter() bir Optional<Integer> döner — API bu değeri içeriyorsa beklenmesi gereken saniye sayısı ile dolu, aksi takdirde boş. JobFailedException.getJobId() başarısız işin kimliğini verir, kayıt veya yeniden deneme mantığı için.

Tasarım notları

SDK'yı değerlendiriyorsanız bilmeniz gereken birkaç karar:

Senkron API. Her yöntem engeller ve sonucu doğrudan döner. Future, CompletableFuture, reaktif akışlar yok. İşlerin sorgulanması, ağır iş yükleri için SDK'nın asenkron hikayesidir — işi gönderin, SDK kendi iş parçacığınızda sorgular ve kuyruk pozisyonu güncellendikçe onProgress geri çağrınızı çağırır.

Builder deseni her yerde. Her parametre nesnesi bir builder kullanır. Pozisyonel yapıcı yok, bu da argüman sırasını tahmin etmeyi, yanlışlıkla alan değiş tokuşunu ve çağrı noktasında net kodu engeller.

Tek çalışma zamanı bağımlılığı. JSON serileştirme için Jackson. Diğer her şey standart kütüphane. OkHttp, Apache HttpClient, Guava yok.

Java 11+. Java 11'de tanıtılan java.net.http.HttpClient kullanır. Projeniz Java 8 veya daha eskiyi hedefliyorsa SDK uyumlu değildir.

Hızlı referans

Yöntem	Uç Nokta	Kimlik doğrulama gerekli mi
`client.health()`	GET /health	Hayır
`client.languages()`	GET /languages	Hayır
`client.translate(...)`	POST /translate	Evet
`client.batch(...)`	POST /translate/batch	Evet
`client.usage()`	GET /usage	Evet
`client.jobs().create(...)`	POST /jobs	Evet
`client.jobs().get(jobId)`	GET /jobs/:id	Evet
`client.jobs().translate(...)`	POST /jobs + sorgulama	Evet

Başlarken

SDK, Maven Central'da central.sonatype.com/artifact/com.usepolylingo/polylingo adresinde bulunur. Kaynak kodu ve Javadoc github.com/UsePolyLingo/polylingo-Java adresindedir. Tam API dokümantasyonu usepolylingo.com/docs/sdk/java adresindedir.

Ücretsiz katman ayda 50.000 token içerir. Kredi kartı gerekmez.

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

API anahtarınızı alın

PolyLingo SDK ile Java'dan yapılandırılmış içerik çevirisi