@nocobase/plugin-flow-engine 2.1.0-alpha.9 → 2.1.0-beta.10

package/dist/ai/docs/runjs/context/resource.md

@@ -1,39 +1,39 @@
 # ctx.resource
 
-The **FlowResource** instance in the current context, used to access and operate on data. In most blocks (Forms, Tables, Details, etc.) and pop-up scenarios, the runtime environment pre-binds `ctx.resource`. In scenarios like JSBlock where there is no resource by default, you must first call [ctx.initResource()](./init-resource.md) to initialize it before using it via `ctx.resource`.
+The **FlowResource** instance in the current context; used to access and operate on data. In most blocks (form, table, detail, etc.) and popups, the runtime binds `ctx.resource`; in JSBlock and similar contexts that have no resource by default, call [ctx.initResource()](./init-resource.md) first, then use `ctx.resource`.
 
-## Applicable Scenarios
+## Use Cases
 
-`ctx.resource` can be used in any RunJS scenario that requires access to structured data (lists, single records, custom APIs, SQL). Forms, Tables, Detail blocks, and pop-ups are typically pre-bound. For JSBlock, JSField, JSItem, JSColumn, etc., if data loading is required, you can call `ctx.initResource(type)` first and then access `ctx.resource`.
+Use whenever RunJS needs structured data (list, single record, custom API, SQL). Form, table, detail blocks and popups usually have it bound; in JSBlock, JSField, JSItem, JSColumn, etc., call `ctx.initResource(type)` first if you need to load data.
 
-## Type Definition
+## Type
 
 ```ts
 resource: FlowResource | undefined;
 ```
 
-- In contexts with pre-binding, `ctx.resource` is the corresponding resource instance.
-- In scenarios like JSBlock where there is no resource by default, it is `undefined` until `ctx.initResource(type)` is called.
+- When the context has a bound resource, `ctx.resource` is that instance.
+- In JSBlock etc. it is `undefined` by default; after `ctx.initResource(type)` it is set.
 
-## Common Methods
+## Common methods
 
-Methods exposed by different resource types (MultiRecordResource, SingleRecordResource, APIResource, SQLResource) vary slightly. Below are the universal or commonly used methods:
+Different resource types (MultiRecordResource, SingleRecordResource, APIResource, SQLResource) expose slightly different APIs; common ones:
 
 | Method | Description |
-|------|------|
-| `getData()` | Get current data (list or single record) |
+|--------|-------------|
+| `getData()` | Current data (list or single record) |
 | `setData(value)` | Set local data |
-| `refresh()` | Initiate a request with current parameters to refresh data |
-| `setResourceName(name)` | Set resource name (e.g., `'users'`, `'users.tags'`) |
-| `setFilterByTk(tk)` | Set primary key filter (for single record `get`, etc.) |
-| `runAction(actionName, options)` | Call any resource action (e.g., `create`, `update`) |
-| `on(event, callback)` / `off(event, callback)` | Subscribe/unsubscribe to events (e.g., `refresh`, `saved`) |
+| `refresh()` | Refetch with current params |
+| `setResourceName(name)` | Set resource name (e.g. `'users'`, `'users.tags'`) |
+| `setFilterByTk(tk)` | Set primary key filter (single get, etc.) |
+| `runAction(actionName, options)` | Call any resource action (e.g. `create`, `update`) |
+| `on(event, callback)` / `off(event, callback)` | Subscribe/unsubscribe (e.g. `refresh`, `saved`) |
 
-**MultiRecordResource Specific**: `getSelectedRows()`, `destroySelectedRows()`, `setPage()`, `next()`, `previous()`, etc.
+**MultiRecordResource**: `getSelectedRows()`, `destroySelectedRows()`, `setPage()`, `next()`, `previous()`, etc.
 
 ## Examples
 
-### List Data (Requires initResource first)
+### List (after initResource)
 
 ```js
 ctx.initResource('MultiRecordResource');
@@ -42,7 +42,7 @@ await ctx.resource.refresh();
 const rows = ctx.resource.getData();
 ```
 
-### Table Scenario (Pre-bound)
+### Table (pre-bound)
 
 ```js
 const rows = ctx.resource?.getSelectedRows?.() || [];
@@ -54,7 +54,7 @@ await ctx.resource.destroySelectedRows();
 ctx.message.success(ctx.t('Deleted'));
 ```
 
-### Single Record
+### Single record
 
 ```js
 ctx.initResource('SingleRecordResource');
@@ -64,29 +64,29 @@ await ctx.resource.refresh();
 const record = ctx.resource.getData();
 ```
 
-### Calling a Custom Action
+### Custom action
 
 ```js
-await ctx.resource.runAction('create', { data: { name: 'John Doe' } });
+await ctx.resource.runAction('create', { data: { name: 'John' } });
 ```
 
-## Relationship with ctx.initResource / ctx.makeResource
+## Relation to ctx.initResource / ctx.makeResource
 
-- **ctx.initResource(type)**: If `ctx.resource` does not exist, it creates and binds one; if it already exists, it returns the existing instance. This ensures `ctx.resource` is available.
-- **ctx.makeResource(type)**: Creates a new resource instance and returns it, but does **not** write it to `ctx.resource`. This is suitable for scenarios requiring multiple independent resources or temporary usage.
-- **ctx.resource**: Accesses the resource already bound to the current context. Most blocks/pop-ups are pre-bound; otherwise, it is `undefined` and requires `ctx.initResource`.
+- **ctx.initResource(type)**: Creates and binds if missing; otherwise returns existing. Ensures `ctx.resource` is set.
+- **ctx.makeResource(type)**: Creates a new instance and returns it; **does not** set `ctx.resource`. Use when you need multiple resources or a temporary one.
+- **ctx.resource**: The bound resource in the current context. Most blocks/popups have it; when not bound it is `undefined` and you must call `ctx.initResource` first.
 
 ## Notes
 
-- It is recommended to perform a null check before use: `ctx.resource?.refresh()`, especially in scenarios like JSBlock where pre-binding might not exist.
-- After initialization, you must call `setResourceName(name)` to specify the collection before loading data via `refresh()`.
-- For the full API of each Resource type, see the links below.
+- Prefer null checks: `ctx.resource?.refresh()`, especially in JSBlock and similar contexts.
+- After init, call `setResourceName(name)` then `refresh()` to load data.
+- See the resource type docs for full API.
 
 ## Related
 
-- [ctx.initResource()](./init-resource.md) - Initialize and bind a resource to the current context
-- [ctx.makeResource()](./make-resource.md) - Create a new resource instance without binding it to `ctx.resource`
-- [MultiRecordResource](../resource/multi-record-resource.md) - Multiple records/Lists
-- [SingleRecordResource](../resource/single-record-resource.md) - Single record
-- [APIResource](../resource/api-resource.md) - General API resource
-- [SQLResource](../resource/sql-resource.md) - SQL query resource
+- [ctx.initResource()](./init-resource.md): init and bind resource
+- [ctx.makeResource()](./make-resource.md): create resource without binding
+- [MultiRecordResource](../resource/multi-record-resource.md)
+- [SingleRecordResource](../resource/single-record-resource.md)
+- [APIResource](../resource/api-resource.md)
+- [SQLResource](../resource/sql-resource.md)

package/dist/ai/docs/runjs/context/route.md

@@ -1,76 +1,74 @@
 # ctx.route
 
-The current route matching information, corresponding to the `route` concept in React Router. It is used to retrieve the current matching route configuration, parameters, and more. It is typically used in conjunction with `ctx.router` and `ctx.location`.
+Current route match info, corresponding to React Router’s route; used to get the matched route config, params, etc. Use with `ctx.router` and `ctx.location`.
 
 ## Use Cases
 
 | Scenario | Description |
-|------|------|
-| **JSBlock / JSField** | Perform conditional rendering or display the current page identifier based on `route.pathname` or `route.params`. |
-| **Linkage Rules / FlowEngine** | Read route parameters (e.g., `params.name`) for logic branching or to pass them to child components. |
-| **View Navigation** | Internally compare `ctx.route.pathname` with a target path to determine whether to trigger `ctx.router.navigate`. |
+|----------|-------------|
+| **JSBlock / JSField** | Conditional render or display based on `route.pathname` or `route.params` |
+| **Linkage / event flow** | Read route params (e.g. `params.name`) for logic or pass to children |
+| **View navigation** | Compare `ctx.route.pathname` with target path to decide `ctx.router.navigate` |
 
-> Note: `ctx.route` is only available in RunJS environments that contain a routing context (such as JSBlocks within a page, Flow pages, etc.). It may be null in pure backend or non-routing contexts (such as background workflows).
+> Note: `ctx.route` is only available in RunJS when a router context exists (e.g. JSBlock on a page, Flow page); in pure backend or non-routed contexts (e.g. workflow) it may be empty.
 
-## Type Definition
+## Type
 
 ```ts
 type RouteOptions = {
-  name?: string;   // Unique route identifier
-  path?: string;   // Route template (e.g., /admin/:name)
-  params?: Record<string, any>;  // Route parameters (e.g., { name: 'users' })
-  pathname?: string;  // Full path of the current route (e.g., /admin/users)
+  name?: string;
+  path?: string;
+  params?: Record<string, any>;
+  pathname?: string;
 };
 ```
 
-## Common Fields
+## Common fields
 
 | Field | Type | Description |
-|------|------|------|
-| `pathname` | `string` | The full path of the current route, consistent with `ctx.location.pathname`. |
-| `params` | `Record<string, any>` | Dynamic parameters parsed from the route template, such as `{ name: 'users' }`. |
-| `path` | `string` | The route template, such as `/admin/:name`. |
-| `name` | `string` | Unique route identifier, commonly used in multi-tab or multi-view scenarios. |
+|-------|------|-------------|
+| `pathname` | `string` | Full path of current route; same as `ctx.location.pathname` |
+| `params` | `Record<string, any>` | Dynamic params from route template, e.g. `{ name: 'users' }` |
+| `path` | `string` | Route template, e.g. `/admin/:name` |
+| `name` | `string` | Route unique id; often used for tabs/views |
 
-## Relationship with ctx.router and ctx.location
+## Relation to ctx.router, ctx.location
 
-| Purpose | Recommended Usage |
-|------|----------|
-| **Read current path** | `ctx.route.pathname` or `ctx.location.pathname`; both are consistent during matching. |
-| **Read route parameters** | `ctx.route.params`, e.g., `params.name` representing the current page UID. |
-| **Navigation** | `ctx.router.navigate(path)` |
-| **Read query parameters, state** | `ctx.location.search`, `ctx.location.state` |
+| Use | Recommended |
+|-----|-------------|
+| **Current path** | `ctx.route.pathname` or `ctx.location.pathname`; they match when route is matched |
+| **Route params** | `ctx.route.params`, e.g. `params.name` for current page UID |
+| **Navigate** | `ctx.router.navigate(path)` |
+| **Query params, state** | `ctx.location.search`, `ctx.location.state` |
 
-`ctx.route` focuses on the "matched route configuration," while `ctx.location` focuses on the "current URL location." Together, they provide a complete description of the current routing state.
+`ctx.route` is “matched route config”; `ctx.location` is “current URL”; together they describe the current route state.
 
 ## Examples
 
-### Reading pathname
+### Read pathname
 
 ```ts
-// Display the current path
-ctx.message.info('Current Page: ' + ctx.route.pathname);
+ctx.message.info('Current page: ' + ctx.route.pathname);
 ```
 
-### Branching based on params
+### Branch by params
 
 ```ts
-// params.name is typically the current page UID (e.g., a Flow page identifier)
 if (ctx.route.params?.name === 'users') {
-  // Execute specific logic on the user management page
+  // On user management page
 }
 ```
 
-### Displaying in a Flow page
+### In Flow page
 
 ```tsx
 <div>
-  <h1>Current Page - {ctx.route.pathname}</h1>
-  <p>Route Identifier: {ctx.route.params?.name}</p>
+  <h1>Current page - {ctx.route.pathname}</h1>
+  <p>Route id: {ctx.route.params?.name}</p>
 </div>
 ```
 
 ## Related
 
-- [ctx.router](./router.md): Route navigation. When `ctx.router.navigate()` changes the path, `ctx.route` will update accordingly.
-- [ctx.location](./location.md): Current URL location (pathname, search, hash, state), used in conjunction with `ctx.route`.
+- [ctx.router](./router.md): navigation; after `ctx.router.navigate()`, `ctx.route` updates
+- [ctx.location](./location.md): current URL (pathname, search, hash, state); use with `ctx.route`

package/dist/ai/docs/runjs/context/router.md

@@ -1,31 +1,31 @@
 # ctx.router
 
-A router instance based on React Router, used for programmatic navigation within RunJS. It is typically used in conjunction with `ctx.route` and `ctx.location`.
+Router instance based on React Router; used for programmatic navigation in RunJS. Use with `ctx.route` and `ctx.location`.
 
 ## Use Cases
 
 | Scenario | Description |
-|------|------|
-| **JSBlock / JSField** | Navigate to detail pages, list pages, or external links after a button click. |
-| **Linkage Rules / Event Flow** | Execute `navigate` to a list or detail page after successful submission, or pass `state` to the target page. |
-| **JSAction / Event Handling** | Execute route navigation within logic such as form submissions or link clicks. |
-| **View Navigation** | Update the URL via `navigate` during internal view stack switching. |
+|----------|-------------|
+| **JSBlock / JSField** | Button navigates to detail, list, or external link |
+| **Linkage / event flow** | After submit success, `navigate` to list or detail, or pass state to target |
+| **JSAction / event handler** | Navigate on form submit, link click, etc. |
+| **View navigation** | Update URL when switching views |
 
-> Note: `ctx.router` is only available in RunJS environments with a routing context (e.g., JSBlock within a page, Flow pages, event flows, etc.); it may be null in pure backend or non-routing contexts (e.g., Workflows).
+> Note: `ctx.router` is only available in RunJS when a router context exists (e.g. JSBlock on a page, Flow page, event flow); in pure backend or non-routed contexts (e.g. workflow) it may be empty.
 
-## Type Definition
+## Type
 
 ```typescript
 router: Router
 ```
 
-`Router` is derived from `@remix-run/router`. In RunJS, navigation operations such as jumping, going back, and refreshing are implemented via `ctx.router.navigate()`.
+`Router` is from `@remix-run/router`; use `ctx.router.navigate()` for navigation, back, refresh.
 
 ## Methods
 
 ### ctx.router.navigate()
 
-Navigates to a target path, or executes a back/refresh action.
+Navigate to a path, or go back/refresh.
 
 **Signature:**
 
@@ -35,77 +35,65 @@ navigate(to: string | number | null, options?: RouterNavigateOptions): Promise<v
 
 **Parameters:**
 
-- `to`: Target path (string), relative history position (number, e.g., `-1` to go back), or `null` (to refresh the current page).
-- `options`: Optional configuration.
-  - `replace?: boolean`: Whether to replace the current history entry (default is `false`, which pushes a new entry).
-  - `state?: any`: State to pass to the target route. This data does not appear in the URL and can be accessed via `ctx.location.state` on the target page. It is suitable for sensitive information, temporary data, or information that should not be placed in the URL.
+- `to`: Target path (string), relative history position (number, e.g. `-1` for back), or `null` (refresh current page)
+- `options`:
+  - `replace?: boolean`: Replace current history entry (default `false`, i.e. push)
+  - `state?: any`: State passed to the target route. Not in URL; target page reads it via `ctx.location.state`. Use for sensitive or temporary data.
 
 ## Examples
 
-### Basic Navigation
+### Basic navigation
 
 ```ts
-// Navigate to the user list (pushes a new history entry, allows going back)
 ctx.router.navigate('/admin/users');
 
-// Navigate to a detail page
 ctx.router.navigate(`/admin/users/${recordId}`);
 ```
 
-### Replacing History (No new entry)
+### Replace (no new history entry)
 
 ```ts
-// Redirect to the home page after login; the user won't return to the login page when going back
 ctx.router.navigate('/admin', { replace: true });
 
-// Replace the current page with the detail page after successful form submission
 ctx.router.navigate(`/admin/users/${newId}`, { replace: true });
 ```
 
-### Passing State
+### Pass state
 
 ```ts
-// Carry data during navigation; the target page retrieves it via ctx.location.state
 ctx.router.navigate('/admin/users/123', { 
   state: { from: 'dashboard', tab: 'profile' } 
 });
 ```
 
-### Back and Refresh
+### Back and refresh
 
 ```ts
-// Go back one page
 ctx.router.navigate(-1);
 
-// Go back two pages
 ctx.router.navigate(-2);
 
-// Refresh the current page
 ctx.router.navigate(null);
 ```
 
-## Relationship with ctx.route and ctx.location
+## Relation to ctx.route, ctx.location
 
-| Purpose | Recommended Usage |
-|------|----------|
-| **Navigation/Jumping** | `ctx.router.navigate(path)` |
-| **Read current path** | `ctx.route.pathname` or `ctx.location.pathname` |
-| **Read state passed during navigation** | `ctx.location.state` |
-| **Read route parameters** | `ctx.route.params` |
+| Use | Recommended |
+|-----|-------------|
+| **Navigate** | `ctx.router.navigate(path)` |
+| **Current path** | `ctx.route.pathname` or `ctx.location.pathname` |
+| **State from navigation** | `ctx.location.state` |
+| **Route params** | `ctx.route.params` |
 
-`ctx.router` is responsible for "navigation actions," while `ctx.route` and `ctx.location` are responsible for the "current route state."
+`ctx.router` does “navigation”; `ctx.route` and `ctx.location` describe “current route state”.
 
 ## Notes
 
-- `navigate(path)` pushes a new history entry by default, allowing users to return via the browser's back button.
-- `replace: true` replaces the current history entry without adding a new one, which is suitable for scenarios like post-login redirection or navigation after successful submission.
-- **Regarding the `state` parameter**:
-  - Data passed via `state` does not appear in the URL, making it suitable for sensitive or temporary data.
-  - It can be accessed via `ctx.location.state` on the target page.
-  - `state` is saved in the browser history and remains accessible during forward/backward navigation.
-  - `state` will be lost after a hard page refresh.
+- `navigate(path)` by default pushes a new history entry; user can use browser back.
+- `replace: true` replaces the current entry; use after login redirect, submit-success redirect, etc.
+- **`state`**: Data in `state` is not in the URL; target page reads it via `ctx.location.state`. State is stored in history (back/forward keep it); it is lost on page refresh.
 
 ## Related
 
-- [ctx.route](./route.md): Current route match information (pathname, params, etc.).
-- [ctx.location](./location.md): Current URL location (pathname, search, hash, state); `state` is read here after navigation.
+- [ctx.route](./route.md): current route match (pathname, params)
+- [ctx.location](./location.md): current URL; read `state` here after navigation

package/dist/ai/docs/runjs/context/set-value.md

@@ -1,29 +1,29 @@
 # ctx.setValue()
 
-Sets the value of the current field in editable field scenarios such as JSField and JSItem. Combined with `ctx.getValue()`, it enables two-way binding with the form.
+In JSField, JSItem, and other editable field contexts, sets the current field’s value. Use with `ctx.getValue()` for two-way binding with the form.
 
 ## Use Cases
 
 | Scenario | Description |
-|------|------|
-| **JSField** | Write user-selected or calculated values into editable custom fields. |
-| **JSItem** | Update the current cell value in editable items of tables/sub-tables. |
-| **JSColumn** | Update the field value of the corresponding row based on logic during table column rendering. |
+|----------|-------------|
+| **JSField** | Write user selection or computed value in editable custom fields |
+| **JSItem** | Update current cell value in table/sub-table editable items |
+| **JSColumn** | Update row field value when rendering a column |
 
-> **Note**: `ctx.setValue(v)` is only available in RunJS contexts with form binding. It is not available in scenarios without field binding, such as FlowEngine, linkage rules, or JSBlock. It is recommended to use optional chaining before use: `ctx.setValue?.(value)`.
+> Note: `ctx.setValue(v)` is only available in RunJS contexts with form binding; in event flow, linkage, JSBlock, etc. (no field binding) the method may not exist—use optional chaining: `ctx.setValue?.(value)`.
 
-## Type Definition
+## Type
 
 ```ts
 setValue<T = any>(value: T): void;
 ```
 
-- **Parameters**: `value` is the field value to be written. The type is determined by the form item type of the field.
+- **Parameter**: `value` is the value to write; type depends on the field’s form item type.
 
 ## Behavior
 
-- `ctx.setValue(v)` updates the value of the current field in the Ant Design Form and triggers related form linkage and validation logic.
-- If the form has not finished rendering or the field is not registered, the call may be ineffective. It is recommended to use `ctx.getValue()` to confirm the write result.
+- `ctx.setValue(v)` updates the current field’s value in the Ant Design Form and triggers linkage and validation.
+- If the form is not yet rendered or the field is not registered, the call may have no effect; use `ctx.getValue()` to confirm.
 
 ## Examples
 
@@ -42,7 +42,7 @@ ctx.render(
 );
 ```
 
-### Setting default values based on conditions
+### Set default by condition
 
 ```ts
 const status = ctx.getValue();
@@ -51,10 +51,9 @@ if (status == null || status === '') {
 }
 ```
 
-### Writing back to the current field when linked to other fields
+### Write current field when linking others
 
 ```ts
-// Synchronously update the current field when another field changes
 const otherValue = ctx.form?.getFieldValue('type');
 if (otherValue === 'custom') {
   ctx.setValue?.({ label: 'Custom', value: 'custom' });
@@ -63,11 +62,11 @@ if (otherValue === 'custom') {
 
 ## Notes
 
-- In non-editable fields (e.g., JSField in Read-only Mode, JSBlock), `ctx.setValue` may be `undefined`. It is recommended to use `ctx.setValue?.(value)` to avoid errors.
-- When setting values for association fields (M2O, O2M, etc.), you need to pass a structure that matches the field type (e.g., `{ id, [titleField]: label }`), depending on the specific field configuration.
+- In non-editable contexts (e.g. JSField detail mode, JSBlock), `ctx.setValue` may be `undefined`; use `ctx.setValue?.(value)`.
+- For association fields (m2o, o2m, etc.), pass a value that matches the field type (e.g. `{ id, [titleField]: label }`); see field config.
 
 ## Related
 
-- [ctx.getValue()](./get-value.md) - Get the current field value, used with setValue for two-way binding.
-- [ctx.form](./form.md) - Ant Design Form instance, used to read or write other fields.
-- `js-field:value-change` - A container event triggered when an external value changes, used to update the display.
+- [ctx.getValue()](./get-value.md): get current field value; use with setValue for two-way binding
+- [ctx.form](./form.md): Ant Design Form; read/write other fields
+- `js-field:value-change`: container event when value changes from outside; use to update display

package/dist/ai/docs/runjs/context/t.md

@@ -1,12 +1,12 @@
 # ctx.t()
 
-An i18n shortcut function used in RunJS to translate text based on the current context's language settings. It is suitable for internationalizing inline copy such as buttons, titles, and prompts.
+i18n helper in RunJS for translating copy; uses the current context’s language. Use for buttons, titles, hints, etc.
 
 ## Use Cases
 
-`ctx.t()` can be used in all RunJS execution environments.
+Available in all RunJS environments.
 
-## Type Definition
+## Type
 
 ```ts
 t(key: string, options?: Record<string, any>): string
@@ -16,38 +16,35 @@ t(key: string, options?: Record<string, any>): string
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `key` | `string` | Translation key or template with placeholders (e.g., `Hello {{name}}`, `{{count}} rows`). |
-| `options` | `object` | Optional. Interpolation variables (e.g., `{ name: 'John', count: 5 }`), or i18n options (e.g., `defaultValue`, `ns`). |
+| `key` | `string` | Translation key or template with placeholders (e.g. `Hello {{name}}`, `{{count}} rows`) |
+| `options` | `object` | Optional. Interpolation (e.g. `{ name: 'John', count: 5 }`) or i18n options (`defaultValue`, `ns`) |
 
-## Return Value
+## Returns
 
-- Returns the translated string. If no translation exists for the key and no `defaultValue` is provided, it may return the key itself or the interpolated string.
+- Translated string; if key has no translation and no `defaultValue`, may return the key or the interpolated string.
 
 ## Namespace (ns)
 
-The **default namespace for the RunJS environment is `runjs`**. When `ns` is not specified, `ctx.t(key)` will look up the key in the `runjs` namespace.
+RunJS **default namespace is `runjs`**. Without `ns`, `ctx.t(key)` looks up the key in the `runjs` namespace.
 
 ```ts
-// Looks up key from the 'runjs' namespace by default
-ctx.t('Submit'); // Equivalent to ctx.t('Submit', { ns: 'runjs' })
+ctx.t('Submit');  // same as ctx.t('Submit', { ns: 'runjs' })
 
-// Looks up key from a specific namespace
 ctx.t('Submit', { ns: 'myModule' });
 
-// Searches multiple namespaces sequentially (first 'runjs', then 'common')
 ctx.t('Save', { ns: ['runjs', 'common'] });
 ```
 
 ## Examples
 
-### Simple Key
+### Simple key
 
 ```ts
 ctx.t('Submit');
 ctx.t('No data');
 ```
 
-### With Interpolation Variables
+### With interpolation
 
 ```ts
 const text = ctx.t('Hello {{name}}', { name: ctx.user?.nickname || 'Guest' });
@@ -58,14 +55,14 @@ ctx.render(`<div>${text}</div>`);
 ctx.message.success(ctx.t('Processed {{count}} rows', { count: rows.length }));
 ```
 
-### Dynamic Copy (e.g., Relative Time)
+### Relative time etc.
 
 ```ts
 if (minutes < 60) return ctx.t('{{count}} minutes ago', { count: minutes });
 if (hours < 24) return ctx.t('{{count}} hours ago', { count: hours });
 ```
 
-### Specifying a Namespace
+### Specify namespace
 
 ```ts
 ctx.t('Hello {{name}}', { name: 'Guest', ns: 'myModule' });
@@ -73,10 +70,10 @@ ctx.t('Hello {{name}}', { name: 'Guest', ns: 'myModule' });
 
 ## Notes
 
-- **Localization Plugin**: To translate text, the Localization plugin must be activated. Missing translation keys will be automatically extracted to the localization management list for unified maintenance and translation.
-- Supports i18next-style interpolation: Use `{{variableName}}` in the key and pass the corresponding variable in `options` to replace it.
-- The language is determined by the current context (e.g., `ctx.i18n.language`, user locale).
+- **Localization plugin**: Activate the localization plugin to manage translations. Missing keys can be collected for translation.
+- i18next-style interpolation: use `{{varName}}` in the key and pass the same name in `options`.
+- Language comes from the current context (e.g. `ctx.i18n.language`, user locale).
 
 ## Related
 
-- [ctx.i18n](./i18n.md): Read or switch languages
+- [ctx.i18n](./i18n.md): read or change language