@jant/core 0.2.2 → 0.2.4

package/src/i18n/README.md

@@ -0,0 +1,296 @@
+# Jant i18n - React-like API for Hono JSX
+
+## ✅ API Overview
+
+We provide a React-like i18n API that works with Hono JSX SSR!
+
+### 1. **I18nProvider** - Like React Context Provider
+
+```tsx
+import { I18nProvider } from "@/i18n";
+
+// Wrap your app in route handler
+dashRoute.get("/", async (c) => {
+  return c.html(
+    <I18nProvider c={c}>
+      <YourApp />
+    </I18nProvider>
+  );
+});
+```
+
+### 2. **useLingui()** - Like React hook
+
+```tsx
+import { useLingui } from "@/i18n";
+
+function MyComponent() {
+  // React-like hook API
+  const { t } = useLingui();
+
+  return (
+    <div>
+      {/* Simple and clean */}
+      <h1>{t({ message: "Dashboard", comment: "@context: Page title" })}</h1>
+    </div>
+  );
+}
+```
+
+### 3. **Trans Component** - For Embedded JSX
+
+```tsx
+import { Trans } from "@/i18n";
+
+function MyComponent() {
+  return (
+    <Trans comment="@context: Help text">
+      Read the <a href="/docs">documentation</a>
+    </Trans>
+  );
+}
+```
+
+---
+
+## 📝 Complete Example
+
+```tsx
+/**
+ * Dashboard Route - React-like i18n API
+ */
+
+import { Hono } from "hono";
+import { I18nProvider, useLingui, Trans } from "@/i18n";
+
+export const dashRoute = new Hono();
+
+// Component: use useLingui() hook
+function DashboardContent({ postCount }: { postCount: number }) {
+  const { t } = useLingui();
+
+  return (
+    <div>
+      {/* 1. Simple translation */}
+      <h1>{t({ message: "Dashboard", comment: "@context: Page title" })}</h1>
+
+      {/* 2. With variables */}
+      <p>
+        {t(
+          { message: "You have {count} posts", comment: "@context: Post count message" },
+          { count: postCount }
+        )}
+      </p>
+
+      {/* 3. With embedded components - use Trans */}
+      <p>
+        <Trans comment="@context: Help text">
+          Read the <a href="/docs" class="underline">documentation</a>
+        </Trans>
+      </p>
+    </div>
+  );
+}
+
+// Route handler: wrap in I18nProvider
+dashRoute.get("/", async (c) => {
+  const posts = await c.var.services.posts.list();
+
+  return c.html(
+    <I18nProvider c={c}>
+      <DashboardContent postCount={posts.length} />
+    </I18nProvider>
+  );
+});
+```
+
+---
+
+## 🆚 Comparison: Before vs Now
+
+### Before (Complex - prop drilling)
+
+```tsx
+import { getI18n } from "@/i18n";
+
+dashRoute.get("/", async (c) => {
+  const i18n = getI18n(c);
+
+  return c.html(
+    <Layout title={i18n._({ message: "Dashboard", comment: "@context: ..." })}>
+      <MyComponent c={c} />  {/* Need to pass c prop */}
+    </Layout>
+  );
+});
+
+function MyComponent({ c }: { c: Context }) {
+  const i18n = getI18n(c);
+  return <h1>{i18n._({ message: "Hello", comment: "@context: ..." })}</h1>;
+}
+```
+
+### Now (Clean - no prop drilling)
+
+```tsx
+import { I18nProvider, useLingui } from "@/i18n";
+
+dashRoute.get("/", async (c) => {
+  return c.html(
+    <I18nProvider c={c}>
+      <Layout>
+        <MyComponent />  {/* No need to pass c prop */}
+      </Layout>
+    </I18nProvider>
+  );
+});
+
+function MyComponent() {
+  const { t } = useLingui();  // Like React hook
+  return <h1>{t({ message: "Hello", comment: "@context: ..." })}</h1>;
+}
+```
+
+---
+
+## ⚠️ Important Notes
+
+### 1. **Always include `comment` field**
+
+```tsx
+// ✅ Correct - comment is crucial for AI translation
+const { t } = useLingui();
+t({ message: "Dashboard", comment: "@context: Page title" })
+
+// ❌ Wrong - missing comment reduces translation quality
+t({ message: "Dashboard" })
+```
+
+### 2. **I18nProvider must wrap your app**
+
+```tsx
+// ✅ Correct - wrap in I18nProvider
+c.html(
+  <I18nProvider c={c}>
+    <App />
+  </I18nProvider>
+)
+
+// ❌ Wrong - useLingui() will throw error
+c.html(<App />)  // useLingui() inside App won't find i18n context
+```
+
+### 3. **useLingui() only works inside components**
+
+```tsx
+// ✅ Correct - inside JSX component
+function MyComponent() {
+  const { t } = useLingui();
+  return <div>{t({ message: "Hello", comment: "@context: ..." })}</div>;
+}
+
+// ❌ Wrong - in route handler (outside I18nProvider)
+dashRoute.get("/", async (c) => {
+  const { t } = useLingui();  // Error: not inside I18nProvider
+  ...
+});
+```
+
+### 4. **Variables go in second parameter**
+
+```tsx
+const { t } = useLingui();
+
+// ✅ Correct - values as second parameter
+t({ message: "Hello {name}", comment: "@context: Greeting" }, { name: "Alice" })
+
+// ❌ Wrong - values inside first parameter (not supported)
+t({ message: "Hello {name}", comment: "@context: Greeting", values: { name: "Alice" } })
+```
+
+---
+
+## 🎯 Best Practices
+
+1. **Route handler**: Wrap app in `<I18nProvider c={c}>`
+2. **Inside components**: Use `useLingui()` hook to get `t()` function
+3. **Translation calls**: `t({ message: "...", comment: "@context: ..." })`
+4. **With embedded JSX**: Use `<Trans>` component
+5. **Always include `comment`**: Helps AI understand context for better translations
+
+---
+
+## 📚 API Reference
+
+### `I18nProvider`
+
+Provides i18n context to all child components. Must wrap your app in route handlers.
+
+```tsx
+interface I18nProviderProps {
+  c: Context;  // Hono context
+  children: JSX.Element;
+}
+
+// Usage
+<I18nProvider c={c}>
+  <YourApp />
+</I18nProvider>
+```
+
+### `useLingui()`
+
+Hook to access i18n functionality inside components. Must be used within `I18nProvider`.
+
+```tsx
+function useLingui(): {
+  i18n: I18n;  // Lingui i18n instance
+  t: (descriptor: MessageDescriptor, values?: Record<string, any>) => string;
+  _: (descriptor: MessageDescriptor, values?: Record<string, any>) => string;
+}
+
+// Usage
+function MyComponent() {
+  const { t } = useLingui();
+  return <h1>{t({ message: "Hello", comment: "@context: Greeting" })}</h1>;
+}
+```
+
+**Note**: `t()` and `_()` are equivalent - use whichever you prefer.
+
+### `Trans`
+
+Component for translations with embedded JSX elements. Simplified implementation that renders children as-is.
+
+```tsx
+interface TransProps {
+  comment?: string;  // @context comment for translators
+  id?: string;       // Optional message ID
+  children: JSX.Element;  // JSX content with embedded elements
+}
+
+// Usage
+<Trans comment="@context: Help text">
+  Read the <a href="/docs">documentation</a>
+</Trans>
+```
+
+**Note**: This is a simplified implementation. For complex translations with dynamic content, use `t()` with placeholders instead.
+
+---
+
+## 🔧 How It Works
+
+1. **I18nProvider** sets the global i18n instance during rendering
+2. **useLingui()** reads the current i18n instance from global state
+3. **Single-pass rendering**: Each request renders only once, making global state safe
+4. **Concurrency-safe**: Each request creates a new i18n instance, preventing race conditions
+
+This implementation mimics React's Context API but is optimized for Hono JSX SSR scenarios.
+
+### Why Global State is Safe
+
+Unlike React (client-side with multiple re-renders), Hono JSX renders once per request on the server:
+- Request arrives → I18nProvider sets global i18n → Components render → Response sent
+- Next request → New i18n instance → Components render → Response sent
+
+Since rendering is synchronous and single-pass, there's no risk of concurrent requests interfering with each other.

package/src/i18n/Trans.tsx

@@ -0,0 +1,31 @@
+/**
+ * Trans Component for Hono JSX
+ *
+ * Simple implementation that just renders children directly.
+ * For complex translations with embedded JSX, use the t() function with placeholders.
+ */
+
+import type { FC, PropsWithChildren } from "hono/jsx";
+
+export interface TransProps extends PropsWithChildren {
+  comment?: string;
+  id?: string;
+}
+
+/**
+ * Trans component - renders children as-is
+ * Note: This is a simplified implementation. For translations with embedded JSX,
+ * it's recommended to use t() with placeholders instead.
+ *
+ * @example
+ * ```tsx
+ * <Trans comment="@context: Help text">
+ *   Visit the <a href="/docs">documentation</a>
+ * </Trans>
+ * ```
+ */
+export const Trans: FC<TransProps> = ({ children }) => {
+  // In a full implementation, this would extract and translate the content
+  // For now, we just render children as-is (works for English/default locale)
+  return <>{children}</>;
+};

package/src/i18n/context.tsx

@@ -0,0 +1,101 @@
+/**
+ * Hono JSX i18n Context System
+ *
+ * Mimics React's Context API for Hono JSX to provide i18n without prop drilling
+ */
+
+import type { Context } from "hono";
+import type { FC, PropsWithChildren } from "hono/jsx";
+import type { I18n, MessageDescriptor } from "@lingui/core";
+import { getI18n as getI18nFromContext } from "./i18n.js";
+
+/**
+ * Message descriptor that accepts both pre-macro (without id) and post-macro (with id) formats
+ * This allows TypeScript to accept t({ message, comment }) before macro transformation
+ */
+type TranslationDescriptor = {
+  id?: string;
+  message: string;
+  comment?: string;
+  values?: Record<string, any>; // eslint-disable-line @typescript-eslint/no-explicit-any
+};
+
+// Store i18n instance during render
+let currentI18n: I18n | null = null;
+
+/**
+ * I18nProvider - wraps your app to provide i18n context
+ *
+ * @example
+ * ```tsx
+ * import { I18nProvider } from "@/i18n";
+ *
+ * return c.html(
+ *   <I18nProvider c={c}>
+ *     <YourApp />
+ *   </I18nProvider>
+ * );
+ * ```
+ */
+export interface I18nProviderProps extends PropsWithChildren {
+  c: Context;
+}
+
+export const I18nProvider: FC<I18nProviderProps> = ({ c, children }) => {
+  // Set current i18n for this render
+  // Note: In Hono JSX, rendering is synchronous and single-threaded per request
+  // so we can safely set global context without cleanup
+  currentI18n = getI18nFromContext(c);
+  return <>{children}</>;
+};
+
+/**
+ * useLingui hook - get i18n instance and translation function
+ * Mimics @lingui/react's useLingui() API
+ *
+ * @example
+ * ```tsx
+ * import { t } from "@lingui/core/macro";
+ * import { useLingui } from "@/i18n";
+ *
+ * function MyComponent() {
+ *   const { t: _ } = useLingui();  // Use _ to avoid conflict with macro
+ *
+ *   return (
+ *     <div>
+ *       <h1>{_(t({ message: "Dashboard", comment: "@context: Page title" }))}</h1>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * Or use the i18n instance directly:
+ * ```tsx
+ * const { i18n } = useLingui();
+ * i18n._(t({ message: "Dashboard", comment: "@context: Page title" }))
+ * ```
+ */
+export function useLingui() {
+  if (!currentI18n) {
+    throw new Error(
+      "useLingui() called outside of I18nProvider. " +
+      "Make sure your component is wrapped in <I18nProvider c={c}>...</I18nProvider>"
+    );
+  }
+
+  // Create translation function that accepts both pre-macro and post-macro formats
+  const translate = (descriptor: TranslationDescriptor) => {
+    // The macro will add the id, or it's already present
+    // At runtime, we pass it to i18n._ which handles the descriptor with values
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- currentI18n is checked above
+    return currentI18n!._(descriptor as MessageDescriptor);
+  };
+
+  return {
+    i18n: currentI18n,
+    // t function - can be used with t macro from @lingui/core/macro
+    t: translate,
+    // _ is an alias for t (shorter)
+    _: translate,
+  };
+}

package/src/i18n/detect.ts

@@ -0,0 +1,100 @@
+/**
+ * Language Detection Utilities
+ */
+
+import type { Context } from "hono";
+import { locales, baseLocale, isLocale, type Locale } from "./locales.js";
+
+export const LANGUAGE_COOKIE_NAME = "lang";
+
+/**
+ * Get display name for a language code
+ */
+export function getLanguageDisplayName(locale: Locale): string {
+  const names: Record<Locale, string> = {
+    en: "English",
+    "zh-Hans": "简体中文",
+    "zh-Hant": "繁體中文",
+  };
+  return names[locale];
+}
+
+/**
+ * Get all supported languages with display names
+ */
+export function getSupportedLanguages(): Array<{ code: Locale; name: string }> {
+  return locales.map((code) => ({
+    code,
+    name: getLanguageDisplayName(code),
+  }));
+}
+
+/**
+ * Check if a language code is valid
+ */
+export function isValidLanguage(lang: unknown): lang is Locale {
+  return isLocale(lang);
+}
+
+/**
+ * Parse Accept-Language header and return best matching locale
+ */
+export function parseAcceptLanguage(header: string | null): Locale {
+  if (!header) return baseLocale;
+
+  // Parse "en-US,en;q=0.9,zh-CN;q=0.8" format
+  const languages = header
+    .split(",")
+    .map((part) => {
+      const [lang, qPart] = part.trim().split(";");
+      const q = qPart ? parseFloat(qPart.replace("q=", "")) : 1;
+      return { lang: lang?.trim() ?? "", q };
+    })
+    .sort((a, b) => b.q - a.q);
+
+  for (const { lang } of languages) {
+    // Direct match
+    if (isLocale(lang)) {
+      return lang;
+    }
+
+    // Map common variants
+    const normalized = lang.toLowerCase();
+    if (normalized.startsWith("zh-cn") || normalized.startsWith("zh-hans")) {
+      return "zh-Hans";
+    }
+    if (
+      normalized.startsWith("zh-tw") ||
+      normalized.startsWith("zh-hk") ||
+      normalized.startsWith("zh-hant")
+    ) {
+      return "zh-Hant";
+    }
+    if (normalized.startsWith("zh")) {
+      return "zh-Hans"; // Default Chinese to Simplified
+    }
+    if (normalized.startsWith("en")) {
+      return "en";
+    }
+  }
+
+  return baseLocale;
+}
+
+/**
+ * Detect user's preferred language from Hono context
+ * Priority: Cookie > Accept-Language header > Default
+ */
+export function detectLanguage(c: Context): Locale {
+  // 1. Check cookie (using getCookie helper)
+  const cookies = c.req.raw.headers.get("Cookie") ?? "";
+  const cookieMatch = cookies.match(new RegExp(`${LANGUAGE_COOKIE_NAME}=([^;]+)`));
+  const cookieLang = cookieMatch?.[1];
+  if (cookieLang && isLocale(cookieLang)) {
+    return cookieLang;
+  }
+
+  // 2. Check Accept-Language header
+  const acceptLang = c.req.header("Accept-Language") ?? null;
+  return parseAcceptLanguage(acceptLang);
+}

package/src/i18n/i18n.ts

@@ -0,0 +1,62 @@
+/**
+ * i18n Runtime using @lingui/core with Lingui macros
+ *
+ * Usage:
+ *   import { msg } from "@lingui/core/macro";
+ *   import { bindI18n } from "@/i18n";
+ *
+ *   const { i18n } = bindI18n(c.get("i18n"));
+ *
+ *   // Simple message
+ *   i18n._(msg({ message: "Hello", comment: "@context: Greeting" }))
+ *
+ *   // With interpolation
+ *   i18n._(msg({ message: "Welcome, {name}!", comment: "@context: Welcome" }), { name })
+ *
+ * The msg macro generates hash-based IDs at compile time, which match the compiled catalogs.
+ */
+
+import { I18n } from "@lingui/core";
+import { locales, baseLocale, isLocale, type Locale } from "./locales.js";
+import { messages as messagesEn } from "./locales/en.js";
+import { messages as messagesZhHans } from "./locales/zh-Hans.js";
+import { messages as messagesZhHant } from "./locales/zh-Hant.js";
+
+export { locales, baseLocale, isLocale, type Locale };
+
+// Export I18n type for convenience
+export type { I18n };
+
+/**
+ * Create a new i18n instance for a specific locale.
+ * IMPORTANT: In Cloudflare Workers (concurrent environment), we must create
+ * a new instance per request to avoid race conditions. Never use a global instance!
+ */
+export function createI18n(locale: Locale): I18n {
+  const i18n = new I18n({});
+
+  // Load all catalogs with English as fallback
+  i18n.load("en", messagesEn);
+  i18n.load("zh-Hans", { ...messagesEn, ...messagesZhHans });
+  i18n.load("zh-Hant", { ...messagesEn, ...messagesZhHant });
+
+  // Activate locale after loading messages to avoid warnings
+  i18n.activate(locale);
+
+  return i18n;
+}
+
+/**
+ * Helper to get the per-request i18n instance from Hono context.
+ * Use this in route handlers.
+ *
+ * @example
+ * import { msg } from "@lingui/core/macro";
+ * import { getI18n } from "@/i18n";
+ *
+ * const i18n = getI18n(c);
+ * const title = i18n._(msg({ message: "Dashboard", comment: "@context: Page title" }));
+ */
+export function getI18n(c: { get(key: "i18n"): I18n }): I18n {
+  return c.get("i18n");
+}

package/src/i18n/index.ts

@@ -0,0 +1,65 @@
+/**
+ * i18n Module
+ *
+ * IMPORTANT: This module is designed for concurrent environments (Cloudflare Workers).
+ * We create a new i18n instance per request to avoid race conditions.
+ *
+ * This is a custom implementation compatible with Hono JSX (SSR), not React.
+ * It provides a React-like API using Lingui macros with a custom context system.
+ *
+ * Usage:
+ * ```tsx
+ * import { useLingui, Trans, I18nProvider } from "@/i18n";
+ *
+ * // Wrap your app in I18nProvider (automatically done by BaseLayout when c is provided)
+ * c.html(
+ *   <I18nProvider c={c}>
+ *     <MyApp />
+ *   </I18nProvider>
+ * );
+ *
+ * // Inside components, use useLingui() hook
+ * function MyApp() {
+ *   const { t } = useLingui();
+ *
+ *   return (
+ *     <div>
+ *       <h1>{t({ message: "Dashboard", comment: "@context: Page title" })}</h1>
+ *       <Trans comment="@context: Help text">
+ *         Read the <a href="/docs">documentation</a>
+ *       </Trans>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+
+// Core i18n runtime
+export {
+  createI18n,
+  getI18n,
+  locales,
+  baseLocale,
+  isLocale,
+  type Locale,
+  type I18n,
+} from "./i18n.js";
+
+// I18nProvider and useLingui hook (custom implementation for Hono JSX, SSR-compatible)
+export { I18nProvider, useLingui } from "./context.js";
+
+// Trans component (simplified for Hono JSX)
+export { Trans } from "./Trans.js";
+
+// Language detection utilities
+export {
+  detectLanguage,
+  isValidLanguage,
+  parseAcceptLanguage,
+  getLanguageDisplayName,
+  getSupportedLanguages,
+  LANGUAGE_COOKIE_NAME,
+} from "./detect.js";
+
+// Hono middleware
+export { i18nMiddleware } from "./middleware.js";