Go SDK (polylingo)

Official Go client for the PolyLingo REST API. Uses only the standard library (net/http + encoding/json) — no third-party dependencies.

• Module: github.com/UsePolyLingo/polylingo-go/polylingo
• Source: UsePolyLingo/polylingo-go

For raw HTTP details, see API reference.

Installation

go get github.com/UsePolyLingo/polylingo-go/polylingo@v0.1.0

Go: >= 1.21

Constructor

client, err := polylingo.New(polylingo.Options{
    APIKey:  os.Getenv("POLYLINGO_API_KEY"), // required
    BaseURL: "https://api.usepolylingo.com/v1", // optional; this is the default
    Timeout: 120 * time.Second,                // optional; HTTP client timeout per request (default 120s)
})
if err != nil {
    log.Fatal(err)
}

Every method takes context.Context as the first argument.

Methods

client.Health(ctx)

GET /health

h, err := client.Health(ctx)
// h.Status, h.Timestamp

client.Languages(ctx)

GET /languages

data, err := client.Languages(ctx)
// data.Languages

client.Translate(ctx, params)

POST /translate

r, err := client.Translate(ctx, polylingo.TranslateParams{
    Content: "# Hello",
    Targets: []string{"es", "fr"},
    Format:  "markdown", // optional; omit to auto-detect
    Source:  "en",       // optional
    Model:   "standard", // optional: "standard" | "advanced"
})
// r.Translations["es"], r.Usage.TotalTokens, etc.

client.Batch(ctx, params)

POST /translate/batch

b, err := client.Batch(ctx, polylingo.BatchParams{
    Items: []polylingo.BatchItem{
        {ID: "a", Content: "Hello"},
        {ID: "b", Content: "## Title", Format: "markdown"},
    },
    Targets: []string{"de"},
})
// b.Results[0].Translations["de"], b.Usage.TotalTokens

client.Usage(ctx)

GET /usage

u, err := client.Usage(ctx)

Jobs (client.Jobs)

client.Jobs.Create(ctx, params)

POST /jobs. Returns the 202 body (job_id, status, …).

job, err := client.Jobs.Create(ctx, polylingo.CreateJobParams{
    Content: longMarkdown,
    Targets: []string{"de", "fr"},
    Format:  "markdown",
})
// job.JobID

client.Jobs.Get(ctx, jobID)

GET /jobs/:id. When status == "completed", the response includes translations and usage at the top level.

status, err := client.Jobs.Get(ctx, job.JobID)

client.Jobs.Translate(ctx, params) (convenience)

Submits a job, then polls until completed or failed, or until the timeout is reached.

Polling options use time.Duration:

done, err := client.Jobs.Translate(ctx, polylingo.JobsTranslateParams{
    TranslateParams: polylingo.TranslateParams{
        Content: longMarkdown,
        Targets: []string{"de", "fr", "es"},
        Format:  "markdown",
    },
    PollInterval: 5 * time.Second,  // default 5s if zero
    Timeout:      20 * time.Minute, // default 20m if zero
    OnProgress: func(pos *int) {
        if pos != nil {
            fmt.Println("Queue:", *pos)
        }
    },
})
// done.Translations, done.Usage

Job lifecycle statuses: pending, processing, completed, failed.

Error handling

Use errors.As with pointer types:

import (
    "errors"
    "github.com/UsePolyLingo/polylingo-go/polylingo"
)

_, err := client.Translate(ctx, polylingo.TranslateParams{Content: "x", Targets: []string{"es"}})
if err != nil {
    var ae *polylingo.AuthError
    if errors.As(err, &ae) { /* invalid key */ }
    var re *polylingo.RateLimitError
    if errors.As(err, &re) { /* re.RetryAfter */ }
    var je *polylingo.JobFailedError
    if errors.As(err, &je) { /* je.JobID */ }
    var pe *polylingo.PolyLingoError
    if errors.As(err, &pe) { /* pe.Status, pe.Code */ }
}

Async jobs pattern (summary)

1. Manual: Jobs.Create → loop Jobs.Get until a terminal state.
2. Helper: Jobs.Translate with PollInterval, Timeout, and optional OnProgress.

Prefer jobs for very large content where synchronous translate might hit client or server timeouts.

Changelog

0.1.0

• Initial release: Health, Languages, Translate, Batch, Usage, Jobs.Create, Jobs.Get, Jobs.Translate.