Merge branch 'chenjiahan/docs-shared-config' into chenjiahan/docs-shared-config-api

Author: chenjiahan

website/docs/en/guide/configuration.mdx

@@ -158,7 +158,7 @@ When `extends` is omitted, Rstack CLI automatically connects the test configurat
 
 If the root test configuration does not define `extends` and contains `projects`, Rstack CLI applies automatic inheritance to each inline project that omits its own `extends`. A function-based application or library configuration is resolved once and shared by those projects. String project entries are passed to Rstest unchanged; they load their external configurations independently and do not inherit the current application or library configuration.
 
-These rules also apply to [shared configurations](#shared-configurations): Rstack first merges the test settings, then uses the merged App or Lib configuration for automatic inheritance.
+These rules also apply to [shared configurations](#shared-configurations): Rstack first merges the test settings, then determines whether to inherit the merged App or Lib configuration.
 
 > For more guidance on testing, see [Testing](./testing).
 
@@ -203,11 +203,11 @@ define.staged({
 });
 ```
 
-`rs staged` requires a staged configuration, provided by `define.staged()` or a shared configuration, and reports an error when it is missing.
+Provide a staged configuration through `define.staged()` or a [shared configuration](#shared-configurations). `rs staged` reports an error if neither provides one.
 
 ## Shared configurations
 
-Use `define.extends()` to share build, test, lint, and formatting settings across projects. Define a shared configuration as a plain object with the `RstackConfig` type. Its fields accept the same values as the corresponding `define.*()` APIs:
+Use `define.extends()` to share build, test, lint, and formatting settings across projects. A shared configuration is a plain object whose fields accept the same values as the corresponding `define.*()` APIs. In TypeScript, use `RstackConfig` to check its types:
 
 ```ts title="shared.ts"
 import type { RstackConfig } from 'rstack';
@@ -248,7 +248,7 @@ Configurations are applied in this order:
 1. Shared configurations in the `define.extends()` array, from left to right.
 2. The project's own `define.*()` configurations, even if they appear before `define.extends()` in the file.
 
-Later configurations take precedence according to each tool's [merge rules](#merge-rules).
+Each tool's [merge rules](#merge-rules) determine which values are combined and which are replaced.
 
 Shared configurations can also extend other shared configurations:
 
@@ -264,33 +264,33 @@ export const teamConfig: RstackConfig = {
 };
 ```
 
-Inherited configurations are applied before the object that extends them. Here, the order is `sharedConfig → teamConfig → project configuration`.
+Inherited configurations are applied first. With `define.extends([teamConfig])`, the order is `sharedConfig → teamConfig → project configuration`.
 
-Shared configurations are applied each time they appear. If both `a` and `b` extend `base`, for example, `define.extends([a, b])` applies `base → a → base → b → project configuration`. Array entries may therefore be added more than once; each tool determines how to handle duplicate plugins. Circular inheritance throws an error with the location of the circular reference.
+Repeated references are not deduplicated. If both `a` and `b` extend `base`, `define.extends([a, b])` applies `base → a → base → b → project configuration`. Each tool handles duplicate plugins according to its own rules. Circular inheritance throws an error that identifies the circular reference.
 
 ### Merge rules
 
 Rstack merges configurations separately for each tool:
 
-| Field    | Merge behavior                                                                                                                                                                        |
-| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `app`    | Uses Rsbuild's `mergeRsbuildConfig`.                                                                                                                                                  |
-| `lib`    | Uses Rslib's `mergeRslibConfig`.                                                                                                                                                      |
-| `test`   | Uses Rstest's `mergeRstestConfig`, then determines whether to inherit the merged App or Lib configuration. See [Test configuration inheritance](./testing#configuration-inheritance). |
-| `lint`   | Concatenates configuration arrays in order; Rslint applies their rules.                                                                                                               |
-| `fmt`    | Shallow merge: later values replace earlier values for the same option. Arrays and objects, including `overrides`, are replaced as a whole.                                           |
-| `doc`    | Uses Rspress's `mergeDocConfig`: recursively merges objects, appends arrays, and replaces ordinary functions with later functions.                                                    |
-| `staged` | Shallow merge by glob pattern: later tasks replace earlier tasks for the same pattern, including command arrays and task functions.                                                   |
+| Field    | Merge behavior                                                                                                                              |
+| -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `app`    | Uses Rsbuild's `mergeRsbuildConfig`.                                                                                                        |
+| `lib`    | Uses Rslib's `mergeRslibConfig`.                                                                                                            |
+| `test`   | Uses Rstest's `mergeRstestConfig`.                                                                                                          |
+| `lint`   | Concatenates configuration arrays in order; Rslint applies their rules.                                                                     |
+| `fmt`    | Shallow merge: later values replace earlier values for the same option. Arrays and objects, including `overrides`, are replaced as a whole. |
+| `doc`    | Uses Rspress's `mergeDocConfig`: recursively merges objects, appends arrays, and replaces ordinary functions with later functions.          |
+| `staged` | Shallow merge by glob pattern: later tasks replace earlier tasks for the same pattern, including command arrays and task functions.         |
 
-For `doc`, Rspress also handles a mix of array and non-array values: if both are defined, it wraps the non-array value in an array before concatenating them. `builderConfig` follows these same Rspress rules. For example, a later `builderConfig.tools.rspack` callback replaces an earlier one, while callback arrays are concatenated.
+The `doc` rules also apply to `builderConfig`: a later `builderConfig.tools.rspack` callback replaces an earlier one, while callback arrays are concatenated. When an array is merged with a defined non-array value, Rspress treats that value as a single array item.
 
-For `staged`, a top-level task-generator function replaces all earlier settings. A later configuration also replaces that function in full. Any subsequent glob mappings then merge as usual. For example, with `glob mappings → function → new glob mappings`, only the new mappings remain. Task functions run when lint-staged passes them the list of staged files.
+For `staged`, if either configuration is a top-level task-generator function, the later configuration replaces the earlier one entirely. For example, `glob mappings → function → new glob mappings` leaves only the new mappings. Task functions run when lint-staged supplies the staged file list.
 
 ### Dependencies and paths
 
 Shared configurations can also [import dependencies dynamically](#loading-dependencies-on-demand) inside tool configuration functions, so each command loads only what it needs.
 
-Relative paths follow each tool's existing rules. Use an absolute path to reference a file shipped with a shared configuration:
+Relative paths follow each tool's existing rules; they are not automatically resolved from the shared module's directory. Use an absolute path for files shipped with the shared configuration:
 
 ```ts title="shared.ts"
 import { fileURLToPath } from 'node:url';
@@ -303,4 +303,4 @@ export const sharedConfig: RstackConfig = {
 };
 ```
 
-Include the file when publishing the shared configuration package, or point the path to its compiled output.
+Make sure the published package includes the referenced file. If you compile it, update the path to match its output location.

website/docs/zh/guide/configuration.mdx

@@ -158,7 +158,7 @@ define.test({
 
 如果测试根配置未定义 `extends` 且包含 `projects`，Rstack CLI 会为每个未自行设置 `extends` 的内联项目应用自动继承。函数形式的应用或库配置只会解析一次，并由这些项目共享。字符串形式的项目会原样传给 Rstest；它们会独立加载外部配置，不继承当前应用或库的配置。
 
-这些规则同样适用于[公共配置](#shared-configurations)：Rstack 先合并测试配置，再使用合并后的 App 或 Lib 配置进行自动继承。
+这些规则同样适用于[公共配置](#shared-configurations)：Rstack 先合并测试配置，再判断是否需要继承合并后的 App 或 Lib 配置。
 
 > 如需了解更多测试相关用法，请参阅[测试](./testing)。
 
@@ -203,11 +203,11 @@ define.staged({
 });
 ```
 
-`rs staged` 必须通过 `define.staged()` 或公共配置提供 staged 配置，缺少配置时会报错。
+请通过 `define.staged()` 或[公共配置](#shared-configurations)提供 staged 配置，否则 `rs staged` 会报错。
 
 ## 公共配置 \{#shared-configurations}
 
-使用 `define.extends()` 可以在多个项目之间共享构建、测试、lint 和格式化配置。公共配置是一个标注了 `RstackConfig` 类型的普通对象，各字段的用法与对应的 `define.*()` API 一致：
+使用 `define.extends()` 可以在多个项目之间共享构建、测试、lint 和格式化配置。公共配置是一个普通对象，各字段的用法与对应的 `define.*()` API 一致。在 TypeScript 中，可以用 `RstackConfig` 检查配置类型：
 
 ```ts title="shared.ts"
 import type { RstackConfig } from 'rstack';
@@ -248,7 +248,7 @@ define.fmt({
 1. `define.extends()` 数组中的公共配置，从左到右。
 2. 项目自己的 `define.*()` 配置，即使这些调用写在 `define.extends()` 之前。
 
-后面的配置按照各工具的[合并规则](#merge-rules)覆盖前面的配置。
+各工具的[合并规则](#merge-rules)决定同一字段的值是合并还是替换。
 
 公共配置也可以继承其他公共配置：
 
@@ -264,33 +264,33 @@ export const teamConfig: RstackConfig = {
 };
 ```
 
-先应用被继承的配置，再应用当前对象。上例的顺序为 `sharedConfig → teamConfig → 项目配置`。
+被继承的配置先应用。使用 `define.extends([teamConfig])` 时，顺序为 `sharedConfig → teamConfig → 项目配置`。
 
-公共配置每出现一次就应用一次。例如，`a` 和 `b` 都继承 `base` 时，`define.extends([a, b])` 的顺序为 `base → a → base → b → 项目配置`。因此，数组中的内容可能被多次添加，重复的插件则由各工具自行处理。循环继承会抛出错误，并指出循环引用的位置。
+重复引用不会去重。例如，`a` 和 `b` 都继承 `base` 时，`define.extends([a, b])` 的顺序为 `base → a → base → b → 项目配置`。重复的插件由各工具按自身规则处理。循环继承会抛出错误，并指出循环引用的位置。
 
 ### 合并规则 \{#merge-rules}
 
 Rstack 分别合并各个工具的配置：
 
-| 字段     | 合并方式                                                                                                                              |
-| -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| `app`    | 使用 Rsbuild 的 `mergeRsbuildConfig`。                                                                                                |
-| `lib`    | 使用 Rslib 的 `mergeRslibConfig`。                                                                                                    |
-| `test`   | 使用 Rstest 的 `mergeRstestConfig`，再判断是否继承合并后的 App 或 Lib 配置，详见[测试配置继承](./testing#configuration-inheritance)。 |
-| `lint`   | 按顺序拼接配置数组，由 Rslint 应用其中的规则。                                                                                        |
-| `fmt`    | 浅合并，同名选项由后面的值覆盖。数组和对象（包括 `overrides`）整体替换。                                                              |
-| `doc`    | 使用 Rspress 的 `mergeDocConfig`：递归合并对象、追加数组，普通函数由后面的函数覆盖。                                                  |
-| `staged` | 按 glob 模式浅合并，同名模式的任务整体替换，包括命令数组和任务函数。                                                                  |
+| 字段     | 合并方式                                                                             |
+| -------- | ------------------------------------------------------------------------------------ |
+| `app`    | 使用 Rsbuild 的 `mergeRsbuildConfig`。                                               |
+| `lib`    | 使用 Rslib 的 `mergeRslibConfig`。                                                   |
+| `test`   | 使用 Rstest 的 `mergeRstestConfig`。                                                 |
+| `lint`   | 按顺序拼接配置数组，由 Rslint 应用其中的规则。                                       |
+| `fmt`    | 浅合并，同名选项由后面的值覆盖。数组和对象（包括 `overrides`）整体替换。             |
+| `doc`    | 使用 Rspress 的 `mergeDocConfig`：递归合并对象、追加数组，普通函数由后面的函数覆盖。 |
+| `staged` | 按 glob 模式浅合并，同名模式的任务整体替换，包括命令数组和任务函数。                 |
 
-对于 `doc`，如果同一字段的两个值都已定义，且只有一个是数组，Rspress 会先将另一个值包装为数组，再拼接。`builderConfig` 也遵循这套 Rspress 合并规则。例如，后面的 `builderConfig.tools.rspack` 回调会覆盖前面的回调，回调数组则按顺序拼接。
+`doc` 的合并规则同样适用于 `builderConfig`：后面的 `builderConfig.tools.rspack` 回调会覆盖前面的回调，回调数组则按顺序拼接。数组与已定义的非数组值合并时，Rspress 会将后者作为一个数组元素参与拼接。
 
-对于 `staged`，顶层任务生成函数会整体替换此前的配置，而它之后的配置也会整体替换这个函数。再往后的 glob 映射则按通常的规则合并。例如，按「glob 映射 → 函数 → 新的 glob 映射」应用时，最终只保留新的映射。任务函数由 lint-staged 传入暂存文件列表后执行。
+合并 `staged` 时，只要任一配置是顶层任务生成函数，就由后一个配置整体替换前一个。例如，「glob 映射 → 函数 → 新的 glob 映射」最终只保留新的映射。任务函数由 lint-staged 传入暂存文件列表后执行。
 
 ### 依赖与路径 \{#dependencies-and-paths}
 
 公共配置也可以在工具配置函数中[动态导入依赖](#loading-dependencies-on-demand)，让各命令只加载需要的依赖。
 
-相对路径沿用各工具的解析规则。引用公共配置自带的文件时，请使用绝对路径：
+相对路径沿用各工具的解析规则，不会自动改为以公共模块所在目录为基准。引用公共配置自带的文件时，请使用绝对路径：
 
 ```ts title="shared.ts"
 import { fileURLToPath } from 'node:url';
@@ -303,4 +303,4 @@ export const sharedConfig: RstackConfig = {
 };
 ```
 
-发布公共配置包时，请包含该文件，或将路径指向它的编译产物。
+发布包中需要包含引用的文件。如果该文件经过编译，请将路径改为编译产物的位置。