@idealyst/translate 1.2.3

package/src/hooks/types.ts

@@ -0,0 +1,113 @@
+import type { i18n, TFunction, Namespace, KeyPrefix } from 'i18next';
+
+/**
+ * Options for the useTranslation hook
+ */
+export interface UseTranslationOptions<TKPrefix extends KeyPrefix<Namespace> = undefined> {
+  /**
+   * Namespace(s) to use for translations
+   */
+  ns?: Namespace;
+
+  /**
+   * Key prefix to prepend to all translation keys
+   */
+  keyPrefix?: TKPrefix;
+
+  /**
+   * Whether to bind the t function to i18n instance
+   * @default true
+   */
+  bindI18n?: string;
+
+  /**
+   * Whether to bind the t function to store
+   * @default false
+   */
+  bindI18nStore?: string;
+}
+
+/**
+ * Result of the useTranslation hook
+ */
+export interface UseTranslationResult<TKPrefix extends KeyPrefix<Namespace> = undefined> {
+  /**
+   * Translation function
+   */
+  t: TFunction<Namespace, TKPrefix>;
+
+  /**
+   * Current language
+   */
+  language: string;
+
+  /**
+   * All available languages
+   */
+  languages: readonly string[];
+
+  /**
+   * Whether translations are ready
+   */
+  ready: boolean;
+
+  /**
+   * The i18next instance
+   */
+  i18n: i18n;
+}
+
+/**
+ * Options for the t() function
+ */
+export interface TranslationOptions {
+  /**
+   * Default value if key is not found
+   */
+  defaultValue?: string;
+
+  /**
+   * Count for pluralization
+   */
+  count?: number;
+
+  /**
+   * Context for contextual translations
+   */
+  context?: string;
+
+  /**
+   * Interpolation values
+   */
+  [key: string]: unknown;
+}
+
+/**
+ * Result of the useLanguage hook
+ */
+export interface UseLanguageResult {
+  /**
+   * Current language code
+   */
+  language: string;
+
+  /**
+   * All available languages
+   */
+  languages: readonly string[];
+
+  /**
+   * Change the current language
+   */
+  setLanguage: (lang: string) => Promise<void>;
+
+  /**
+   * Check if a language is supported
+   */
+  isSupported: (lang: string) => boolean;
+
+  /**
+   * Get the display name for a language code
+   */
+  getDisplayName: (lang: string, inLanguage?: string) => string;
+}

package/src/hooks/useLanguage.ts

@@ -0,0 +1,73 @@
+import { useCallback } from 'react';
+import { useTranslation } from 'react-i18next';
+import type { UseLanguageResult } from './types';
+
+/**
+ * Hook for managing the current language
+ *
+ * @returns Language management utilities
+ *
+ * @example
+ * ```tsx
+ * import { useLanguage } from '@idealyst/translate';
+ *
+ * function LanguageSwitcher() {
+ *   const { language, languages, setLanguage } = useLanguage();
+ *
+ *   return (
+ *     <select
+ *       value={language}
+ *       onChange={(e) => setLanguage(e.target.value)}
+ *     >
+ *       {languages.map((lang) => (
+ *         <option key={lang} value={lang}>
+ *           {lang}
+ *         </option>
+ *       ))}
+ *     </select>
+ *   );
+ * }
+ * ```
+ */
+export function useLanguage(): UseLanguageResult {
+  const { i18n } = useTranslation();
+
+  const setLanguage = useCallback(
+    async (lang: string): Promise<void> => {
+      await i18n.changeLanguage(lang);
+    },
+    [i18n]
+  );
+
+  const isSupported = useCallback(
+    (lang: string): boolean => {
+      return i18n.languages.includes(lang);
+    },
+    [i18n.languages]
+  );
+
+  const getDisplayName = useCallback(
+    (lang: string, inLanguage?: string): string => {
+      try {
+        const displayNames = new Intl.DisplayNames([inLanguage ?? lang], {
+          type: 'language',
+        });
+        return displayNames.of(lang) ?? lang;
+      } catch {
+        // Fallback if Intl.DisplayNames is not available
+        return lang;
+      }
+    },
+    []
+  );
+
+  return {
+    language: i18n.language,
+    languages: i18n.languages,
+    setLanguage,
+    isSupported,
+    getDisplayName,
+  };
+}
+
+export default useLanguage;

package/src/hooks/useTranslation.ts

@@ -0,0 +1,52 @@
+import { useTranslation as useI18nextTranslation } from 'react-i18next';
+import type { Namespace, KeyPrefix } from 'i18next';
+import type { UseTranslationOptions, UseTranslationResult } from './types';
+
+/**
+ * Hook to access translation functions
+ *
+ * @param ns - Namespace(s) to use for translations
+ * @param options - Additional options
+ * @returns Translation result with t function and metadata
+ *
+ * @example
+ * ```tsx
+ * import { useTranslation } from '@idealyst/translate';
+ *
+ * function MyComponent() {
+ *   const { t, language, ready } = useTranslation('common');
+ *
+ *   if (!ready) return <Loading />;
+ *
+ *   return (
+ *     <div>
+ *       <h1>{t('welcome.title')}</h1>
+ *       <p>{t('welcome.message', { name: 'World' })}</p>
+ *       <span>Current: {language}</span>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example With key prefix
+ * ```tsx
+ * const { t } = useTranslation('common', { keyPrefix: 'buttons' });
+ * // t('submit') is equivalent to t('buttons.submit')
+ * ```
+ */
+export function useTranslation<TKPrefix extends KeyPrefix<Namespace> = undefined>(
+  ns?: Namespace,
+  options?: UseTranslationOptions<TKPrefix>
+): UseTranslationResult<TKPrefix> {
+  const { t, i18n, ready } = useI18nextTranslation(ns, options);
+
+  return {
+    t: t as UseTranslationResult<TKPrefix>['t'],
+    language: i18n.language,
+    languages: i18n.languages,
+    ready,
+    i18n,
+  };
+}
+
+export default useTranslation;

package/src/index.native.ts

@@ -0,0 +1,2 @@
+// React Native specific exports (currently identical to main)
+export * from './index';

package/src/index.ts

@@ -0,0 +1,22 @@
+// Provider
+export { TranslateProvider, useTranslateContext } from './provider';
+export type { TranslateConfig, TranslateProviderProps, TranslateContextValue } from './provider';
+
+// Hooks
+export { useTranslation, useLanguage } from './hooks';
+export type {
+  UseTranslationOptions,
+  UseTranslationResult,
+  TranslationOptions,
+  UseLanguageResult,
+} from './hooks';
+
+// Components
+export { Trans } from './components';
+export type { TransProps } from './components';
+
+// Utils
+export { parseKey, hasNestedKey, getNestedValue, flattenKeys } from './utils';
+
+// Config
+export { defineConfig } from './config';

package/src/index.web.ts

@@ -0,0 +1,24 @@
+// Web-specific exports
+
+// Provider
+export { TranslateProvider, useTranslateContext } from './provider';
+export type { TranslateConfig, TranslateProviderProps, TranslateContextValue } from './provider';
+
+// Hooks
+export { useTranslation, useLanguage } from './hooks';
+export type {
+  UseTranslationOptions,
+  UseTranslationResult,
+  TranslationOptions,
+  UseLanguageResult,
+} from './hooks';
+
+// Components
+export { Trans } from './components';
+export type { TransProps } from './components';
+
+// Utils
+export { parseKey, hasNestedKey, getNestedValue, flattenKeys } from './utils';
+
+// Config
+export { defineConfig } from './config';

package/src/provider/TranslateProvider.tsx

@@ -0,0 +1,132 @@
+import React, { useEffect, useState, createContext, useContext, useMemo } from 'react';
+import i18next from 'i18next';
+import { I18nextProvider, initReactI18next } from 'react-i18next';
+import type { TranslateProviderProps, TranslateContextValue, TranslateConfig } from './types';
+
+/**
+ * Internal context for additional translate features
+ */
+const TranslateContext = createContext<TranslateContextValue | null>(null);
+
+/**
+ * Hook to access the translate context
+ */
+export function useTranslateContext(): TranslateContextValue {
+  const context = useContext(TranslateContext);
+  if (!context) {
+    throw new Error('useTranslateContext must be used within a TranslateProvider');
+  }
+  return context;
+}
+
+/**
+ * Creates and initializes an i18next instance with the given config
+ */
+function createI18nInstance(config: TranslateConfig): typeof i18next {
+  // If a custom instance is provided, use it directly
+  if (config.i18nInstance) {
+    return config.i18nInstance;
+  }
+
+  const instance = i18next.createInstance();
+
+  instance.use(initReactI18next).init({
+    lng: config.defaultLanguage,
+    fallbackLng: config.fallbackLanguage ?? config.defaultLanguage,
+    supportedLngs: config.languages,
+    defaultNS: config.defaultNamespace ?? 'translation',
+    resources: config.resources,
+    debug: config.debug ?? false,
+
+    interpolation: {
+      escapeValue: config.interpolation?.escapeValue ?? false, // React already escapes
+    },
+
+    react: {
+      useSuspense: false,
+    },
+  });
+
+  return instance;
+}
+
+/**
+ * Provider component that initializes i18next and provides translation context
+ *
+ * @example
+ * ```tsx
+ * import { TranslateProvider } from '@idealyst/translate';
+ * import en from './locales/en/common.json';
+ * import es from './locales/es/common.json';
+ *
+ * const config = {
+ *   defaultLanguage: 'en',
+ *   languages: ['en', 'es'],
+ *   resources: {
+ *     en: { common: en },
+ *     es: { common: es },
+ *   },
+ *   defaultNamespace: 'common',
+ * };
+ *
+ * export function App() {
+ *   return (
+ *     <TranslateProvider config={config}>
+ *       <MyApp />
+ *     </TranslateProvider>
+ *   );
+ * }
+ * ```
+ */
+export function TranslateProvider({
+  config,
+  children,
+  onInitialized,
+  onLanguageChanged,
+}: TranslateProviderProps) {
+  const [i18n] = useState(() => createI18nInstance(config));
+  const [ready, setReady] = useState(i18n.isInitialized);
+  const [language, setLanguage] = useState(i18n.language || config.defaultLanguage);
+
+  useEffect(() => {
+    // Handle initialization
+    if (!i18n.isInitialized) {
+      i18n.on('initialized', () => {
+        setReady(true);
+        onInitialized?.(i18n);
+      });
+    } else {
+      onInitialized?.(i18n);
+    }
+
+    // Handle language changes
+    const handleLanguageChanged = (lng: string) => {
+      setLanguage(lng);
+      onLanguageChanged?.(lng);
+    };
+
+    i18n.on('languageChanged', handleLanguageChanged);
+
+    return () => {
+      i18n.off('languageChanged', handleLanguageChanged);
+    };
+  }, [i18n, onInitialized, onLanguageChanged]);
+
+  const contextValue = useMemo<TranslateContextValue>(
+    () => ({
+      ready,
+      i18n,
+      language,
+      languages: config.languages,
+    }),
+    [ready, i18n, language, config.languages]
+  );
+
+  return (
+    <TranslateContext.Provider value={contextValue}>
+      <I18nextProvider i18n={i18n}>{children}</I18nextProvider>
+    </TranslateContext.Provider>
+  );
+}
+
+export default TranslateProvider;

package/src/provider/index.ts

@@ -0,0 +1,6 @@
+export { TranslateProvider, useTranslateContext, default } from './TranslateProvider';
+export type {
+  TranslateConfig,
+  TranslateProviderProps,
+  TranslateContextValue,
+} from './types';

package/src/provider/types.ts

@@ -0,0 +1,119 @@
+import type { i18n, Resource } from 'i18next';
+import type { ReactNode } from 'react';
+
+/**
+ * Configuration options for the TranslateProvider
+ */
+export interface TranslateConfig {
+  /**
+   * Default language code (e.g., 'en', 'es', 'fr')
+   */
+  defaultLanguage: string;
+
+  /**
+   * List of supported language codes
+   */
+  languages: string[];
+
+  /**
+   * Pre-loaded translation resources
+   * Format: { [lang]: { [namespace]: { key: value } } }
+   */
+  resources?: Resource;
+
+  /**
+   * Default namespace to use when none is specified
+   * @default 'translation'
+   */
+  defaultNamespace?: string;
+
+  /**
+   * Fallback language when translation is missing
+   * @default defaultLanguage
+   */
+  fallbackLanguage?: string;
+
+  /**
+   * Enable debug mode for i18next
+   * @default false
+   */
+  debug?: boolean;
+
+  /**
+   * Custom i18next instance (for advanced use cases)
+   * If provided, other config options are ignored
+   */
+  i18nInstance?: i18n;
+
+  /**
+   * Interpolation options
+   */
+  interpolation?: {
+    /**
+     * Escape HTML in interpolated values
+     * @default true for web, false for native
+     */
+    escapeValue?: boolean;
+  };
+
+  /**
+   * Backend configuration for loading translations dynamically
+   */
+  backend?: {
+    /**
+     * URL pattern for loading translations
+     * Use {{lng}} for language and {{ns}} for namespace
+     */
+    loadPath?: string;
+  };
+}
+
+/**
+ * Props for the TranslateProvider component
+ */
+export interface TranslateProviderProps {
+  /**
+   * Configuration for i18next
+   */
+  config: TranslateConfig;
+
+  /**
+   * Child components
+   */
+  children: ReactNode;
+
+  /**
+   * Callback when i18next is initialized
+   */
+  onInitialized?: (i18n: i18n) => void;
+
+  /**
+   * Callback when language changes
+   */
+  onLanguageChanged?: (language: string) => void;
+}
+
+/**
+ * Context value provided by TranslateProvider
+ */
+export interface TranslateContextValue {
+  /**
+   * Whether i18next is initialized and ready
+   */
+  ready: boolean;
+
+  /**
+   * The i18next instance
+   */
+  i18n: i18n;
+
+  /**
+   * Current language
+   */
+  language: string;
+
+  /**
+   * Available languages
+   */
+  languages: string[];
+}