@lokalise/polyglot-sdk 4.1.1 → 4.3.0

package/README.md

@@ -0,0 +1,111 @@
+# Polyglot Client SDK
+
+Polyglot service provides a REST API to interact with it directly, but we recommend using
+this [@lokalise/polyglot-sdk](https://www.npmjs.com/package/@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:
+
+```typescript
+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:
+
+```typescript
+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:
+
+```json
+// 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

package/dist/sdk/types/requests.d.ts

@@ -14,6 +14,9 @@ export type TranslateAsyncRequestBody = TranslateSyncRequest & {
 };
 export type TranslateSyncContentUnits = {
     id: string;
+    context?: {
+        description: string;
+    };
     segments: {
         id: string;
         position: number;
@@ -28,6 +31,9 @@ export type LqaSyncRequest = {
 };
 export type LqaContentUnit = {
     id: string;
+    assets?: {
+        description?: string;
+    };
     segments: LqaSegment[];
 };
 export type LqaSegment = {

package/dist/sdk/types/responses.d.ts

@@ -27,6 +27,8 @@ export type ContentUnitTranslationResponse = {
         position: number;
         translation: string;
         integration: string;
+        score?: string | null;
+        polyglotRefId?: string;
     }[];
 };
 export type LqaSeverityResponse = 'neutral' | 'minor' | 'major' | 'critical';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lokalise/polyglot-sdk",
-  "version": "4.1.1",
+  "version": "4.3.0",
   "author": {
     "name": "Lokalise",
     "url": "https://lokalise.com/"
@@ -33,16 +33,16 @@
   },
   "dependencies": {
     "@amplitude/analytics-types": "^2.5.0",
-    "@lokalise/fastify-extras": "^17.0.3",
+    "@lokalise/fastify-extras": "^18.0.0",
     "@lokalise/id-utils": "^1.0.0",
-    "@lokalise/node-core": "^9.13.0",
+    "@lokalise/node-core": "^9.16.0",
     "@lokalise/zod-extras": "^2.0.1",
-    "undici": "^6.13.0",
+    "undici": "^6.15.0",
     "undici-retry": "^5.0.2",
-    "zod": "^3.22.4"
+    "zod": "^3.23.4"
   },
   "devDependencies": {
-    "@types/node": "^20.12.7",
+    "@types/node": "^20.12.9",
     "@typescript-eslint/eslint-plugin": "^7.4.0",
     "@typescript-eslint/parser": "^7.4.0",
     "@vitest/coverage-v8": "^0.34.6",