← 返回博客
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("写入 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 会在响应中保留，方便您将结果映射回源数据，无需依赖顺序。

异步作业

对于长文档或大规模翻译工作量，作业 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("队列位置: " + queuePosition))
        .build()
);

result.getTranslations().forEach((lang, text) ->
    System.out.println(lang + ": " + text.substring(0, 100) + "...")
);

onProgress 回调在每次轮询时触发，传入当前队列位置（整数），如果 API 未返回则为 null。可用于记录进度或更新 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("已用令牌数: " + usage.getUsage().getTokensUsed());
System.out.println("剩余令牌数: " + 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("认证失败: " + e.getError());
} catch (RateLimitException e) {
    // HTTP 429 — 达到每分钟限制
    e.getRetryAfter().ifPresent(s ->
        System.out.println("请在 " + s + " 秒后重试")
    );
} catch (JobFailedException e) {
    // 异步作业达到失败终态或轮询超时
    System.out.println("作业 " + e.getJobId() + " 失败: " + 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 密钥