@modern-js/main-doc 3.1.4 → 3.2.0

package/docs/en/guides/advanced-features/international/resource-loading.mdx

@@ -4,47 +4,43 @@ title: Resource Loading
 
 # Resource Loading
 
-The plugin supports three resource loading methods: HTTP backend, File System backend (FS Backend), and SDK backend. Additionally, the plugin supports chained backend, which allows combining multiple backends.
+How translation files are loaded depends on where your translation resources are stored:
 
-## HTTP Backend
+| Scenario | Loading method |
+| --- | --- |
+| Translation files are local to the project | Static file backend (the default method in this guide) |
+| Translations come from a remote API or translation platform | Custom backend |
+| Both: local fallback + remote real-time updates | Chained backend |
 
-HTTP backend loads resource files through HTTP requests, suitable for client-side rendering (CSR) scenarios.
+## Static File Backend
 
-### Configuration
+Put translation files in your project and the plugin loads them directly. This is the most common approach.
 
-```ts
-i18nPlugin({
-  backend: {
-    enabled: true,
-    loadPath: '/locales/{{lng}}/{{ns}}.json',
-  },
-});
-```
+**CSR and SSR use different loading mechanisms, but the configuration is exactly the same:**
+
+- CSR: The browser fetches translation files through HTTP, such as `GET /locales/zh/translation.json`.
+- SSR: The server reads files directly from disk without making HTTP requests.
 
-### Resource File Structure
+The plugin automatically chooses the right mechanism based on the runtime environment. You only need to configure `loadPath` once.
 
-Resource files need to be placed in the `config/public` directory or the directory configured through `server.publicDir`:
+**Resource file location:**
 
 ```
-config/public/
-└── locales/
-    ├── en/
-    │   └── translation.json
-    └── zh/
-        └── translation.json
+config/public/locales/    <- Default location. No extra configuration required.
+├── en/translation.json
+└── zh/translation.json
 ```
 
-Or configure a custom directory through `server.publicDir`:
-
 ```ts
+// modern.config.ts
 export default defineConfig({
-  server: {
-    publicDir: './locales', // Specify resource file directory
-  },
   plugins: [
+    appTools(),
     i18nPlugin({
       backend: {
-        enabled: true,
+        // `{{lng}}` is the language code, and `{{ns}}` is the namespace name.
+        // During SSR, the plugin automatically converts the leading `/` prefix
+        // to a relative path before reading the file. No extra handling is needed.
         loadPath: '/locales/{{lng}}/{{ns}}.json',
       },
     }),
@@ -52,115 +48,43 @@ export default defineConfig({
 });
 ```
 
-**Resource File Format**:
-
-```json
-{
-  "key1": "value1",
-  "key2": "value2",
-  "nested": {
-    "key": "value"
-  }
-}
-```
-
-### Path Variables
-
-`loadPath` supports the following variables:
-
-- `{{lng}}`: Language code (e.g., `en`, `zh`)
-- `{{ns}}`: Namespace (e.g., `translation`, `common`)
-
-**Examples**:
-
-```ts
-// Default path format
-loadPath: '/locales/{{lng}}/{{ns}}.json';
-// Actual loading paths:
-// /locales/en/translation.json
-// /locales/zh/translation.json
-
-// Custom path format
-loadPath: '/i18n/{{lng}}/{{ns}}.json';
-// Actual loading paths:
-// /i18n/en/translation.json
-// /i18n/zh/translation.json
-```
-
-## File System Backend (FS Backend)
-
-File System backend reads resource files directly from the file system, suitable for server-side rendering (SSR) scenarios.
-
-### Configuration
-
-In SSR scenarios, the plugin will automatically use the file system backend. Resource files need to be placed in the project directory:
-
-```
-Project Root/
-└── locales/
-    ├── en/
-    │   └── translation.json
-    └── zh/
-        └── translation.json
-```
-
-### Resource File Path
-
-The default path format for file system backend is a relative path:
-
-```
-./locales/{{lng}}/{{ns}}.json
-```
-
-You can customize the path through `loadPath`:
-
-```ts
-i18nPlugin({
-  backend: {
-    enabled: true,
-    loadPath: '/locales/{{lng}}/{{ns}}.json', // Use absolute path (recommended)
-  },
-});
-```
-
-:::warning
-The `loadPath` configuration is used for both HTTP backend (frontend) and file system backend (server-side). If configured as an absolute path starting with `/` (e.g., `/locales/{{lng}}/{{ns}}.json`), the file system backend will automatically convert it to a relative path (`./locales/{{lng}}/{{ns}}.json`). Therefore, it's recommended to use absolute paths in the configuration, which can meet both frontend and backend requirements.
-
-:::
+To store files in another directory, configure `server.publicDir`. The relationship between **`server.publicDir` and `backend.loadPath`** is:
 
-## SDK Backend
+- `server.publicDir`: Decides which local directory is exposed as static assets, that is, where files are placed.
+- `backend.loadPath`: Decides which URL i18next requests for translation files, or which path the server reads from.
 
-SDK backend allows loading resources through custom functions, suitable for scenarios where translation resources need to be loaded from external services, databases, or other custom sources.
+## Custom Backend
 
-### Enable SDK Mode
+When translation resources are not local files but come from a remote API, database, or translation platform, load them with an async function.
 
-**Step 1: Enable SDK mode in `modern.config.ts`**
+**Step 1: declare it enabled in `modern.config.ts`**
 
 ```ts
 i18nPlugin({
   backend: {
-    enabled: true,
-    sdk: true, // Enable SDK mode
+    sdk: true,
   },
 });
 ```
 
-**Step 2: Implement SDK function in `modern.runtime.ts`**
+**Step 2: implement the loader function in `modern.runtime.ts`**
 
 ```ts
 import { defineRuntimeConfig } from '@modern-js/runtime';
-import type { I18nSdkLoader, Resources } from '@modern-js/plugin-i18n/runtime';
+import type { I18nSdkLoader } from '@modern-js/plugin-i18n/runtime';
 
-const mySdkLoader: I18nSdkLoader = async options => {
-  // Implement resource loading logic
-  if (options.all) {
-    // Load all resources
-    return await loadAllResources();
+const myLoader: I18nSdkLoader = async options => {
+  // Most common case: load a single resource by language + namespace.
+  if (options.lng && options.ns) {
+    const res = await fetch(`/api/i18n/${options.lng}/${options.ns}`);
+    const data = await res.json();
+    return { [options.lng]: { [options.ns]: data } };
   }
 
-  if (options.lng && options.ns) {
-    // Load single resource
-    return await loadSingleResource(options.lng, options.ns);
+  // Load all resources at once.
+  if (options.all) {
+    const res = await fetch('/api/i18n/all');
+    return res.json(); // Format: { en: { translation: {...} }, zh: { translation: {...} } }
   }
 
   return {};
@@ -169,238 +93,53 @@ const mySdkLoader: I18nSdkLoader = async options => {
 export default defineRuntimeConfig({
   i18n: {
     initOptions: {
-      backend: {
-        sdk: mySdkLoader,
-      },
+      backend: { sdk: myLoader },
     },
   },
 });
 ```
 
-### Implement SDK Loader Function
-
-The SDK function receives an `I18nSdkLoadOptions` parameter and needs to return data in `Resources` format:
+**Loader parameter type:**
 
 ```ts
 interface I18nSdkLoadOptions {
-  /** Single language code */
-  lng?: string;
-  /** Single namespace */
-  ns?: string;
-  /** Multiple language codes */
-  lngs?: string[];
-  /** Multiple namespaces */
-  nss?: string[];
-  /** Load all resources */
-  all?: boolean;
+  lng?: string;      // Single language code
+  ns?: string;       // Single namespace
+  lngs?: string[];   // Multiple language codes
+  nss?: string[];    // Multiple namespaces
+  all?: boolean;     // Load all resources
 }
-
-type Resources = {
-  [lng: string]: {
-    [ns: string]: Record<string, string>;
-  };
-};
-```
-
-### Batch Loading Examples
-
-SDK backend supports multiple loading modes:
-
-**1. Load single resource**:
-
-```ts
-const sdkLoader: I18nSdkLoader = async options => {
-  if (options.lng && options.ns) {
-    const response = await fetch(`/api/i18n/${options.lng}/${options.ns}`);
-    const data = await response.json();
-    return {
-      [options.lng]: {
-        [options.ns]: data,
-      },
-    };
-  }
-  return {};
-};
 ```
 
-**2. Batch load multiple languages**:
-
-```ts
-const sdkLoader: I18nSdkLoader = async options => {
-  if (options.lngs && options.ns) {
-    const resources: Resources = {};
-    for (const lng of options.lngs) {
-      const response = await fetch(`/api/i18n/${lng}/${options.ns}`);
-      resources[lng] = {
-        [options.ns]: await response.json(),
-      };
-    }
-    return resources;
-  }
-  return {};
-};
-```
-
-**3. Batch load multiple namespaces**:
-
-```ts
-const sdkLoader: I18nSdkLoader = async options => {
-  if (options.lng && options.nss) {
-    const resources: Resources = {
-      [options.lng]: {},
-    };
-    for (const ns of options.nss) {
-      const response = await fetch(`/api/i18n/${options.lng}/${ns}`);
-      resources[options.lng][ns] = await response.json();
-    }
-    return resources;
-  }
-  return {};
-};
-```
-
-**4. Load all resources**:
-
-```ts
-const sdkLoader: I18nSdkLoader = async options => {
-  if (options.all) {
-    const response = await fetch('/api/i18n/all');
-    return await response.json();
-  }
-  return {};
-};
-```
-
-### Check Resource Loading State
-
-When using SDK backend, you can check if resources are loaded using `isResourcesReady`:
-
-```tsx
-import { useModernI18n } from '@modern-js/plugin-i18n/runtime';
-
-function MyComponent() {
-  const { isResourcesReady } = useModernI18n();
-
-  if (!isResourcesReady) {
-    return <div>Loading translation resources...</div>;
-  }
-
-  return <div>Resources are ready!</div>;
-}
-```
-
-This is particularly useful when resources are loaded asynchronously, as it ensures all required namespaces for the current language are loaded before rendering content that depends on translations.
+When using a custom backend, translation resources are loaded asynchronously. You can use `isResourcesReady` to show a loading state before loading is complete. See [Best Practices -> Loading State Handling](./best-practices.md#loading-state-handling).
 
 ## Chained Backend
 
-Chained backend allows using multiple backends simultaneously, enabling progressive resource loading and updates. When both `loadPath` (or FS backend) and `sdk` are configured, the plugin automatically uses `i18next-chained-backend` to chain resource loading.
-
-### How It Works
-
-The chained backend workflow:
-
-1. **Initial Load**: First load resources from HTTP/FS backend and display immediately (quick display of basic translations)
-2. **Async Update**: Then asynchronously load resources from SDK backend and update the i18next store (update/supplement translations)
-
-This ensures users see page content quickly while the latest translation resources are loaded in the background.
-
-### Configuration
-
-**Step 1: Configure chained backend in `modern.config.ts`**
-
-```ts
-i18nPlugin({
-  backend: {
-    enabled: true,
-    loadPath: '/locales/{{lng}}/{{ns}}.json', // HTTP/FS backend
-    sdk: true, // SDK backend
-    // cacheHitMode: 'refreshAndUpdateStore', // Default value, can be omitted
-  },
-});
-```
+Use local files and a custom backend together to implement "show local translations quickly first, then update asynchronously with the latest translations":
 
-**Step 2: Implement SDK function in `modern.runtime.ts`**
-
-```ts
-import { defineRuntimeConfig } from '@modern-js/runtime';
-
-export default defineRuntimeConfig({
-  i18n: {
-    initOptions: {
-      backend: {
-        sdk: async options => {
-          // SDK implementation
-          if (options.lng && options.ns) {
-            return await mySdk.getResource(options.lng, options.ns);
-          }
-        },
-      },
-    },
-  },
-});
-```
-
-### Cache Hit Mode (cacheHitMode)
-
-The `cacheHitMode` option controls the behavior of chained backend:
-
-- **`'none'`** (default, only when chained backend is not configured): If the first backend returns resources, stop and don't try the next backend
-- **`'refresh'`**: Try to refresh the cache by loading from the next backend and update the cache
-- **`'refreshAndUpdateStore'`** (default for chained backend): Try to refresh the cache by loading from the next backend, update the cache and also update the i18next resource store. This allows FS/HTTP resources to be displayed first, then SDK resources will update them asynchronously.
-
-**Configuration example**:
+1. When the page loads, translations are loaded from local files and displayed immediately.
+2. The custom backend loads the latest translations asynchronously in the background. After it completes, the page updates automatically.
 
 ```ts
+// modern.config.ts
 i18nPlugin({
   backend: {
-    enabled: true,
-    loadPath: '/locales/{{lng}}/{{ns}}.json',
-    sdk: true,
-    cacheHitMode: 'refreshAndUpdateStore', // Explicitly specify (default value)
+    loadPath: '/locales/{{lng}}/{{ns}}.json', // Local files, fast display
+    sdk: true,                                 // Remote loading, async update
   },
 });
 ```
 
-### Use Cases
-
-Chained backend is particularly suitable for the following scenarios:
-
-1. **Progressive Loading**: Display local/static resources first, then load latest translations from remote services
-2. **Offline Support**: Local resources as offline fallback, SDK resources provide online updates
-3. **Performance Optimization**: Quickly display basic translations, load complete translation content in the background
-4. **A/B Testing**: Local resources as default values, SDK provides dynamic translation variants
-
-### Complete Example
-
 ```ts
-// modern.config.ts
-i18nPlugin({
-  backend: {
-    enabled: true,
-    loadPath: '/locales/{{lng}}/{{ns}}.json', // Local resources
-    sdk: true, // Remote SDK resources
-    cacheHitMode: 'refreshAndUpdateStore',
-  },
-});
-
 // modern.runtime.ts
-import { defineRuntimeConfig } from '@modern-js/runtime';
-
 export default defineRuntimeConfig({
   i18n: {
     initOptions: {
       backend: {
         sdk: async options => {
           if (options.lng && options.ns) {
-            // Load latest translations from remote service
-            const response = await fetch(
-              `https://api.example.com/i18n/${options.lng}/${options.ns}`,
-            );
-            return {
-              [options.lng]: {
-                [options.ns]: await response.json(),
-              },
-            };
+            const res = await fetch(`https://api.example.com/i18n/${options.lng}/${options.ns}`);
+            return { [options.lng]: { [options.ns]: await res.json() } };
           }
           return {};
         },
@@ -410,8 +149,10 @@ export default defineRuntimeConfig({
 });
 ```
 
-In this example:
+**`cacheHitMode` option** (controls how the two backends cooperate):
 
-- When the page loads, resources are first loaded from `/locales/{{lng}}/{{ns}}.json` and displayed immediately
-- Latest translations are loaded asynchronously from `https://api.example.com/i18n/...` in the background
-- After SDK resources are loaded, the i18next store is automatically updated, and the UI text is automatically updated
+| Value | Behavior |
+| --- | --- |
+| `'none'` | Use local files after a successful local hit and do not request the custom backend |
+| `'refresh'` | Continue requesting the custom backend and update cache, but do not update the current page |
+| `'refreshAndUpdateStore'` | Continue requesting the custom backend, update cache, and refresh page text (default) |