Get Namespace Bundle

GET /api/v1/translations/:locale/:namespace — 🌐 Public · Rate limit: 60 req / minute

Returns the APPROVED translations for a single namespace inside a locale. Use this when you want to lazy-load (auth namespace on the auth screen, chat namespace inside the chat surface) instead of pulling the entire bundle up-front. Cache semantics, ETag shape, and ?v=N immutable pinning behave the same as GET /api/v1/translations/:locale — the only differences are the path, the ETag (which embeds the namespace), and the response key shape.

Request

Path parameters

Query parameters

Headers

No body, no auth required.

Response

200 OK — Record<string, string> (flat map, no namespace prefix)

{
  "login.title": "Sign in to your account",
  "login.button": "Sign in",
  "signup.cta": "Create account",
  "errors.invalid_credentials": "Invalid email or password"
}

304 Not Modified

Returned when If-None-Match matches the current ETag. No body.

Response headers (always)

Errors

No other documented errors. Unknown :locale or :namespace → 200 + empty {}.

Side effects

1. cache.getVersion(locale) — read i18n:version:<locale> from Redis (returns 0 if unavailable).
2. Build ETag = "i18n-<locale>-<namespace>-<version>". If If-None-Match === ETag → res.status(304); return.
3. translationService.getBundle(locale, namespace) — multi-layer cache lookup:
   • L1 (bundle:<locale>:<namespace>, 60s) → if hit, return.
   • L2 (Redis, i18n:bundle:<locale>:<namespace>, 5 min) → if hit, promote to L1, return.
   • On miss: prisma.translation.findMany({ where: { languageCode, status: 'APPROVED', translationKey: { namespace } } }).
4. Project to flat map. The key is just translation.translationKey.key — no <namespace>. prefix (because the namespace is implied by the URL).
5. Write to L2 + L1.
6. Set ETag header. Set Cache-Control based on ?v= match.
7. Return the bundle.

Invalidation note

The write-side invalidateLocale(locale) clears all namespace bundles for that locale (it loops through known namespaces and DELs each Redis key). There's no narrower per-namespace invalidation today.

Code samples

curl -i 'https://api.bio.re/api/v1/translations/en/auth?v=42' \
  -H 'If-None-Match: "i18n-en-auth-42"'
# 304 if version matches and ETag matches; else 200 + JSON body.

type NamespaceBundle = Record<string, string>;

async function getNamespaceBundle(
  locale: string,
  namespace: string,
  version: number,
): Promise<NamespaceBundle> {
  const url = `https://api.bio.re/api/v1/translations/${locale}/${namespace}?v=${version}`;
  const res = await fetch(url);
  if (!res.ok) throw new Error(`Bundle fetch failed: ${res.status}`);
  return (await res.json()) as NamespaceBundle;
}

// Usage in an auth screen — the `auth` namespace is the only thing this view needs:
const auth = await getNamespaceBundle('en', 'auth', 42);
const title = auth['login.title'] ?? 'Sign in';

import { useQuery } from '@tanstack/react-query';

export function useNamespaceBundle(locale: string, namespace: string, version: number) {
  return useQuery({
    queryKey: ['i18n', 'bundle', locale, namespace, version],
    queryFn: async () => {
      const res = await fetch(`/api/v1/translations/${locale}/${namespace}?v=${version}`);
      if (!res.ok) throw new Error(`Bundle fetch failed: ${res.status}`);
      return (await res.json()) as Record<string, string>;
    },
    enabled: version > 0,
    staleTime: Infinity,
    gcTime: 60 * 60_000,
  });
}

Try it

curl -X GET "https://loading/api/v1/translations/en/auth"

{}

Source