Get Translation Bundle

curl -i https://api.bio.re/api/v1/translations/en
# ETag: "i18n-en-42"
# Cache-Control: public, max-age=60, stale-while-revalidate=300

# When you already know version=42 from GET /locales, lock the cache:
curl -i 'https://api.bio.re/api/v1/translations/en?v=42'
# ETag: "i18n-en-42"
# Cache-Control: public, max-age=31536000, immutable

curl -i https://api.bio.re/api/v1/translations/en \
  -H 'If-None-Match: "i18n-en-42"'
# HTTP/1.1 304 Not Modified  (no body)

type TranslationBundle = Record<string, string>;

async function getBundle(
  locale: string,
  opts?: { version?: number; ifNoneMatch?: string },
): Promise<{ bundle: TranslationBundle | null; etag: string | null; status: 200 | 304 }> {
  const url = new URL(`https://api.bio.re/api/v1/translations/${locale}`);
  if (opts?.version != null) url.searchParams.set('v', String(opts.version));

  const headers: Record<string, string> = {};
  if (opts?.ifNoneMatch) headers['If-None-Match'] = opts.ifNoneMatch;

  const res = await fetch(url, { headers });
  const etag = res.headers.get('ETag');

  if (res.status === 304) {
    return { bundle: null, etag, status: 304 };
  }
  if (!res.ok) {
    throw new Error(`Bundle fetch failed: ${res.status}`);
  }
  return { bundle: (await res.json()) as TranslationBundle, etag, status: 200 };
}

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

// Pair this hook with useLocales(). When versions[locale] changes upstream,
// the queryKey changes too — TanStack treats it as a fresh cache entry.
export function useTranslationBundle(locale: string, version: number) {
  return useQuery({
    queryKey: ['i18n', 'bundle', locale, version],
    queryFn: async () => {
      const url = `/api/v1/translations/${locale}?v=${version}`;
      const res = await fetch(url);
      if (!res.ok) throw new Error(`Bundle fetch failed: ${res.status}`);
      return (await res.json()) as Record<string, string>;
    },
    enabled: version > 0,        // skip while version is unknown
    staleTime: Infinity,         // version-pinned URL → never stales until version bumps
    gcTime: 60 * 60_000,         // keep prior versions around 1h for back-nav
  });
}