@hua-labs/i18n-loaders 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+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. 

package/README.md

@@ -0,0 +1,415 @@
+# @hua-labs/i18n-loaders
+
+Production-ready translation loaders, caching, and preloading utilities. Use with `@hua-labs/i18n-core` to reuse proven loading strategies from SUM API.
+
+## Key Features
+
+- API-based translation loader (`createApiTranslationLoader`)
+- Built-in TTL/global cache/duplicate request prevention
+- Namespace preloading & fallback language warming
+- Default translation (JSON) merging (SUM API style)
+- Works on both server and client
+- **Production tested**: Currently used in SUM API
+
+## Installation
+
+```bash
+pnpm add @hua-labs/i18n-loaders
+# or
+npm install @hua-labs/i18n-loaders
+```
+
+## Quick Start
+
+### Basic Usage
+
+```ts
+import { createCoreI18n } from '@hua-labs/i18n-core';
+import { createApiTranslationLoader } from '@hua-labs/i18n-loaders';
+
+const loadTranslations = createApiTranslationLoader({
+  translationApiPath: '/api/translations',
+  cacheTtlMs: 60_000, // 1 minute
+  enableGlobalCache: true
+});
+
+export const I18nProvider = createCoreI18n({
+  defaultLanguage: 'ko',
+  fallbackLanguage: 'en',
+  namespaces: ['common', 'dashboard'],
+  translationLoader: 'custom',
+  loadTranslations
+});
+```
+
+### Preloading
+
+```ts
+import { createApiTranslationLoader, preloadNamespaces } from '@hua-labs/i18n-loaders';
+
+const loadTranslations = createApiTranslationLoader({
+  translationApiPath: '/api/translations'
+});
+
+// Preload required namespaces at app startup
+preloadNamespaces('ko', ['common', 'dashboard'], loadTranslations);
+```
+
+### Using Default Translation Merging
+
+```ts
+import { createApiTranslationLoader, withDefaultTranslations } from '@hua-labs/i18n-loaders';
+
+const apiLoader = createApiTranslationLoader({
+  translationApiPath: '/api/translations'
+});
+
+const defaultTranslations = {
+  ko: {
+    common: {
+      welcome: 'Welcome',
+      hello: 'Hello'
+    }
+  },
+  en: {
+    common: {
+      welcome: 'Welcome',
+      hello: 'Hello'
+    }
+  }
+};
+
+// Use default translations if API fails, merge if API succeeds
+const loadTranslations = withDefaultTranslations(apiLoader, defaultTranslations);
+```
+
+## API Reference
+
+### createApiTranslationLoader
+
+Creates an API-based translation loader. Includes TTL caching, duplicate request prevention, and global cache.
+
+```ts
+function createApiTranslationLoader(
+  options?: ApiLoaderOptions
+): TranslationLoader
+```
+
+#### Options
+
+```ts
+interface ApiLoaderOptions {
+  // API path (default: '/api/translations')
+  translationApiPath?: string;
+  
+  // Base URL (for server-side use)
+  baseUrl?: string;
+  
+  // Local fallback URL (for development)
+  localFallbackBaseUrl?: string;
+  
+  // Cache TTL (milliseconds, default: 5 minutes)
+  cacheTtlMs?: number;
+  
+  // Disable cache
+  disableCache?: boolean;
+  
+  // Fetch request options
+  requestInit?: RequestInit | ((language: string, namespace: string) => RequestInit | undefined);
+  
+  // Custom fetcher (for testing)
+  fetcher?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+  
+  // Logger (default: console)
+  logger?: Pick<typeof console, 'log' | 'warn' | 'error'>;
+  
+  // Retry configuration for network errors
+  retryCount?: number; // Number of retry attempts (default: 0, no retry)
+  retryDelay?: number; // Base delay in milliseconds (default: 1000), uses exponential backoff
+}
+```
+
+#### Examples
+
+```ts
+// Basic usage
+const loader = createApiTranslationLoader();
+
+// Custom options
+const loader = createApiTranslationLoader({
+  translationApiPath: '/api/v2/translations',
+  cacheTtlMs: 10 * 60 * 1000, // 10 minutes
+  disableCache: false,
+  retryCount: 3,              // Retry 3 times on network errors
+  retryDelay: 1000,            // 1 second base delay (exponential backoff)
+  requestInit: {
+    headers: {
+      'Authorization': 'Bearer token'
+    }
+  }
+});
+
+// Dynamic request options
+const loader = createApiTranslationLoader({
+  requestInit: (language, namespace) => ({
+    headers: {
+      'X-Language': language,
+      'X-Namespace': namespace
+    }
+  })
+});
+```
+
+### preloadNamespaces
+
+Preloads multiple namespaces in parallel.
+
+```ts
+function preloadNamespaces(
+  language: string,
+  namespaces: string[],
+  loader: TranslationLoader,
+  options?: PreloadOptions
+): Promise<{
+  fulfilled: string[];
+  rejected: unknown[];
+}>
+```
+
+#### Options
+
+```ts
+interface PreloadOptions {
+  // Logger (default: console)
+  logger?: Pick<typeof console, 'log' | 'warn'>;
+  
+  // Suppress errors (default: false)
+  suppressErrors?: boolean;
+}
+```
+
+#### Examples
+
+```ts
+import { preloadNamespaces } from '@hua-labs/i18n-loaders';
+
+const loader = createApiTranslationLoader();
+
+// Preload multiple namespaces
+const result = await preloadNamespaces(
+  'ko',
+  ['common', 'navigation', 'footer'],
+  loader
+);
+
+console.log(`Loaded: ${result.fulfilled.length}`);
+console.log(`Failed: ${result.rejected.length}`);
+```
+
+### warmFallbackLanguages
+
+Pre-warms fallback languages.
+
+```ts
+function warmFallbackLanguages(
+  currentLanguage: string,
+  languages: string[],
+  namespaces: string[],
+  loader: TranslationLoader,
+  options?: PreloadOptions
+): Promise<Array<{
+  fulfilled: string[];
+  rejected: unknown[];
+}>>
+```
+
+#### Examples
+
+```ts
+import { warmFallbackLanguages } from '@hua-labs/i18n-loaders';
+
+const loader = createApiTranslationLoader();
+
+// When current language is 'ko', preload 'en', 'ja'
+await warmFallbackLanguages(
+  'ko',
+  ['ko', 'en', 'ja'],
+  ['common', 'navigation'],
+  loader
+);
+```
+
+### withDefaultTranslations
+
+Merges default translations with API translations. Uses default translations if API fails.
+
+```ts
+function withDefaultTranslations(
+  loader: TranslationLoader,
+  defaults: DefaultTranslations
+): TranslationLoader
+```
+
+#### Types
+
+```ts
+type DefaultTranslations = Record<
+  string, // language
+  Record<string, TranslationRecord> // namespace -> translations
+>;
+```
+
+#### Examples
+
+```ts
+import { withDefaultTranslations } from '@hua-labs/i18n-loaders';
+
+const apiLoader = createApiTranslationLoader();
+
+const defaults = {
+  ko: {
+    common: {
+      welcome: 'Welcome',
+      hello: 'Hello'
+    }
+  },
+  en: {
+    common: {
+      welcome: 'Welcome',
+      hello: 'Hello'
+    }
+  }
+};
+
+const loader = withDefaultTranslations(apiLoader, defaults);
+
+// Merges with default translations if API succeeds
+// Uses only default translations if API fails
+const translations = await loader('ko', 'common');
+```
+
+## Usage Scenarios
+
+### Next.js App Router
+
+```tsx
+// lib/i18n-config.ts
+import { createCoreI18n } from '@hua-labs/i18n-core';
+import { createApiTranslationLoader, preloadNamespaces } from '@hua-labs/i18n-loaders';
+
+const loadTranslations = createApiTranslationLoader({
+  translationApiPath: '/api/translations',
+  cacheTtlMs: 60_000
+});
+
+export const I18nProvider = createCoreI18n({
+  defaultLanguage: 'ko',
+  fallbackLanguage: 'en',
+  namespaces: ['common', 'navigation', 'footer'],
+  translationLoader: 'custom',
+  loadTranslations
+});
+
+// Use in app/layout.tsx
+export default function RootLayout({ children }) {
+  // Preload on client
+  if (typeof window !== 'undefined') {
+    preloadNamespaces('ko', ['common', 'navigation'], loadTranslations);
+  }
+  
+  return (
+    <html>
+      <body>
+        <I18nProvider>{children}</I18nProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+### Using with SSR
+
+```tsx
+// app/layout.tsx (Server Component)
+import { loadSSRTranslations } from './lib/ssr-translations';
+import { createCoreI18n } from '@hua-labs/i18n-core';
+import { createApiTranslationLoader } from '@hua-labs/i18n-loaders';
+
+export default async function RootLayout({ children }) {
+  // Load translations from SSR
+  const ssrTranslations = await loadSSRTranslations('ko');
+  
+  // Client loader
+  const loadTranslations = createApiTranslationLoader({
+    translationApiPath: '/api/translations'
+  });
+  
+  const I18nProvider = createCoreI18n({
+    defaultLanguage: 'ko',
+    fallbackLanguage: 'en',
+    namespaces: ['common', 'navigation', 'footer'],
+    translationLoader: 'custom',
+    loadTranslations,
+    initialTranslations: ssrTranslations // Pass SSR translations
+  });
+  
+  return (
+    <html lang="ko">
+      <body>
+        <I18nProvider>{children}</I18nProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+## Caching Behavior
+
+- **TTL Cache**: Each translation is cached for `cacheTtlMs` duration
+- **Duplicate Request Prevention**: Reuses existing Promise if same translation is loading
+- **Global Cache**: Same loader instance shares cache across all components
+
+## Error Handling
+
+- **Automatic retry**: Network errors are automatically retried with exponential backoff (configurable via `retryCount` and `retryDelay`)
+- Throws error on API request failure after all retries are exhausted
+- Falls back to default translations when using `withDefaultTranslations`
+- `preloadNamespaces` uses `Promise.allSettled` to continue even if some fail
+
+### Retry Configuration
+
+```ts
+const loader = createApiTranslationLoader({
+  translationApiPath: '/api/translations',
+  retryCount: 3,        // Retry up to 3 times on network errors (default: 0, no retry)
+  retryDelay: 1000,    // Start with 1 second delay, doubles on each retry (exponential backoff)
+});
+```
+
+The retry mechanism uses exponential backoff:
+- 1st retry: waits `retryDelay` ms (e.g., 1000ms)
+- 2nd retry: waits `retryDelay * 2` ms (e.g., 2000ms)
+- 3rd retry: waits `retryDelay * 4` ms (e.g., 4000ms)
+
+## Examples
+
+- **[Next.js Example](../../examples/next-app-router-example/)** - Complete example using API loader with caching
+
+## Error Handling Improvements
+
+The API loader now includes enhanced error detection:
+
+- **Network error detection**: Improved detection of network failures
+- **HTTP status code handling**: Automatic retry for 5xx errors and 408 timeouts
+- **Exponential backoff**: Smart retry strategy with configurable delays
+- **Error type classification**: Better distinction between retryable and non-retryable errors
+
+See [API Loader Guide](./docs/API_LOADER.md) for detailed error handling documentation.
+
+## Documentation
+
+- [API Loader Guide](./docs/API_LOADER.md) - Detailed API loader documentation and error handling
+
+## License
+
+MIT License

package/dist/api-loader.d.ts

@@ -0,0 +1,3 @@
+import { ApiLoaderOptions, TranslationLoader } from './types';
+export declare function createApiTranslationLoader(options?: ApiLoaderOptions): TranslationLoader;
+//# sourceMappingURL=api-loader.d.ts.map

package/dist/api-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-loader.d.ts","sourceRoot":"","sources":["../src/api-loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAqB,MAAM,SAAS,CAAC;AAiDjF,wBAAgB,0BAA0B,CACxC,OAAO,GAAE,gBAAqB,GAC7B,iBAAiB,CAkJnB"}

package/dist/api-loader.js

@@ -0,0 +1,142 @@
+const FIVE_MINUTES = 5 * 60 * 1000;
+const defaultFetcher = (input, init) => fetch(input, init);
+/**
+ * 재시도 가능한 에러인지 확인
+ */
+function isRetryableError(error) {
+    // 네트워크 에러 (TypeError)
+    if (error instanceof TypeError) {
+        return true;
+    }
+    // Fetch API 에러 메시지 확인
+    if (error instanceof Error) {
+        const message = error.message.toLowerCase();
+        if (message.includes('failed to fetch') ||
+            message.includes('networkerror') ||
+            message.includes('network request failed')) {
+            return true;
+        }
+    }
+    // Response 객체가 있는 경우 HTTP 상태 코드 확인
+    if (error && typeof error === 'object' && 'status' in error) {
+        const status = error.status;
+        // 5xx 서버 에러는 재시도 가능
+        if (status >= 500 && status < 600) {
+            return true;
+        }
+        // 408 Request Timeout도 재시도 가능
+        if (status === 408) {
+            return true;
+        }
+    }
+    return false;
+}
+export function createApiTranslationLoader(options = {}) {
+    const translationApiPath = options.translationApiPath ?? '/api/translations';
+    const cacheTtlMs = options.cacheTtlMs ?? FIVE_MINUTES;
+    const fetcher = options.fetcher ?? defaultFetcher;
+    const logger = options.logger ?? console;
+    const retryCount = options.retryCount ?? 0;
+    const retryDelay = options.retryDelay ?? 1000;
+    const localCache = new Map();
+    const inFlightRequests = new Map();
+    const buildUrl = (language, namespace) => {
+        const safeNamespace = namespace.replace(/[^a-zA-Z0-9-_]/g, '');
+        const path = `${translationApiPath}/${language}/${safeNamespace}`;
+        if (typeof window !== 'undefined') {
+            return path;
+        }
+        if (options.baseUrl) {
+            return `${options.baseUrl}${path}`;
+        }
+        if (process.env.NEXT_PUBLIC_SITE_URL) {
+            return `${process.env.NEXT_PUBLIC_SITE_URL}${path}`;
+        }
+        if (process.env.VERCEL_URL) {
+            const vercelUrl = process.env.VERCEL_URL.startsWith('http')
+                ? process.env.VERCEL_URL
+                : `https://${process.env.VERCEL_URL}`;
+            return `${vercelUrl}${path}`;
+        }
+        const fallbackBase = options.localFallbackBaseUrl ?? 'http://localhost:3000';
+        return `${fallbackBase}${path}`;
+    };
+    const getRequestInit = (language, namespace) => {
+        if (typeof options.requestInit === 'function') {
+            return options.requestInit(language, namespace) ?? {};
+        }
+        return options.requestInit ?? {};
+    };
+    const getCached = (cacheKey) => {
+        if (options.disableCache) {
+            return null;
+        }
+        const entry = localCache.get(cacheKey);
+        if (!entry) {
+            return null;
+        }
+        if (entry.expiresAt < Date.now()) {
+            localCache.delete(cacheKey);
+            return null;
+        }
+        return entry.data;
+    };
+    const setCached = (cacheKey, data) => {
+        if (options.disableCache) {
+            return;
+        }
+        localCache.set(cacheKey, {
+            data,
+            expiresAt: Date.now() + cacheTtlMs
+        });
+    };
+    const loadTranslations = async (language, namespace) => {
+        const cacheKey = `${language}:${namespace}`;
+        const cached = getCached(cacheKey);
+        if (cached) {
+            return cached;
+        }
+        const inFlight = inFlightRequests.get(cacheKey);
+        if (inFlight) {
+            return inFlight;
+        }
+        const url = buildUrl(language, namespace);
+        const requestInit = getRequestInit(language, namespace);
+        const performRequest = async (attempt) => {
+            try {
+                const response = await fetcher(url, {
+                    cache: 'no-store',
+                    ...requestInit
+                });
+                if (!response.ok) {
+                    throw new Error(`[i18n-loaders] Failed to load ${language}/${namespace} (${response.status})`);
+                }
+                const data = (await response.json());
+                setCached(cacheKey, data);
+                return data;
+            }
+            catch (error) {
+                // 재시도 가능한 에러인지 확인
+                const isRetryable = isRetryableError(error);
+                if (isRetryable && attempt < retryCount) {
+                    logger.warn?.(`[i18n-loaders] Translation fetch failed (attempt ${attempt + 1}/${retryCount + 1}), retrying...`, language, namespace, error);
+                    // 지수 백오프: 각 재시도마다 지연 시간 증가
+                    const delay = retryDelay * Math.pow(2, attempt);
+                    await new Promise(resolve => setTimeout(resolve, delay));
+                    return performRequest(attempt + 1);
+                }
+                // 재시도 불가능하거나 재시도 횟수 초과
+                logger.warn?.('[i18n-loaders] translation fetch failed', language, namespace, error);
+                throw error;
+            }
+        };
+        const requestPromise = performRequest(0)
+            .finally(() => {
+            inFlightRequests.delete(cacheKey);
+        });
+        inFlightRequests.set(cacheKey, requestPromise);
+        return requestPromise;
+    };
+    return loadTranslations;
+}
+//# sourceMappingURL=api-loader.js.map

package/dist/api-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-loader.js","sourceRoot":"","sources":["../src/api-loader.ts"],"names":[],"mappings":"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"}

package/dist/defaults.d.ts

@@ -0,0 +1,3 @@
+import { DefaultTranslations, TranslationLoader } from './types';
+export declare function withDefaultTranslations(loader: TranslationLoader, defaults: DefaultTranslations): TranslationLoader;
+//# sourceMappingURL=defaults.d.ts.map

package/dist/defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EAElB,MAAM,SAAS,CAAC;AAEjB,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,iBAAiB,EACzB,QAAQ,EAAE,mBAAmB,GAC5B,iBAAiB,CA2BnB"}

package/dist/defaults.js

@@ -0,0 +1,40 @@
+export function withDefaultTranslations(loader, defaults) {
+    return async (language, namespace) => {
+        const fallback = defaults[language]?.[namespace];
+        try {
+            const remote = await loader(language, namespace);
+            // API 응답이 빈 객체이거나 null/undefined인 경우 fallback 반환
+            if (!remote || (typeof remote === 'object' && Object.keys(remote).length === 0)) {
+                if (fallback) {
+                    return fallback;
+                }
+                return remote || {};
+            }
+            if (!fallback) {
+                return remote;
+            }
+            return mergeTranslations(fallback, remote);
+        }
+        catch (error) {
+            if (fallback) {
+                return fallback;
+            }
+            throw error;
+        }
+    };
+}
+function mergeTranslations(base, override) {
+    const result = { ...base };
+    for (const [key, value] of Object.entries(override)) {
+        if (isPlainObject(value) && isPlainObject(result[key])) {
+            result[key] = mergeTranslations(result[key], value);
+            continue;
+        }
+        result[key] = value;
+    }
+    return result;
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=defaults.js.map

package/dist/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAMA,MAAM,UAAU,uBAAuB,CACrC,MAAyB,EACzB,QAA6B;IAE7B,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE;QACnC,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC;QAEjD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;YAEjD,iDAAiD;YACjD,IAAI,CAAC,MAAM,IAAI,CAAC,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC;gBAChF,IAAI,QAAQ,EAAE,CAAC;oBACb,OAAO,QAAQ,CAAC;gBAClB,CAAC;gBACD,OAAO,MAAM,IAAI,EAAE,CAAC;YACtB,CAAC;YAED,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,OAAO,MAAM,CAAC;YAChB,CAAC;YAED,OAAO,iBAAiB,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC7C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,QAAQ,EAAE,CAAC;gBACb,OAAO,QAAQ,CAAC;YAClB,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,iBAAiB,CACxB,IAAuB,EACvB,QAA2B;IAE3B,MAAM,MAAM,GAAsB,EAAE,GAAG,IAAI,EAAE,CAAC;IAE9C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QACpD,IAAI,aAAa,CAAC,KAAK,CAAC,IAAI,aAAa,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;YACvD,MAAM,CAAC,GAAG,CAAC,GAAG,iBAAiB,CAC7B,MAAM,CAAC,GAAG,CAAsB,EAChC,KAA0B,CAC3B,CAAC;YACF,SAAS;QACX,CAAC;QAED,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACtB,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { createApiTranslationLoader } from './api-loader';
+export { preloadNamespaces, warmFallbackLanguages } from './preload';
+export { withDefaultTranslations } from './defaults';
+export type { ApiLoaderOptions, DefaultTranslations, PreloadOptions, TranslationLoader, TranslationRecord } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AACrE,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAErD,YAAY,EACV,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createApiTranslationLoader } from './api-loader';
+export { preloadNamespaces, warmFallbackLanguages } from './preload';
+export { withDefaultTranslations } from './defaults';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AACrE,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC"}

package/dist/preload.d.ts

@@ -0,0 +1,10 @@
+import { PreloadOptions, TranslationLoader } from './types';
+export declare function preloadNamespaces(language: string, namespaces: string[], loader: TranslationLoader, options?: PreloadOptions): Promise<{
+    fulfilled: string[];
+    rejected: any[];
+}>;
+export declare function warmFallbackLanguages(currentLanguage: string, languages: string[], namespaces: string[], loader: TranslationLoader, options?: PreloadOptions): Promise<{
+    fulfilled: string[];
+    rejected: any[];
+}[]>;
+//# sourceMappingURL=preload.d.ts.map

package/dist/preload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preload.d.ts","sourceRoot":"","sources":["../src/preload.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAI5D,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAAE,EACpB,MAAM,EAAE,iBAAiB,EACzB,OAAO,GAAE,cAAmB;;;GAmC7B;AAED,wBAAsB,qBAAqB,CACzC,eAAe,EAAE,MAAM,EACvB,SAAS,EAAE,MAAM,EAAE,EACnB,UAAU,EAAE,MAAM,EAAE,EACpB,MAAM,EAAE,iBAAiB,EACzB,OAAO,GAAE,cAAmB;;;KAY7B"}

package/dist/preload.js

@@ -0,0 +1,28 @@
+const defaultLogger = console;
+export async function preloadNamespaces(language, namespaces, loader, options = {}) {
+    const logger = options.logger ?? defaultLogger;
+    const results = await Promise.allSettled(namespaces.map(async (namespace) => {
+        await loader(language, namespace);
+        return namespace;
+    }));
+    const fulfilled = results.filter((result) => result.status === 'fulfilled');
+    const rejected = results.filter((result) => result.status === 'rejected');
+    if (fulfilled.length > 0) {
+        logger.log?.(`[i18n-loaders] Preloaded ${fulfilled.length}/${namespaces.length} namespaces for ${language}`);
+    }
+    if (rejected.length > 0 && !options.suppressErrors) {
+        logger.warn?.(`[i18n-loaders] Failed to preload ${rejected.length} namespaces for ${language}`);
+    }
+    return {
+        fulfilled: fulfilled.map((result) => result.value),
+        rejected: rejected.map((result) => result.reason)
+    };
+}
+export async function warmFallbackLanguages(currentLanguage, languages, namespaces, loader, options = {}) {
+    const targets = languages.filter((language) => language !== currentLanguage);
+    if (targets.length === 0) {
+        return [];
+    }
+    return Promise.all(targets.map((language) => preloadNamespaces(language, namespaces, loader, options)));
+}
+//# sourceMappingURL=preload.js.map

package/dist/preload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preload.js","sourceRoot":"","sources":["../src/preload.ts"],"names":[],"mappings":"AAEA,MAAM,aAAa,GAAG,OAAO,CAAC;AAE9B,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,QAAgB,EAChB,UAAoB,EACpB,MAAyB,EACzB,UAA0B,EAAE;IAE5B,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,aAAa,CAAC;IAE/C,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,CACtC,UAAU,CAAC,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE;QACjC,MAAM,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;QAClC,OAAO,SAAS,CAAC;IACnB,CAAC,CAAC,CACH,CAAC;IAEF,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAC9B,CAAC,MAAM,EAA4C,EAAE,CACnD,MAAM,CAAC,MAAM,KAAK,WAAW,CAChC,CAAC;IACF,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAC7B,CAAC,MAAM,EAAmC,EAAE,CAAC,MAAM,CAAC,MAAM,KAAK,UAAU,CAC1E,CAAC;IAEF,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,CAAC,GAAG,EAAE,CACV,4BAA4B,SAAS,CAAC,MAAM,IAAI,UAAU,CAAC,MAAM,mBAAmB,QAAQ,EAAE,CAC/F,CAAC;IACJ,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC;QACnD,MAAM,CAAC,IAAI,EAAE,CACX,oCAAoC,QAAQ,CAAC,MAAM,mBAAmB,QAAQ,EAAE,CACjF,CAAC;IACJ,CAAC;IAED,OAAO;QACL,SAAS,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC;QAClD,QAAQ,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC;KAClD,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,eAAuB,EACvB,SAAmB,EACnB,UAAoB,EACpB,MAAyB,EACzB,UAA0B,EAAE;IAE5B,MAAM,OAAO,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,KAAK,eAAe,CAAC,CAAC;IAC7E,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,OAAO,OAAO,CAAC,GAAG,CAChB,OAAO,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CACvB,iBAAiB,CAAC,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,CACzD,CACF,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,22 @@
+export type TranslationRecord = Record<string, unknown>;
+export type TranslationLoader = (language: string, namespace: string) => Promise<TranslationRecord>;
+export interface ApiLoaderOptions {
+    translationApiPath?: string;
+    baseUrl?: string;
+    localFallbackBaseUrl?: string;
+    cacheTtlMs?: number;
+    disableCache?: boolean;
+    requestInit?: RequestInit | ((language: string, namespace: string) => RequestInit | undefined);
+    fetcher?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+    logger?: Pick<typeof console, 'log' | 'warn' | 'error'>;
+    /** 재시도 횟수 (기본값: 0, 재시도 안 함) */
+    retryCount?: number;
+    /** 재시도 지연 시간 (밀리초, 기본값: 1000) */
+    retryDelay?: number;
+}
+export interface PreloadOptions {
+    logger?: Pick<typeof console, 'log' | 'warn'>;
+    suppressErrors?: boolean;
+}
+export type DefaultTranslations = Record<string, Record<string, TranslationRecord>>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAExD,MAAM,MAAM,iBAAiB,GAAG,CAC9B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,KACd,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAEhC,MAAM,WAAW,gBAAgB;IAC/B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EACR,WAAW,GACX,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,WAAW,GAAG,SAAS,CAAC,CAAC;IACvE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,GAAG,GAAG,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC9E,MAAM,CAAC,EAAE,IAAI,CAAC,OAAO,OAAO,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IACxD,+BAA+B;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iCAAiC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,IAAI,CAAC,OAAO,OAAO,EAAE,KAAK,GAAG,MAAM,CAAC,CAAC;IAC9C,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,MAAM,mBAAmB,GAAG,MAAM,CACtC,MAAM,EACN,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAClC,CAAC"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@hua-labs/i18n-loaders",
+  "version": "1.0.0",
+  "description": "Production-ready loaders, caching, and preloading helpers for @hua-labs/i18n-core.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@hua-labs/i18n-core": "1.0.0"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/react": "^19.2.7",
+    "eslint": "^8.0.0",
+    "react": "^19.2.0",
+    "typescript": "^5.8.3"
+  },
+  "keywords": [
+    "i18n",
+    "internationalization",
+    "loader",
+    "preload",
+    "cache"
+  ],
+  "author": "HUA Labs",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/HUA-Labs/HUA-Labs-public.git"
+  },
+  "bugs": {
+    "url": "https://github.com/HUA-Labs/HUA-Labs-public/issues"
+  },
+  "homepage": "https://github.com/HUA-Labs/HUA-Labs-public#readme",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "test": "echo \"No tests defined\"",
+    "lint": "echo 'Skipping lint for hua-i18n-loaders (TypeScript only, linted by tsc)'",
+    "type-check": "tsc --noEmit"
+  }
+}

package/src/api-loader.ts

@@ -0,0 +1,199 @@
+import { ApiLoaderOptions, TranslationLoader, TranslationRecord } from './types';
+
+interface CacheEntry {
+  data: TranslationRecord;
+  expiresAt: number;
+}
+
+const FIVE_MINUTES = 5 * 60 * 1000;
+
+const defaultFetcher = (input: RequestInfo | URL, init?: RequestInit) =>
+  fetch(input, init);
+
+/**
+ * 재시도 가능한 에러인지 확인
+ */
+function isRetryableError(error: unknown): boolean {
+  // 네트워크 에러 (TypeError)
+  if (error instanceof TypeError) {
+    return true;
+  }
+
+  // Fetch API 에러 메시지 확인
+  if (error instanceof Error) {
+    const message = error.message.toLowerCase();
+    if (
+      message.includes('failed to fetch') ||
+      message.includes('networkerror') ||
+      message.includes('network request failed')
+    ) {
+      return true;
+    }
+  }
+
+  // Response 객체가 있는 경우 HTTP 상태 코드 확인
+  if (error && typeof error === 'object' && 'status' in error) {
+    const status = (error as { status: number }).status;
+    // 5xx 서버 에러는 재시도 가능
+    if (status >= 500 && status < 600) {
+      return true;
+    }
+    // 408 Request Timeout도 재시도 가능
+    if (status === 408) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+export function createApiTranslationLoader(
+  options: ApiLoaderOptions = {}
+): TranslationLoader {
+  const translationApiPath = options.translationApiPath ?? '/api/translations';
+  const cacheTtlMs = options.cacheTtlMs ?? FIVE_MINUTES;
+  const fetcher = options.fetcher ?? defaultFetcher;
+  const logger = options.logger ?? console;
+  const retryCount = options.retryCount ?? 0;
+  const retryDelay = options.retryDelay ?? 1000;
+  const localCache = new Map<string, CacheEntry>();
+  const inFlightRequests = new Map<string, Promise<TranslationRecord>>();
+
+  const buildUrl = (language: string, namespace: string) => {
+    const safeNamespace = namespace.replace(/[^a-zA-Z0-9-_]/g, '');
+    const path = `${translationApiPath}/${language}/${safeNamespace}`;
+
+    if (typeof window !== 'undefined') {
+      return path;
+    }
+
+    if (options.baseUrl) {
+      return `${options.baseUrl}${path}`;
+    }
+
+    if (process.env.NEXT_PUBLIC_SITE_URL) {
+      return `${process.env.NEXT_PUBLIC_SITE_URL}${path}`;
+    }
+
+    if (process.env.VERCEL_URL) {
+      const vercelUrl = process.env.VERCEL_URL.startsWith('http')
+        ? process.env.VERCEL_URL
+        : `https://${process.env.VERCEL_URL}`;
+      return `${vercelUrl}${path}`;
+    }
+
+    const fallbackBase = options.localFallbackBaseUrl ?? 'http://localhost:3000';
+    return `${fallbackBase}${path}`;
+  };
+
+  const getRequestInit = (language: string, namespace: string): RequestInit => {
+    if (typeof options.requestInit === 'function') {
+      return options.requestInit(language, namespace) ?? {};
+    }
+
+    return options.requestInit ?? {};
+  };
+
+  const getCached = (cacheKey: string) => {
+    if (options.disableCache) {
+      return null;
+    }
+
+    const entry = localCache.get(cacheKey);
+    if (!entry) {
+      return null;
+    }
+
+    if (entry.expiresAt < Date.now()) {
+      localCache.delete(cacheKey);
+      return null;
+    }
+
+    return entry.data;
+  };
+
+  const setCached = (cacheKey: string, data: TranslationRecord) => {
+    if (options.disableCache) {
+      return;
+    }
+
+    localCache.set(cacheKey, {
+      data,
+      expiresAt: Date.now() + cacheTtlMs
+    });
+  };
+
+  const loadTranslations: TranslationLoader = async (language, namespace) => {
+    const cacheKey = `${language}:${namespace}`;
+    const cached = getCached(cacheKey);
+
+    if (cached) {
+      return cached;
+    }
+
+    const inFlight = inFlightRequests.get(cacheKey);
+    if (inFlight) {
+      return inFlight;
+    }
+
+    const url = buildUrl(language, namespace);
+    const requestInit = getRequestInit(language, namespace);
+
+    const performRequest = async (attempt: number): Promise<TranslationRecord> => {
+      try {
+        const response = await fetcher(url, {
+          cache: 'no-store',
+          ...requestInit
+        });
+
+        if (!response.ok) {
+          throw new Error(
+            `[i18n-loaders] Failed to load ${language}/${namespace} (${response.status})`
+          );
+        }
+
+        const data = (await response.json()) as TranslationRecord;
+        setCached(cacheKey, data);
+        return data;
+      } catch (error) {
+        // 재시도 가능한 에러인지 확인
+        const isRetryable = isRetryableError(error);
+
+        if (isRetryable && attempt < retryCount) {
+          logger.warn?.(
+            `[i18n-loaders] Translation fetch failed (attempt ${attempt + 1}/${retryCount + 1}), retrying...`,
+            language,
+            namespace,
+            error
+          );
+          
+          // 지수 백오프: 각 재시도마다 지연 시간 증가
+          const delay = retryDelay * Math.pow(2, attempt);
+          await new Promise(resolve => setTimeout(resolve, delay));
+          
+          return performRequest(attempt + 1);
+        }
+
+        // 재시도 불가능하거나 재시도 횟수 초과
+        logger.warn?.(
+          '[i18n-loaders] translation fetch failed',
+          language,
+          namespace,
+          error
+        );
+        throw error;
+      }
+    };
+
+    const requestPromise = performRequest(0)
+      .finally(() => {
+        inFlightRequests.delete(cacheKey);
+      });
+
+    inFlightRequests.set(cacheKey, requestPromise);
+    return requestPromise;
+  };
+
+  return loadTranslations;
+}
+

package/src/defaults.ts

@@ -0,0 +1,63 @@
+import {
+  DefaultTranslations,
+  TranslationLoader,
+  TranslationRecord
+} from './types';
+
+export function withDefaultTranslations(
+  loader: TranslationLoader,
+  defaults: DefaultTranslations
+): TranslationLoader {
+  return async (language, namespace) => {
+    const fallback = defaults[language]?.[namespace];
+
+    try {
+      const remote = await loader(language, namespace);
+      
+      // API 응답이 빈 객체이거나 null/undefined인 경우 fallback 반환
+      if (!remote || (typeof remote === 'object' && Object.keys(remote).length === 0)) {
+        if (fallback) {
+          return fallback;
+        }
+        return remote || {};
+      }
+      
+      if (!fallback) {
+        return remote;
+      }
+
+      return mergeTranslations(fallback, remote);
+    } catch (error) {
+      if (fallback) {
+        return fallback;
+      }
+      throw error;
+    }
+  };
+}
+
+function mergeTranslations(
+  base: TranslationRecord,
+  override: TranslationRecord
+): TranslationRecord {
+  const result: TranslationRecord = { ...base };
+
+  for (const [key, value] of Object.entries(override)) {
+    if (isPlainObject(value) && isPlainObject(result[key])) {
+      result[key] = mergeTranslations(
+        result[key] as TranslationRecord,
+        value as TranslationRecord
+      );
+      continue;
+    }
+
+    result[key] = value;
+  }
+
+  return result;
+}
+
+function isPlainObject(value: unknown): value is TranslationRecord {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+

package/src/index.ts

@@ -0,0 +1,12 @@
+export { createApiTranslationLoader } from './api-loader';
+export { preloadNamespaces, warmFallbackLanguages } from './preload';
+export { withDefaultTranslations } from './defaults';
+
+export type {
+  ApiLoaderOptions,
+  DefaultTranslations,
+  PreloadOptions,
+  TranslationLoader,
+  TranslationRecord
+} from './types';
+

package/src/preload.ts

@@ -0,0 +1,64 @@
+import { PreloadOptions, TranslationLoader } from './types';
+
+const defaultLogger = console;
+
+export async function preloadNamespaces(
+  language: string,
+  namespaces: string[],
+  loader: TranslationLoader,
+  options: PreloadOptions = {}
+) {
+  const logger = options.logger ?? defaultLogger;
+
+  const results = await Promise.allSettled(
+    namespaces.map(async (namespace) => {
+      await loader(language, namespace);
+      return namespace;
+    })
+  );
+
+  const fulfilled = results.filter(
+    (result): result is PromiseFulfilledResult<string> =>
+      result.status === 'fulfilled'
+  );
+  const rejected = results.filter(
+    (result): result is PromiseRejectedResult => result.status === 'rejected'
+  );
+
+  if (fulfilled.length > 0) {
+    logger.log?.(
+      `[i18n-loaders] Preloaded ${fulfilled.length}/${namespaces.length} namespaces for ${language}`
+    );
+  }
+
+  if (rejected.length > 0 && !options.suppressErrors) {
+    logger.warn?.(
+      `[i18n-loaders] Failed to preload ${rejected.length} namespaces for ${language}`
+    );
+  }
+
+  return {
+    fulfilled: fulfilled.map((result) => result.value),
+    rejected: rejected.map((result) => result.reason)
+  };
+}
+
+export async function warmFallbackLanguages(
+  currentLanguage: string,
+  languages: string[],
+  namespaces: string[],
+  loader: TranslationLoader,
+  options: PreloadOptions = {}
+) {
+  const targets = languages.filter((language) => language !== currentLanguage);
+  if (targets.length === 0) {
+    return [];
+  }
+
+  return Promise.all(
+    targets.map((language) =>
+      preloadNamespaces(language, namespaces, loader, options)
+    )
+  );
+}
+

package/src/types.ts

@@ -0,0 +1,34 @@
+export type TranslationRecord = Record<string, unknown>;
+
+export type TranslationLoader = (
+  language: string,
+  namespace: string
+) => Promise<TranslationRecord>;
+
+export interface ApiLoaderOptions {
+  translationApiPath?: string;
+  baseUrl?: string;
+  localFallbackBaseUrl?: string;
+  cacheTtlMs?: number;
+  disableCache?: boolean;
+  requestInit?:
+    | RequestInit
+    | ((language: string, namespace: string) => RequestInit | undefined);
+  fetcher?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+  logger?: Pick<typeof console, 'log' | 'warn' | 'error'>;
+  /** 재시도 횟수 (기본값: 0, 재시도 안 함) */
+  retryCount?: number;
+  /** 재시도 지연 시간 (밀리초, 기본값: 1000) */
+  retryDelay?: number;
+}
+
+export interface PreloadOptions {
+  logger?: Pick<typeof console, 'log' | 'warn'>;
+  suppressErrors?: boolean;
+}
+
+export type DefaultTranslations = Record<
+  string,
+  Record<string, TranslationRecord>
+>;
+