@lokalise/polyglot-sdk

Polyglot Client SDK

Polyglot service provides a REST API to interact with it directly, but we recommend using this @lokalise/polyglot-sdk NPM package to integrate Translation and LQA capabilities into your Node.js application.

Usage

Use the following command to add the package to your project:

npm install @lokalise/polyglot-sdk

After that, you can start using the SDK like this:

import { PolyglotClient } from '@lokalise/polyglot-sdk'

const client = new PolyglotClient({
  // Polyglot instance URL
  baseUrl: 'e.g. https://polyglot-service-main.test.lokalise.cloud',
  // Authentication token in JWT format
  jwtToken: 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.ey...',
  // Optional Undici retry config (see RetryConfig in https://github.com/kibertoad/undici-retry)
  retryConfig: {},
  logger,
})

Translate

To translate some content units asynchronously, you can use a following call example:

const reqContext: RequestContext

// Either<Error, 'scheduled' | 'nothingToTranslate'>
const polyglotResponse = await this.polyglotClient.translateAsync(
  {
    sourceLocale: 'en',
    targetLocale: 'de',
    contentUnits: [
      {
        id: '018f5231-7be5-b816-116b-4b0426d0f428',
        segments: [
          {
            id: '018f5231-d61d-aec6-c6b2-ed676bbab868',
            position: 0,
            value: 'Hello world',
          },
        ],
      },
    ],
    tenantId: 'autopilot',
    ownerId: '<unique_project_id>',
    originCorrelationId: '<unique_job_id',
    callbackUrl: 'https://<callback_url_on_consumer_side>',
    callbackToken: '<auth_token_that_will_be_passed_within_callback>',
  },
  { reqContext, fakeProcessing: false },
)

If polyglotResponse is 'scheduled', that means the request was put into the Polyglot queue and after it is processed, Polyglot will call given callbackUrl and provide the results (see Callback section for details).

Results callback will have the following structure:

// POST <callbackUrl>
// Authorization: Bearer <callbackToken>

{
  "data": {
    "originCorrelationId": "018f3958-a3bb-05cc-2243-58976a74cd35#1",
    "errors": [],
    "sourceLocale": "en-US",
    "targetLocale": "es",
    "contentUnits": [
      {
        "id": "018f3414-7070-e998-3628-5ab485306760",
        "locale": "es",
        "segments": [
          {
            "id": "018f3414-7070-e998-3628-5ab485306761",
            "position": 0,
            "translation": "mundo",
            "integration": "ChatGPT-4",
            "score": 0.88
          },
          {
            "id": "018f3414-7070-e998-3628-5ab485306762",
            "position": 1,
            "translation": "hola",
            "integration": "ChatGPT-4",
            "score": null
          }
        ]
      }
    ]
  }
}

See https://lokalise.atlassian.net/wiki/spaces/PDE/pages/2787180586/Polyglot+APIs+and+Usage+guidelines#Translate-API-(async) for more details on available parameters and results.

LQA

TBD after async endpoint is implemented