Translate Product Strings at Runtime with General Translation

your app
   |
   v
POST https://api.gtx.dev/v2/translate
   {requests: {<your-id>: {source, metadata}}, sourceLocale, targetLocale, metadata}
   |
   v
{<your-id>: {success, dataFormat, translation, locale}}
   201 = newly translated     200 = every string served from cache

Implement a Node function that translates UI strings through General
Translation's runtime API.

Requirements:
- POST https://api.gtx.dev/v2/translate
- Auth: "Authorization: Bearer <key>". A project key is bound to one project
  and needs nothing else. Project keys come in two types: production
  (gtx-api-) and development (gtx-dev-). Both authenticate THIS endpoint,
  but a development key is rejected by the CLI file workflow, which needs a
  production key. An organization key (gtx-org-) also requires a
  "gt-project-id: <projectId>" header.
- Request body requires all four of: requests, sourceLocale, targetLocale,
  metadata. Send "metadata": {} if you have nothing to put in it. Omitting
  it is a validation error.
- "requests" is a map keyed by ids you choose. The response comes back keyed
  by those same ids, so use stable keys you can look up.
- Each request entry is {source, metadata: {id, dataFormat}}. dataFormat is
  one of JSX, ICU, I18NEXT, STRING.
- Treat BOTH 200 and 201 as success. 201 means newly translated, 200 means
  every string was served from cache. Do not branch on 200 alone.
- Pass metadata.context for any string whose meaning is ambiguous out of
  context. Assert that the contextual result is appropriate for the domain,
  not that it differs from the uncontextualised one; both can be acceptable.
- Never fall back to returning the untranslated source silently. If
  success is false for an entry, surface it.

curl -s -X POST https://api.gtx.dev/v2/translate \
  -H "Authorization: Bearer $GT_ORG_KEY" \
  -H "Content-Type: application/json" \
  -d '{"requests":{"r1":{"source":"Hello","metadata":{"id":"greeting","dataFormat":"STRING"}}},"sourceLocale":"en","targetLocale":"es","metadata":{}}'

{"error":"projectId is required"}

# Option A: organization key plus an explicit project header
curl -s -X POST https://api.gtx.dev/v2/translate \
  -H "Authorization: Bearer $GT_ORG_KEY" \
  -H "gt-project-id: $GT_PROJECT_ID" \
  -H "Content-Type: application/json" -d @body.json

# Option B: a project key, which is already bound to its project
curl -s -X POST https://api.gtx.dev/v2/translate \
  -H "Authorization: Bearer $GT_API_KEY" \
  -H "Content-Type: application/json" -d @body.json

cat > body.json <<'JSON'
{
  "requests": {
    "r1": {
      "source": "Your trial ends in 3 days.",
      "metadata": { "id": "billing.trial_ends", "dataFormat": "STRING" }
    }
  },
  "sourceLocale": "en",
  "targetLocale": "es",
  "metadata": {}
}
JSON

curl -s -w '\nHTTP %{http_code}\n' -X POST https://api.gtx.dev/v2/translate \
  -H "Authorization: Bearer $GT_API_KEY" \
  -H "Content-Type: application/json" --data @body.json

{"r1":{"success":true,"dataFormat":"STRING","translation":"Tu período de prueba termina en 3 días.","locale":"es"}}
HTTP 201

// translate.mjs
const API = 'https://api.gtx.dev/v2/translate';

/**
 * Translate a batch of strings.
 * @param {Record<string, {source: string, context?: string}>} entries keyed by your own ids
 * @param {{from: string, to: string}} locales
 * @returns {Promise<Record<string, string>>} translations keyed by the same ids
 */
export async function translate(entries, { from, to }) {
  const apiKey = process.env.GT_API_KEY;
  if (!apiKey) throw new Error('GT_API_KEY is not set');

  const requests = Object.fromEntries(
    Object.entries(entries).map(([id, { source, context }]) => [
      id,
      { source, metadata: { id, dataFormat: 'STRING', ...(context ? { context } : {}) } },
    ])
  );

  const res = await fetch(API, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
      ...(process.env.GT_PROJECT_ID ? { 'gt-project-id': process.env.GT_PROJECT_ID } : {}),
    },
    body: JSON.stringify({ requests, sourceLocale: from, targetLocale: to, metadata: {} }),
  });

  // HTTP-level failure. 200 and 201 are both success; do not branch on 200 alone.
  if (!res.ok) {
    const body = await res.text();
    throw new Error(`GT ${res.status}: ${body.slice(0, 200)}`);
  }

  const payload = await res.json();

  // Per-entry failure. A 2xx does not mean every string translated.
  const out = {};
  const failed = [];
  for (const id of Object.keys(entries)) {
    const entry = payload[id];
    if (!entry || entry.success !== true || typeof entry.translation !== 'string') {
      failed.push(id);
      continue;
    }
    out[id] = entry.translation;
  }
  if (failed.length) {
    throw new Error(`GT returned no translation for: ${failed.join(', ')}`);
  }
  return out;
}

import { translate } from './translate.mjs';

const out = await translate(
  {
    'billing.trial_ends': { source: 'Your trial ends in 3 days.' },
    'billing.seat': {
      source: 'Seat',
      context: 'A billing seat: one paid user licence in a SaaS subscription. Not furniture.',
    },
  },
  { from: 'en', to: 'de' }
);
console.log(out);

{
  'billing.trial_ends': 'Dein Testzeitraum endet in 3 Tagen.',
  'billing.seat': 'Lizenzplatz'
}

curl -s -X POST https://api.gtx.dev/v2/translate \
  -H "Authorization: Bearer $GT_API_KEY" -H "Content-Type: application/json" \
  -d '{"requests":{"s":{"source":"Seat","metadata":{"id":"billing.seat","dataFormat":"STRING"}}},"sourceLocale":"en","targetLocale":"de","metadata":{}}'

{"s":{"success":true,"dataFormat":"STRING","translation":"Sitz","locale":"de"}}

curl -s -X POST https://api.gtx.dev/v2/translate \
  -H "Authorization: Bearer $GT_API_KEY" -H "Content-Type: application/json" \
  -d '{"requests":{"s":{"source":"Seat","metadata":{"id":"billing.seat","dataFormat":"STRING","context":"A billing seat: one paid user licence in a SaaS subscription. Not furniture."}}},"sourceLocale":"en","targetLocale":"de","metadata":{}}'

{"s":{"success":true,"dataFormat":"STRING","translation":"Lizenzplatz","locale":"de"}}

verification:
  status: verified
  tested_at: "2026-09-22"
  product_version: "2026-03-06.v1"
  command: "node demo.mjs and node errors.mjs against https://api.gtx.dev/v2/translate"
  expected_result: "translate() returns a map keyed by the caller's ids; HTTP failures and per-entry failures both throw; the contextual result for an ambiguous term is appropriate for the domain"

  documented_behavior:
    "201": "Translations completed"
    "200": "All translations were served from cache"
    source: "https://generaltranslation.com/openapi.json, spec version 2026-03-06.v1"

  observed_in_run:
    demo: "{'billing.trial_ends': 'Dein Testzeitraum endet in 3 Tagen.', 'billing.seat': 'Lizenzplatz'}"
    error_paths:
      missing_key: "GT_API_KEY is not set"
      invalid_key: "GT 401: Unauthorized!"
      org_key_no_project: 'GT 400: {"error":"projectId is required"}'
    context_effect:
      run_1: "bare Sitz, context Nutzerlizenz"
      run_2: "bare Sitz, context Lizenzplatz"
      run_3: "bare Sitzplatz, context Lizenzplatz"
      note: "both columns vary between runs. An earlier run returned Seat unchanged for the bare call, so the bare side is not reliably wrong. Assert the contextual result is not in a furniture denylist, not that the two differ."
    spanish_context_pair: "the developer-docs context kept 'trial' in English on 2026-09-16 and in two fresh-id runs on 2026-09-22. One run was reported where it did not. Treated as a strong hint rather than a guarantee."

  corrections_from_review:
    - "an earlier version told readers to assert on the difference between the two calls. That is wrong: both can correctly return the billing sense, and such a test fails for the wrong reason. The doc now gives a denylist check as the concrete assertion."
    - "the runnable Node function promised by the opening paragraph is now present and exercised, including both failure modes."