first commit

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-20 22:41:25 +02:00
commit aa1771ea20
136 changed files with 27069 additions and 0 deletions
@@ -0,0 +1,74 @@
+/**
+ * Island-side i18n. This is the file that ships.
+ *
+ * The page carries its own copy: `Base.astro` emits one `<script type="application/json"
+ * data-i18n>` holding the current locale's client-facing keys, already resolved against
+ * English. So a Spanish page ships Spanish strings and no others, in the HTML it was
+ * going to send anyway. No second request, no catalog chunk per language, no waterfall
+ * before an island can draw a label, and nothing in a shared JS chunk that has to be
+ * one language for everybody.
+ *
+ * The alternative, a dynamic `import('./es.json')` keyed on locale, also avoids
+ * shipping three languages, but it costs a round trip on the critical path of every
+ * island and it leaves all three catalogs sitting in `dist/_astro/`. This does not.
+ */
+import { DEFAULT_LOCALE, type Locale } from './config.js';
+import { createTranslator, type Catalog, type Translator } from './translate.js';
+
+interface Payload {
+  locale: Locale;
+  catalog: Catalog;
+}
+
+/**
+ * Read the payload out of the current document.
+ *
+ * Read every time rather than cached at module scope, because the view transition
+ * router swaps the document under this module without reloading it. An island that
+ * cached its translator on first load would keep drawing Spanish after the reader
+ * clicked through to a Dutch page. Islands call `useI18n()` inside their `onReady`
+ * setup, which runs again on every arrival, so this reads the page that is actually on
+ * screen.
+ */
+function readPayload(): Payload {
+  const tag = document.querySelector<HTMLScriptElement>('script[data-i18n]');
+  if (!tag) return { locale: DEFAULT_LOCALE, catalog: {} };
+
+  try {
+    const parsed = JSON.parse(tag.textContent ?? '{}') as Partial<Payload>;
+    return {
+      locale: parsed.locale ?? DEFAULT_LOCALE,
+      catalog: parsed.catalog ?? {},
+    };
+  } catch {
+    // A payload that will not parse is a build bug, not a runtime condition. Falling
+    // back to the key humaniser beats throwing inside every island on the page.
+    return { locale: DEFAULT_LOCALE, catalog: {} };
+  }
+}
+
+/**
+ * One translator per document, rebuilt when the router swaps in a new one.
+ *
+ * Keyed on the script element itself: a new page brings a new element, and identity
+ * comparison is cheaper and more honest than re-parsing the JSON on every `t()`.
+ */
+let cachedTag: Element | null = null;
+let cached: Translator | null = null;
+
+export function useI18n(): Translator {
+  const tag = document.querySelector('script[data-i18n]');
+  if (cached && tag === cachedTag) return cached;
+
+  const { locale, catalog } = readPayload();
+  // The payload is already resolved against English at build time, so the fallback
+  // catalog here is the same object: there is nothing further to fall back to.
+  cached = createTranslator(locale, catalog, catalog);
+  cachedTag = tag;
+  return cached;
+}
+
+/** The locale this page is in, for `Intl` calls that do not go through `t()`. */
+export function currentLocale(): Locale {
+  return useI18n().locale;
+}