@colixsystems/translation-client

Scoped client for the AppStudio runtime content-translation API (sc-3783). It is a communication-plane sibling of @colixsystems/notifications-client, @colixsystems/datastore-client, @colixsystems/assets-client, and @colixsystems/directory-client. It is a standalone fetch-based client you instantiate with createTranslationClient({ baseUrl, getToken, getTenantId }).

Two surfaces, one package. This client serves two callers:

1. External / server-side integrations instantiate it directly with an API key and call translate below.
2. The widget runtime — the Player and exported Expo app instantiate the same package and inject it into WidgetContext.i18n.translate. Widgets never import this package; they call the SDK hook useTranslate() from @colixsystems/widget-sdk, which reads ctx.i18n. Both surfaces speak the identical snake_case REST contract.

What this is for — and what it is NOT

This translates user-generated content: datastore record text, file names, REST payloads — anything whose language nobody chose at build time. It costs a provider call the first time it sees a string.

It is not for the app's own copy. Author-written strings live in the workspace's translation dictionary and are resolved for free by useI18n().t("key"). Reach for useTranslate() only when there is no key because there is no author.

Status

v0.1.0 — pre-publish. Not yet published to npm.

Wire format — snake_case, no transform

The wire format is snake_case in both directions (REQ-GEN-09) and that is the client contract. The SDK does no camelCase↔snake_case transform. Request bodies are sent snake_case verbatim ({ segments, target_language, source_language? }); the response envelope is returned snake_case verbatim ({ translations, source_language, target_language, cached_count, translated_count }). The only caller-facing camelCase is the JS method names (translate, status) and the factory option names.

Public API

import {
  createTranslationClient,
  TranslationError,
  ValidationError,
  PayloadTooLargeError,
  RateLimitedError,
  QuotaExceededError,
  NotConfiguredError,
  ServerError,
} from "@colixsystems/translation-client";

const client = createTranslationClient({
  baseUrl: "https://api.appstudio.io/api/v1",
  getToken: () => "Bearer ...",
  getTenantId: () => "tenant_abc",
  // Optional: per-request extra headers. Called with
  // { namespace: "translation", operation } and merged into the request.
  getRequestHeaders: ({ namespace, operation }) => ({}),
  // fetchImpl defaults to globalThis.fetch
});

// Translate content into the app user's language. `translations` is
// positionally aligned with `segments`.
const res = await client.translate({
  segments: ["Hej", "Tack för din order"],
  target_language: "en",
  source_language: "sv", // optional — omit to auto-detect
});
// → { translations: ["Hi", "Thanks for your order"], source_language: "sv",
//     target_language: "en", cached_count: 0, translated_count: 2 }

// Whether the platform has a provider configured at all.
const { configured } = await client.status();

Limits

One request carries at most 50 segments, 5 000 characters per segment, and 20 000 characters in total. Exceeding any of these rejects with PayloadTooLargeError (total) or ValidationError (per-segment / count) — batch instead of retrying.

Every workspace has a monthly translated-character cap. Only cache misses count against it, so a steady-state app converges on near-zero usage. Reaching it rejects with QuotaExceededError (code: "TRANSLATION_QUOTA_EXCEEDED"), which — unlike a plain RateLimitedError — will not clear until the next period. Cached translations keep working.

Caching

Three layers keep the same string from being paid for twice: the SDK hook memoizes per session, the API keeps a short-lived in-process cache, and the backend keeps a durable per-workspace cache keyed by the content itself. A repeat translation of text the workspace has already seen never reaches the provider.

Errors

| Class | Status | When | | ----- | ------ | ---- | | ValidationError | 400 | Bad segments, bad or missing target_language | | ForbiddenError | 403 | Caller is not an app user of the workspace | | PayloadTooLargeError | 413 | Request exceeds the total character limit | | RateLimitedError | 429 | Per-actor rate limiter tripped — retry shortly | | QuotaExceededError | 429 | Workspace's monthly character cap reached — will not clear until next period | | NotConfiguredError | 503 | The platform operator has configured no translation provider | | ServerError | 5xx | Upstream or platform failure |

translate is retried on 429 (rate limit) and 5xx with exponential backoff (200/400/800 ms) even though it is a POST: translating creates nothing observable twice and the server answers a repeat from cache. QuotaExceededError and NotConfiguredError are never retried — neither clears on a retry.

License

MIT