Fetch translations

Once you have a namespace with translated terms and an API key, your app can fetch translations on demand or at build time.

Endpoint

GET https://api.norcube.com/langsync/api/v1/namespaces/{namespaceName}/terms/translations?langId={languageId}

Authentication is via the Authorization header:

Authorization: Apikey <your-api-key>

The langId query parameter is the numeric language ID (not the BCP 47 code). Get the IDs with the list languages endpoint – typically you'd cache them or hard-code them in your app config since they don't change.

Response shape

{
  "translations": {
    "welcome.title": "Willkommen",
    "welcome.subtitle": "Schön, dass Sie hier sind",
    "button.submit": "Absenden",
    "button.cancel": "Abbrechen"
  }
}

A flat map from term mark to translated value. Empty translations are returned as empty strings – your i18n library should treat them as missing and fall back to the default language.

Patterns

Fetch once at build time

For static sites and SPAs, fetch translations during build and ship them as JSON files alongside your bundle. Cache-friendly, fast, no runtime LangSync dependency.

# In your build script
for lang in en-US de-DE fr-FR; do
  curl -H "Authorization: Apikey $LANGSYNC_API_KEY" \
       "https://api.norcube.com/langsync/api/v1/namespaces/web-app/terms/translations?langId=$LANG_ID" \
       -o ./src/locales/$lang.json
done

Fetch at runtime with caching

For server-rendered apps and mobile clients, fetch on app start and cache in-memory. Refresh on a TTL (e.g. every 5 minutes) or invalidate via a webhook (when one ships).

const translations = await fetch(
  `https://api.norcube.com/langsync/api/v1/namespaces/${ns}/terms/translations?langId=${langId}`,
  { headers: { Authorization: `Apikey ${process.env.LANGSYNC_API_KEY}` } }
).then((r) => r.json());

List available languages

GET https://api.norcube.com/langsync/api/v1/namespaces/{namespaceName}/languages
Authorization: Apikey <your-api-key>

Returns the languages attached to that namespace, each with its id, code, and name. Use this to populate a language picker in your app, or to discover the numeric langId for the translations endpoint.

Limits

• Rate limit: Up to 200 requests per hour per organization, 50 per hour per individual user/API key.
• Response size: A namespace with 10,000 terms returns roughly 1 MB uncompressed. The endpoint serves Content-Encoding: gzip if your client accepts it.

See Limits & errors for details and error codes.

Caching tips

• Translations rarely change between deploys. Cache aggressively at the CDN layer or in your app's memory.
• The endpoint sets Last-Modified and supports If-Modified-Since. Conditional fetches return 304 Not Modified with no body, saving bandwidth.

What's next

• Public API reference – every endpoint and parameter.
• Limits & errors – rate limits and error response shapes.