@modern-js/main-doc 2.69.5 → 3.0.0-alpha.0

package/docs/en/guides/advanced-features/international/api.mdx

@@ -0,0 +1,400 @@
+---
+title: API Reference
+---
+
+# API Reference
+
+## useModernI18n Hook
+
+`useModernI18n` is a React Hook provided by the plugin for accessing internationalization functionality in components.
+
+### Return Value
+
+```ts
+interface UseModernI18nReturn {
+  /** Current language code */
+  language: string;
+
+  /** Function to change language */
+  changeLanguage: (newLang: string) => Promise<void>;
+
+  /** i18next instance (for advanced usage) */
+  i18nInstance: I18nInstance;
+
+  /** Supported language list */
+  supportedLanguages: string[];
+
+  /** Check if language is supported */
+  isLanguageSupported: (lang: string) => boolean;
+
+  /** Indicates if translation resources for current language are ready to use */
+  isResourcesReady: boolean;
+}
+```
+
+### Usage Example
+
+```tsx
+import { useModernI18n } from '@modern-js/plugin-i18n/runtime';
+
+function LanguageSwitcher() {
+  const { language, changeLanguage, supportedLanguages, isLanguageSupported } =
+    useModernI18n();
+
+  return (
+    <div>
+      <p>Current language: {language}</p>
+      <div>
+        {supportedLanguages.map(lang => (
+          <button
+            key={lang}
+            onClick={() => changeLanguage(lang)}
+            disabled={lang === language}
+          >
+            {lang}
+          </button>
+        ))}
+      </div>
+      <button
+        onClick={() => {
+          if (isLanguageSupported('ja')) {
+            changeLanguage('ja');
+          }
+        }}
+      >
+        Switch to Japanese
+      </button>
+    </div>
+  );
+}
+```
+
+### changeLanguage Method
+
+The `changeLanguage` method is used to switch languages. It will:
+
+1. Update the language of the i18next instance
+2. Update browser cache (Cookie/LocalStorage)
+3. Update URL path (if `localePathRedirect` is enabled)
+
+```tsx
+const { changeLanguage } = useModernI18n();
+
+// Switch language
+await changeLanguage('zh');
+```
+
+:::info
+`changeLanguage` is an async function that returns a Promise.
+
+:::
+
+### Language Support Check
+
+`isLanguageSupported` is used to check if a language is in the supported language list:
+
+```tsx
+const { isLanguageSupported, changeLanguage } = useModernI18n();
+
+function handleLanguageChange(lang: string) {
+  if (isLanguageSupported(lang)) {
+    changeLanguage(lang);
+  } else {
+    console.warn(`Language ${lang} is not supported`);
+  }
+}
+```
+
+### Resource Loading State
+
+`isResourcesReady` indicates whether the translation resources for the current language are loaded and ready to use. This is particularly useful when using SDK backend to load resources dynamically.
+
+```tsx
+import { useModernI18n } from '@modern-js/plugin-i18n/runtime';
+
+function MyComponent() {
+  const { isResourcesReady } = useModernI18n();
+
+  if (!isResourcesReady) {
+    return <div>Loading translation resources...</div>;
+  }
+
+  return <div>Translation resources are ready</div>;
+}
+```
+
+**When to use:**
+
+- Display a loading state while resources are being loaded
+- Prevent rendering content that depends on translations before resources are ready
+- Handle resource loading errors gracefully
+
+:::info
+`isResourcesReady` automatically checks:
+
+- If i18n instance is initialized
+- If any resources for the current language are currently loading (SDK backend only)
+- If all required namespaces for the current language are loaded in the store
+
+:::
+
+## I18nLink Component
+
+The `I18nLink` component is used to create links with language prefixes.
+
+### Props
+
+```tsx
+interface I18nLinkProps {
+  /** Target path (no need to include language prefix) */
+  to: string;
+  /** Child elements */
+  children: React.ReactNode;
+  /** Other Link component props (such as replace, state, etc.) */
+  [key: string]: any;
+}
+```
+
+### Usage Example
+
+```tsx
+import { I18nLink } from '@modern-js/plugin-i18n/runtime';
+
+function Navigation() {
+  return (
+    <nav>
+      <I18nLink to="/">Home</I18nLink>
+      <I18nLink to="/about">About</I18nLink>
+      <I18nLink to="/contact" replace>
+        Contact
+      </I18nLink>
+    </nav>
+  );
+}
+```
+
+## Runtime Plugin API
+
+In the `onBeforeRender` hook of Runtime plugins, you can modify the language using the `context.changeLanguage` method. This is useful for scenarios where you need to dynamically set the language based on request information (such as user preferences, geographic location, etc.).
+
+### context.changeLanguage
+
+In the `onBeforeRender` hook, the i18n plugin adds a `changeLanguage` method to the `context` for use by other Runtime plugins.
+
+**Type Definition:**
+
+```ts
+interface TInternalRuntimeContext {
+  i18nInstance?: I18nInstance;
+  changeLanguage?: (lang: string) => Promise<void>;
+}
+```
+
+### Usage Example
+
+```ts
+import type { RuntimePlugin } from '@modern-js/runtime';
+
+const myRuntimePlugin = (): RuntimePlugin => ({
+  name: 'my-runtime-plugin',
+  setup: api => {
+    api.onBeforeRender(async context => {
+      // Check if changeLanguage method exists (ensure i18n plugin is loaded)
+      if (context.changeLanguage) {
+        // Determine language based on some condition
+        const userLang = getUserLanguageFromRequest(context);
+
+        // Change language
+        await context.changeLanguage(userLang);
+      }
+    });
+  },
+});
+
+function getUserLanguageFromRequest(context: any): string {
+  // Get user language from request headers, cookies, or other sources
+  const acceptLanguage = context.ssrContext?.req?.headers['accept-language'];
+  // Parse and return appropriate language code
+  return parseAcceptLanguage(acceptLanguage) || 'zh';
+}
+
+export default myRuntimePlugin;
+```
+
+### Notes
+
+1. **Execution Order**: Ensure the i18n plugin is registered before other plugins that use `changeLanguage`, so that `context.changeLanguage` is available.
+
+2. **Async Operation**: `changeLanguage` is an async method and requires using `await` to wait for completion.
+
+3. **Error Handling**: If an invalid language code is passed, an error will be thrown. It's recommended to add error handling:
+
+```ts
+api.onBeforeRender(async context => {
+  if (context.changeLanguage) {
+    try {
+      await context.changeLanguage('zh');
+    } catch (error) {
+      console.error('Failed to change language:', error);
+    }
+  }
+});
+```
+
+4. **Language Validation**: It's recommended to verify that the language is in the supported language list before calling `changeLanguage`:
+
+```ts
+api.onBeforeRender(async context => {
+  if (context.changeLanguage && context.i18nInstance) {
+    const supportedLngs = context.i18nInstance.options?.supportedLngs || [];
+    const targetLang = 'zh';
+
+    if (supportedLngs.includes(targetLang)) {
+      await context.changeLanguage(targetLang);
+    }
+  }
+});
+```
+
+:::info
+The `changeLanguage` method will:
+
+- Update the language of the i18n instance
+- Cache the language selection in the browser environment (Cookie/LocalStorage)
+- Trigger callbacks related to language switching
+
+However, it will not automatically update the URL path. If you need to update the URL, you need to coordinate with the routing plugin or handle it manually.
+:::
+
+## Integration with react-i18next
+
+The plugin is fully compatible with `react-i18next` and can use the `useTranslation` Hook and other `react-i18next` features.
+
+### useTranslation Hook
+
+```tsx
+import { useTranslation } from 'react-i18next';
+
+function MyComponent() {
+  const { t, i18n } = useTranslation();
+
+  return (
+    <div>
+      <h1>{t('welcome')}</h1>
+      <p>{t('description', { name: 'Modern.js' })}</p>
+    </div>
+  );
+}
+```
+
+### Accessing i18next Instance
+
+You can get the i18next instance through `useModernI18n`:
+
+```tsx
+import { useModernI18n } from '@modern-js/plugin-i18n/runtime';
+import { useTranslation } from 'react-i18next';
+
+function MyComponent() {
+  const { i18nInstance } = useModernI18n();
+  const { t } = useTranslation();
+
+  // Directly access i18next instance
+  console.log(i18nInstance.language);
+  console.log(i18nInstance.options);
+
+  return <div>{t('hello')}</div>;
+}
+```
+
+## Type Definitions
+
+### I18nInstance Interface
+
+```ts
+interface I18nInstance {
+  language: string;
+  isInitialized: boolean;
+  init: (options?: I18nInitOptions) => void | Promise<void>;
+  changeLanguage: (lang: string) => void | Promise<void>;
+  use: (plugin: any) => void;
+  createInstance: (options?: I18nInitOptions) => I18nInstance;
+  cloneInstance?: () => I18nInstance;
+  services?: {
+    languageDetector?: {
+      detect: (request?: any, options?: any) => string | string[] | undefined;
+      [key: string]: any;
+    };
+    [key: string]: any;
+  };
+  options?: {
+    backend?: BackendOptions;
+    [key: string]: any;
+  };
+}
+```
+
+### I18nInitOptions Interface
+
+```ts
+interface I18nInitOptions {
+  lng?: string;
+  fallbackLng?: string;
+  supportedLngs?: string[];
+  initImmediate?: boolean;
+  detection?: LanguageDetectorOptions;
+  backend?: BackendOptions;
+  resources?: Resources;
+  ns?: string | string[];
+  defaultNS?: string | string[];
+  react?: {
+    useSuspense?: boolean;
+    [key: string]: any;
+  };
+  [key: string]: any;
+}
+```
+
+### LanguageDetectorOptions Interface
+
+```ts
+interface LanguageDetectorOptions {
+  /** Detection order */
+  order?: string[];
+  /** Query parameter key name, default 'lng' */
+  lookupQuerystring?: string;
+  /** Cookie key name, default 'i18next' */
+  lookupCookie?: string;
+  /** LocalStorage key name, default 'i18nextLng' (browser only) */
+  lookupLocalStorage?: string;
+  /** SessionStorage key name (browser only) */
+  lookupSession?: string;
+  /** Starting index in path for language detection, default 0 */
+  lookupFromPathIndex?: number;
+  /** Cache method, can be false or string array (e.g., ['cookie', 'localStorage']) */
+  caches?: boolean | string[];
+  /** Cookie expiration time (minutes) */
+  cookieMinutes?: number;
+  /** Cookie expiration date (Date object, takes precedence over cookieMinutes) */
+  cookieExpirationDate?: Date;
+  /** Cookie domain */
+  cookieDomain?: string;
+  /** Request header key name, default 'accept-language' */
+  lookupHeader?: string;
+}
+```
+
+### Resources Type
+
+```ts
+type Resources = {
+  [lng: string]: {
+    [ns: string]: string | Record<string, string>;
+  };
+};
+```
+
+:::info
+The namespace value can be a string (for simple key-value pairs) or an object (for nested translation structures).
+
+:::