@hua-labs/i18n-loaders 1.1.1 → 2.0.2

package/README.md

@@ -1,93 +1,78 @@
 # @hua-labs/i18n-loaders
 
-Translation loaders with caching and preloading for @hua-labs/i18n-core.
-캐싱 및 프리로딩 기능을 갖춘 번역 로더.
+Production-ready translation loaders with built-in TTL caching, duplicate request prevention, and namespace preloading. Designed to work seamlessly with @hua-labs/i18n-core. Supports both server and client environments.
 
 [![npm version](https://img.shields.io/npm/v/@hua-labs/i18n-loaders.svg)](https://www.npmjs.com/package/@hua-labs/i18n-loaders)
-[![npm downloads](https://img.shields.io/npm/dw/@hua-labs/i18n-loaders.svg)](https://www.npmjs.com/package/@hua-labs/i18n-loaders)
+[![npm downloads](https://img.shields.io/npm/dm/@hua-labs/i18n-loaders.svg)](https://www.npmjs.com/package/@hua-labs/i18n-loaders)
 [![license](https://img.shields.io/npm/l/@hua-labs/i18n-loaders.svg)](https://github.com/HUA-Labs/HUA-Labs-public/blob/main/LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue)](https://www.typescriptlang.org/)
 [![React](https://img.shields.io/badge/React-19-blue)](https://reactjs.org/)
 
-> **Alpha**: APIs may change before stable release. | **알파**: 안정 릴리스 전 API가 변경될 수 있습니다.
-
-## Overview | 개요
-
-Production-ready translation loaders with built-in TTL caching, duplicate request prevention, and namespace preloading. Designed to work seamlessly with @hua-labs/i18n-core. Supports both server and client environments.
-
-TTL 캐싱, 중복 요청 방지, 네임스페이스 프리로딩이 내장된 프로덕션 레디 번역 로더입니다. @hua-labs/i18n-core와 원활하게 작동하도록 설계되었습니다. 서버/클라이언트 환경 모두 지원합니다.
-
 ## Features
 
-- **API loader** — `createApiTranslationLoader` with configurable endpoints
-- **TTL caching** — Time-based cache with global cache support
-- **Duplicate prevention** — Deduplicates concurrent requests for the same resource
-- **Preloading** — Warm up namespaces and fallback languages at startup
-- **Default merging** — Merge API translations with bundled defaults
+- **API loader — createApiTranslationLoader with configurable endpoints**
+- **TTL caching — Time-based cache with global cache support**
+- **Duplicate prevention — Deduplicates concurrent requests for the same resource**
+- **Preloading — Warm up namespaces and fallback languages at startup**
+- **Default merging — Merge API translations with bundled defaults**
 
-## Installation | 설치
+## Installation
 
 ```bash
 pnpm add @hua-labs/i18n-loaders
 ```
 
-Peer dependency: `react >= 19.0.0`
+> Peer dependencies: react >=19.0.0
 
-## Quick Start | 빠른 시작
+## Quick Start
 
 ```tsx
 import { createCoreI18n } from '@hua-labs/i18n-core';
 import { createApiTranslationLoader, preloadNamespaces } from '@hua-labs/i18n-loaders';
 
-const loadTranslations = createApiTranslationLoader({
+const loader = createApiTranslationLoader({
   translationApiPath: '/api/translations',
   cacheTtlMs: 60_000,
-  enableGlobalCache: true,
+  retryCount: 2,
 });
 
 // Preload at startup
-preloadNamespaces('ko', ['common', 'dashboard'], loadTranslations);
+preloadNamespaces('ko', ['common', 'dashboard'], loader);
 
 // Use with i18n-core
 const I18nProvider = createCoreI18n({
   defaultLanguage: 'ko',
-  fallbackLanguage: 'en',
-  namespaces: ['common', 'dashboard'],
   translationLoader: 'custom',
-  loadTranslations,
+  loadTranslations: loader,
 });
-```
-
-## API Overview | API 개요
-
-| Function | Description |
-|----------|-------------|
-| `createApiTranslationLoader(config)` | Create an API-based translation loader |
-| `preloadNamespaces(lang, namespaces, loader)` | Preload translation namespaces |
-| `withDefaultTranslations(loader, defaults)` | Merge API results with bundled defaults |
 
-**Loader config:**
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `translationApiPath` | `string` | — | API endpoint path |
-| `cacheTtlMs` | `number` | `300000` | Cache TTL in ms |
-| `enableGlobalCache` | `boolean` | `true` | Enable global cache |
+```
 
-## Documentation | 문서
+## API
 
-- [📚 Documentation Site | 문서 사이트](https://docs.hua-labs.com)
+| Export | Type | Description |
+|--------|------|-------------|
+| `createApiTranslationLoader` | function | Create API-based loader with caching and retry |
+| `preloadNamespaces` | function | Preload translation namespaces |
+| `warmFallbackLanguages` | function | Warm up fallback language caches |
+| `withDefaultTranslations` | function | Merge API results with bundled defaults |
+| `ApiLoaderOptions` | type |  |
+| `CacheInvalidation` | type |  |
+| `DefaultTranslations` | type |  |
+| `PreloadOptions` | type |  |
+| `TranslationLoader` | type |  |
+| `TranslationRecord` | type |  |
 
-## Related Packages | 관련 패키지
+## Documentation
 
-- [`@hua-labs/i18n-core`](https://www.npmjs.com/package/@hua-labs/i18n-core) — Core i18n library
-- [`@hua-labs/i18n-core-zustand`](https://www.npmjs.com/package/@hua-labs/i18n-core-zustand) — Zustand state adapter
-- [`@hua-labs/i18n-formatters`](https://www.npmjs.com/package/@hua-labs/i18n-formatters) — Date, number, currency formatters
+[Full Documentation](https://docs.hua-labs.com)
 
-## Requirements | 요구사항
+## Related Packages
 
-React >= 19.0.0 · TypeScript >= 5.9
+- [`@hua-labs/i18n-core`](https://www.npmjs.com/package/@hua-labs/i18n-core)
+- [`@hua-labs/i18n-core-zustand`](https://www.npmjs.com/package/@hua-labs/i18n-core-zustand)
+- [`@hua-labs/i18n-formatters`](https://www.npmjs.com/package/@hua-labs/i18n-formatters)
 
 ## License
 
-MIT — [HUA Labs](https://github.com/HUA-Labs/HUA-Labs-public)
+MIT — [HUA Labs](https://hua-labs.com)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hua-labs/i18n-loaders",
-  "version": "1.1.1",
+  "version": "2.0.2",
   "description": "Production-ready loaders, caching, and preloading helpers for @hua-labs/i18n-core.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -17,19 +17,23 @@
     }
   },
   "sideEffects": false,
+  "engines": {
+    "node": ">=20.0.0"
+  },
   "dependencies": {
-    "@hua-labs/i18n-core": "^1.1.0"
+    "@hua-labs/i18n-core": "latest"
   },
   "peerDependencies": {
     "react": ">=19.0.0"
   },
   "devDependencies": {
-    "@types/node": "^25.0.3",
-    "@types/react": "^19.2.7",
-    "eslint": "^9.39.1",
-    "react": "^19.2.0",
+    "@types/node": "^25.2.0",
+    "@types/react": "^19.2.10",
+    "eslint": "^10.0.0",
+    "react": "^19.2.4",
     "tsup": "^8.5.1",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.1"
   },
   "keywords": [
     "hua-labs",
@@ -60,7 +64,8 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "clean": "rm -rf dist",
-    "test": "echo \"No tests defined\"",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "lint": "echo 'Skipping lint for hua-i18n-loaders (TypeScript only, linted by tsc)'",
     "type-check": "tsc --noEmit"
   }

package/src/__tests__/api-loader.test.ts

@@ -0,0 +1,610 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { createApiTranslationLoader } from '../api-loader';
+import type { TranslationRecord } from '../types';
+
+describe('createApiTranslationLoader', () => {
+  let mockFetch: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    mockFetch = vi.fn();
+    global.fetch = mockFetch;
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.useRealTimers();
+  });
+
+  describe('Basic functionality', () => {
+    it('should fetch and return translations', async () => {
+      const translations: TranslationRecord = { hello: 'world' };
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => translations,
+      });
+
+      const loader = createApiTranslationLoader({
+        baseUrl: 'https://example.com',
+        translationApiPath: '/api/translations',
+      });
+
+      const result = await loader('en', 'common');
+
+      expect(result).toEqual(translations);
+      expect(mockFetch).toHaveBeenCalledWith(
+        'https://example.com/api/translations/en/common',
+        expect.objectContaining({
+          cache: 'no-store',
+        })
+      );
+    });
+
+    it('should throw error on failed fetch', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 404,
+      });
+
+      const loader = createApiTranslationLoader();
+
+      await expect(loader('en', 'common')).rejects.toThrow(
+        '[i18n-loaders] Failed to load en/common (404)'
+      );
+    });
+  });
+
+  describe('Caching', () => {
+    it('should return cached data on subsequent requests', async () => {
+      const translations: TranslationRecord = { hello: 'world' };
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => translations,
+      });
+
+      const loader = createApiTranslationLoader({
+        cacheTtlMs: 5 * 60 * 1000,
+      });
+
+      const result1 = await loader('en', 'common');
+      const result2 = await loader('en', 'common');
+
+      expect(result1).toEqual(translations);
+      expect(result2).toEqual(translations);
+      expect(mockFetch).toHaveBeenCalledTimes(1);
+    });
+
+    it('should refetch after cache TTL expires', async () => {
+      const translations1: TranslationRecord = { hello: 'world' };
+      const translations2: TranslationRecord = { hello: 'updated' };
+
+      mockFetch
+        .mockResolvedValueOnce({
+          ok: true,
+          json: async () => translations1,
+        })
+        .mockResolvedValueOnce({
+          ok: true,
+          json: async () => translations2,
+        });
+
+      const loader = createApiTranslationLoader({
+        cacheTtlMs: 1000,
+      });
+
+      const result1 = await loader('en', 'common');
+      expect(result1).toEqual(translations1);
+
+      // Advance time past TTL
+      vi.advanceTimersByTime(1001);
+
+      const result2 = await loader('en', 'common');
+      expect(result2).toEqual(translations2);
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+    });
+
+    it('should skip cache when disableCache is true', async () => {
+      const translations: TranslationRecord = { hello: 'world' };
+      mockFetch.mockResolvedValue({
+        ok: true,
+        json: async () => translations,
+      });
+
+      const loader = createApiTranslationLoader({
+        disableCache: true,
+      });
+
+      await loader('en', 'common');
+      await loader('en', 'common');
+
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe('In-flight request deduplication', () => {
+    it('should deduplicate concurrent requests', async () => {
+      vi.useRealTimers(); // Use real timers for this test
+
+      const translations: TranslationRecord = { hello: 'world' };
+      mockFetch.mockImplementation(
+        () =>
+          new Promise((resolve) => {
+            setTimeout(() => {
+              resolve({
+                ok: true,
+                json: async () => translations,
+              });
+            }, 10);
+          })
+      );
+
+      const loader = createApiTranslationLoader({
+        baseUrl: 'https://example.com',
+      });
+
+      const [result1, result2, result3] = await Promise.all([
+        loader('en', 'common'),
+        loader('en', 'common'),
+        loader('en', 'common'),
+      ]);
+
+      expect(result1).toEqual(translations);
+      expect(result2).toEqual(translations);
+      expect(result3).toEqual(translations);
+      expect(mockFetch).toHaveBeenCalledTimes(1);
+
+      vi.useFakeTimers(); // Restore fake timers
+    });
+
+    it('should not deduplicate different language/namespace combinations', async () => {
+      const translations1: TranslationRecord = { hello: 'world' };
+      const translations2: TranslationRecord = { hello: 'mundo' };
+
+      mockFetch.mockImplementation((url) => {
+        const urlStr = typeof url === 'string' ? url : url.toString();
+        if (urlStr.includes('/en/')) {
+          return Promise.resolve({
+            ok: true,
+            json: async () => translations1,
+          });
+        }
+        return Promise.resolve({
+          ok: true,
+          json: async () => translations2,
+        });
+      });
+
+      const loader = createApiTranslationLoader({
+        baseUrl: 'https://example.com',
+      });
+
+      const [result1, result2] = await Promise.all([
+        loader('en', 'common'),
+        loader('es', 'common'),
+      ]);
+
+      expect(result1).toEqual(translations1);
+      expect(result2).toEqual(translations2);
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe('Retry logic', () => {
+    it('should retry on 5xx errors with exponential backoff', async () => {
+      vi.useRealTimers(); // Use real timers for retry test
+
+      const translations: TranslationRecord = { hello: 'world' };
+      let callCount = 0;
+
+      mockFetch.mockImplementation(async () => {
+        callCount++;
+        if (callCount < 3) {
+          const error = new Error('Internal Server Error') as Error & { status: number };
+          error.status = 500;
+          throw error;
+        }
+        return {
+          ok: true,
+          json: async () => translations,
+        } as Response;
+      });
+
+      const loader = createApiTranslationLoader({
+        baseUrl: 'https://example.com',
+        retryCount: 2,
+        retryDelay: 10, // Short delay for faster test
+      });
+
+      const result = await loader('en', 'common');
+
+      expect(result).toEqual(translations);
+      expect(callCount).toBe(3);
+
+      vi.useFakeTimers(); // Restore fake timers
+    });
+
+    it('should retry on network errors', async () => {
+      vi.useRealTimers(); // Use real timers for retry test
+
+      const translations: TranslationRecord = { hello: 'world' };
+      let callCount = 0;
+
+      mockFetch.mockImplementation(() => {
+        callCount++;
+        if (callCount === 1) {
+          return Promise.reject(new TypeError('Failed to fetch'));
+        }
+        return Promise.resolve({
+          ok: true,
+          json: async () => translations,
+        });
+      });
+
+      const loader = createApiTranslationLoader({
+        baseUrl: 'https://example.com',
+        retryCount: 1,
+        retryDelay: 10, // Short delay for faster test
+      });
+
+      const result = await loader('en', 'common');
+
+      expect(result).toEqual(translations);
+      expect(callCount).toBe(2);
+
+      vi.useFakeTimers(); // Restore fake timers
+    });
+
+    it('should not retry on 4xx errors', async () => {
+      mockFetch.mockResolvedValue({
+        ok: false,
+        status: 404,
+      });
+
+      const loader = createApiTranslationLoader({
+        retryCount: 2,
+        retryDelay: 100,
+      });
+
+      await expect(loader('en', 'common')).rejects.toThrow();
+      expect(mockFetch).toHaveBeenCalledTimes(1);
+    });
+
+    it('should throw error after max retries exceeded', async () => {
+      vi.useRealTimers(); // Use real timers for retry test
+
+      let callCount = 0;
+      mockFetch.mockImplementation(async () => {
+        callCount++;
+        const error = new Error('Internal Server Error') as Error & { status: number };
+        error.status = 500;
+        throw error;
+      });
+
+      const logger = {
+        log: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+      };
+
+      const loader = createApiTranslationLoader({
+        baseUrl: 'https://example.com',
+        retryCount: 2,
+        retryDelay: 10, // Short delay for faster test
+        logger,
+      });
+
+      await expect(loader('en', 'common')).rejects.toThrow();
+      expect(callCount).toBe(3); // Initial + 2 retries
+      expect(logger.warn).toHaveBeenCalled();
+
+      vi.useFakeTimers(); // Restore fake timers
+    });
+  });
+
+  describe('URL building', () => {
+    it('should use baseUrl in server environment', async () => {
+      const translations: TranslationRecord = { hello: 'world' };
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => translations,
+      });
+
+      const loader = createApiTranslationLoader({
+        baseUrl: 'https://example.com',
+        translationApiPath: '/api/translations',
+      });
+
+      await loader('en', 'common');
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        'https://example.com/api/translations/en/common',
+        expect.any(Object)
+      );
+    });
+
+    it('should sanitize namespace in URL', async () => {
+      const translations: TranslationRecord = { hello: 'world' };
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => translations,
+      });
+
+      const loader = createApiTranslationLoader({
+        baseUrl: 'https://example.com',
+      });
+
+      await loader('en', 'my@namespace#test');
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        'https://example.com/api/translations/en/mynamespacetest',
+        expect.any(Object)
+      );
+    });
+
+    it('should fall back to NEXT_PUBLIC_SITE_URL', async () => {
+      const originalEnv = process.env.NEXT_PUBLIC_SITE_URL;
+      process.env.NEXT_PUBLIC_SITE_URL = 'https://site.com';
+
+      const translations: TranslationRecord = { hello: 'world' };
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => translations,
+      });
+
+      const loader = createApiTranslationLoader();
+
+      await loader('en', 'common');
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        'https://site.com/api/translations/en/common',
+        expect.any(Object)
+      );
+
+      process.env.NEXT_PUBLIC_SITE_URL = originalEnv;
+    });
+
+    it('should fall back to VERCEL_URL', async () => {
+      const originalSiteUrl = process.env.NEXT_PUBLIC_SITE_URL;
+      const originalVercelUrl = process.env.VERCEL_URL;
+
+      delete process.env.NEXT_PUBLIC_SITE_URL;
+      process.env.VERCEL_URL = 'vercel-app.vercel.app';
+
+      const translations: TranslationRecord = { hello: 'world' };
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => translations,
+      });
+
+      const loader = createApiTranslationLoader();
+
+      await loader('en', 'common');
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        'https://vercel-app.vercel.app/api/translations/en/common',
+        expect.any(Object)
+      );
+
+      process.env.NEXT_PUBLIC_SITE_URL = originalSiteUrl;
+      process.env.VERCEL_URL = originalVercelUrl;
+    });
+
+    it('should use localFallbackBaseUrl as final fallback', async () => {
+      const originalSiteUrl = process.env.NEXT_PUBLIC_SITE_URL;
+      const originalVercelUrl = process.env.VERCEL_URL;
+
+      delete process.env.NEXT_PUBLIC_SITE_URL;
+      delete process.env.VERCEL_URL;
+
+      const translations: TranslationRecord = { hello: 'world' };
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => translations,
+      });
+
+      const loader = createApiTranslationLoader({
+        localFallbackBaseUrl: 'http://localhost:4000',
+      });
+
+      await loader('en', 'common');
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        'http://localhost:4000/api/translations/en/common',
+        expect.any(Object)
+      );
+
+      process.env.NEXT_PUBLIC_SITE_URL = originalSiteUrl;
+      process.env.VERCEL_URL = originalVercelUrl;
+    });
+  });
+
+  describe('Cache invalidation', () => {
+    it('should invalidate specific language/namespace', async () => {
+      const translations1: TranslationRecord = { hello: 'world' };
+      const translations2: TranslationRecord = { hello: 'updated' };
+
+      mockFetch
+        .mockResolvedValueOnce({
+          ok: true,
+          json: async () => translations1,
+        })
+        .mockResolvedValueOnce({
+          ok: true,
+          json: async () => translations2,
+        });
+
+      const loader = createApiTranslationLoader();
+
+      const result1 = await loader('en', 'common');
+      expect(result1).toEqual(translations1);
+
+      loader.invalidate('en', 'common');
+
+      const result2 = await loader('en', 'common');
+      expect(result2).toEqual(translations2);
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+    });
+
+    it('should invalidate all namespaces for a language', async () => {
+      const translations: TranslationRecord = { hello: 'world' };
+      mockFetch.mockResolvedValue({
+        ok: true,
+        json: async () => translations,
+      });
+
+      const loader = createApiTranslationLoader();
+
+      await loader('en', 'common');
+      await loader('en', 'auth');
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+
+      loader.invalidate('en');
+
+      await loader('en', 'common');
+      await loader('en', 'auth');
+      expect(mockFetch).toHaveBeenCalledTimes(4);
+    });
+
+    it('should invalidate specific namespace across all languages', async () => {
+      const translations: TranslationRecord = { hello: 'world' };
+      mockFetch.mockResolvedValue({
+        ok: true,
+        json: async () => translations,
+      });
+
+      const loader = createApiTranslationLoader();
+
+      await loader('en', 'common');
+      await loader('es', 'common');
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+
+      loader.invalidate(undefined, 'common');
+
+      await loader('en', 'common');
+      await loader('es', 'common');
+      expect(mockFetch).toHaveBeenCalledTimes(4);
+    });
+
+    it('should clear entire cache', async () => {
+      const translations: TranslationRecord = { hello: 'world' };
+      mockFetch.mockResolvedValue({
+        ok: true,
+        json: async () => translations,
+      });
+
+      const loader = createApiTranslationLoader();
+
+      await loader('en', 'common');
+      await loader('en', 'auth');
+      await loader('es', 'common');
+      expect(mockFetch).toHaveBeenCalledTimes(3);
+
+      loader.clear();
+
+      await loader('en', 'common');
+      await loader('en', 'auth');
+      await loader('es', 'common');
+      expect(mockFetch).toHaveBeenCalledTimes(6);
+    });
+  });
+
+  describe('Custom fetcher', () => {
+    it('should use custom fetcher when provided', async () => {
+      const translations: TranslationRecord = { hello: 'world' };
+      const customFetcher = vi.fn().mockResolvedValue({
+        ok: true,
+        json: async () => translations,
+      });
+
+      const loader = createApiTranslationLoader({
+        fetcher: customFetcher,
+      });
+
+      await loader('en', 'common');
+
+      expect(customFetcher).toHaveBeenCalledTimes(1);
+      expect(mockFetch).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('Custom requestInit', () => {
+    it('should use static requestInit', async () => {
+      const translations: TranslationRecord = { hello: 'world' };
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => translations,
+      });
+
+      const loader = createApiTranslationLoader({
+        requestInit: {
+          headers: {
+            'X-Custom-Header': 'test',
+          },
+        },
+      });
+
+      await loader('en', 'common');
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.objectContaining({
+          headers: {
+            'X-Custom-Header': 'test',
+          },
+        })
+      );
+    });
+
+    it('should use function-based requestInit', async () => {
+      const translations: TranslationRecord = { hello: 'world' };
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => translations,
+      });
+
+      const loader = createApiTranslationLoader({
+        requestInit: (language, namespace) => ({
+          headers: {
+            'X-Language': language,
+            'X-Namespace': namespace,
+          },
+        }),
+      });
+
+      await loader('en', 'common');
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.objectContaining({
+          headers: {
+            'X-Language': 'en',
+            'X-Namespace': 'common',
+          },
+        })
+      );
+    });
+  });
+
+  describe('Logger', () => {
+    it('should use custom logger', async () => {
+      const logger = {
+        log: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+      };
+
+      mockFetch.mockResolvedValue({
+        ok: false,
+        status: 404,
+      });
+
+      const loader = createApiTranslationLoader({
+        logger,
+      });
+
+      await expect(loader('en', 'common')).rejects.toThrow();
+
+      expect(logger.warn).toHaveBeenCalled();
+    });
+  });
+});

package/src/__tests__/defaults.test.ts

@@ -0,0 +1,327 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { withDefaultTranslations } from '../defaults';
+import type { TranslationLoader, TranslationRecord, DefaultTranslations } from '../types';
+
+describe('withDefaultTranslations', () => {
+  let mockLoader: TranslationLoader;
+
+  beforeEach(() => {
+    mockLoader = vi.fn();
+  });
+
+  it('should return merged translations when loader succeeds', async () => {
+    const remoteTranslations: TranslationRecord = {
+      hello: 'world',
+      goodbye: 'farewell',
+    };
+
+    (mockLoader as ReturnType<typeof vi.fn>).mockResolvedValue(remoteTranslations);
+
+    const defaults: DefaultTranslations = {
+      en: {
+        common: {
+          hello: 'default hello',
+          other: 'default other',
+        },
+      },
+    };
+
+    const loader = withDefaultTranslations(mockLoader, defaults);
+    const result = await loader('en', 'common');
+
+    expect(result).toEqual({
+      hello: 'world', // Remote overrides default
+      goodbye: 'farewell', // From remote
+      other: 'default other', // From defaults
+    });
+  });
+
+  it('should merge remote translations with defaults', async () => {
+    const remoteTranslations: TranslationRecord = {
+      hello: 'remote hello',
+    };
+
+    (mockLoader as ReturnType<typeof vi.fn>).mockResolvedValue(remoteTranslations);
+
+    const defaults: DefaultTranslations = {
+      en: {
+        common: {
+          hello: 'default hello',
+          goodbye: 'default goodbye',
+        },
+      },
+    };
+
+    const loader = withDefaultTranslations(mockLoader, defaults);
+    const result = await loader('en', 'common');
+
+    expect(result).toEqual({
+      hello: 'remote hello', // Remote overrides default
+      goodbye: 'default goodbye', // Default is preserved
+    });
+  });
+
+  it('should return defaults when loader fails', async () => {
+    const error = new Error('Failed to load');
+    (mockLoader as ReturnType<typeof vi.fn>).mockRejectedValue(error);
+
+    const defaults: DefaultTranslations = {
+      en: {
+        common: {
+          hello: 'default hello',
+        },
+      },
+    };
+
+    const loader = withDefaultTranslations(mockLoader, defaults);
+    const result = await loader('en', 'common');
+
+    expect(result).toEqual({
+      hello: 'default hello',
+    });
+  });
+
+  it('should throw error when loader fails and no defaults available', async () => {
+    const error = new Error('Failed to load');
+    (mockLoader as ReturnType<typeof vi.fn>).mockRejectedValue(error);
+
+    const defaults: DefaultTranslations = {
+      es: {
+        common: {
+          hola: 'mundo',
+        },
+      },
+    };
+
+    const loader = withDefaultTranslations(mockLoader, defaults);
+
+    await expect(loader('en', 'common')).rejects.toThrow('Failed to load');
+  });
+
+  it('should return defaults when remote returns empty object', async () => {
+    (mockLoader as ReturnType<typeof vi.fn>).mockResolvedValue({});
+
+    const defaults: DefaultTranslations = {
+      en: {
+        common: {
+          hello: 'default hello',
+        },
+      },
+    };
+
+    const loader = withDefaultTranslations(mockLoader, defaults);
+    const result = await loader('en', 'common');
+
+    expect(result).toEqual({
+      hello: 'default hello',
+    });
+  });
+
+  it('should return defaults when remote returns null', async () => {
+    (mockLoader as ReturnType<typeof vi.fn>).mockResolvedValue(null);
+
+    const defaults: DefaultTranslations = {
+      en: {
+        common: {
+          hello: 'default hello',
+        },
+      },
+    };
+
+    const loader = withDefaultTranslations(mockLoader, defaults);
+    const result = await loader('en', 'common');
+
+    expect(result).toEqual({
+      hello: 'default hello',
+    });
+  });
+
+  it('should return empty object when both remote and defaults are empty', async () => {
+    (mockLoader as ReturnType<typeof vi.fn>).mockResolvedValue({});
+
+    const defaults: DefaultTranslations = {};
+
+    const loader = withDefaultTranslations(mockLoader, defaults);
+    const result = await loader('en', 'common');
+
+    expect(result).toEqual({});
+  });
+
+  it('should deep merge nested translations', async () => {
+    const remoteTranslations: TranslationRecord = {
+      user: {
+        profile: {
+          name: 'remote name',
+        },
+      },
+    };
+
+    (mockLoader as ReturnType<typeof vi.fn>).mockResolvedValue(remoteTranslations);
+
+    const defaults: DefaultTranslations = {
+      en: {
+        common: {
+          user: {
+            profile: {
+              name: 'default name',
+              email: 'default email',
+            },
+            settings: {
+              theme: 'default theme',
+            },
+          },
+        },
+      },
+    };
+
+    const loader = withDefaultTranslations(mockLoader, defaults);
+    const result = await loader('en', 'common');
+
+    expect(result).toEqual({
+      user: {
+        profile: {
+          name: 'remote name', // Overridden by remote
+          email: 'default email', // From defaults
+        },
+        settings: {
+          theme: 'default theme', // From defaults
+        },
+      },
+    });
+  });
+
+  it('should handle arrays as leaf values', async () => {
+    const remoteTranslations: TranslationRecord = {
+      items: ['remote1', 'remote2'],
+    };
+
+    (mockLoader as ReturnType<typeof vi.fn>).mockResolvedValue(remoteTranslations);
+
+    const defaults: DefaultTranslations = {
+      en: {
+        common: {
+          items: ['default1', 'default2', 'default3'],
+        },
+      },
+    };
+
+    const loader = withDefaultTranslations(mockLoader, defaults);
+    const result = await loader('en', 'common');
+
+    // Arrays are replaced, not merged
+    expect(result).toEqual({
+      items: ['remote1', 'remote2'],
+    });
+  });
+
+  it('should handle mixed types between defaults and remote', async () => {
+    const remoteTranslations: TranslationRecord = {
+      value: {
+        nested: 'remote nested',
+      },
+    };
+
+    (mockLoader as ReturnType<typeof vi.fn>).mockResolvedValue(remoteTranslations);
+
+    const defaults: DefaultTranslations = {
+      en: {
+        common: {
+          value: 'default string',
+        },
+      },
+    };
+
+    const loader = withDefaultTranslations(mockLoader, defaults);
+    const result = await loader('en', 'common');
+
+    // Remote value replaces default entirely
+    expect(result).toEqual({
+      value: {
+        nested: 'remote nested',
+      },
+    });
+  });
+
+  it('should not mutate original defaults', async () => {
+    const remoteTranslations: TranslationRecord = {
+      hello: 'remote hello',
+    };
+
+    (mockLoader as ReturnType<typeof vi.fn>).mockResolvedValue(remoteTranslations);
+
+    const defaults: DefaultTranslations = {
+      en: {
+        common: {
+          hello: 'default hello',
+          goodbye: 'default goodbye',
+        },
+      },
+    };
+
+    const defaultsCopy = JSON.parse(JSON.stringify(defaults));
+
+    const loader = withDefaultTranslations(mockLoader, defaults);
+    await loader('en', 'common');
+
+    // Defaults should remain unchanged
+    expect(defaults).toEqual(defaultsCopy);
+  });
+
+  it('should handle multiple namespaces', async () => {
+    const translations1: TranslationRecord = { hello: 'world' };
+    const translations2: TranslationRecord = { login: 'sign in' };
+
+    (mockLoader as ReturnType<typeof vi.fn>)
+      .mockResolvedValueOnce(translations1)
+      .mockResolvedValueOnce(translations2);
+
+    const defaults: DefaultTranslations = {
+      en: {
+        common: {
+          hello: 'default hello',
+        },
+        auth: {
+          login: 'default login',
+        },
+      },
+    };
+
+    const loader = withDefaultTranslations(mockLoader, defaults);
+
+    const result1 = await loader('en', 'common');
+    const result2 = await loader('en', 'auth');
+
+    expect(result1).toEqual({ hello: 'world' });
+    expect(result2).toEqual({ login: 'sign in' });
+  });
+
+  it('should handle multiple languages', async () => {
+    const enTranslations: TranslationRecord = { hello: 'world' };
+    const esTranslations: TranslationRecord = { hello: 'mundo' };
+
+    (mockLoader as ReturnType<typeof vi.fn>)
+      .mockResolvedValueOnce(enTranslations)
+      .mockResolvedValueOnce(esTranslations);
+
+    const defaults: DefaultTranslations = {
+      en: {
+        common: {
+          hello: 'default hello',
+        },
+      },
+      es: {
+        common: {
+          hello: 'default hola',
+        },
+      },
+    };
+
+    const loader = withDefaultTranslations(mockLoader, defaults);
+
+    const enResult = await loader('en', 'common');
+    const esResult = await loader('es', 'common');
+
+    expect(enResult).toEqual({ hello: 'world' });
+    expect(esResult).toEqual({ hello: 'mundo' });
+  });
+});

package/src/__tests__/preload.test.ts

@@ -0,0 +1,265 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { preloadNamespaces, warmFallbackLanguages } from '../preload';
+import type { TranslationLoader, TranslationRecord } from '../types';
+
+describe('preloadNamespaces', () => {
+  let mockLoader: TranslationLoader;
+
+  beforeEach(() => {
+    mockLoader = vi.fn();
+  });
+
+  it('should preload all namespaces successfully', async () => {
+    const translations: TranslationRecord = { hello: 'world' };
+    (mockLoader as ReturnType<typeof vi.fn>).mockResolvedValue(translations);
+
+    const namespaces = ['common', 'auth', 'dashboard'];
+    const result = await preloadNamespaces('en', namespaces, mockLoader);
+
+    expect(result.fulfilled).toEqual(namespaces);
+    expect(result.rejected).toEqual([]);
+    expect(mockLoader).toHaveBeenCalledTimes(3);
+    expect(mockLoader).toHaveBeenCalledWith('en', 'common');
+    expect(mockLoader).toHaveBeenCalledWith('en', 'auth');
+    expect(mockLoader).toHaveBeenCalledWith('en', 'dashboard');
+  });
+
+  it('should handle partial failures', async () => {
+    const translations: TranslationRecord = { hello: 'world' };
+    const error = new Error('Failed to load');
+
+    (mockLoader as ReturnType<typeof vi.fn>)
+      .mockResolvedValueOnce(translations) // common succeeds
+      .mockRejectedValueOnce(error) // auth fails
+      .mockResolvedValueOnce(translations); // dashboard succeeds
+
+    const namespaces = ['common', 'auth', 'dashboard'];
+    const result = await preloadNamespaces('en', namespaces, mockLoader);
+
+    expect(result.fulfilled).toEqual(['common', 'dashboard']);
+    expect(result.rejected).toHaveLength(1);
+    expect(result.rejected[0]).toBe(error);
+  });
+
+  it('should log success messages', async () => {
+    const translations: TranslationRecord = { hello: 'world' };
+    (mockLoader as ReturnType<typeof vi.fn>).mockResolvedValue(translations);
+
+    const logger = {
+      log: vi.fn(),
+      warn: vi.fn(),
+    };
+
+    const namespaces = ['common', 'auth'];
+    await preloadNamespaces('en', namespaces, mockLoader, { logger });
+
+    expect(logger.log).toHaveBeenCalledWith(
+      '[i18n-loaders] Preloaded 2/2 namespaces for en'
+    );
+  });
+
+  it('should log warning messages for failures', async () => {
+    const error = new Error('Failed to load');
+    (mockLoader as ReturnType<typeof vi.fn>)
+      .mockResolvedValueOnce({ hello: 'world' })
+      .mockRejectedValueOnce(error);
+
+    const logger = {
+      log: vi.fn(),
+      warn: vi.fn(),
+    };
+
+    const namespaces = ['common', 'auth'];
+    await preloadNamespaces('en', namespaces, mockLoader, { logger });
+
+    expect(logger.log).toHaveBeenCalled();
+    expect(logger.warn).toHaveBeenCalledWith(
+      '[i18n-loaders] Failed to preload 1 namespaces for en'
+    );
+  });
+
+  it('should suppress error warnings when option is set', async () => {
+    const error = new Error('Failed to load');
+    (mockLoader as ReturnType<typeof vi.fn>).mockRejectedValue(error);
+
+    const logger = {
+      log: vi.fn(),
+      warn: vi.fn(),
+    };
+
+    const namespaces = ['common', 'auth'];
+    await preloadNamespaces('en', namespaces, mockLoader, {
+      logger,
+      suppressErrors: true,
+    });
+
+    expect(logger.warn).not.toHaveBeenCalled();
+  });
+
+  it('should handle empty namespace list', async () => {
+    const result = await preloadNamespaces('en', [], mockLoader);
+
+    expect(result.fulfilled).toEqual([]);
+    expect(result.rejected).toEqual([]);
+    expect(mockLoader).not.toHaveBeenCalled();
+  });
+
+  it('should call loader concurrently', async () => {
+    const callOrder: string[] = [];
+
+    (mockLoader as ReturnType<typeof vi.fn>).mockImplementation(
+      async (language: string, namespace: string) => {
+        callOrder.push(`start-${namespace}`);
+        await new Promise((resolve) => setTimeout(resolve, 10));
+        callOrder.push(`end-${namespace}`);
+        return {};
+      }
+    );
+
+    const namespaces = ['common', 'auth', 'dashboard'];
+    await preloadNamespaces('en', namespaces, mockLoader);
+
+    // All starts should happen before any ends (concurrent execution)
+    const firstEndIndex = callOrder.findIndex((item) => item.startsWith('end-'));
+    const lastStartIndex = callOrder.reduce(
+      (acc, item, idx) => (item.startsWith('start-') ? idx : acc),
+      -1
+    );
+
+    expect(firstEndIndex).toBeGreaterThan(lastStartIndex);
+  });
+});
+
+describe('warmFallbackLanguages', () => {
+  let mockLoader: TranslationLoader;
+
+  beforeEach(() => {
+    mockLoader = vi.fn();
+  });
+
+  it('should preload all fallback languages', async () => {
+    const translations: TranslationRecord = { hello: 'world' };
+    (mockLoader as ReturnType<typeof vi.fn>).mockResolvedValue(translations);
+
+    const languages = ['en', 'es', 'fr'];
+    const namespaces = ['common', 'auth'];
+
+    await warmFallbackLanguages('en', languages, namespaces, mockLoader);
+
+    // Should preload es and fr (not en, as it's the current language)
+    expect(mockLoader).toHaveBeenCalledTimes(4); // 2 languages * 2 namespaces
+    expect(mockLoader).toHaveBeenCalledWith('es', 'common');
+    expect(mockLoader).toHaveBeenCalledWith('es', 'auth');
+    expect(mockLoader).toHaveBeenCalledWith('fr', 'common');
+    expect(mockLoader).toHaveBeenCalledWith('fr', 'auth');
+    expect(mockLoader).not.toHaveBeenCalledWith('en', expect.any(String));
+  });
+
+  it('should return empty array when no fallback languages', async () => {
+    const languages = ['en'];
+    const namespaces = ['common'];
+
+    const result = await warmFallbackLanguages(
+      'en',
+      languages,
+      namespaces,
+      mockLoader
+    );
+
+    expect(result).toEqual([]);
+    expect(mockLoader).not.toHaveBeenCalled();
+  });
+
+  it('should handle all languages being current language', async () => {
+    const languages = ['en'];
+    const namespaces = ['common', 'auth'];
+
+    const result = await warmFallbackLanguages(
+      'en',
+      languages,
+      namespaces,
+      mockLoader
+    );
+
+    expect(result).toEqual([]);
+    expect(mockLoader).not.toHaveBeenCalled();
+  });
+
+  it('should pass options to preloadNamespaces', async () => {
+    const translations: TranslationRecord = { hello: 'world' };
+    const error = new Error('Failed to load');
+
+    (mockLoader as ReturnType<typeof vi.fn>)
+      .mockResolvedValueOnce(translations)
+      .mockRejectedValueOnce(error);
+
+    const logger = {
+      log: vi.fn(),
+      warn: vi.fn(),
+    };
+
+    const languages = ['en', 'es'];
+    const namespaces = ['common'];
+
+    await warmFallbackLanguages('en', languages, namespaces, mockLoader, {
+      logger,
+      suppressErrors: true,
+    });
+
+    expect(logger.log).toHaveBeenCalled();
+    expect(logger.warn).not.toHaveBeenCalled(); // suppressErrors is true
+  });
+
+  it('should return results for each fallback language', async () => {
+    const translations: TranslationRecord = { hello: 'world' };
+    const error = new Error('Failed to load');
+
+    (mockLoader as ReturnType<typeof vi.fn>)
+      .mockResolvedValueOnce(translations) // es/common succeeds
+      .mockRejectedValueOnce(error) // fr/common fails
+      .mockResolvedValueOnce(translations); // ko/common succeeds
+
+    const languages = ['en', 'es', 'fr', 'ko'];
+    const namespaces = ['common'];
+
+    const results = await warmFallbackLanguages(
+      'en',
+      languages,
+      namespaces,
+      mockLoader,
+      { suppressErrors: true }
+    );
+
+    expect(results).toHaveLength(3); // es, fr, ko (excluding current language 'en')
+    expect(results[0].fulfilled).toEqual(['common']);
+    expect(results[1].rejected).toHaveLength(1);
+    expect(results[2].fulfilled).toEqual(['common']);
+  });
+
+  it('should execute preloads concurrently for different languages', async () => {
+    const callOrder: string[] = [];
+
+    (mockLoader as ReturnType<typeof vi.fn>).mockImplementation(
+      async (language: string) => {
+        callOrder.push(`start-${language}`);
+        await new Promise((resolve) => setTimeout(resolve, 10));
+        callOrder.push(`end-${language}`);
+        return {};
+      }
+    );
+
+    const languages = ['en', 'es', 'fr'];
+    const namespaces = ['common'];
+
+    await warmFallbackLanguages('en', languages, namespaces, mockLoader);
+
+    // All starts should happen before any ends (concurrent execution)
+    const firstEndIndex = callOrder.findIndex((item) => item.startsWith('end-'));
+    const lastStartIndex = callOrder.reduce(
+      (acc, item, idx) => (item.startsWith('start-') ? idx : acc),
+      -1
+    );
+
+    expect(firstEndIndex).toBeGreaterThan(lastStartIndex);
+  });
+});

package/LICENSE

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