@bleedingdev/modern-js-app-tools 3.5.0-ultramodern.98 → 3.5.0-ultramodern.99

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

@@ -0,0 +1,271 @@
+---
+title: API Reference
+---
+
+# 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` |
+| `localisedUrls` | `boolean \| Record<string, Record<string, string>>` | Localised URL mapping from `localeDetection.localisedUrls` |
+| `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 |
+
+When `localePathRedirect` is enabled and `localisedUrls` is omitted, Modern.js keeps prefix-only paths such as `/en/about`. Translated path segments are enabled only by a non-empty `localisedUrls` map. Route generation validates every localisable path and every configured language only while that map is enabled.
+
+### 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 | Passed to the active router link when a router is available |
+
+### 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:
+
+:::warning BREAKING (UltraModern)
+`I18nInstance` no longer declares a top-level `[key: string]: unknown` index
+signature: TypeScript never grants an interface an implicit index signature, so
+that member made the documented `runtime: { i18n: { i18nInstance: i18next } }`
+usage fail to typecheck. Reading a property that is not declared below is now a
+type error (TS2339) — cast to the concrete instance type instead. `t` is now a
+REQUIRED member, so object literals that produce an `I18nInstance` must supply
+one.
+:::
+
+```ts
+type TranslateFn = (
+  key: string | string[],
+  options?: Record<string, unknown>,
+) => string;
+
+interface I18nInstance {
+  language: string;
+  isInitialized?: boolean;
+  init(options?: any, callback?: any): Promise<any>;
+  changeLanguage?(lng?: string, callback?: any): Promise<any>;
+  setLang?: (lang: string) => void | Promise<void>;
+  use(plugin: any): unknown;
+  t: TranslateFn;
+  exists?: (key: string | string[], options?: Record<string, unknown>) => boolean;
+  getFixedT?: (
+    lng: string | readonly string[] | null,
+    ns?: string | readonly string[] | null,
+    keyPrefix?: string,
+  ) => TranslateFn;
+  hasLoadedNamespace?: (
+    ns: string | readonly string[],
+    options?: Record<string, unknown>,
+  ) => boolean;
+  dir?: (lng?: string) => string;
+  languages?: readonly string[];
+  resolvedLanguage?: string;
+  createInstance?(options?: any, callback?: any): I18nInstance;
+  cloneInstance?(options?: any, callback?: any): I18nInstance;
+  options?: {
+    detection?: any;
+    backend?: any;
+    ns?: any;
+    defaultNS?: any;
+  };
+  // ...see src/runtime/i18n/instance.ts for the full member list.
+}
+```
+
+### 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.mdx

@@ -0,0 +1,290 @@
+---
+title: Best Practices
+---
+
+# 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.
+:::