@modern-js/app-tools 3.7.0 → 3.8.1

package/docs/guides/advanced-features/international/api.md

@@ -0,0 +1,231 @@
+# API Reference
+
+## useModernI18n
+
+`useModernI18n` is a React Hook provided by the plugin. Use it to access internationalization state and actions in components.
+
+### Return Value
+
+| Field                 | Type                              | Description                                                                  |
+| --------------------- | --------------------------------- | ---------------------------------------------------------------------------- |
+| `language`            | `string`                          | Current language code                                                        |
+| `changeLanguage`      | `(lang: string) => Promise<void>` | Switches language                                                            |
+| `supportedLanguages`  | `string[]`                        | Supported language list, from `localeDetection.languages`                    |
+| `isLanguageSupported` | `(lang: string) => boolean`       | Checks whether a language is in the supported list                           |
+| `isResourcesReady`    | `boolean`                         | Whether translation resources for the current language have finished loading |
+| `i18nInstance`        | `I18nInstance`                    | i18next instance for advanced scenarios                                      |
+
+### Basic Usage
+
+```tsx
+import { useModernI18n } from '@modern-js/plugin-i18n/runtime';
+import { useTranslation } from 'react-i18next';
+
+function LanguageSwitcher() {
+  const { language, changeLanguage, supportedLanguages } = useModernI18n();
+  const { t } = useTranslation();
+
+  return (
+    <div>
+      <p>{t('welcome')}</p>
+      {supportedLanguages.map(lang => (
+        <button
+          key={lang}
+          onClick={() => changeLanguage(lang)}
+          disabled={lang === language}
+        >
+          {lang}
+        </button>
+      ))}
+    </div>
+  );
+}
+```
+
+### changeLanguage
+
+When switching language, the following happens in order:
+
+1. The language of the i18next instance is updated.
+2. Browser cache is updated (Cookie / LocalStorage, depending on the `caches` configuration).
+3. The URL path prefix is updated if `localePathRedirect` is enabled.
+
+`changeLanguage` is asynchronous, so use `await` when calling it:
+
+```ts
+await changeLanguage('zh');
+```
+
+### isResourcesReady
+
+In custom backend scenarios, translation resources are loaded asynchronously. Use `isResourcesReady` to avoid rendering before resources are ready:
+
+```tsx
+function MyComponent() {
+  const { isResourcesReady } = useModernI18n();
+  const { t } = useTranslation();
+
+  if (!isResourcesReady) {
+    return <div>Loading translations...</div>;
+  }
+
+  return <div>{t('content')}</div>;
+}
+```
+
+`isResourcesReady` checks whether the i18n instance is initialized, whether resources are currently loading for the current language, and whether all required namespaces have finished loading.
+
+## I18nLink Component
+
+A route link component with a locale prefix.
+
+### Props
+
+| Prop             | Type              | Required | Description                                                        |
+| ---------------- | ----------------- | -------- | ------------------------------------------------------------------ |
+| `to`             | `string`          | Yes      | Target path. Do not include the locale prefix                      |
+| `children`       | `React.ReactNode` | Yes      | Link content                                                       |
+| `replace`        | `boolean`         | No       | Uses `history.replace` instead of `push`                           |
+| `state`          | `any`             | No       | State passed to the target route                                   |
+| Other Link props | -                 | No       | Inherited from the `Link` component in `@modern-js/runtime/router` |
+
+### Usage
+
+```tsx
+import { I18nLink } from '@modern-js/plugin-i18n/runtime';
+
+<I18nLink to="/about">About</I18nLink>
+<I18nLink to="/contact" replace>Contact</I18nLink>
+<I18nLink to="/profile" state={{ from: 'home' }}>Profile</I18nLink>
+```
+
+## Runtime Plugin API
+
+The i18n plugin mounts `changeLanguage` and `i18nInstance` on the `context` of the `onBeforeRender` hook for other runtime plugins:
+
+```ts
+import type { RuntimePlugin } from '@modern-js/runtime';
+
+const myPlugin = (): RuntimePlugin => ({
+  name: 'my-plugin',
+  setup: api => {
+    api.onBeforeRender(async context => {
+      if (!context.changeLanguage) return; // Make sure the i18n plugin is loaded.
+
+      const lang = detectLangFromRequest(context);
+      const supported = context.i18nInstance?.options?.supportedLngs ?? [];
+
+      if (supported.includes(lang)) {
+        try {
+          await context.changeLanguage(lang);
+        } catch (e) {
+          console.error('Language change failed:', e);
+        }
+      }
+    });
+  },
+});
+```
+
+**Notes:**
+
+- Make sure the i18n plugin is registered before plugins that use `context.changeLanguage`.
+- `changeLanguage` does not update the URL path on the server. Use it together with the routing plugin or handle the path manually.
+
+## Type Definitions
+
+### I18nInstance
+
+The i18next instance type used by the plugin. It is a subset of the i18next `i18n` type and only lists fields actually used by the plugin:
+
+```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;
+  options?: {
+    backend?: BackendOptions;
+    supportedLngs?: string[];
+    [key: string]: any;
+  };
+}
+```
+
+### I18nSdkLoader
+
+Type of the custom backend loader function:
+
+```ts
+type I18nSdkLoader = (options: I18nSdkLoadOptions) => Promise<Resources>;
+
+interface I18nSdkLoadOptions {
+  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, any>;
+  };
+};
+```
+
+### LanguageDetectorOptions
+
+```ts
+interface LanguageDetectorOptions {
+  order?: string[];
+  lookupQuerystring?: string;   // Default: 'lng'
+  lookupCookie?: string;        // Default: 'i18next'
+  lookupLocalStorage?: string;  // Default: 'i18nextLng'
+  lookupSession?: string;
+  lookupHeader?: string;        // Default: 'accept-language'
+  lookupFromPathIndex?: number; // Default: 0
+  caches?: false | string[];
+  cookieMinutes?: number;       // Default: 525600 (1 year)
+  cookieExpirationDate?: Date;
+  cookieDomain?: string;
+}
+```
+
+## Integration with react-i18next
+
+The plugin is fully compatible with react-i18next, and the two API sets can be used together:
+
+- **`useTranslation`** (react-i18next): Gets the `t()` function for translation. This is the most commonly used Hook.
+- **`useModernI18n`** (provided by the plugin): Gets plugin-level state such as language switching, supported language list, and resource loading status.
+
+Most components only need `useTranslation`. Use `useModernI18n` only when you need language switching or resource loading status:
+
+```tsx
+import { useTranslation } from 'react-i18next';
+import { useModernI18n } from '@modern-js/plugin-i18n/runtime';
+
+function App() {
+  const { t } = useTranslation();                          // Translate text
+  const { language, changeLanguage } = useModernI18n();    // Switch language
+
+  return (
+    <div>
+      <h1>{t('welcome')}</h1>
+      <button onClick={() => changeLanguage('zh')}>Chinese</button>
+      <button onClick={() => changeLanguage('en')}>English</button>
+    </div>
+  );
+}
+```
+
+You can also get the i18next instance from `useModernI18n` and call capabilities outside react-i18next directly:
+
+```tsx
+const { i18nInstance } = useModernI18n();
+
+// Dynamically add translation resources.
+i18nInstance.addResourceBundle('zh', 'translation', { key: 'Value' }, true, true);
+```

package/docs/guides/advanced-features/international/best-practices.md

@@ -0,0 +1,286 @@
+# Best Practices
+
+## Resource File Organization
+
+Namespaces are used to split translation files by business module. The default namespace is `translation`. Splitting by module can reduce the initial loading size and load only the namespaces that are actually used.
+
+Recommended directory structure:
+
+```
+locales/
+├── en/
+│   ├── translation.json  <- Default namespace for common text
+│   ├── common.json       <- Common UI text such as buttons and labels
+│   └── errors.json       <- Error messages
+└── zh/
+    ├── translation.json
+    ├── common.json
+    └── errors.json
+```
+
+Declare multiple namespaces:
+
+```ts
+// src/modern.runtime.ts
+export default defineRuntimeConfig({
+  i18n: {
+    initOptions: {
+      ns: ['translation', 'common', 'errors'],
+      defaultNS: 'translation',
+    },
+  },
+});
+```
+
+Use a specific namespace in components:
+
+```tsx
+import { useTranslation } from 'react-i18next';
+
+// Use a single namespace.
+function MyButton() {
+  const { t } = useTranslation('common');
+  return <button>{t('submit')}</button>;
+}
+
+// Use multiple namespaces and access keys with namespace:key.
+function Dashboard() {
+  const { t } = useTranslation(['dashboard', 'common']);
+  return (
+    <header>
+      <h1>{t('dashboard:title')}</h1>
+      <button>{t('common:button.refresh')}</button>
+    </header>
+  );
+}
+
+// keyPrefix can omit repeated prefixes.
+function ButtonGroup() {
+  const { t } = useTranslation('common', { keyPrefix: 'button' });
+  return (
+    <>
+      <button>{t('submit')}</button>   {/* common:button.submit */}
+      <button>{t('cancel')}</button>   {/* common:button.cancel */}
+    </>
+  );
+}
+```
+
+## Translation Key Naming
+
+The quality of translation key names directly affects maintenance cost. Recommendations:
+
+- **Use semantic words** and avoid abbreviations: `button.submit` is better than `btn.sbm`.
+- **Use module-based prefixes**: `dashboard.table.header`, `auth.login.title`.
+- **Do not use complete source-language text as keys**: Keys should be stable identifiers, not the translation content itself.
+- **Use dots for hierarchy**: Match the nested JSON structure.
+
+```json
+// Recommended
+{
+  "page": {
+    "title": "User Settings",
+    "description": "Manage your account information"
+  },
+  "form": {
+    "username": { "label": "Username", "placeholder": "Enter username" },
+    "submit": "Save changes"
+  }
+}
+```
+
+```tsx
+t('page.title')
+t('form.username.label')
+t('form.submit', { defaultValue: 'Save' }) // defaultValue prevents showing the key string when the key is missing.
+```
+
+## Plurals
+
+i18next automatically selects the correct plural form based on the `count` parameter. **Note: since i18next v21, JSON v4 format is used by default**. Plural suffixes changed to CLDR standards such as `_zero`, `_one`, and `_other`; the old `_plural` format is deprecated.
+
+```json
+// locales/en/translation.json (JSON v4 format)
+{
+  "item_zero": "No items",
+  "item_one": "{{count}} item",
+  "item_other": "{{count}} items"
+}
+```
+
+```json
+// locales/zh/translation.json
+{
+  "item_zero": "没有条目",
+  "item_other": "{{count}} 个条目"
+}
+```
+
+```tsx
+t('item', { count: 0 })  // "没有条目" / "No items"
+t('item', { count: 1 })  // "没有条目" / "1 item" (Chinese usually has only one form)
+t('item', { count: 5 })  // "5 个条目" / "5 items"
+```
+
+Different languages have different plural rules. English has singular and plural, while Russian has one/few/many forms. i18next automatically matches CLDR rules based on the language code.
+
+:::tip
+Use the `_plural` format only if your project uses an old i18next version or explicitly configures `compatibilityJSON: 'v3'`. New projects should use v4 format.
+:::
+
+## Nested Keys
+
+Nested structures can clearly reflect UI hierarchy and are accessed with dots:
+
+```json
+{
+  "modal": {
+    "confirm": {
+      "title": "Confirm deletion",
+      "message": "This action cannot be undone. Continue?",
+      "actions": {
+        "ok": "Confirm",
+        "cancel": "Cancel"
+      }
+    }
+  }
+}
+```
+
+```tsx
+t('modal.confirm.title')
+t('modal.confirm.actions.ok')
+```
+
+Avoid nesting deeper than 4 levels. Excessive depth makes key names long and hard to maintain.
+
+## Formatting Interpolation
+
+Use the `interpolation.format` function to handle number, date, currency, and other formatting consistently, instead of calling `Intl` APIs separately in each component:
+
+```ts
+// src/modern.runtime.ts
+export default defineRuntimeConfig({
+  i18n: {
+    initOptions: {
+      interpolation: {
+        escapeValue: false, // React already escapes text. Disable this to avoid double escaping.
+        format(value, format, lng) {
+          if (format === 'currency') {
+            return new Intl.NumberFormat(lng, {
+              style: 'currency',
+              currency: lng === 'zh' ? 'CNY' : 'USD',
+            }).format(Number(value));
+          }
+          if (format === 'date') {
+            return new Intl.DateTimeFormat(lng, { dateStyle: 'medium' }).format(
+              value instanceof Date ? value : new Date(value),
+            );
+          }
+          return value;
+        },
+      },
+    },
+  },
+});
+```
+
+Use `, format` in translation files to specify the formatting type:
+
+```json
+{
+  "price": "Current price: {{value, currency}}",
+  "expiry": "Expiry date: {{date, date}}"
+}
+```
+
+```tsx
+t('price', { value: 99.5 })       // "当前价格：¥99.50" (zh) / "$99.50" (en)
+t('expiry', { date: new Date() }) // "到期日：2025年5月12日" (zh)
+```
+
+## Error Handling
+
+### Loading State Handling
+
+When using a custom backend, translation resources are loaded asynchronously. Use `isResourcesReady` to handle the loading state:
+
+```tsx
+import { useModernI18n } from '@modern-js/plugin-i18n/runtime';
+import { useTranslation } from 'react-i18next';
+
+function MyComponent() {
+  const { isResourcesReady } = useModernI18n();
+  const { t } = useTranslation();
+
+  if (!isResourcesReady) {
+    return <div>Loading translations...</div>;
+  }
+
+  return <div>{t('content', { defaultValue: 'Default content' })}</div>;
+}
+```
+
+Static resources (HTTP/FS backend) load quickly, so loading state handling is usually unnecessary. If you need to check, use `i18n.isInitialized`:
+
+```tsx
+const { t, i18n } = useTranslation();
+if (!i18n.isInitialized) return null;
+```
+
+### Missing Translation Keys
+
+Provide fallback text with `defaultValue` to prevent key strings from appearing in the UI:
+
+```tsx
+t('missing.key', { defaultValue: 'Default text' })
+```
+
+In development, you can enable `saveMissing` to output missing keys to the console for debugging:
+
+```ts
+initOptions: {
+  fallbackLng: 'en',
+  saveMissing: true, // Recommended only in development.
+}
+```
+
+### Network Failures and Resource 404s
+
+When translation file loading fails, i18next falls back to the resources for `fallbackLng`. If those also fail, `t()` returns the key string directly. Recommendations:
+
+- In production, make sure the translation files for `fallbackLng`, usually `en`, are complete and stable.
+- When using chained backend, use local files as the fallback to reduce dependency on remote services.
+
+## Type Safety
+
+Extend react-i18next type definitions so TypeScript can check whether translation keys exist and provide autocomplete:
+
+```ts
+// types/i18n.d.ts
+import 'react-i18next';
+import type translation from '../locales/en/translation.json';
+import type common from '../locales/en/common.json';
+
+declare module 'react-i18next' {
+  interface CustomTypeOptions {
+    defaultNS: 'translation';
+    resources: {
+      translation: typeof translation;
+      common: typeof common;
+    };
+  }
+}
+```
+
+Referencing JSON file types directly is less likely to drift from actual translation files than manually written interfaces:
+
+```tsx
+const { t } = useTranslation();
+t('welcome');       // TypeScript autocomplete
+t('nonExistent');   // TypeScript error
+```
+
+:::tip Large projects
+When there are many translation files, manually maintaining type files is costly. You can use [i18next-parser](https://github.com/i18next/i18next-parser) or [i18next-resources-for-ts](https://github.com/i18next/i18next-resources-for-ts) to generate TypeScript types from translation files automatically.
+:::