@hua-labs/i18n-core 2.2.0 → 2.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present HUA Labs
+
+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

@@ -1,6 +1,6 @@
 # @hua-labs/i18n-core
 
-Lightweight, production-ready i18n library for React. Delivers zero-flicker language transitions through intelligent caching, SSR-first hydration handling, and built-in state management integration. ~6.5KB gzipped with zero dependencies (React only).
+Lightweight, production-ready i18n library for React. Delivers zero-flicker language transitions through intelligent caching, SSR-first hydration handling, and built-in state management integration. ~7KB gzipped with zero dependencies (React only).
 
 [![npm version](https://img.shields.io/npm/v/@hua-labs/i18n-core.svg)](https://www.npmjs.com/package/@hua-labs/i18n-core)
 [![npm downloads](https://img.shields.io/npm/dm/@hua-labs/i18n-core.svg)](https://www.npmjs.com/package/@hua-labs/i18n-core)
@@ -18,7 +18,7 @@ Lightweight, production-ready i18n library for React. Delivers zero-flicker lang
 - **State management — First-class Zustand support via i18n-core-zustand**
 - **Automatic retry — Exponential backoff for API loader failures**
 - **React Native — Works in Expo and bare RN projects via CJS/ESM dual format**
-- **~6.5KB gzipped — Zero external dependencies**
+- **~7KB gzipped — Zero external dependencies**
 - **Cross-platform — I18nPlatformAdapter for Web, React Native, Flutter bridge**
 - **Generic getRawValue<T>() — type-safe raw value access without casting**
 
@@ -68,8 +68,8 @@ function Welcome() {
 | `Translator` | class | Core translator class (for manual instantiation) |
 | `ssrTranslate` | function | Server-side translation function (no React needed) |
 | `serverTranslate` | function | Server-side translate with full config |
-| `webPlatformAdapter` | function | Default web adapter — navigator.language detection + window event language sync |
-| `headlessPlatformAdapter` | function | No-op adapter for SSR, testing, and Flutter bridge scenarios |
+| `webPlatformAdapter` | adapter | Default web adapter — navigator.language detection + window event language sync |
+| `headlessPlatformAdapter` | adapter | No-op adapter for SSR, testing, and Flutter bridge scenarios |
 | `I18nConfig` | type |  |
 | `I18nContextType` | type |  |
 | `TranslationParams` | type |  |

package/dist/{chunk-7ZYOSEMW.mjs → chunk-4IYWT7MS.mjs}

@@ -1,7 +1,15 @@
 // src/types/index.ts
-var PLURAL_CATEGORIES = /* @__PURE__ */ new Set(["zero", "one", "two", "few", "many", "other"]);
+var PLURAL_CATEGORIES = /* @__PURE__ */ new Set([
+  "zero",
+  "one",
+  "two",
+  "few",
+  "many",
+  "other"
+]);
 function isPluralValue(value) {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  if (typeof value !== "object" || value === null || Array.isArray(value))
+    return false;
   const obj = value;
   const keys = Object.keys(obj);
   return keys.length > 0 && keys.every((k) => PLURAL_CATEGORIES.has(k)) && Object.values(obj).every((v) => typeof v === "string") && typeof obj.other === "string";
@@ -99,7 +107,9 @@ var Translator = class {
     this.currentLang = config.defaultLanguage;
     if (config.initialTranslations) {
       this.allTranslations = config.initialTranslations;
-      for (const [language, namespaces] of Object.entries(config.initialTranslations)) {
+      for (const [language, namespaces] of Object.entries(
+        config.initialTranslations
+      )) {
         for (const namespace of Object.keys(namespaces)) {
           this.loadedNamespaces.add(`${language}:${namespace}`);
         }
@@ -197,9 +207,15 @@ var Translator = class {
         }
       }
       if (this.config.debug) {
-        console.log("\u{1F30D} [TRANSLATOR] Initializing translator with languages:", languages);
+        console.log(
+          "\u{1F30D} [TRANSLATOR] Initializing translator with languages:",
+          languages
+        );
         console.log("\u{1F4CD} [TRANSLATOR] Current language:", this.currentLang);
-        console.log("\u{1F4E6} [TRANSLATOR] Config namespaces:", this.config.namespaces);
+        console.log(
+          "\u{1F4E6} [TRANSLATOR] Config namespaces:",
+          this.config.namespaces
+        );
       }
       for (const language of languages) {
         if (this.config.debug) {
@@ -212,12 +228,23 @@ var Translator = class {
           const cacheKey = `${language}:${namespace}`;
           if (skipNamespaces.has(cacheKey)) {
             if (this.config.debug) {
-              console.log("\u23ED\uFE0F [TRANSLATOR] Skipping", namespace, "for", language, "(already loaded from SSR)");
+              console.log(
+                "\u23ED\uFE0F [TRANSLATOR] Skipping",
+                namespace,
+                "for",
+                language,
+                "(already loaded from SSR)"
+              );
             }
             continue;
           }
           if (this.config.debug) {
-            console.log("Loading namespace:", namespace, "for language:", language);
+            console.log(
+              "Loading namespace:",
+              namespace,
+              "for language:",
+              language
+            );
           }
           try {
             const data = await this.safeLoadTranslations(language, namespace);
@@ -237,7 +264,10 @@ var Translator = class {
             if (isRecoverableError(translationError)) {
               if (language !== this.config.fallbackLanguage) {
                 try {
-                  const fallbackData = await this.safeLoadTranslations(this.config.fallbackLanguage || "en", namespace);
+                  const fallbackData = await this.safeLoadTranslations(
+                    this.config.fallbackLanguage || "en",
+                    namespace
+                  );
                   this.allTranslations[language][namespace] = fallbackData;
                   this.loadedNamespaces.add(`${language}:${namespace}`);
                   if (this.config.debug) {
@@ -275,7 +305,9 @@ var Translator = class {
       this.logError(this.initializationError);
       this.isInitialized = true;
       if (this.config.debug) {
-        console.warn("Translator initialized with errors, using fallback translations");
+        console.warn(
+          "Translator initialized with errors, using fallback translations"
+        );
       }
     }
   }
@@ -290,7 +322,10 @@ var Translator = class {
     const result = this.findInNamespace(namespace, actualKey, targetLang);
     if (result) {
       if (this.config.debug) {
-        console.log(`\u2705 [TRANSLATOR] Found fallback translation from initialTranslations:`, result);
+        console.log(
+          `\u2705 [TRANSLATOR] Found fallback translation from initialTranslations:`,
+          result
+        );
       }
       return result;
     }
@@ -354,10 +389,17 @@ var Translator = class {
     }
     if (!this.isInitialized) {
       const raw = this.translateBeforeInitialized(key, targetLang);
+      if ((!raw || raw === key) && params && typeof params === "object" && "defaultValue" in params && typeof params.defaultValue === "string") {
+        return this.interpolate(params.defaultValue, params);
+      }
       return params ? this.interpolate(raw, params) : raw;
     }
     const { namespace, key: actualKey } = this.parseKey(key);
-    let result = this.findInNamespace(namespace, actualKey, targetLang);
+    let result = this.findInNamespace(
+      namespace,
+      actualKey,
+      targetLang
+    );
     if (result) {
       this.cacheStats.hits++;
       return params ? this.interpolate(result, params) : result;
@@ -371,6 +413,9 @@ var Translator = class {
       return params ? this.interpolate(result, params) : result;
     }
     this.cacheStats.misses++;
+    if (params && typeof params === "object" && "defaultValue" in params && typeof params.defaultValue === "string") {
+      return this.interpolate(params.defaultValue, params);
+    }
     if (this.config.debug) {
       const missing = this.config.missingKeyHandler?.(key, targetLang, namespace) || key;
       return params ? this.interpolate(missing, params) : missing;
@@ -387,11 +432,16 @@ var Translator = class {
       if (!this.loadedNamespaces.has(cacheKey) && !this.loadingPromises.has(cacheKey)) {
         this.loadTranslationData(language, namespace).catch((error) => {
           if (this.config.debug) {
-            console.warn(`\u26A0\uFE0F [TRANSLATOR] Auto-load failed for ${language}/${namespace}:`, error);
+            console.warn(
+              `\u26A0\uFE0F [TRANSLATOR] Auto-load failed for ${language}/${namespace}:`,
+              error
+            );
           }
         });
         if (this.config.debug) {
-          console.warn(`\u274C [TRANSLATOR] No translations found for ${language}/${namespace}, attempting auto-load...`);
+          console.warn(
+            `\u274C [TRANSLATOR] No translations found for ${language}/${namespace}, attempting auto-load...`
+          );
         }
       }
       return "";
@@ -411,7 +461,9 @@ var Translator = class {
       return nestedValue[Math.floor(Math.random() * nestedValue.length)];
     }
     if (this.config.debug) {
-      console.warn(`\u274C [TRANSLATOR] No match found for key: ${key} in ${language}/${namespace}`);
+      console.warn(
+        `\u274C [TRANSLATOR] No match found for key: ${key} in ${language}/${namespace}`
+      );
     }
     return "";
   }
@@ -477,7 +529,10 @@ var Translator = class {
         if (actualKey in fallbackTranslations) {
           return fallbackTranslations[actualKey];
         }
-        const fallbackNestedValue = this.getNestedValue(fallbackTranslations, actualKey);
+        const fallbackNestedValue = this.getNestedValue(
+          fallbackTranslations,
+          actualKey
+        );
         if (fallbackNestedValue !== void 0) {
           return fallbackNestedValue;
         }
@@ -523,7 +578,9 @@ var Translator = class {
     const raw = this.getRawValue(key, targetLang);
     const mergedParams = { count, ...params };
     if (isPluralValue(raw)) {
-      const category = this.getPluralRules(targetLang).select(count);
+      const category = this.getPluralRules(targetLang).select(
+        count
+      );
       const text = raw[category] ?? raw.other;
       return this.interpolate(text, mergedParams);
     }
@@ -566,7 +623,9 @@ var Translator = class {
       });
     }
     if (this.config.debug) {
-      console.log(`\u{1F310} [TRANSLATOR] Language changed: ${previousLanguage} -> ${language}`);
+      console.log(
+        `\u{1F310} [TRANSLATOR] Language changed: ${previousLanguage} -> ${language}`
+      );
     }
   }
   /**
@@ -678,7 +737,11 @@ var Translator = class {
    */
   logError(error) {
     if (this.config.errorHandler) {
-      this.config.errorHandler(error, error.language || "", error.namespace || "");
+      this.config.errorHandler(
+        error,
+        error.language || "",
+        error.namespace || ""
+      );
     }
   }
   /**
@@ -701,7 +764,9 @@ var Translator = class {
         if (attempt === maxRetries) {
           break;
         }
-        await new Promise((resolve) => setTimeout(resolve, Math.pow(2, attempt) * 1e3));
+        await new Promise(
+          (resolve) => setTimeout(resolve, Math.pow(2, attempt) * 1e3)
+        );
       }
     }
     throw lastError;
@@ -711,21 +776,29 @@ var Translator = class {
    */
   async safeLoadTranslations(language, namespace) {
     if (this.config.debug) {
-      console.log(`\u{1F4E5} [TRANSLATOR] safeLoadTranslations called:`, { language, namespace });
+      console.log(`\u{1F4E5} [TRANSLATOR] safeLoadTranslations called:`, {
+        language,
+        namespace
+      });
     }
     const loadOperation = async () => {
       if (!this.config.loadTranslations) {
         throw new Error("No translation loader configured");
       }
       if (this.config.debug) {
-        console.log(`\u{1F504} [TRANSLATOR] Calling loadTranslations for:`, { language, namespace });
+        console.log(`\u{1F504} [TRANSLATOR] Calling loadTranslations for:`, {
+          language,
+          namespace
+        });
       }
       const data = await this.config.loadTranslations(language, namespace);
       if (this.config.debug) {
         console.log(`\u{1F4E6} [TRANSLATOR] loadTranslations returned:`, data);
       }
       if (!isTranslationNamespace(data)) {
-        throw new Error(`Invalid translation data for ${language}:${namespace}`);
+        throw new Error(
+          `Invalid translation data for ${language}:${namespace}`
+        );
       }
       return data;
     };
@@ -738,7 +811,10 @@ var Translator = class {
         language,
         namespace
       );
-      return this.retryOperation(loadOperation, translationError, { language, namespace });
+      return this.retryOperation(loadOperation, translationError, {
+        language,
+        namespace
+      });
     }
   }
   /**
@@ -775,35 +851,30 @@ var Translator = class {
     if (!this.isInitialized) {
       await this.initialize();
     }
-    const translated = this.translate(key);
-    if (!params) {
-      return translated;
-    }
-    return this.interpolate(translated, params);
+    return this.translate(key, params);
   }
   /**
    * 동기 번역 (고급 기능)
    */
   translateSync(key, params) {
     if (!this.isInitialized) {
+      if (params && typeof params === "object" && "defaultValue" in params && typeof params.defaultValue === "string") {
+        return this.interpolate(params.defaultValue, params);
+      }
       if (this.config.debug) {
         console.warn("Translator not initialized for sync translation");
       }
       const { namespace } = this.parseKey(key);
       return this.config.missingKeyHandler?.(key, this.currentLang, namespace) || key;
     }
-    const translated = this.translate(key);
-    if (!params) {
-      return translated;
-    }
-    return this.interpolate(translated, params);
+    return this.translate(key, params);
   }
   /**
    * 키 파싱 (네임스페이스:키 형식)
-   * 
+   *
    * - 콜론(:)만 네임스페이스 구분자로 사용
    * - 점(.)은 키 이름의 일부로 취급 (중첩 객체 접근용)
-   * 
+   *
    * @example
    * parseKey("home:hero.badge") → { namespace: "home", key: "hero.badge" }
    * parseKey("hero.badge") → { namespace: "common", key: "hero.badge" }
@@ -812,7 +883,10 @@ var Translator = class {
   parseKey(key) {
     const colonIndex = key.indexOf(":");
     if (colonIndex !== -1) {
-      return { namespace: key.substring(0, colonIndex), key: key.substring(colonIndex + 1) };
+      return {
+        namespace: key.substring(0, colonIndex),
+        key: key.substring(colonIndex + 1)
+      };
     }
     return { namespace: "common", key };
   }
@@ -851,7 +925,9 @@ var Translator = class {
       this.loadedNamespaces.add(cacheKey);
       this.setCacheEntry(cacheKey, data);
       if (this.config.debug) {
-        console.log(`\u2705 [TRANSLATOR] Auto-loaded and saved ${language}/${namespace}`);
+        console.log(
+          `\u2705 [TRANSLATOR] Auto-loaded and saved ${language}/${namespace}`
+        );
       }
       this.notifyTranslationLoaded(language, namespace);
       return data;
@@ -869,7 +945,9 @@ var Translator = class {
     try {
       const data = await this.config.loadTranslations(language, namespace);
       if (!isTranslationNamespace(data)) {
-        throw new Error(`Invalid translation data for ${language}:${namespace}`);
+        throw new Error(
+          `Invalid translation data for ${language}:${namespace}`
+        );
       }
       return data;
     } catch (error) {
@@ -892,12 +970,20 @@ function ssrTranslate({
   missingKeyHandler = (key2) => key2
 }) {
   const { namespace, key: actualKey } = parseKey(key);
-  let result = ssrFindInNamespace(translations, namespace, actualKey, language);
+  let result = ssrFindInNamespace(
+    translations,
+    namespace,
+    actualKey,
+    language);
   if (result) {
     return result;
   }
   if (language !== fallbackLanguage) {
-    result = ssrFindInNamespace(translations, namespace, actualKey, fallbackLanguage);
+    result = ssrFindInNamespace(
+      translations,
+      namespace,
+      actualKey,
+      fallbackLanguage);
     if (result) {
       return result;
     }
@@ -936,7 +1022,10 @@ function isStringValue(value) {
 function parseKey(key) {
   const colonIndex = key.indexOf(":");
   if (colonIndex !== -1) {
-    return { namespace: key.substring(0, colonIndex), key: key.substring(colonIndex + 1) };
+    return {
+      namespace: key.substring(0, colonIndex),
+      key: key.substring(colonIndex + 1)
+    };
   }
   return { namespace: "common", key };
 }
@@ -958,7 +1047,11 @@ function serverTranslate({
       return cached;
     }
   }
-  const result = findInTranslations(translations, key, language, fallbackLanguage);
+  const result = findInTranslations(
+    translations,
+    key,
+    language,
+    fallbackLanguage);
   if (cache && result) {
     const cacheKey = `${language}:${key}`;
     cache.set(cacheKey, result);
@@ -974,7 +1067,12 @@ function findInTranslations(translations, key, language, fallbackLanguage, missi
     return result;
   }
   if (language !== fallbackLanguage) {
-    result = findInNamespace(translations, namespace, actualKey, fallbackLanguage);
+    result = findInNamespace(
+      translations,
+      namespace,
+      actualKey,
+      fallbackLanguage
+    );
     if (result) {
       return result;
     }
@@ -1002,5 +1100,5 @@ function findInNamespace(translations, namespace, key, language) {
 }
 
 export { Translator, headlessPlatformAdapter, serverTranslate, ssrTranslate, validateI18nConfig, webPlatformAdapter };
-//# sourceMappingURL=chunk-7ZYOSEMW.mjs.map
-//# sourceMappingURL=chunk-7ZYOSEMW.mjs.map
+//# sourceMappingURL=chunk-4IYWT7MS.mjs.map
+//# sourceMappingURL=chunk-4IYWT7MS.mjs.map