Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(zh): translate other zh docs #551

Merged
merged 29 commits into from
Dec 12, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
29 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions website/docs/en/guide/advanced/dts.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ TypeScript Declaration Files (DTS) provide type information for JavaScript code.
2. **Code Completion**: Enhance code editor features like autocomplete and code navigation.
3. **Documentation Generation**: Generate documentation for JavaScript code, providing better developer experience.
4. **IDE Support**: Improve the developer experience in IDEs like Visual Studio Code, WebStorm, and others.
5. **Library Consumption**: Make it easier for other developers to use and understand your library.
5. **Library Consumption**: Make it easier for users to use and understand your library.

## What are Bundle DTS and Bundleless DTS

Expand Down Expand Up @@ -50,7 +50,7 @@ If you want to generate bundleless DTS, you can:

If you want to generate bundle DTS, you can:

1. Install `@microsoft/api-extractor` as a development dependency, which is the underlying tool used for bundling DTS files.
1. Install `@microsoft/api-extractor` as `devDependencies`, which is the underlying tool used for bundling DTS files.

import { PackageManagerTabs } from '@theme';

Expand Down
10 changes: 5 additions & 5 deletions website/docs/en/guide/advanced/module-federation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ import { PackageManagerTabs } from '@theme';

<PackageManagerTabs command="add @module-federation/rsbuild-plugin -D" />

Then add the plugin to the `rslib.config.ts` file:
Then register the plugin in the `rslib.config.ts` file:

```ts title='rslib.config.ts' {8-43}
import { pluginModuleFederation } from '@module-federation/rsbuild-plugin';
Expand Down Expand Up @@ -82,7 +82,7 @@ export default defineConfig({
});
```

In this way, we have completed the integration of Rslib Module as a producer. After the construction is completed, we can see that the mf directory has been added to the product, and consumers can directly consume this package
In this way, we have completed the integration of Rslib Module as a producer. After the construction is completed, we can see that the mf directory has been added to the product, and consumers can directly consume this package.

In the above example we added a new `format: 'mf'` , which will help you add an additional Module Federation product, while also configuring the format of `cjs` and `esm` , which does not conflict.

Expand All @@ -94,7 +94,7 @@ However, if you want this Rslib Module to consume other producers at the same ti

Rslib support developing Module Federation Rslib project with a host application.

#### 1. Start MF `dev` of library
#### 1. Start `rslib mf dev` command of library

Adding the `dev` command to the `package.json` file:

Expand Down Expand Up @@ -152,7 +152,7 @@ Then start the host app with `rsbuild dev`.

Rslib support developing Module Federation Rslib project with Storybook.

#### 1. Start MF `dev` of library
#### 1. Start `rslib mf dev` command of library

Adding the `dev` command to the `package.json` file:

Expand Down Expand Up @@ -310,7 +310,7 @@ This ensures that modules can be loaded as expected in multiple formats.
## FAQs

If the Rslib producer is built with build, this means that the `process.env.NODE_ENV` of the producer is `production` . If the consumer is started in dev mode at this time,
Due to the shared loading policy of Module Federation being `version-first` by default, there may be problems loading into different modes of react and react-dom (e.g. react in development mode, react-dom in production mode).
due to the shared loading strategy of Module Federation being `version-first` by default, there may be problems loading into different modes of react and react-dom (e.g. react in development mode, react-dom in production mode).
You can set up [shareStrategy](https://module-federation.io/configure/sharestrategy) at the consumer to solve this problem, but make sure you fully understand this configuration

```ts
Expand Down
6 changes: 2 additions & 4 deletions website/docs/en/guide/solution/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@ In this chapter, we will introduce how to use Rslib to development libraries for

## Browser Target

Rslib outputs code for the browser by default, so no additional configuration is necessary to get started.

When developing a library that runs in the browser, you can package it in both [ESM](/guide/basic/output-format#esm--cjs) and [CJS](/guide/basic/output-format#esm--cjs) formats for integration with application bundlers. Configuring the package [conditional exports](https://nodejs.org/api/packages.html#conditional-exports) to ESM output allows for better tree shaking. Additionally, you can create [UMD](/guide/basic/output-format#umd) format output for direct browser use and even generate [Module Federation ](/guide/advanced/module-federation) formats for dynamic loading by other applications. Configure [Browserslist](https://rsbuild.dev/guide/advanced/browserslist) according to the target browser support to determine the downgrade syntax of the output, or adding [polyfill](/guide/advanced/output-compatibility) for API compatibility.

When publishing to npm, you can choose not to [minify](/config/rsbuild/output#outputminify) your code or to minify it while providing a [sourcemap](/config/rsbuild/output#outputsourcemap) to enhance the debugging experience for users of your library. For styling, you can use [CSS](/guide/advanced/css), or [CSS pre-processors](/guide/advanced/css#preprocessors) like Sass, Less, or Stylus, or apply [PostCSS](/guide/advanced/css#postcss) for CSS post-processing. Tools like [Tailwind CSS](/guide/advanced/css#tailwind-css) can also help in building your styles. Using [CSS modules](/guide/advanced/css#css-modules) to create CSS modules is another option.
Expand All @@ -19,9 +17,9 @@ Refer to the solutions in this chapter to learn how to use Rslib to develop brow

## Node.js Target

By setting set [target](/config/rsbuild/output#outputtarget) to `"node"` to development libraries for Node.js.
Rslib set [target](/config/rsbuild/output#outputtarget) to `"node"` by default to development libraries for Node.js.

You can create a [pure ESM](/guide/basic/output-format#esm--cjs) package or a [dual package](/guide/basic/output-format#esm--cjs) that supports both ESM and CJS as needed. In CJS output, `import.meta.url` will be automatically [shimmed](/config/lib/shims) for compatibility and `__dirname` and `__filename` got an optional ESM shims to ensure proper use across different module system. Node.js's built-in packages will be [externalized by default](/guide/advanced/third-party-deps), simplifying the configuration.
You can create a [pure ESM](/guide/basic/output-format#esm--cjs) package or a [dual package](/guide/basic/output-format#esm--cjs) that supports both ESM and CJS as needed. In CJS output, `import.meta.url` will be automatically [shimmed](/config/lib/shims) for compatibility and `__dirname` and `__filename` got optional ESM shims to ensure proper use across different module system. Node.js's built-in packages will be [externalized by default](/guide/advanced/third-party-deps).

{/* TODO: Clarify default behavior */}
{/* ### Default Behavior */}
2 changes: 1 addition & 1 deletion website/docs/en/guide/solution/nodejs.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ export default defineConfig({

Rslib set [target](/config/rsbuild/output#outputtarget) to `"node"` by default, which is different from the default target of Rsbuild.

Rslib adjusts many configurations for Node.js. For example, [output.externals](/config/rsbuild/output#outputtarget) will exclude built-in Node.js modules, and [shims](/config/lib/shims) will add a shim for `import.meta.url` in CJS output by default.
When target is set to `"node"`, Rslib adjusts many configurations for Node.js. For example, [output.externals](/config/rsbuild/output#outputtarget) will exclude built-in Node.js modules, and [shims](/config/lib/shims) will add a shim for `import.meta.url` in CJS output by default.

### Externals

Expand Down
4 changes: 2 additions & 2 deletions website/docs/en/guide/solution/react.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ export default defineConfig({

React introduced a [new JSX transform](https://legacy.reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html) in version 17. This new transform removes the need to import `React` when using JSX.

By default, Rsbuild uses the new JSX transform, which is `runtime: 'automatic'`. It requires at least React `16.14.0` or higher. The peer dependency for React should be declared as above `16.14.0`.
By default, Rsbuild uses the new JSX transform, which is `runtime: 'automatic'`. It requires at least React `16.14.0` or higher. The `peerDependencies` should be declared as `"react": ">=16.14.0"`.

To change the JSX transform, you can pass the [swcReactOptions](https://rsbuild.dev/plugins/list/plugin-react#swcreactoptionsruntime) option to the React plugin. For example, to use the classic runtime:

Expand Down Expand Up @@ -79,7 +79,7 @@ export default defineConfig({
- **Type**: `string`
- **Default**: `'react'`

When `runtime` is `'automatic'`, you can specify the import path of the JSX transform through `importSource`.
When `runtime` is set to `'automatic'`, you can specify the import path of the JSX transform through `importSource`.

For example, when using [Emotion](https://emotion.sh/), you can set `importSource` to `'@emotion/react'`:

Expand Down
2 changes: 1 addition & 1 deletion website/docs/en/guide/start/glossary.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ CJS stands for [CommonJS](https://nodejs.org/api/modules.html#modules-commonjs-m

## Bundleless

Bundleless refers to a development approach that avoids the traditional practice of bundling multiple JavaScript / TypeScript files into a single or fewer output files before serving them to the client. Instead, it aims to serve individual modules directly.
Bundleless refers to a development mode that departs from the traditional practice of bundling multiple JavaScript / TypeScript files into a single or few output files that are then served to the app. Instead, it transforms each file.

## DTS

Expand Down
4 changes: 2 additions & 2 deletions website/docs/en/guide/start/quick-start.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ We're working to provide templates for more frameworks (such as Vue).

### Development Tools

`create-rslib` can help you set up some commonly used development linter tools, including [Vitest](https://vitest.dev/), [Storybook](https://storybook.js.org/). You can use the arrow keys and the space bar to make your selections. If you don't need these tools, you can simply press Enter to skip.
`create-rslib` can help you set up some commonly used development tools, including [Vitest](https://vitest.dev/), [Storybook](https://storybook.js.org/). You can use the arrow keys and the space bar to make your selections. If you don't need these tools, you can simply press Enter to skip.

- Vitest is available for all templates, it will be adapted based on the template's selection.
- Storybook is available for web targeted templates (React), it will be adapted based on the template's selection.
Expand All @@ -70,7 +70,7 @@ We're working to provide templates for more frameworks (such as Vue).

### Optional Tools

`create-rslib` can help you set up some commonly used formatter and linter tools, including [Biome](https://biomejs.dev/), [ESLint](https://eslint.org/), and [prettier](https://prettier.io/). You can use the arrow keys and the space bar to make your selections. If you don't need these tools, you can simply press Enter to skip.
`create-rslib` can help you set up some commonly used linter and formatter tools, including [Biome](https://biomejs.dev/), [ESLint](https://eslint.org/), and [prettier](https://prettier.io/). You can use the arrow keys and the space bar to make your selections. If you don't need these tools, you can simply press Enter to skip.

```text
◆ Select additional tools (Use <space> to select, <enter> to continue)
Expand Down
64 changes: 64 additions & 0 deletions website/docs/zh/guide/advanced/dts.mdx
Original file line number Diff line number Diff line change
@@ -1 +1,65 @@
# 类型生成

本章介绍什么是 TypeScript 声明文件(DTS)以及如何在 Rslib 中生成 DTS 文件。

## 什么是 DTS

TypeScript 声明文件 (DTS) 提供 JavaScript 代码的类型信息。 DTS 文件通常具有 `.d.ts` 扩展名。它们允许 TypeScript 编译器理解 JavaScript 代码的类型结构,从而实现以下功能:

1. **类型检查**: 为 JavaScript 代码提供类型信息,帮助开发人员在编译时捕获潜在的类型错误。
2. **代码补全**: 增强代码编辑器功能,例如自动完成和代码导航。
3. **文档生成**: 生成 JavaScript 代码文档,提供更好的开发体验。
4. **IDE 支持**: 改善 Visual Studio Code、WebStorm 等 IDE 中的开发者体验。
5. **库消费**: 让其他使用者更容易使用和理解该库。

## 什么是 Bundle DTS 和 Bundleless DTS

### Bundle DTS

Bundle DTS 将多个 TypeScript 声明文件 bundle 到一个声明文件中。

- **优势:**

- **简化管理**: 简化类型文件的管理和引用。
- **容易分发**: 减少用户使用库时需要处理的文件数量。

- **劣势:**
- **生成复杂**: 在大型项目中,生成和维护单个 bundle 文件可能会变得复杂。
- **调试困难**: 调试类型问题可能不像各个文件单独输出那样直观。

### Bundleless DTS

Bundleless DTS 为库中的每个模块生成单独的声明文件,就像 `tsc` 一样。

- **优势:**

- **模块化**: 每个模块都有自己的类型定义,使维护和调试更容易。
- **灵活**: 适合大型项目,避免单个文件的复杂性。

- **劣势:**
- **多文件**: 用户在使用该库时可能需要处理多个声明文件。
- **管理复杂**: 可能需要额外的配置才能正确引用所有文件。

## 如何在 Rslib 中生成 DTS

Rslib 默认使用 [TypeScript Compiler API](https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API) 生成 Bundleless DTS, 用 [API Extractor](https://api-extractor.com/) 生成 Bundle DTS。

如果你想生成 Bundleless DTS,可以:

- 设置 `dts: true` 或者 `dts: { bundle: false }` 在 Rslib 配置文件。

如果你想生成 Bundle DTS,可以:

1. 安装 `@microsoft/api-extractor` 作为 `devDependencies`, 这是用于 bundle DTS 文件的底层工具。

import { PackageManagerTabs } from '@theme';

<PackageManagerTabs command="add @microsoft/api-extractor -D" />

2. 在 Rslib 配置文件中设置 `dts: { bundle: true }`。

::: tip

你可以参考 [lib.dts](/config/lib/dts) 获取更多有关 DTS 配置的详细信息。

:::
Loading
Loading