@meursyphus/i18n-llm 0.0.1

package/dist/client.js

@@ -0,0 +1,86 @@
+"use client";
+"use client";
+
+// src/client/use-translations.ts
+import { useContext } from "react";
+
+// src/client/translations-context.tsx
+import { createContext } from "react";
+import { jsx } from "react/jsx-runtime";
+var TranslationsContext = createContext({
+  messages: {},
+  locale: ""
+});
+function ClientTranslationsProvider({
+  messages,
+  locale,
+  children
+}) {
+  return /* @__PURE__ */ jsx(TranslationsContext.Provider, { value: { messages, locale }, children });
+}
+
+// src/shared/interpolate.ts
+function interpolate(template, variables) {
+  return template.replace(/\{(\w+)\}/g, (match, key) => {
+    if (Object.prototype.hasOwnProperty.call(variables, key)) {
+      return String(variables[key]);
+    }
+    return match;
+  });
+}
+
+// src/shared/nested-key-utils.ts
+function getNestedValue(obj, path) {
+  const keys = path.split(".");
+  let value = obj;
+  for (const key of keys) {
+    if (value === null || value === void 0) return void 0;
+    value = value[key];
+  }
+  return value;
+}
+function isReactNode(value) {
+  return value !== null && value !== void 0 && (typeof value === "string" || typeof value === "number" || typeof value === "boolean" || typeof value === "object" && value.$$typeof !== void 0);
+}
+
+// src/client/use-translations.ts
+function useTranslations(namespace) {
+  const { messages } = useContext(TranslationsContext);
+  function t(key, variables) {
+    const namespaceMessages = messages[namespace];
+    const value = getNestedValue(namespaceMessages, key);
+    if (value === void 0 || value === null) {
+      console.warn(
+        `i18n-llm: Translation for key "${String(namespace)}.${key}" not found.`
+      );
+      return key;
+    }
+    if (typeof value === "string") {
+      if (variables) {
+        return interpolate(value, variables);
+      }
+      return value;
+    }
+    if (isReactNode(value)) {
+      return value;
+    }
+    console.warn(
+      `i18n-llm: Translation for key "${String(namespace)}.${key}" is not a valid type.`
+    );
+    return key;
+  }
+  return t;
+}
+
+// src/client/use-current-language.ts
+import { useContext as useContext2 } from "react";
+function useCurrentLanguage() {
+  const { locale } = useContext2(TranslationsContext);
+  return locale;
+}
+export {
+  ClientTranslationsProvider,
+  TranslationsContext,
+  useCurrentLanguage,
+  useTranslations
+};

package/dist/index-KVK-m3p1.d.ts

@@ -0,0 +1,29 @@
+import { ReactNode } from 'react';
+
+interface I18nConfig {
+    defaultLocale: string;
+    locales: readonly string[];
+    messagesPath: string;
+}
+type Messages = Record<string, unknown>;
+type NestedKeyOf<TObj extends object> = {
+    [Key in keyof TObj & (string | number)]: TObj[Key] extends object ? `${Key}` | `${Key}.${NestedKeyOf<TObj[Key]>}` : `${Key}`;
+}[keyof TObj & (string | number)];
+type NestedValueOf<TObj extends object, TPath extends string> = TPath extends `${infer Key}.${infer Rest}` ? Key extends keyof TObj ? TObj[Key] extends object ? NestedValueOf<TObj[Key], Rest> : never : never : TPath extends keyof TObj ? TObj[TPath] : never;
+type InterpolationVariables = Record<string, string | number>;
+type TranslationValue = string | ReactNode;
+interface TranslationsContextType<TMessages = Messages> {
+    messages: TMessages;
+    locale: string;
+}
+interface MiddlewareConfig {
+    locales: string[];
+    defaultLocale: string;
+    localePrefix?: "always" | "as-needed" | "never";
+    redirects?: Array<{
+        from: string;
+        to: string;
+    }>;
+}
+
+export type { InterpolationVariables as I, Messages as M, NestedKeyOf as N, TranslationValue as T, NestedValueOf as a, I18nConfig as b, MiddlewareConfig as c, TranslationsContextType as d };

package/dist/index.d.ts

@@ -0,0 +1,99 @@
+import { M as Messages, N as NestedKeyOf, I as InterpolationVariables, a as NestedValueOf, b as I18nConfig } from './index-KVK-m3p1.js';
+export { c as MiddlewareConfig, T as TranslationValue, d as TranslationsContextType } from './index-KVK-m3p1.js';
+import { ReactNode } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { NextRequest } from 'next/server';
+
+/**
+ * Gets translations for a specific namespace in server components.
+ *
+ * @example
+ * // In a Server Component
+ * const t = await getTranslations('common', lang);
+ * return <h1>{t('title')}</h1>;
+ *
+ * // With variables
+ * return <p>{t('greeting', { name: 'World' })}</p>;
+ */
+declare function getTranslations<TMessages extends Messages, Namespace extends keyof TMessages>(namespace: Namespace, locale: string): Promise<(<Key extends NestedKeyOf<TMessages[Namespace] & object>>(key: Key, variables?: InterpolationVariables) => NestedValueOf<TMessages[Namespace] & object, Key> extends string ? string : NestedValueOf<TMessages[Namespace] & object, Key> extends ReactNode ? ReactNode : string)>;
+
+interface TranslationsProviderProps {
+    children: ReactNode;
+    locale: string;
+}
+/**
+ * Server-side translations provider.
+ * Loads translations and passes them to the client context.
+ *
+ * @example
+ * // In your root layout
+ * export default async function RootLayout({ children, params }) {
+ *   const { lang } = await params;
+ *   return (
+ *     <html lang={lang}>
+ *       <body>
+ *         <TranslationsProvider locale={lang}>
+ *           {children}
+ *         </TranslationsProvider>
+ *       </body>
+ *     </html>
+ *   );
+ * }
+ */
+declare function TranslationsProvider<TMessages extends Messages = Messages>({ children, locale }: TranslationsProviderProps): Promise<react_jsx_runtime.JSX.Element>;
+
+/**
+ * Gets the user's preferred language from the request.
+ * Checks in order: cookie preference, Accept-Language header, default locale.
+ */
+declare function getPreferredLanguage(request: NextRequest): string;
+
+/**
+ * Sets the i18n configuration for message loading.
+ * This should be called once at application startup.
+ */
+declare function setI18nConfig(config: {
+    defaultLocale: string;
+    locales: string[];
+    messagesPath: string;
+}): void;
+/**
+ * Gets the current i18n configuration.
+ */
+declare function getI18nConfig(): {
+    defaultLocale: string;
+    locales: string[];
+    messagesPath: string;
+} | null;
+/**
+ * Loads translation messages for a specific locale.
+ * Falls back to the default locale if the requested locale is not found.
+ */
+declare function loadTranslations<T extends Messages = Messages>(locale: string): Promise<T>;
+/**
+ * Creates a message loader function bound to a specific messages path.
+ * Use this if you need custom message loading logic.
+ */
+declare function createMessageLoader<T extends Messages = Messages>(messagesPath: string, defaultLocale: string, locales: string[]): (locale: string) => Promise<T>;
+
+/**
+ * Helper function to define and initialize i18n configuration.
+ * Call this in your i18n.config.ts file.
+ *
+ * @example
+ * // i18n.config.ts
+ * import { defineI18nConfig } from 'i18n-llm';
+ *
+ * export default defineI18nConfig({
+ *   defaultLocale: 'en',
+ *   locales: ['en', 'ko', 'ja'] as const,
+ *   messagesPath: './messages',
+ * });
+ */
+declare function defineI18nConfig<T extends readonly string[]>(config: {
+    defaultLocale: T[number];
+    locales: T;
+    messagesPath: string;
+}): I18nConfig;
+
+export { I18nConfig, InterpolationVariables, Messages, NestedKeyOf, NestedValueOf, TranslationsProvider, createMessageLoader, defineI18nConfig, getI18nConfig, getPreferredLanguage, getTranslations, loadTranslations, setI18nConfig };

package/dist/index.js

@@ -0,0 +1,122 @@
+import {
+  createMessageLoader,
+  getI18nConfig,
+  loadTranslations,
+  setI18nConfig
+} from "./chunk-OTLHL53Z.js";
+
+// src/shared/interpolate.ts
+function interpolate(template, variables) {
+  return template.replace(/\{(\w+)\}/g, (match, key) => {
+    if (Object.prototype.hasOwnProperty.call(variables, key)) {
+      return String(variables[key]);
+    }
+    return match;
+  });
+}
+
+// src/shared/nested-key-utils.ts
+function getNestedValue(obj, path) {
+  const keys = path.split(".");
+  let value = obj;
+  for (const key of keys) {
+    if (value === null || value === void 0) return void 0;
+    value = value[key];
+  }
+  return value;
+}
+
+// src/server/get-translations.ts
+async function getTranslations(namespace, locale) {
+  const messages = await loadTranslations(locale);
+  function t(key, variables) {
+    const namespaceMessages = messages[namespace];
+    const value = getNestedValue(namespaceMessages, key);
+    if (value === void 0 || value === null) {
+      console.warn(
+        `i18n-llm: Translation for key "${String(namespace)}.${key}" not found.`
+      );
+      return key;
+    }
+    if (typeof value === "string" && variables) {
+      return interpolate(value, variables);
+    }
+    return value;
+  }
+  return t;
+}
+
+// src/client/translations-context.tsx
+import { createContext } from "react";
+import { jsx } from "react/jsx-runtime";
+var TranslationsContext = createContext({
+  messages: {},
+  locale: ""
+});
+function ClientTranslationsProvider({
+  messages,
+  locale,
+  children
+}) {
+  return /* @__PURE__ */ jsx(TranslationsContext.Provider, { value: { messages, locale }, children });
+}
+
+// src/server/translations-provider.tsx
+import { jsx as jsx2 } from "react/jsx-runtime";
+async function TranslationsProvider({ children, locale }) {
+  const messages = await loadTranslations(locale);
+  return /* @__PURE__ */ jsx2(ClientTranslationsProvider, { messages, locale, children });
+}
+
+// src/server/get-preferred-language.ts
+var LANGUAGE_COOKIE_NAME = "preferred-language";
+function getPreferredLanguage(request) {
+  const config = getI18nConfig();
+  if (!config) {
+    console.warn(
+      "i18n-llm: Configuration not set. Returning 'en' as default."
+    );
+    return "en";
+  }
+  const { defaultLocale, locales } = config;
+  const cookieValue = request.cookies.get(LANGUAGE_COOKIE_NAME)?.value;
+  if (cookieValue && locales.includes(cookieValue)) {
+    return cookieValue;
+  }
+  const acceptLanguage = request.headers.get("accept-language");
+  if (acceptLanguage) {
+    const langs = acceptLanguage.split(",").map((lang) => lang.split(";")[0]);
+    for (const lang of langs) {
+      const shortLang = lang.slice(0, 2).toLowerCase();
+      if (locales.includes(shortLang)) {
+        return shortLang;
+      }
+    }
+  }
+  return defaultLocale;
+}
+
+// src/index.ts
+function defineI18nConfig(config) {
+  const i18nConfig = {
+    defaultLocale: config.defaultLocale,
+    locales: config.locales,
+    messagesPath: config.messagesPath
+  };
+  setI18nConfig({
+    defaultLocale: config.defaultLocale,
+    locales: [...config.locales],
+    messagesPath: config.messagesPath
+  });
+  return i18nConfig;
+}
+export {
+  TranslationsProvider,
+  createMessageLoader,
+  defineI18nConfig,
+  getI18nConfig,
+  getPreferredLanguage,
+  getTranslations,
+  loadTranslations,
+  setI18nConfig
+};

package/dist/middleware.d.ts

@@ -0,0 +1,31 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { c as MiddlewareConfig } from './index-KVK-m3p1.js';
+import 'react';
+
+/**
+ * Defines the i18n middleware configuration.
+ * Call this once in your middleware.ts file.
+ *
+ * @example
+ * // middleware.ts
+ * import { defineMiddleware, middleware } from 'i18n-llm/middleware';
+ *
+ * defineMiddleware({
+ *   locales: ['en', 'ko', 'ja'],
+ *   defaultLocale: 'en',
+ * });
+ *
+ * export { middleware };
+ *
+ * export const config = {
+ *   matcher: ['/((?!api|_next|.*\\..*).*)'],
+ * };
+ */
+declare function defineMiddleware(config: MiddlewareConfig): void;
+/**
+ * The i18n middleware function.
+ * Make sure to call defineMiddleware() before exporting this.
+ */
+declare function middleware(request: NextRequest): NextResponse;
+
+export { defineMiddleware, middleware };

package/dist/middleware.js

@@ -0,0 +1,75 @@
+// src/middleware.ts
+import { NextResponse } from "next/server";
+var LANGUAGE_COOKIE_NAME = "preferred-language";
+var middlewareConfig = null;
+function defineMiddleware(config) {
+  middlewareConfig = config;
+}
+function middleware(request) {
+  if (!middlewareConfig) {
+    console.error(
+      "i18n-llm: Middleware not configured. Call defineMiddleware() first."
+    );
+    return NextResponse.next();
+  }
+  const {
+    locales,
+    defaultLocale,
+    localePrefix = "always",
+    redirects = []
+  } = middlewareConfig;
+  const { pathname } = request.nextUrl;
+  if (pathname.startsWith("/_next") || pathname.startsWith("/api") || pathname.includes(".")) {
+    return NextResponse.next();
+  }
+  const pathnameLocale = locales.find(
+    (locale) => pathname.startsWith(`/${locale}/`) || pathname === `/${locale}`
+  );
+  const preferredLocale = getPreferredLocale(request, locales, defaultLocale);
+  if (pathname === "/") {
+    if (localePrefix === "always") {
+      return NextResponse.redirect(
+        new URL(`/${preferredLocale}`, request.url)
+      );
+    }
+    return NextResponse.next();
+  }
+  if (!pathnameLocale) {
+    if (localePrefix === "always") {
+      return NextResponse.redirect(
+        new URL(`/${preferredLocale}${pathname}`, request.url)
+      );
+    }
+    return NextResponse.next();
+  }
+  for (const redirect of redirects) {
+    const pathWithoutLocale = pathname.replace(`/${pathnameLocale}`, "");
+    if (pathWithoutLocale === redirect.from) {
+      return NextResponse.redirect(
+        new URL(`/${pathnameLocale}${redirect.to}`, request.url)
+      );
+    }
+  }
+  return NextResponse.next();
+}
+function getPreferredLocale(request, locales, defaultLocale) {
+  const cookieValue = request.cookies.get(LANGUAGE_COOKIE_NAME)?.value;
+  if (cookieValue && locales.includes(cookieValue)) {
+    return cookieValue;
+  }
+  const acceptLanguage = request.headers.get("accept-language");
+  if (acceptLanguage) {
+    const langs = acceptLanguage.split(",").map((lang) => lang.split(";")[0]);
+    for (const lang of langs) {
+      const shortLang = lang.slice(0, 2).toLowerCase();
+      if (locales.includes(shortLang)) {
+        return shortLang;
+      }
+    }
+  }
+  return defaultLocale;
+}
+export {
+  defineMiddleware,
+  middleware
+};

package/llm.txt

@@ -0,0 +1,254 @@
+# i18n-llm Setup Guide
+
+You are setting up i18n-llm for a Next.js App Router project.
+Follow these steps exactly in order.
+
+## Step 1: Install the package
+
+Run this command:
+```bash
+npm install @meursyphus/i18n-llm
+```
+
+## Step 2: Create i18n.config.ts in project root
+
+Create file `i18n.config.ts`:
+```typescript
+import { defineI18nConfig } from '@meursyphus/i18n-llm';
+
+export default defineI18nConfig({
+  defaultLocale: 'en',
+  locales: ['en', 'ko'] as const,
+  messagesPath: './messages',
+});
+
+export type Locale = 'en' | 'ko';
+```
+
+## Step 3: Create middleware.ts in project root
+
+Create file `middleware.ts`:
+```typescript
+import { defineMiddleware, middleware } from '@meursyphus/i18n-llm/middleware';
+
+defineMiddleware({
+  locales: ['en', 'ko'],
+  defaultLocale: 'en',
+});
+
+export { middleware };
+
+export const config = {
+  matcher: ['/((?!api|_next|.*\\..*).*)'],
+};
+```
+
+## Step 4: Create messages directory structure
+
+Create these files:
+
+`messages/types.ts`:
+```typescript
+export interface Messages {
+  common: {
+    title: string;
+    greeting: string; // "Hello, {name}!"
+  };
+}
+```
+
+`messages/en/index.ts`:
+```typescript
+import type { Messages } from '../types';
+
+const messages: Messages = {
+  common: {
+    title: 'Welcome',
+    greeting: 'Hello, {name}!',
+  },
+};
+
+export default messages;
+```
+
+`messages/ko/index.ts`:
+```typescript
+import type { Messages } from '../types';
+
+const messages: Messages = {
+  common: {
+    title: '환영합니다',
+    greeting: '안녕하세요, {name}님!',
+  },
+};
+
+export default messages;
+```
+
+## Step 5: Update app directory structure
+
+Rename `app/` contents to `app/[lang]/`:
+
+Before:
+```
+app/
+├── layout.tsx
+├── page.tsx
+└── about/page.tsx
+```
+
+After:
+```
+app/
+└── [lang]/
+    ├── layout.tsx
+    ├── page.tsx
+    └── about/page.tsx
+```
+
+## Step 6: Update layout.tsx
+
+Replace `app/[lang]/layout.tsx`:
+```typescript
+import { TranslationsProvider } from '@meursyphus/i18n-llm';
+
+interface LayoutProps {
+  children: React.ReactNode;
+  params: Promise<{ lang: string }>;
+}
+
+export default async function RootLayout({ children, params }: LayoutProps) {
+  const { lang } = await params;
+
+  return (
+    <html lang={lang}>
+      <body>
+        <TranslationsProvider locale={lang}>
+          {children}
+        </TranslationsProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+## Step 7: Use translations in components
+
+Server Component:
+```typescript
+import { getTranslations } from '@meursyphus/i18n-llm';
+
+export default async function Page({ params }: { params: Promise<{ lang: string }> }) {
+  const { lang } = await params;
+  const t = await getTranslations('common', lang);
+
+  return (
+    <div>
+      <h1>{t('title')}</h1>
+      <p>{t('greeting', { name: 'World' })}</p>
+    </div>
+  );
+}
+```
+
+Client Component:
+```typescript
+'use client';
+
+import { useTranslations } from '@meursyphus/i18n-llm/client';
+
+export function Greeting({ name }: { name: string }) {
+  const t = useTranslations('common');
+
+  return <p>{t('greeting', { name })}</p>;
+}
+```
+
+## Step 8: Language Switcher (Optional)
+
+Create a language switcher component:
+```typescript
+'use client';
+
+import { useCurrentLanguage } from '@meursyphus/i18n-llm/client';
+import { setLanguagePreference } from '@meursyphus/i18n-llm/actions';
+import { usePathname } from 'next/navigation';
+
+export function LanguageSwitcher() {
+  const currentLang = useCurrentLanguage();
+  const pathname = usePathname();
+
+  const handleChange = async (locale: string) => {
+    await setLanguagePreference(locale, pathname);
+  };
+
+  return (
+    <select value={currentLang} onChange={(e) => handleChange(e.target.value)}>
+      <option value="en">English</option>
+      <option value="ko">한국어</option>
+    </select>
+  );
+}
+```
+
+## Step 9: Generate Metadata (Optional)
+
+Use translations in generateMetadata:
+```typescript
+import { getTranslations } from '@meursyphus/i18n-llm';
+import type { Metadata } from 'next';
+
+interface PageProps {
+  params: Promise<{ lang: string }>;
+}
+
+export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
+  const { lang } = await params;
+  const t = await getTranslations('common', lang);
+
+  return {
+    title: t('title'),
+    description: t('description'),
+  };
+}
+```
+
+## Setup Complete!
+
+i18n-llm has been configured successfully.
+The app now supports English (en) and Korean (ko).
+
+To add more locales:
+1. Add locale to `locales` array in `i18n.config.ts`
+2. Add locale to `locales` array in `middleware.ts` (in defineMiddleware)
+3. Create new message file at `messages/{locale}/index.ts`
+
+## Variable Interpolation
+
+Use `{variableName}` in translations:
+
+```typescript
+// In messages file
+"greeting": "Hello, {name}! You have {count} new messages."
+
+// In component
+t('greeting', { name: 'John', count: 5 })
+// Output: "Hello, John! You have 5 new messages."
+```
+
+## Nested Keys
+
+Access nested translations with dot notation:
+
+```typescript
+// In messages file
+{
+  nav: {
+    home: 'Home',
+    about: 'About',
+  }
+}
+
+// In component
+t('nav.home')  // "Home"
+```