Skip to Content

Development diagnostics

Collect locale, fallback, missing-key, namespace, and route diagnostics without adding DevTools to production bundles.

@puzzle-ui/i18n/devtools is an opt-in React panel. The separate subpath is not imported by the runtime; dynamically import it only in development builds.

import { lazy, Suspense } from "react";
import { createI18n } from "@puzzle-ui/i18n";

const diagnosticsModule = import.meta.env.DEV
  ? await import("@puzzle-ui/i18n/devtools")
  : undefined;
const diagnostics = diagnosticsModule?.createI18nDiagnostics();
const i18n = createI18n({
  locales: [{ locale: "en" }, { locale: "nl" }],
  defaultLocale: "en",
  catalogs: { en: { greeting: "Hello" }, nl: {} },
  onEvent: diagnostics.record,
});

const I18nDevTools = import.meta.env.DEV
  ? lazy(() =>
      import("@puzzle-ui/i18n/devtools").then((module) => ({
        default: module.I18nDevTools,
      })),
    )
  : null;

Render the panel under a Suspense boundary when it is available. The runtime reports missing keys, fallbacks, and lazy namespace load states. The bounded diagnostics store keeps a recent event history and supports subscriptions and clearing.

Framework request adapters can automatically add safe, pathname-only route events when given the localized route map and the diagnostics callback:

import { createTanStackLocaleLoader } from "@puzzle-ui/i18n/tanstack";

const resolveLocale = createTanStackLocaleLoader({
  registry: i18n.registry,
  routes: localizedRoutes,
  onRoute: diagnostics.record,
});

export const Route = createFileRoute("/$locale/articles/$slug")({
  loader: (args) => resolveLocale(args),
});

Loaders report matched, redirected, or unmatched plus the route ID when available. The diagnostic pathname is the canonical route template (for example /articles/:slug), not the concrete URL; unmatched paths use a sentinel. Events omit query strings, fragments, and parameter values. Configure a route map to avoid reporting unrelated paths as localized route matches.