@etamong-playground/i18n 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 etamong
+
+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

@@ -0,0 +1,77 @@
+# @etamong-playground/i18n
+
+> **About** — One of several small shared libraries used across a personal "fleet" of small apps (error handling · audit logging · encryption-at-rest · i18n · UI · …). Authored and maintained with [Claude Code](https://www.anthropic.com/claude-code) (Anthropic's agentic CLI). Each README documents the design rationale behind the library.
+>
+> **This is a public repository** — keep internal infrastructure details (hostnames, secret/Vault paths, private URLs, internal issue/MR references) out of code, comments, and commit messages.
+
+Shared, framework-agnostic React i18n engine for etamong-playground apps. Plain React
+Context — works in Vite + React and Next.js (App Router, inside a `"use client"`
+boundary). The package owns the **machinery**; each app owns its **dictionaries**.
+
+## Install
+
+```sh
+pnpm add @etamong-playground/i18n
+```
+
+Resolving `@etamong-playground/*` from GitHub Packages requires the registry in `.npmrc`:
+
+```
+@etamong-playground:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=<your-github-token>
+```
+
+## Usage
+
+```ts
+// app/i18n.ts
+import { createI18n } from "@etamong-playground/i18n";
+import ko from "./locales/ko";
+import en from "./locales/en";
+
+export const { I18nProvider, useI18n, LanguageSwitcher } = createI18n({
+  locales: ["ko", "en"] as const,
+  defaultLocale: "ko",
+  dictionaries: { ko, en },
+  labels: { ko: "한국어", en: "English" },
+});
+
+export type Dict = typeof ko; // dictionaries are checked against this shape
+```
+
+```tsx
+// main.tsx
+import { I18nProvider } from "./i18n";
+<I18nProvider>{app}</I18nProvider>;
+
+// any component
+const { t, locale, setLocale } = useI18n(); // t is fully typed
+<h1>{t.landing.title}</h1>;
+<LanguageSwitcher className="lang" />;
+```
+
+`interpolate("{{n}} clicks", { n: 3 })` fills `{{name}}` placeholders.
+
+### Locale resolution order
+
+1. Stored choice (`localStorage["locale"]`, key configurable)
+2. `userLocale` prop (e.g. from auth/profile) — exact or base match
+3. `navigator.language` base match
+4. `defaultLocale`
+
+An explicit stored choice always wins; `userLocale` is adopted only when nothing
+is stored yet.
+
+## Release
+
+Push a `vX.Y.Z` tag — CI publishes to GitHub Packages (`@etamong-playground/i18n`).
+
+The tag must match `version` in `package.json` or the publish job fails.
+
+## Acknowledgements
+
+Built for [React](https://react.dev) (peer dependency, MIT).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/dist/index.cjs

@@ -0,0 +1,102 @@
+'use strict';
+
+var react = require('react');
+var jsxRuntime = require('react/jsx-runtime');
+
+// src/createI18n.tsx
+function safeGet(key) {
+  try {
+    return typeof localStorage !== "undefined" ? localStorage.getItem(key) : null;
+  } catch {
+    return null;
+  }
+}
+function safeSet(key, value) {
+  try {
+    localStorage.setItem(key, value);
+  } catch {
+  }
+}
+function createI18n(config) {
+  const storageKey = config.storageKey ?? "locale";
+  const labels = config.labels ?? Object.fromEntries(config.locales.map((l) => [l, String(l)]));
+  const isLocale = (v) => typeof v === "string" && config.locales.includes(v);
+  function resolve(userLocale) {
+    const stored = safeGet(storageKey);
+    if (isLocale(stored)) return stored;
+    if (userLocale) {
+      if (isLocale(userLocale)) return userLocale;
+      const base = userLocale.split("-")[0];
+      if (isLocale(base)) return base;
+    }
+    if (typeof navigator !== "undefined" && navigator.language) {
+      const nav = navigator.language.split("-")[0];
+      if (isLocale(nav)) return nav;
+    }
+    return config.defaultLocale;
+  }
+  const Ctx = react.createContext({
+    locale: config.defaultLocale,
+    setLocale: () => {
+    },
+    t: config.dictionaries[config.defaultLocale],
+    locales: config.locales,
+    labels
+  });
+  function I18nProvider({ children, userLocale }) {
+    const [locale, setLocaleState] = react.useState(() => resolve(userLocale));
+    const setLocale = react.useCallback((l) => {
+      setLocaleState(l);
+      safeSet(storageKey, l);
+    }, []);
+    react.useEffect(() => {
+      try {
+        document.documentElement.lang = locale;
+      } catch {
+      }
+    }, [locale]);
+    const [seenUserLocale, setSeenUserLocale] = react.useState(userLocale);
+    if (userLocale !== seenUserLocale) {
+      setSeenUserLocale(userLocale);
+      if (userLocale && !safeGet(storageKey)) {
+        setLocaleState(resolve(userLocale));
+      }
+    }
+    const value = {
+      locale,
+      setLocale,
+      t: config.dictionaries[locale],
+      locales: config.locales,
+      labels
+    };
+    return /* @__PURE__ */ jsxRuntime.jsx(Ctx.Provider, { value, children });
+  }
+  function useI18n() {
+    return react.useContext(Ctx);
+  }
+  function LanguageSwitcher({ className, "aria-label": ariaLabel }) {
+    const { locale, setLocale, locales } = useI18n();
+    return /* @__PURE__ */ jsxRuntime.jsx(
+      "select",
+      {
+        className,
+        value: locale,
+        "aria-label": ariaLabel ?? "Language",
+        onChange: (e) => setLocale(e.target.value),
+        children: locales.map((l) => /* @__PURE__ */ jsxRuntime.jsx("option", { value: l, children: labels[l] ?? l }, l))
+      }
+    );
+  }
+  return { I18nProvider, useI18n, LanguageSwitcher };
+}
+
+// src/interpolate.ts
+function interpolate(template, vars) {
+  return template.replace(
+    /\{\{(\w+)\}\}/g,
+    (_, key) => key in vars ? String(vars[key]) : `{{${key}}}`
+  );
+}
+
+exports.createI18n = createI18n;
+exports.interpolate = interpolate;

package/dist/index.d.cts

@@ -0,0 +1,61 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+interface I18nConfig<L extends string, Dict> {
+    /** Supported locale codes, e.g. `["ko", "en", "ja"]`. */
+    locales: readonly L[];
+    /** Locale used when nothing else resolves. */
+    defaultLocale: L;
+    /** One dictionary per locale; all share the same shape (the `Dict` type). */
+    dictionaries: Record<L, Dict>;
+    /** Display names for the language switcher, e.g. `{ ko: "한국어", en: "English", ja: "日本語" }`. */
+    labels?: Record<L, string>;
+    /** localStorage key for the persisted choice. Default `"locale"`. */
+    storageKey?: string;
+}
+interface I18n<L extends string, Dict> {
+    locale: L;
+    setLocale: (locale: L) => void;
+    /** The active locale's dictionary. */
+    t: Dict;
+    locales: readonly L[];
+    labels: Record<L, string>;
+}
+interface I18nProviderProps {
+    children: ReactNode;
+    /** Upstream preference (e.g. from auth/profile). Adopted only when no stored choice exists. */
+    userLocale?: string;
+}
+interface LanguageSwitcherProps {
+    className?: string;
+    "aria-label"?: string;
+}
+/**
+ * Build a typed i18n instance bound to a fixed set of locales and dictionaries.
+ * Framework-agnostic (plain React Context) — works in Vite + React and Next.js
+ * (App Router: render `<I18nProvider>` inside a `"use client"` boundary).
+ *
+ *   const { I18nProvider, useI18n, LanguageSwitcher } = createI18n({
+ *     locales: ["ko", "en", "ja"] as const,
+ *     defaultLocale: "ko",
+ *     dictionaries: { ko, en, ja },
+ *     labels: { ko: "한국어", en: "English", ja: "日本語" },
+ *   });
+ *
+ * `useI18n().t` is fully typed as the dictionary shape.
+ */
+declare function createI18n<L extends string, Dict>(config: I18nConfig<L, Dict>): {
+    I18nProvider: ({ children, userLocale }: I18nProviderProps) => react.JSX.Element;
+    useI18n: () => I18n<L, Dict>;
+    LanguageSwitcher: ({ className, "aria-label": ariaLabel }: LanguageSwitcherProps) => react.JSX.Element;
+};
+
+/**
+ * Replace `{{name}}` placeholders in a template with values from `vars`.
+ * Unknown placeholders are left untouched so missing data is visible, not silent.
+ *
+ *   interpolate("{{n}} clicks", { n: 3 }) // "3 clicks"
+ */
+declare function interpolate(template: string, vars: Record<string, string | number>): string;
+
+export { type I18n, type I18nConfig, type I18nProviderProps, type LanguageSwitcherProps, createI18n, interpolate };

package/dist/index.d.ts

@@ -0,0 +1,61 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+interface I18nConfig<L extends string, Dict> {
+    /** Supported locale codes, e.g. `["ko", "en", "ja"]`. */
+    locales: readonly L[];
+    /** Locale used when nothing else resolves. */
+    defaultLocale: L;
+    /** One dictionary per locale; all share the same shape (the `Dict` type). */
+    dictionaries: Record<L, Dict>;
+    /** Display names for the language switcher, e.g. `{ ko: "한국어", en: "English", ja: "日本語" }`. */
+    labels?: Record<L, string>;
+    /** localStorage key for the persisted choice. Default `"locale"`. */
+    storageKey?: string;
+}
+interface I18n<L extends string, Dict> {
+    locale: L;
+    setLocale: (locale: L) => void;
+    /** The active locale's dictionary. */
+    t: Dict;
+    locales: readonly L[];
+    labels: Record<L, string>;
+}
+interface I18nProviderProps {
+    children: ReactNode;
+    /** Upstream preference (e.g. from auth/profile). Adopted only when no stored choice exists. */
+    userLocale?: string;
+}
+interface LanguageSwitcherProps {
+    className?: string;
+    "aria-label"?: string;
+}
+/**
+ * Build a typed i18n instance bound to a fixed set of locales and dictionaries.
+ * Framework-agnostic (plain React Context) — works in Vite + React and Next.js
+ * (App Router: render `<I18nProvider>` inside a `"use client"` boundary).
+ *
+ *   const { I18nProvider, useI18n, LanguageSwitcher } = createI18n({
+ *     locales: ["ko", "en", "ja"] as const,
+ *     defaultLocale: "ko",
+ *     dictionaries: { ko, en, ja },
+ *     labels: { ko: "한국어", en: "English", ja: "日本語" },
+ *   });
+ *
+ * `useI18n().t` is fully typed as the dictionary shape.
+ */
+declare function createI18n<L extends string, Dict>(config: I18nConfig<L, Dict>): {
+    I18nProvider: ({ children, userLocale }: I18nProviderProps) => react.JSX.Element;
+    useI18n: () => I18n<L, Dict>;
+    LanguageSwitcher: ({ className, "aria-label": ariaLabel }: LanguageSwitcherProps) => react.JSX.Element;
+};
+
+/**
+ * Replace `{{name}}` placeholders in a template with values from `vars`.
+ * Unknown placeholders are left untouched so missing data is visible, not silent.
+ *
+ *   interpolate("{{n}} clicks", { n: 3 }) // "3 clicks"
+ */
+declare function interpolate(template: string, vars: Record<string, string | number>): string;
+
+export { type I18n, type I18nConfig, type I18nProviderProps, type LanguageSwitcherProps, createI18n, interpolate };

package/dist/index.js

@@ -0,0 +1,99 @@
+import { createContext, useState, useCallback, useEffect, useContext } from 'react';
+import { jsx } from 'react/jsx-runtime';
+
+// src/createI18n.tsx
+function safeGet(key) {
+  try {
+    return typeof localStorage !== "undefined" ? localStorage.getItem(key) : null;
+  } catch {
+    return null;
+  }
+}
+function safeSet(key, value) {
+  try {
+    localStorage.setItem(key, value);
+  } catch {
+  }
+}
+function createI18n(config) {
+  const storageKey = config.storageKey ?? "locale";
+  const labels = config.labels ?? Object.fromEntries(config.locales.map((l) => [l, String(l)]));
+  const isLocale = (v) => typeof v === "string" && config.locales.includes(v);
+  function resolve(userLocale) {
+    const stored = safeGet(storageKey);
+    if (isLocale(stored)) return stored;
+    if (userLocale) {
+      if (isLocale(userLocale)) return userLocale;
+      const base = userLocale.split("-")[0];
+      if (isLocale(base)) return base;
+    }
+    if (typeof navigator !== "undefined" && navigator.language) {
+      const nav = navigator.language.split("-")[0];
+      if (isLocale(nav)) return nav;
+    }
+    return config.defaultLocale;
+  }
+  const Ctx = createContext({
+    locale: config.defaultLocale,
+    setLocale: () => {
+    },
+    t: config.dictionaries[config.defaultLocale],
+    locales: config.locales,
+    labels
+  });
+  function I18nProvider({ children, userLocale }) {
+    const [locale, setLocaleState] = useState(() => resolve(userLocale));
+    const setLocale = useCallback((l) => {
+      setLocaleState(l);
+      safeSet(storageKey, l);
+    }, []);
+    useEffect(() => {
+      try {
+        document.documentElement.lang = locale;
+      } catch {
+      }
+    }, [locale]);
+    const [seenUserLocale, setSeenUserLocale] = useState(userLocale);
+    if (userLocale !== seenUserLocale) {
+      setSeenUserLocale(userLocale);
+      if (userLocale && !safeGet(storageKey)) {
+        setLocaleState(resolve(userLocale));
+      }
+    }
+    const value = {
+      locale,
+      setLocale,
+      t: config.dictionaries[locale],
+      locales: config.locales,
+      labels
+    };
+    return /* @__PURE__ */ jsx(Ctx.Provider, { value, children });
+  }
+  function useI18n() {
+    return useContext(Ctx);
+  }
+  function LanguageSwitcher({ className, "aria-label": ariaLabel }) {
+    const { locale, setLocale, locales } = useI18n();
+    return /* @__PURE__ */ jsx(
+      "select",
+      {
+        className,
+        value: locale,
+        "aria-label": ariaLabel ?? "Language",
+        onChange: (e) => setLocale(e.target.value),
+        children: locales.map((l) => /* @__PURE__ */ jsx("option", { value: l, children: labels[l] ?? l }, l))
+      }
+    );
+  }
+  return { I18nProvider, useI18n, LanguageSwitcher };
+}
+
+// src/interpolate.ts
+function interpolate(template, vars) {
+  return template.replace(
+    /\{\{(\w+)\}\}/g,
+    (_, key) => key in vars ? String(vars[key]) : `{{${key}}}`
+  );
+}
+
+export { createI18n, interpolate };

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@etamong-playground/i18n",
+  "version": "0.1.2",
+  "description": "Shared framework-agnostic React i18n engine (typed createI18n factory, provider, hook, interpolate, language switcher) for etamong-lab apps.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.12",
+    "react": "^18.3.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3"
+  },
+  "license": "MIT"
+}