npm - @meursyphus/i18n-llm - Versions diffs - 0.0.1 - Mend

@meursyphus/i18n-llm 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2024 MeurSyphus
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,244 @@
+# i18n-llm
+LLM-friendly Next.js i18n library with type-safe translations.
+## Features
+- **LLM-readable documentation**: Copy-paste `llm.txt` to set up i18n instantly
+- **Type-safe translations**: Full TypeScript support with key autocomplete
+- **Variable interpolation**: `t("greeting", { name: "John" })`
+- **Zero dependencies**: Only requires Next.js and React
+- **App Router only**: Built specifically for Next.js 14+ App Router
+- **Server & Client components**: Works seamlessly in both
+## Installation
+```bash
+npm install @meursyphus/i18n-llm
+```
+## Quick Start
+### 1. Initialize (CLI)
+```bash
+npx i18n-llm init --locales en,ko --default en
+```
+Or follow the manual setup in [llm.txt](./llm.txt).
+### 2. Wrap your app
+```tsx
+// app/[lang]/layout.tsx
+import { TranslationsProvider } from '@meursyphus/i18n-llm';
+export default async function RootLayout({ children, params }) {
+  const { lang } = await params;
+  return (
+    <html lang={lang}>
+      <body>
+        <TranslationsProvider locale={lang}>
+          {children}
+        </TranslationsProvider>
+      </body>
+    </html>
+  );
+}
+```
+### 3. Use translations
+**Server Component:**
+```tsx
+import { getTranslations } from '@meursyphus/i18n-llm';
+export default async function Page({ params }) {
+  const { lang } = await params;
+  const t = await getTranslations('common', lang);
+  return <h1>{t('greeting', { name: 'World' })}</h1>;
+}
+```
+**Client Component:**
+```tsx
+'use client';
+import { useTranslations } from '@meursyphus/i18n-llm/client';
+export function Greeting({ name }) {
+  const t = useTranslations('common');
+  return <p>{t('greeting', { name })}</p>;
+}
+```
+## API Reference
+### Server Exports (`i18n-llm`)
+| Export | Description |
+|--------|-------------|
+| `getTranslations(namespace, locale)` | Get translation function for server components |
+| `TranslationsProvider` | Provider component for client components |
+| `defineI18nConfig(config)` | Define i18n configuration |
+| `getPreferredLanguage(request)` | Get user's preferred language from request |
+### Client Exports (`i18n-llm/client`)
+| Export | Description |
+|--------|-------------|
+| `useTranslations(namespace)` | Hook to get translation function |
+| `useCurrentLanguage()` | Hook to get current locale |
+### Middleware (`i18n-llm/middleware`)
+| Export | Description |
+|--------|-------------|
+| `defineMiddleware(config)` | Configure i18n middleware |
+| `middleware` | The middleware function to export |
+### Actions (`i18n-llm/actions`)
+| Export | Description |
+|--------|-------------|
+| `setLanguagePreference(locale, path)` | Server action to change language |
+| `getLanguagePreference()` | Get stored language preference |
+## Configuration
+### i18n.config.ts
+```typescript
+import { defineI18nConfig } from '@meursyphus/i18n-llm';
+export default defineI18nConfig({
+  defaultLocale: 'en',
+  locales: ['en', 'ko', 'ja'] as const,
+  messagesPath: './messages',
+});
+```
+### middleware.ts
+```typescript
+import { defineMiddleware, middleware } from '@meursyphus/i18n-llm/middleware';
+defineMiddleware({
+  locales: ['en', 'ko', 'ja'],
+  defaultLocale: 'en',
+});
+export { middleware };
+export const config = {
+  matcher: ['/((?!api|_next|.*\\..*).*)'],
+};
+```
+## Message Files
+### Structure
+```
+messages/
+├── types.ts          # Type definitions
+├── en/
+│   └── index.ts      # English translations
+├── ko/
+│   └── index.ts      # Korean translations
+└── ja/
+    └── index.ts      # Japanese translations
+```
+### Type Definition
+```typescript
+// messages/types.ts
+export interface Messages {
+  common: {
+    title: string;
+    greeting: string;  // "Hello, {name}!"
+    nav: {
+      home: string;
+      about: string;
+    };
+  };
+}
+```
+### Translation File
+```typescript
+// messages/en/index.ts
+import type { Messages } from '../types';
+const messages: Messages = {
+  common: {
+    title: 'Welcome',
+    greeting: 'Hello, {name}!',
+    nav: {
+      home: 'Home',
+      about: 'About',
+    },
+  },
+};
+export default messages;
+```
+## Variable Interpolation
+Use `{variableName}` placeholders in your translations:
+```typescript
+// Message
+"greeting": "Hello, {name}! You have {count} messages."
+// Usage
+t('greeting', { name: 'John', count: 5 });
+// Output: "Hello, John! You have 5 messages."
+```
+## Language Switcher
+```tsx
+'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>
+      <option value="ja">日本語</option>
+    </select>
+  );
+}
+```
+## CLI Commands
+```bash
+# Initialize i18n-llm in your project
+npx i18n-llm init --locales en,ko --default en
+# Add a new locale
+npx i18n-llm add-locale ja --name "日本語"
+```
+## LLM Setup
+For AI-assisted setup, copy the contents of [llm.txt](./llm.txt) to your AI assistant.
+## License
+MIT

package/dist/actions.d.ts ADDED Viewed

@@ -0,0 +1,29 @@
+/**
+ * Server action to set the user's language preference.
+ * Updates the cookie and redirects to the new locale path.
+ *
+ * @example
+ * 'use client';
+ * import { setLanguagePreference } from 'i18n-llm/actions';
+ *
+ * function LanguageSwitcher() {
+ *   const handleChange = async (locale: string) => {
+ *     await setLanguagePreference(locale, window.location.pathname);
+ *   };
+ *
+ *   return (
+ *     <select onChange={(e) => handleChange(e.target.value)}>
+ *       <option value="en">English</option>
+ *       <option value="ko">한국어</option>
+ *     </select>
+ *   );
+ * }
+ */
+declare function setLanguagePreference(locale: string, currentPath: string): Promise<void>;
+/**
+ * Gets the user's stored language preference from cookies.
+ * Returns null if no preference is set.
+ */
+declare function getLanguagePreference(): Promise<string | null>;
+export { getLanguagePreference, setLanguagePreference };

package/dist/actions.js ADDED Viewed

@@ -0,0 +1,37 @@
+"use server";
+import {
+  getI18nConfig
+} from "./chunk-OTLHL53Z.js";
+// src/actions.ts
+import { cookies } from "next/headers";
+import { redirect } from "next/navigation";
+var LANGUAGE_COOKIE_NAME = "preferred-language";
+var COOKIE_MAX_AGE = 60 * 60 * 24 * 365;
+async function setLanguagePreference(locale, currentPath) {
+  const config = getI18nConfig();
+  if (config && !config.locales.includes(locale)) {
+    throw new Error(`i18n-llm: Unsupported locale: ${locale}`);
+  }
+  const cookieStore = await cookies();
+  cookieStore.set(LANGUAGE_COOKIE_NAME, locale, {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === "production",
+    sameSite: "lax",
+    maxAge: COOKIE_MAX_AGE,
+    path: "/"
+  });
+  const pathSegments = currentPath.split("/");
+  pathSegments[1] = locale;
+  const newPath = pathSegments.join("/");
+  redirect(newPath);
+}
+async function getLanguagePreference() {
+  const cookieStore = await cookies();
+  const cookie = cookieStore.get(LANGUAGE_COOKIE_NAME);
+  return cookie?.value || null;
+}
+export {
+  getLanguagePreference,
+  setLanguagePreference
+};

package/dist/chunk-OTLHL53Z.js ADDED Viewed

@@ -0,0 +1,75 @@
+// src/shared/load-translations.ts
+var cachedConfig = null;
+function setI18nConfig(config) {
+  cachedConfig = config;
+}
+function getI18nConfig() {
+  return cachedConfig;
+}
+async function loadTranslations(locale) {
+  if (!cachedConfig) {
+    throw new Error(
+      "i18n-llm: Configuration not set. Call setI18nConfig() first or use defineI18nConfig() in your i18n.config.ts file."
+    );
+  }
+  const { defaultLocale, locales, messagesPath } = cachedConfig;
+  const isSupported = locales.includes(locale);
+  const localeToLoad = isSupported ? locale : defaultLocale;
+  try {
+    const messages = await import(
+      /* @vite-ignore */
+      `${messagesPath}/${localeToLoad}`
+    ).then((module) => module.default);
+    return messages;
+  } catch (error) {
+    console.error(
+      `i18n-llm: Failed to load messages for locale: ${localeToLoad}`,
+      error
+    );
+    if (localeToLoad !== defaultLocale) {
+      const fallbackMessages = await import(
+        /* @vite-ignore */
+        `${messagesPath}/${defaultLocale}`
+      ).then((module) => module.default);
+      return fallbackMessages;
+    }
+    throw new Error(
+      `i18n-llm: Failed to load default locale messages (${defaultLocale}).`
+    );
+  }
+}
+function createMessageLoader(messagesPath, defaultLocale, locales) {
+  return async (locale) => {
+    const isSupported = locales.includes(locale);
+    const localeToLoad = isSupported ? locale : defaultLocale;
+    try {
+      const messages = await import(
+        /* @vite-ignore */
+        `${messagesPath}/${localeToLoad}`
+      ).then((module) => module.default);
+      return messages;
+    } catch (error) {
+      console.error(
+        `i18n-llm: Failed to load messages for locale: ${localeToLoad}`,
+        error
+      );
+      if (localeToLoad !== defaultLocale) {
+        const fallbackMessages = await import(
+          /* @vite-ignore */
+          `${messagesPath}/${defaultLocale}`
+        ).then((module) => module.default);
+        return fallbackMessages;
+      }
+      throw new Error(
+        `i18n-llm: Failed to load default locale messages (${defaultLocale}).`
+      );
+    }
+  };
+}
+export {
+  setI18nConfig,
+  getI18nConfig,
+  loadTranslations,
+  createMessageLoader
+};

package/dist/cli/index.js ADDED Viewed

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+// cli/index.ts
+import { Command } from "commander";
+// cli/commands/init.ts
+import * as fs from "fs";
+import * as path from "path";
+function init(options) {
+  const locales = options.locales.split(",").map((l) => l.trim());
+  const defaultLocale = options.default;
+  console.log("\n\u{1F30D} Initializing i18n-llm...\n");
+  const dirs = ["messages", ...locales.map((l) => `messages/${l}`)];
+  for (const dir of dirs) {
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+      console.log(`  \u2713 Created ${dir}/`);
+    }
+  }
+  const configContent = `import { defineI18nConfig } from '@meursyphus/i18n-llm';
+export default defineI18nConfig({
+  defaultLocale: '${defaultLocale}',
+  locales: [${locales.map((l) => `'${l}'`).join(", ")}] as const,
+  messagesPath: './messages',
+});
+export type Locale = ${locales.map((l) => `'${l}'`).join(" | ")};
+`;
+  fs.writeFileSync("i18n.config.ts", configContent);
+  console.log("  \u2713 Created i18n.config.ts");
+  const middlewareContent = `import { defineMiddleware, middleware } from '@meursyphus/i18n-llm/middleware';
+defineMiddleware({
+  locales: [${locales.map((l) => `'${l}'`).join(", ")}],
+  defaultLocale: '${defaultLocale}',
+});
+export { middleware };
+export const config = {
+  matcher: ['/((?!api|_next|.*\\\\..*).*)'],
+};
+`;
+  fs.writeFileSync("middleware.ts", middlewareContent);
+  console.log("  \u2713 Created middleware.ts");
+  const typesContent = `export interface Messages {
+  common: CommonMessages;
+}
+export interface CommonMessages {
+  title: string;
+  greeting: string; // "Hello, {name}!"
+}
+`;
+  fs.writeFileSync("messages/types.ts", typesContent);
+  console.log("  \u2713 Created messages/types.ts");
+  const messageTemplates = {
+    en: `import type { Messages } from '../types';
+const messages: Messages = {
+  common: {
+    title: 'Welcome',
+    greeting: 'Hello, {name}!',
+  },
+};
+export default messages;
+`,
+    ko: `import type { Messages } from '../types';
+const messages: Messages = {
+  common: {
+    title: '\uD658\uC601\uD569\uB2C8\uB2E4',
+    greeting: '\uC548\uB155\uD558\uC138\uC694, {name}\uB2D8!',
+  },
+};
+export default messages;
+`,
+    ja: `import type { Messages } from '../types';
+const messages: Messages = {
+  common: {
+    title: '\u3088\u3046\u3053\u305D',
+    greeting: '\u3053\u3093\u306B\u3061\u306F\u3001{name}\u3055\u3093\uFF01',
+  },
+};
+export default messages;
+`,
+    zh: `import type { Messages } from '../types';
+const messages: Messages = {
+  common: {
+    title: '\u6B22\u8FCE',
+    greeting: '\u4F60\u597D\uFF0C{name}\uFF01',
+  },
+};
+export default messages;
+`
+  };
+  const defaultTemplate = `import type { Messages } from '../types';
+const messages: Messages = {
+  common: {
+    title: 'Welcome',
+    greeting: 'Hello, {name}!',
+  },
+};
+export default messages;
+`;
+  for (const locale of locales) {
+    const content = messageTemplates[locale] || defaultTemplate;
+    const filePath = path.join("messages", locale, "index.ts");
+    fs.writeFileSync(filePath, content);
+    console.log(`  \u2713 Created ${filePath}`);
+  }
+  console.log(`
+\u2705 i18n-llm initialized successfully!
+Next steps:
+1. Move your app/ contents to app/[lang]/
+2. Update your root layout to use TranslationsProvider:
+   import { TranslationsProvider } from '@meursyphus/i18n-llm';
+   export default async function RootLayout({ children, params }) {
+     const { lang } = await params;
+     return (
+       <html lang={lang}>
+         <body>
+           <TranslationsProvider locale={lang}>
+             {children}
+           </TranslationsProvider>
+         </body>
+       </html>
+     );
+   }
+3. Use translations in your components:
+   // Server Component
+   import { getTranslations } from '@meursyphus/i18n-llm';
+   const t = await getTranslations('common', lang);
+   // Client Component
+   import { useTranslations } from '@meursyphus/i18n-llm/client';
+   const t = useTranslations('common');
+`);
+}
+// cli/commands/add-locale.ts
+import * as fs2 from "fs";
+import * as path2 from "path";
+function addLocale(locale, options) {
+  const displayName = options.name || locale.toUpperCase();
+  console.log(`
+\u{1F30D} Adding locale: ${locale} (${displayName})
+`);
+  if (!fs2.existsSync("messages")) {
+    console.error("\u274C Error: messages/ directory not found.");
+    console.error("   Run 'npx i18n-llm init' first to set up your project.");
+    process.exit(1);
+  }
+  const localeDir = path2.join("messages", locale);
+  if (fs2.existsSync(localeDir)) {
+    console.error(`\u274C Error: Locale '${locale}' already exists.`);
+    process.exit(1);
+  }
+  fs2.mkdirSync(localeDir, { recursive: true });
+  console.log(`  \u2713 Created ${localeDir}/`);
+  const existingLocales = fs2.readdirSync("messages").filter(
+    (f) => fs2.statSync(path2.join("messages", f)).isDirectory() && f !== locale
+  );
+  if (existingLocales.length > 0) {
+    const sourceLocale = existingLocales[0];
+    const sourceDir = path2.join("messages", sourceLocale);
+    const files = fs2.readdirSync(sourceDir).filter((f) => f.endsWith(".ts") || f.endsWith(".tsx"));
+    for (const file of files) {
+      const sourcePath = path2.join(sourceDir, file);
+      const targetPath = path2.join(localeDir, file);
+      const content = fs2.readFileSync(sourcePath, "utf-8");
+      const modifiedContent = `// TODO: Translate this file to ${displayName}
+${content}`;
+      fs2.writeFileSync(targetPath, modifiedContent);
+      console.log(`  \u2713 Created ${targetPath}`);
+    }
+  } else {
+    const defaultContent = `// TODO: Translate this file to ${displayName}
+import type { Messages } from '../types';
+const messages: Messages = {
+  common: {
+    title: 'Welcome',
+    greeting: 'Hello, {name}!',
+  },
+};
+export default messages;
+`;
+    fs2.writeFileSync(path2.join(localeDir, "index.ts"), defaultContent);
+    console.log(`  \u2713 Created ${path2.join(localeDir, "index.ts")}`);
+  }
+  console.log(`
+\u2705 Locale '${locale}' added successfully!
+Next steps:
+1. Update your i18n.config.ts to include '${locale}' in the locales array
+2. Update your middleware.ts to include '${locale}' in the locales array
+3. Translate the message files in messages/${locale}/
+`);
+}
+// cli/index.ts
+var program = new Command();
+program.name("i18n-llm").description("LLM-friendly i18n library for Next.js").version("0.1.0");
+program.command("init").description("Initialize i18n-llm in your Next.js project").option("-l, --locales <locales>", "Comma-separated list of locales", "en,ko").option("-d, --default <locale>", "Default locale", "en").action(init);
+program.command("add-locale").description("Add a new locale to your project").argument("<locale>", "Locale code to add (e.g., ja, zh, fr)").option("-n, --name <name>", "Display name for the locale").action(addLocale);
+program.parse();