@terrafirmagreg-team/translate 0.0.0-stage → 1.2.0

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@terrafirmagreg-team/translate",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.2.0",
+  "type": "module",
+  "description": "Localization runtime and catalogs",
+  "license": "LGPL-3.0-only",
+  "exports": {
+    ".": "./src/components/runtime.tsx",
+    "./provider": "./src/components/provider.tsx",
+    "./lang": "./src/lang.ts",
+    "./create": "./src/create.ts",
+    "./config": "./src/config.ts",
+    "./server": "./src/server.ts",
+    "./hooks": "./src/hooks/index.ts",
+    "./hooks/*": [
+      "./src/hooks/*.ts",
+      "./src/hooks/*/index.ts"
+    ],
+    "./lib/*": [
+      "./src/lib/*.ts",
+      "./src/lib/*/index.ts"
+    ],
+    "./types/*": "./src/types/*.ts",
+    "./runtime": "./src/components/runtime.tsx"
+  },
+  "files": [
+    "src"
+  ],
+  "dependencies": {
+    "@fuma-translate/react": "1.0.2"
+  },
+  "peerDependencies": {
+    "react": "catalog:"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "@types/react": "catalog:",
+    "@types/react-dom": "catalog:"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TerraFirmaGreg-Team/Web-Foundation.git",
+    "directory": "packages/translate"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/components/provider.tsx

@@ -0,0 +1,66 @@
+'use client';
+import {
+  createContext,
+  use,
+  useLayoutEffect,
+  useMemo,
+  type ReactNode,
+} from 'react';
+import { TranslationProvider } from './runtime';
+import { LangScopeContext } from '@terrafirmagreg-team/translate/hooks/use-resolved-lang';
+import type { LangProviderProps, LocaleItem } from '@terrafirmagreg-team/translate/lang';
+
+export interface LangContextValue {
+  locale?: string;
+  locales?: LocaleItem[];
+  onLocaleChange?: (v: string) => void;
+}
+
+const LangContext = createContext<LangContextValue>({});
+
+export function LangProvider({
+  locale,
+  translations,
+  locales,
+  onLocaleChange,
+  children,
+}: LangProviderProps) {
+  const value = useMemo(
+    () => ({ locale, locales, onLocaleChange }),
+    [locale, locales, onLocaleChange],
+  );
+  return (
+    <LangContext value={value}>
+      <TranslationProvider translations={translations ?? {}}>
+        {children}
+      </TranslationProvider>
+    </LangContext>
+  );
+}
+
+export function useLang(): LangContextValue {
+  return use(LangContext);
+}
+
+export function LangLocalesScope({
+  locales,
+  children,
+}: {
+  locales: readonly LocaleItem[];
+  children: ReactNode;
+}) {
+  const base = useLang();
+  const { setLangs } = use(LangScopeContext);
+  const scopeKey = locales.map((item) => item.locale).join(',');
+  useLayoutEffect(() => {
+    const langs = scopeKey ? scopeKey.split(',') : null;
+    setLangs(langs);
+    return () => setLangs(null);
+  }, [scopeKey, setLangs]);
+  const value = useMemo(
+    () => ({ ...base, locales: [...locales] }),
+    [base, locales],
+  );
+  return <LangContext value={value}>{children}</LangContext>;
+}
+

package/src/components/runtime.tsx

@@ -0,0 +1,9 @@
+'use client';
+export {
+  T,
+  TranslationProvider,
+  fromTranslations,
+  useTranslations,
+  type TranslationsHook,
+} from '@fuma-translate/react';
+

package/src/config.ts

@@ -0,0 +1,15 @@
+export type TranslateConfig = {
+
+  locales?: Record<string, unknown> | Record<string, unknown>[];
+};
+
+let config: TranslateConfig = {};
+
+export function registerTranslateConfig(next: TranslateConfig): void {
+  config = { ...config, ...next };
+}
+
+export function translateConfig(): TranslateConfig {
+  return config;
+}
+

package/src/create.ts

@@ -0,0 +1,64 @@
+import type {
+  Lang,
+  LocaleMessages,
+  LocaleRegistry,
+} from './types/locale';
+import type { LangConfig, LangProviderProps, LocaleItem } from './lang';
+import { nativeLanguageName } from './lib/code';
+
+export function localeItems(codes: readonly string[]): LocaleItem[] {
+  return codes.map((code) => ({
+    locale: code,
+    name: nativeLanguageName(code) ?? code,
+  }));
+}
+
+function messagesFor(
+  lang: Lang,
+  registry: LocaleRegistry,
+  fallback: LocaleMessages,
+): LocaleMessages & { displayName: string } {
+  const locale = registry.messages[lang];
+  const merged = { ...fallback, ...locale };
+  const displayName = nativeLanguageName(lang) ?? lang;
+  const { 'language.name': _name, displayName: _dn, ...rest } = merged;
+  return { ...rest, displayName };
+}
+
+export function createLocaleSet(registry: LocaleRegistry) {
+  const fallback = {
+    ...(registry.messages[registry.defaultLanguage] ?? {}),
+  };
+  const bundles: Record<string, LocaleMessages & { displayName: string }> = {};
+  for (const lang of registry.languages) {
+    bundles[lang] = messagesFor(lang, registry, fallback);
+  }
+
+  const config: LangConfig = {
+    defaultLanguage: registry.defaultLanguage,
+    languages: [...registry.languages],
+    fallbackLanguage: registry.defaultLanguage,
+  };
+
+  return {
+    fumadocs: config,
+    translations: bundles,
+    languages: registry.languages,
+    defaultLanguage: registry.defaultLanguage,
+    providerProps(lang: Lang): LangProviderProps {
+      const locale = lang ?? registry.defaultLanguage;
+      return {
+        locale,
+        defaultLanguage: registry.defaultLanguage,
+        translations: bundles[locale] ?? bundles[registry.defaultLanguage],
+        locales: registry.languages.map((code) => ({
+          locale: code,
+          name: bundles[code]?.displayName ?? code,
+        })),
+      };
+    },
+  };
+}
+
+export type LocaleSet = ReturnType<typeof createLocaleSet>;
+

package/src/hooks/index.ts

@@ -0,0 +1,11 @@
+export { useTranslations } from './use-translations';
+export {
+  ResolvedLangContext,
+  useResolvedLang,
+  type ResolvedLangValue,
+} from './use-resolved-lang';
+export {
+  LocaleRegistryContext,
+  useLocaleRegistry,
+} from './use-locale-registry';
+

package/src/hooks/use-locale-registry.ts

@@ -0,0 +1,12 @@
+'use client';
+import { createContext, useContext } from 'react';
+import type { LocaleRegistry } from '@terrafirmagreg-team/translate/types/locale';
+
+export const LocaleRegistryContext = createContext<LocaleRegistry | null>(null);
+
+export function useLocaleRegistry(): LocaleRegistry {
+  const registry = useContext(LocaleRegistryContext);
+  if (!registry) throw new Error('Missing LocaleRegistryContext');
+  return registry;
+}
+

package/src/hooks/use-resolved-lang.ts

@@ -0,0 +1,37 @@
+'use client';
+import { createContext, useContext } from 'react';
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+
+export type ResolvedLangValue = {
+  lang: Lang;
+
+  defaultLang: Lang;
+  setLang: (lang: Lang) => void;
+};
+
+export const ResolvedLangContext = createContext<ResolvedLangValue | null>(
+  null,
+);
+
+export type LangScopeValue = {
+  langs: readonly Lang[] | null;
+  setLangs: (langs: readonly Lang[] | null) => void;
+};
+
+export const LangScopeContext = createContext<LangScopeValue>({
+  langs: null,
+  setLangs: () => {},
+});
+
+export function useResolvedLang(): Lang {
+  const ctx = useContext(ResolvedLangContext);
+  if (!ctx) throw new Error('Missing ResolvedLangContext');
+  return ctx.lang;
+}
+
+export function useDefaultLang(): Lang {
+  const ctx = useContext(ResolvedLangContext);
+  if (!ctx) throw new Error('Missing ResolvedLangContext');
+  return ctx.defaultLang;
+}
+

package/src/hooks/use-translations.ts

@@ -0,0 +1,24 @@
+'use client';
+import { useMemo } from 'react';
+import { useTranslations as useFumaTranslations } from '@terrafirmagreg-team/translate/runtime';
+
+export function useTranslations<K extends string = string>(options?: {
+  note?: string;
+}) {
+  const base = useFumaTranslations(options);
+  return useMemo(
+    () =>
+      ((key: K, opts?: {
+        note?: string;
+        variables?: Record<string, string>;
+      }) => {
+        const value = base(key, opts);
+        return opts?.note && value === key ? base(key) : value;
+      }) as (key: K, opts?: {
+        note?: string;
+        variables?: Record<string, string>;
+      }) => string,
+    [base],
+  );
+}
+

package/src/lang.ts

@@ -0,0 +1,29 @@
+import type { ReactNode } from 'react';
+
+export interface LangConfig<Languages extends string = string> {
+
+  languages: Languages[];
+
+  defaultLanguage: NoInfer<Languages>;
+
+  hideLocale?: 'always' | 'default-locale' | 'never';
+
+  parser?: 'dot' | 'dir' | 'none';
+
+  fallbackLanguage?: NoInfer<Languages> | null;
+}
+
+export interface LocaleItem {
+  name: string;
+  locale: string;
+}
+
+export interface LangProviderProps
+  extends Partial<Pick<LangConfig, 'defaultLanguage' | 'hideLocale'>> {
+  locale?: string;
+  onLocaleChange?: (v: string) => void;
+  translations?: Partial<Record<string, string>>;
+  locales?: LocaleItem[];
+  children?: ReactNode;
+}
+

package/src/lib/code.ts

@@ -0,0 +1,51 @@
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+
+export function sortLangCodes(codes: readonly string[]): string[] {
+  return [...codes].sort((a, b) => {
+    if (a === 'en_us') return -1;
+    if (b === 'en_us') return 1;
+    return a.localeCompare(b);
+  });
+}
+
+export function isLang(
+  value: string,
+  languages: readonly string[],
+): value is Lang {
+  return languages.includes(value);
+}
+
+export function resolveLang(
+  value: string | string[] | undefined | null,
+  languages: readonly string[],
+  defaultLanguage: string,
+): Lang {
+  const raw = Array.isArray(value) ? value[0] : value;
+  if (raw && isLang(raw, languages)) return raw;
+  return defaultLanguage;
+}
+
+export function htmlLang(lang: Lang): string {
+  return lang.split('_')[0] || lang;
+}
+
+function bcp47(lang: Lang): string {
+  const [primary, region] = lang.split('_');
+  if (!primary) return lang;
+  return region ? `${primary}-${region.toUpperCase()}` : primary;
+}
+
+export function nativeLanguageName(lang: Lang): string | undefined {
+  try {
+    const tag = bcp47(lang);
+    const name = new Intl.DisplayNames([tag], {
+      type: 'language',
+      languageDisplay: 'standard',
+    }).of(tag);
+    if (!name) return undefined;
+    return name.charAt(0).toLocaleUpperCase(tag) + name.slice(1);
+  } catch {
+    return undefined;
+  }
+}
+

package/src/lib/content.ts

@@ -0,0 +1,53 @@
+import 'server-only';
+import type { ReactNode } from 'react';
+import { loadLocaleRegistry } from './registry.server';
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+import type { LangContent } from '@terrafirmagreg-team/translate/types/content';
+
+type Resolve<P> = (
+  slug: string[] | undefined,
+  lang: Lang,
+) => { page: P; isFallback: boolean } | undefined;
+
+type Get<P> = (slug: string[] | undefined, lang: Lang) => P | undefined;
+
+export function langContent<P>(
+  slug: string[] | undefined,
+  resolve: Resolve<P>,
+  render: (page: P, lang: Lang) => ReactNode,
+): LangContent | null {
+  const { messages, defaultLanguage } = loadLocaleRegistry();
+  const primary = resolve(slug, defaultLanguage);
+  if (primary && !primary.isFallback) {
+    return {
+      lang: defaultLanguage,
+      node: render(primary.page, defaultLanguage),
+    };
+  }
+  for (const locale of Object.keys(messages)) {
+    const resolved = resolve(slug, locale as Lang);
+    if (!resolved || resolved.isFallback) continue;
+    return { lang: locale as Lang, node: render(resolved.page, locale as Lang) };
+  }
+  return primary
+    ? { lang: defaultLanguage, node: render(primary.page, defaultLanguage) }
+    : null;
+}
+
+export function firstLocalizedPage<P>(
+  slug: string[] | undefined,
+  getPage: Get<P>,
+  initial?: P,
+): P | undefined {
+  if (initial) return initial;
+  const { languages, defaultLanguage } = loadLocaleRegistry();
+  const page = getPage(slug, defaultLanguage);
+  if (page) return page;
+  for (const locale of languages) {
+    if (locale === defaultLanguage) continue;
+    const found = getPage(slug, locale as Lang);
+    if (found) return found;
+  }
+  return undefined;
+}
+

package/src/lib/coverage.ts

@@ -0,0 +1,71 @@
+import 'server-only';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export type TranslationState = 'untranslated' | 'partial' | 'ok';
+
+function proseLines(text: string): string[] {
+  const out: string[] = [];
+  let fence = false;
+  let frontmatter = false;
+  let body = false;
+  for (const raw of text.split('\n')) {
+    const line = raw.trim();
+    if (!body) {
+      if (!line) continue;
+      body = true;
+      if (line === '---') {
+        frontmatter = true;
+        continue;
+      }
+    }
+    if (frontmatter) {
+      if (line === '---' || line === '...') frontmatter = false;
+      continue;
+    }
+    if (line.startsWith('```')) {
+      fence = !fence;
+      continue;
+    }
+    if (fence || !line) continue;
+    if (
+      line.startsWith('import ') ||
+      line.startsWith('export ') ||
+      line.startsWith('<') ||
+      line.startsWith(':::')
+    ) {
+      continue;
+    }
+    out.push(line);
+  }
+  return out;
+}
+
+export function translationState(src: string, ref: string): TranslationState {
+  if (src === ref) return 'untranslated';
+  const lines = proseLines(src);
+  if (lines.length < 5) return 'ok';
+  const refSet = new Set(proseLines(ref));
+  const shared = lines.filter((line) => refSet.has(line)).length;
+  return shared / lines.length >= 0.7 ? 'partial' : 'ok';
+}
+
+export function readPageSource(
+  contentDir: string,
+  pagePath: string,
+): string | undefined {
+  try {
+    return readFileSync(
+      join(
+        process.cwd(),
+        'content',
+        contentDir.replace(/^content[\\/]?/, ''),
+        pagePath.replace(/\\/g, '/'),
+      ),
+      'utf8',
+    );
+  } catch {
+    return undefined;
+  }
+}
+

package/src/lib/flatten.ts

@@ -0,0 +1,17 @@
+export function flattenMessages(
+  value: unknown,
+  file: string,
+  prefix = '',
+): Record<string, string> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`Locale ${file}: ${prefix || '<root>'} must be an object`);
+  }
+  const out: Record<string, string> = {};
+  for (const [key, entry] of Object.entries(value)) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    if (typeof entry === 'string') out[path] = entry;
+    else Object.assign(out, flattenMessages(entry, file, path));
+  }
+  return out;
+}
+

package/src/lib/key-index.ts

@@ -0,0 +1,21 @@
+const NOTE_KEY = /^[a-z][a-z0-9_]*(\.[a-z0-9_]+)+$/;
+
+export function buildKeyIndex(
+  messages: Partial<Record<string, string>>,
+): Map<string, string> {
+  const index = new Map<string, string>();
+  for (const key of Object.keys(messages)) {
+    const end = key.lastIndexOf('(');
+    if (!key.endsWith(')') || end < 0) continue;
+    const note = key.slice(end + 1, -1);
+    if (NOTE_KEY.test(note)) index.set(note, key);
+  }
+  return index;
+}
+
+export function stripKeyNote(full: string, key: string): string {
+  return full !== key && full.endsWith(`(${key})`)
+    ? full.slice(0, -(key.length + 2))
+    : full;
+}
+

package/src/lib/locales.ts

@@ -0,0 +1,24 @@
+export function createLocaleCatalog(
+  modules: Record<string, unknown>,
+): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(modules).map(([path, messages]) => [
+      path.slice(path.lastIndexOf('/') + 1, -'.json'.length),
+      messages,
+    ]),
+  );
+}
+
+export function createLocaleCatalogs(
+  modules: Record<string, unknown>,
+): Record<string, Record<string, unknown>> {
+  const catalogs: Record<string, Record<string, unknown>> = {};
+  for (const [path, messages] of Object.entries(modules)) {
+    const dir = path.slice(0, path.lastIndexOf('/'));
+    const catalog = dir.slice(dir.lastIndexOf('/') + 1);
+    const lang = path.slice(path.lastIndexOf('/') + 1, -'.json'.length);
+    (catalogs[catalog] ??= {})[lang] = messages;
+  }
+  return catalogs;
+}
+

package/src/lib/registry.server.ts

@@ -0,0 +1,59 @@
+import 'server-only';
+import { createLocaleSet, type LocaleSet } from '@terrafirmagreg-team/translate/create';
+import { translateConfig } from '@terrafirmagreg-team/translate/config';
+import { flattenMessages } from './flatten';
+import { sortLangCodes } from './code';
+import type { LocaleMessages, LocaleRegistry } from '@terrafirmagreg-team/translate/types/locale';
+
+export { sortLangCodes };
+
+const LANG_PATTERN = /^[a-z]{2}(_[a-z0-9]+)?$/i;
+
+let cached: LocaleRegistry | undefined;
+let cachedSet: LocaleSet | undefined;
+
+function flattenAll(
+  raw: Record<string, unknown>,
+  origin: string,
+): Record<string, LocaleMessages> {
+  const messages: Record<string, LocaleMessages> = {};
+  for (const [code, value] of Object.entries(raw)) {
+    if (!LANG_PATTERN.test(code)) {
+      throw new Error(`Invalid locale code "${code}" in ${origin}`);
+    }
+    messages[code] = flattenMessages(value, `${origin}/${code}.json`);
+  }
+  return messages;
+}
+
+function discoverLocaleRegistry(): LocaleRegistry {
+  const catalogs = [translateConfig().locales ?? []].flat();
+
+  const messages: Record<string, LocaleMessages> = {};
+  for (const catalog of catalogs) {
+    const flattened = flattenAll(catalog, 'locales');
+    for (const [lang, catalogMessages] of Object.entries(flattened)) {
+      messages[lang] = { ...messages[lang], ...catalogMessages };
+    }
+  }
+
+  const languages = sortLangCodes(Object.keys(messages));
+  if (languages.length === 0) {
+    throw new Error('No locale messages registered');
+  }
+  const defaultLanguage = languages.includes('en_us')
+    ? 'en_us'
+    : languages[0]!;
+  return { languages, defaultLanguage, messages };
+}
+
+export function loadLocaleRegistry(): LocaleRegistry {
+  cached ??= discoverLocaleRegistry();
+  return cached;
+}
+
+export function loadLocaleSet(): LocaleSet {
+  cachedSet ??= createLocaleSet(loadLocaleRegistry());
+  return cachedSet;
+}
+

package/src/lib/slug.ts

@@ -0,0 +1,30 @@
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+
+export function stripLangFromUrl(
+  url: string,
+  languages: readonly string[],
+): string {
+  const langPathPattern = new RegExp(
+    `\\/(${languages.map((l) => l.replace(/[.*+?^${}()|[\]\\]/g, '\$&')).join('|')})(?=\\/|$)`,
+  );
+  return url.replace(langPathPattern, '');
+}
+
+export function toInternalSlugs(
+  slug: string[] | undefined,
+  lang: Lang,
+): string[] | undefined {
+  if (!slug?.length) return undefined;
+  const [dataset, ...rest] = slug;
+  return [dataset, lang, ...rest];
+}
+
+export function toPublicSlug(
+  slugs: string[],
+  languages: readonly string[],
+): string[] {
+  const [dataset, maybeLang, ...rest] = slugs;
+  if (!dataset || !languages.includes(maybeLang)) return slugs;
+  return [dataset, ...rest];
+}
+

package/src/lib/tree.ts

@@ -0,0 +1,249 @@
+import { cloneElement, isValidElement } from 'react';
+import type * as PageTree from '@terrafirmagreg-team/translate/types/tree';
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+import { isLang } from './code';
+import { loadLocaleRegistry } from './registry.server';
+import { stripLangFromUrl } from './slug';
+
+type LocaleTreeOptions = {
+  languages: readonly string[];
+  fallbackLanguage: string;
+};
+
+function localeTreeOptions(): LocaleTreeOptions {
+  const { languages, defaultLanguage } = loadLocaleRegistry();
+  return { languages, fallbackLanguage: defaultLanguage };
+}
+
+function folderLang(
+  node: PageTree.Folder,
+  languages: readonly string[],
+): Lang | undefined {
+  for (const lang of languages) {
+    if (typeof node.name === 'string' && node.name === lang) return lang;
+
+    const id = node.$id?.split('/').filter(Boolean).at(-1);
+    if (id === lang) return lang;
+  }
+  return undefined;
+}
+
+function rewritePage(
+  page: PageTree.Item,
+  languages: readonly string[],
+): PageTree.Item {
+  return { ...page, url: stripLangFromUrl(page.url, languages) };
+}
+
+function rewriteNodes(
+  nodes: PageTree.Node[],
+  languages: readonly string[],
+): PageTree.Node[] {
+  return nodes.map((node) => {
+    if (node.type === 'page') return rewritePage(node, languages);
+    if (node.type === 'folder') {
+      return {
+        ...node,
+        index: node.index ? rewritePage(node.index, languages) : undefined,
+        children: rewriteNodes(node.children, languages),
+      };
+    }
+    return node;
+  });
+}
+
+function nodeKey(
+  node: PageTree.Node,
+  languages: readonly string[],
+): string | undefined {
+  if (node.type === 'page') return stripLangFromUrl(node.url, languages);
+  if (node.type === 'folder') {
+    if (node.$id) return stripLangFromUrl(`/${node.$id}`, languages);
+    if (node.index) return stripLangFromUrl(node.index.url, languages);
+    return `folder:${String(node.name)}`;
+  }
+  return undefined;
+}
+
+function mergeWithFallback(
+  active: PageTree.Node[],
+  fallback: PageTree.Node[],
+  languages: readonly string[],
+): PageTree.Node[] {
+  const out: PageTree.Node[] = active.map((node) => {
+    if (node.type !== 'folder') return node;
+    const key = nodeKey(node, languages);
+    const fb = fallback.find(
+      (candidate) =>
+        candidate.type === 'folder' && nodeKey(candidate, languages) === key,
+    );
+    if (!fb || fb.type !== 'folder') return node;
+    return {
+      ...node,
+      children: mergeWithFallback(node.children, fb.children, languages),
+    };
+  });
+
+  const keys = new Set(
+    out
+      .map((node) => nodeKey(node, languages))
+      .filter((key): key is string => Boolean(key)),
+  );
+
+  for (const node of fallback) {
+    if (node.type === 'separator') continue;
+    const key = nodeKey(node, languages);
+    if (!key || keys.has(key)) continue;
+    keys.add(key);
+    out.push(node);
+  }
+
+  return out;
+}
+
+function promoteLangFolderChildren(
+  folder: PageTree.Folder,
+  lang: Lang,
+  options: LocaleTreeOptions,
+) {
+  const children = folder.children.filter(
+    (c) => !(c.type === 'page' && /\/index\.mdx?$/.test(c.$id ?? '')),
+  );
+  return rewriteNodes(promoteLang(children, lang, options), options.languages);
+}
+
+function promoteLang(
+  nodes: PageTree.Node[],
+  lang: Lang,
+  options: LocaleTreeOptions,
+): PageTree.Node[] {
+  const { languages, fallbackLanguage } = options;
+  const out: PageTree.Node[] = [];
+
+  for (const node of nodes) {
+    if (node.type !== 'folder') {
+      if (node.type === 'page') {
+        const parts = node.url.split('/').filter(Boolean);
+        const locked = isLang(parts[2] ?? '', languages) ? parts[2] : undefined;
+        if (locked && locked !== lang) continue;
+        out.push(rewritePage(node, languages));
+      } else {
+        out.push(node);
+      }
+      continue;
+    }
+
+    const langOf = folderLang(node, languages);
+    if (langOf) {
+      if (langOf !== lang) continue;
+      out.push(...promoteLangFolderChildren(node, lang, options));
+      continue;
+    }
+
+    const activeLangFolder = node.children.find(
+      (child): child is PageTree.Folder =>
+        child.type === 'folder' && folderLang(child, languages) === lang,
+    );
+    const fallbackLangFolder =
+      lang !== fallbackLanguage
+        ? node.children.find(
+            (child): child is PageTree.Folder =>
+              child.type === 'folder' &&
+              folderLang(child, languages) === fallbackLanguage,
+          )
+        : undefined;
+
+    const rest = node.children.filter((child) => {
+      if (child.type !== 'folder') return true;
+      return folderLang(child, languages) === undefined;
+    });
+
+    let promoted: PageTree.Node[] = [];
+    if (activeLangFolder) {
+      promoted = promoteLangFolderChildren(activeLangFolder, lang, options);
+    }
+    if (fallbackLangFolder) {
+      const fallbackNodes = promoteLangFolderChildren(
+        fallbackLangFolder,
+        fallbackLanguage,
+        options,
+      );
+      const stamped = rewriteNodes(fallbackNodes, languages);
+      promoted = mergeWithFallback(promoted, stamped, languages);
+    }
+    promoted.push(...promoteLang(rest, lang, options));
+
+    const indexPage = activeLangFolder?.index
+      ? rewritePage(activeLangFolder.index, languages)
+      : fallbackLangFolder?.index
+        ? rewritePage(fallbackLangFolder.index, languages)
+        : node.index
+          ? rewritePage(node.index, languages)
+          : undefined;
+
+    const indexUrl = indexPage?.url;
+    const withoutIndex = promoted.filter(
+      (child) => !(child.type === 'page' && indexUrl && child.url === indexUrl),
+    );
+
+    out.push({
+      ...node,
+      index: indexPage,
+      children:
+        indexPage && node.root ? [indexPage, ...withoutIndex] : withoutIndex,
+    });
+  }
+
+  return out;
+}
+
+function withIconKey<T extends PageTree.Node>(node: T, key: string): T {
+  if (node.type === 'separator') return node;
+  if (!isValidElement(node.icon) || node.icon.key != null) return node;
+  return { ...node, icon: cloneElement(node.icon, { key }) };
+}
+
+export function keyTreeNode(node: PageTree.Node): PageTree.Node {
+  switch (node.type) {
+    case 'page':
+      return withIconKey(node, node.url);
+    case 'folder':
+      return {
+        ...withIconKey(node, node.$id ?? node.index?.url ?? String(node.name)),
+        index: node.index ? withIconKey(node.index, node.index.url) : node.index,
+        children: node.children.map(keyTreeNode),
+      };
+    case 'separator':
+      return node;
+    default: {
+      const _never: never = node;
+      return _never;
+    }
+  }
+}
+
+export function localizePageTree(
+  tree: PageTree.Root,
+  lang: Lang,
+  options?: LocaleTreeOptions,
+): PageTree.Root {
+  const opts = options ?? localeTreeOptions();
+  const children = promoteLang(tree.children, lang, opts);
+  const merged =
+    lang === opts.fallbackLanguage
+      ? children
+      : mergeWithFallback(
+          children,
+          rewriteNodes(
+            promoteLang(tree.children, opts.fallbackLanguage, opts),
+            opts.languages,
+          ),
+          opts.languages,
+        );
+  return {
+    ...tree,
+    $id: `${tree.$id ?? 'root'}:${lang}`,
+    children: merged.map(keyTreeNode),
+  };
+}
+

package/src/lib/url.ts

@@ -0,0 +1,92 @@
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+
+const QUERY_SAFE = /[A-Za-z0-9\-._~:/[\]@!$'()*{},;|]/u;
+
+export function encodeQueryValue(value: string): string {
+  return Array.from(value, (ch) =>
+    QUERY_SAFE.test(ch) ? ch : encodeURIComponent(ch),
+  ).join('');
+}
+
+export function encodeQuery(
+  entries: Iterable<readonly [string, string | number | undefined]>,
+): string {
+  const parts: string[] = [];
+  for (const [key, value] of entries) {
+    if (value === undefined || value === '') continue;
+    parts.push(`${encodeQueryValue(key)}=${encodeQueryValue(String(value))}`);
+  }
+  return parts.join('&');
+}
+
+const toQuery = (params: URLSearchParams): string => {
+  const parts: string[] = [];
+  for (const [key, value] of params) {
+    parts.push(`${encodeQueryValue(key)}=${encodeQueryValue(value)}`);
+  }
+  return parts.join('&');
+};
+
+const splitFragment = (fragment: string): { anchor: string; params: URLSearchParams } => {
+  const sep = fragment.indexOf('&');
+  if (sep === -1) return { anchor: fragment, params: new URLSearchParams() };
+  return {
+    anchor: fragment.slice(0, sep),
+    params: new URLSearchParams(fragment.slice(sep + 1)),
+  };
+};
+
+export function langFromFragment(hash: string): string | undefined {
+  if (!hash.includes('&')) return undefined;
+  return splitFragment(hash.startsWith('#') ? hash.slice(1) : hash).params.get('lang') ?? undefined;
+}
+
+let effectiveDefault: Lang | undefined;
+
+export function publishDefaultLang(lang: Lang | undefined): void {
+  effectiveDefault = lang;
+}
+
+export function hrefWithLang(href: string, lang: Lang, fallback?: Lang): string {
+  if (!href || href.startsWith('//')) return href;
+  const hashIndex = href.indexOf('#');
+  const path = hashIndex === -1 ? href : href.slice(0, hashIndex);
+  const fragment = hashIndex === -1 ? '' : href.slice(hashIndex + 1);
+  const qIndex = path.indexOf('?');
+  const qs = qIndex === -1 ? '' : path.slice(qIndex + 1);
+  const existing =
+    new URLSearchParams(qs).get('lang') ?? langFromFragment(fragment) ?? null;
+  const def = fallback ?? effectiveDefault;
+  if (existing !== null) {
+
+    if (existing === def) return withLang(href, def, fallback);
+    return href;
+  }
+  return withLang(href, lang, fallback);
+}
+
+export function withLang(href: string, lang: Lang, fallback?: Lang): string {
+  const isDefault = lang === (fallback ?? effectiveDefault);
+  const hashIndex = href.indexOf('#');
+  const path = hashIndex === -1 ? href : href.slice(0, hashIndex);
+  const fragment = hashIndex === -1 ? '' : href.slice(hashIndex + 1);
+  const qIndex = path.indexOf('?');
+  const pathname = qIndex === -1 ? path : path.slice(0, qIndex);
+  const existing = qIndex === -1 ? '' : path.slice(qIndex + 1);
+  const params = new URLSearchParams(existing);
+  if (!fragment) {
+    if (isDefault) params.delete('lang');
+    else params.set('lang', lang);
+    const q = toQuery(params);
+    return `${pathname}${q ? `?${q}` : ''}`;
+  }
+  const { anchor, params: fragParams } = splitFragment(fragment);
+  params.delete('lang');
+  if (isDefault) fragParams.delete('lang');
+  else fragParams.set('lang', lang);
+  const fragQuery = toQuery(fragParams);
+  const q = toQuery(params);
+  const frag = fragQuery ? `${anchor}&${fragQuery}` : anchor;
+  return `${pathname}${q ? `?${q}` : ''}#${frag}`;
+}
+

package/src/server.ts

@@ -0,0 +1,7 @@
+import 'server-only';
+
+export * from './lib/content';
+export * from './lib/coverage';
+export * from './lib/registry.server';
+export * from './lib/tree';
+

package/src/types/content.ts

@@ -0,0 +1,5 @@
+import type { ReactNode } from 'react';
+import type { Lang } from './locale';
+
+export type LangContent = { lang: Lang; node: ReactNode };
+

package/src/types/locale.ts

@@ -0,0 +1,10 @@
+export type Lang = string;
+
+export type LocaleMessages = Record<string, string>;
+
+export type LocaleRegistry = {
+  languages: string[];
+  defaultLanguage: string;
+  messages: Record<string, LocaleMessages>;
+};
+

package/src/types/tree.ts

@@ -0,0 +1,56 @@
+import type { ReactNode } from 'react';
+
+interface ID {
+
+  $id?: string;
+}
+
+export interface Root extends ID {
+
+  $ref?: Folder['$ref'];
+  type?: 'root';
+  name: ReactNode;
+  description?: ReactNode;
+  children: Node[];
+
+  fallback?: Root;
+}
+
+export type Node = Item | Separator | Folder;
+
+export interface Item extends ID {
+
+  $ref?: string;
+  type: 'page';
+  name: ReactNode;
+  url: string;
+
+  external?: boolean;
+  description?: ReactNode;
+  icon?: ReactNode;
+}
+
+export interface Separator extends ID {
+  type: 'separator';
+  name?: ReactNode;
+  icon?: ReactNode;
+}
+
+export interface Folder extends ID {
+
+  $ref?: {
+    meta?: string;
+    folder: string;
+  };
+  type: 'folder';
+  name: ReactNode;
+  description?: ReactNode;
+
+  root?: boolean | string;
+  defaultOpen?: boolean;
+  collapsible?: boolean;
+  index?: Item;
+  icon?: ReactNode;
+  children: Node[];
+}
+

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.