Käännä jäsennelty sisältö Javalla PolyLingo SDK:n avulla

PolyLingo Java SDK on nyt saatavilla Maven Centralissa. Se kattaa koko PolyLingo API:n: synkronisen käännöksen, eräpyynnöt, asynkroniset työt kyselyllä ja kaikki apupäätepisteet. Se vaatii Java 11:n tai uudemman, käyttää standardikirjaston HTTP-asiakasta ja sillä on tarkalleen yksi ajonaikainen riippuvuus: Jackson JSON:lle.

Asennus

Maven

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

Gradle

implementation 'com.usepolylingo:polylingo:0.1.0'

Lisä-HTTP-asiakasriippuvuutta ei tarvita. SDK käyttää java.net.http.HttpClient Java 11:n standardikirjastosta.

Asiakkaan määrittäminen

import com.usepolylingo.polylingo.PolyLingo;

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

Kaksi valinnaista rakentajaparametria on saatavilla:

PolyLingo client = PolyLingo.builder()
    .apiKey(System.getenv("POLYLINGO_API_KEY"))
    .baseUrl("https://api.usepolylingo.com/v1") // oletus, ylikirjoita itseisännöidyissä instansseissa
    .timeout(Duration.ofSeconds(30))            // oletus on 120 sekuntia
    .build();

Pidä API-avaimesi ympäristömuuttujassa. Älä koskaan kovakoodaa sitä tai tallenna versionhallintaan.

SDK käyttää rakentajamallia kauttaaltaan. Ei paikkaan sidottuja konstruktoreita, ei vaadittua kenttien järjestystä. Kaikilla valinnaisilla kentillä on järkevät oletusarvot, joten konfiguroit vain ne asiat, jotka todella haluat muuttaa.

Sisällön kääntäminen

Yksi pyyntö

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-rakentaja hyväksyy content ja targets vaadittuina kenttinä. Valinnaisia parametreja ovat format (plain, markdown, json tai html — automaattisesti tunnistettu jos jätetään pois), source kielivihjeenä ja model joko standard (oletus) tai advanced.

Muodon säilytys toimii kuten muuallakin PolyLingo API:ssa. json-sisällössä vain merkkijonoarvot käännetään, avaimet, sisäkkäisyys ja ei-merkkijonotyypit jätetään koskemattomiksi. markdown-sisällössä otsikot pysyvät otsikoina ja koodilohkot jätetään sellaisiksi kuin ovat. html-sisällössä tagit ja attribuutit säilytetään ja vain tekstisolmut käännetään.

JSON-lokalisointitiedoston kääntäminen

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

Yksi pyyntö käsittelee kaikki kolme lokalisointia. Avaimet ovat identtiset lähteen kanssa kaikissa tulostiedostoissa.

Eräpyynnöt

Lähetä jopa 100 sisältöä yhdellä pyynnöllä, jokaisella oma id ja valinnainen 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());
}

Kaikilla kohteilla on sama targets-lista. Määrittämäsi id säilyy vastauksessa, joten voit yhdistää tulokset lähdetietoihisi ilman, että täytyy luottaa järjestykseen.

Asynkroniset työt

Pitkille dokumenteille tai suurille käännösmäärille jobs API hyväksyy pyynnön, palauttaa heti työn ID:n ja antaa sinun kysellä tulosta. SDK hoitaa tämän kahdella tavalla.

Yksi kutsu, joka kysyy kunnes valmis

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-takaisinkutsu laukeaa jokaisella kyselyllä nykyisellä jonopaikalla kokonaislukuna tai null jos API ei palauta sitä. Käytä sitä edistymisen kirjaamiseen tai käyttöliittymän päivittämiseen.

Jonoon laittaminen ja kysely manuaalisesti

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

// Kysy itse
Job status = client.jobs().get(job.getJobId());
System.out.println(status.getStatus()); // pending / processing / completed / failed

Apupäätepisteet

// Tarkista API:n tila (ei vaadi API-avainta)
HealthResponse health = client.health();
System.out.println(health.getStatus()); // "ok"

// Listaa tuetut kielet (ei vaadi API-avainta)
LanguagesResponse langs = client.languages();
langs.getLanguages().forEach(l ->
    System.out.println(l.getCode() + " — " + l.getName())
);

// Tarkista tokenien käyttö nykyiseltä laskutuskuukaudelta
UsageResponse usage = client.usage();
System.out.println("Tokens used: " + usage.getUsage().getTokensUsed());
System.out.println("Tokens remaining: " + usage.getUsage().getTokensRemaining());

Virheenkäsittely

Kaikki poikkeukset ovat tarkistamattomia. Ei pakollisia throws-määrityksiä, ei tarkistettavia poikkeusketjuja purkamaan:

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 — virheellinen, puuttuva tai peruutettu API-avain
    System.out.println("Auth failed: " + e.getError());
} catch (RateLimitException e) {
    // HTTP 429 — minuuttikohtainen raja saavutettu
    e.getRetryAfter().ifPresent(s ->
        System.out.println("Retry after: " + s + "s")
    );
} catch (JobFailedException e) {
    // Asynkroninen työ saavutti epäonnistuneen lopputilan tai kysely aikakatkaistiin
    System.out.println("Job " + e.getJobId() + " failed: " + e.getError());
} catch (PolyLingoException e) {
    // Kaikki muut API-virheet
    System.out.println(e.getStatus() + ": " + e.getMessage());
}

RateLimitException.getRetryAfter() palauttaa Optional<Integer> — läsnä oleva, jos API sisältää odotusajan sekunteina, muuten tyhjä. JobFailedException.getJobId() antaa epäonnistuneen työn ID:n lokitusta tai uudelleenyritystä varten.

Suunnittelumuistiinpanot

Muutama päätös, jotka on hyvä tietää SDK:ta arvioidessa:

Synkroninen API. Jokainen metodi estää ja palauttaa tuloksen suoraan. Ei Futurea, ei CompletableFuturea, ei reaktiovirtoja. Jobs-kysely on SDK:n asynkroninen ratkaisu raskaalle kuormalle — lähetä työ, SDK kysyy omalla säikeelläsi ja kutsuu onProgress-takaisinkutsua jonopaikan päivittyessä.

Rakentajamalli kauttaaltaan. Jokainen parametriobjekti käyttää rakentajaa. Ei paikkaan sidottuja konstruktoreita tarkoittaa, ettei tarvitse arvata argumenttien järjestystä, ei vahingossa vaihdu kenttiä ja koodi kutsupaikassa on selkeää.

Yksi ajonaikainen riippuvuus. Jackson JSON-sarjallistukseen. Kaikki muu on standardikirjastoa. Ei OkHttp:ta, ei Apache HttpClientiä, ei Guavaa.

Java 11+. Käyttää java.net.http.HttpClient-luokkaa, joka esiteltiin Javassa 11. Jos projektisi kohdekieli on Java 8 tai aiempi, SDK ei ole yhteensopiva.

Pikaviite

Metodi	Päätepiste	Tarvitseeko autentikoinnin
`client.health()`	GET /health	Ei
`client.languages()`	GET /languages	Ei
`client.translate(...)`	POST /translate	Kyllä
`client.batch(...)`	POST /translate/batch	Kyllä
`client.usage()`	GET /usage	Kyllä
`client.jobs().create(...)`	POST /jobs	Kyllä
`client.jobs().get(jobId)`	GET /jobs/:id	Kyllä
`client.jobs().translate(...)`	POST /jobs + kysely	Kyllä

Aloita

SDK on Maven Centralissa osoitteessa central.sonatype.com/artifact/com.usepolylingo/polylingo. Lähdekoodi ja Javadoc löytyvät osoitteesta github.com/UsePolyLingo/polylingo-Java. Täydellinen API-dokumentaatio on osoitteessa usepolylingo.com/docs/sdk/java.

Ilmainen taso sisältää 50 000 tokenia kuukaudessa. Ei luottokorttia vaadita.

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

Hanki API-avaimesi

Käännä jäsennelty sisältö Javasta PolyLingo SDK:lla