feat: i18n plugin support change language for runtime plugin && split i18n doc for components (#7949)

Author: caohuilin

packages/document/docs/en/components/international/install-command.mdx

@@ -0,0 +1,9 @@
+```bash
+pnpm add @modern-js/plugin-i18n i18next react-i18next
+```
+
+:::info
+`i18next` and `react-i18next` are peer dependencies and need to be installed manually.
+
+:::
+

packages/document/docs/en/components/international/introduce.mdx

@@ -0,0 +1,2 @@
+`@modern-js/plugin-i18n` is Modern.js's internationalization plugin, built on top of [i18next](https://www.i18next.com/) and [react-i18next](https://react.i18next.com/), providing a complete internationalization solution for Modern.js applications.
+

packages/document/docs/en/components/international/platform-support.mdx

@@ -4,7 +4,9 @@ title: Internationalization
 
 # Internationalization
 
-`@modern-js/plugin-i18n` is Modern.js's internationalization plugin, built on top of [i18next](https://www.i18next.com/) and [react-i18next](https://react.i18next.com/), providing a complete internationalization solution for Modern.js applications.
+import I18nPluginIntroduce from '@site-docs/components/international/introduce';
+
+<I18nPluginIntroduce />
 
 ## Core Features
 
@@ -24,6 +26,7 @@ title: Internationalization
 
 ## Documentation Navigation
 
+- [Basic Concepts](./international/basic) - Core concepts and terminology
 - [Quick Start](./international/quick-start) - Detailed installation and configuration guide
 - [Configuration](./international/configuration) - CLI and runtime configuration details
 - [Locale Detection](./international/locale-detection) - Multiple language detection methods and priorities

packages/document/docs/en/guides/advanced-features/international.mdx

@@ -1,4 +1,5 @@
 [
+  "basic",
   "quick-start",
   "configuration",
   "locale-detection",

packages/document/docs/en/guides/advanced-features/international/_meta.json

@@ -173,6 +173,99 @@ function Navigation() {
 }
 ```
 
+## 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.