feat(@vben/docs): support english documents (#4202)
* chore(@vben/docs): 完成guide文档的翻译 * chore(@vben/docs): 完成other文档的翻译 * chore: 翻译部分文档 * chore: 完成英文config的配置 * chore: 完成in-depth的文档翻译 * chore: 调整调整链接 * chore: typo * chore: typo * chore: update links --------- Co-authored-by: Li Kui <90845831+likui628@users.noreply.github.com>
This commit is contained in:
invalid w
21
docs/src/en/guide/project/changeset.md
Normal file
21
docs/src/en/guide/project/changeset.md
Normal file
@@ -0,0 +1,21 @@
|
||||
# Changeset
|
||||
|
||||
The project has integrated [changeset](https://github.com/changesets/changesets) as a version management tool. Changeset is a version management tool that helps us better manage versions, generate changelogs, and automate releases.
|
||||
|
||||
For detailed usage, please refer to the official documentation. If you do not need it, you can ignore it directly.
|
||||
|
||||
## Command Line
|
||||
|
||||
The changeset command is already built into the project:
|
||||
|
||||
### Interactively Add Changesets
|
||||
|
||||
```bash
|
||||
pnpm run changeset
|
||||
```
|
||||
|
||||
### Uniformly Increment Version Numbers
|
||||
|
||||
```bash
|
||||
pnpm run version
|
||||
```
|
||||
123
docs/src/en/guide/project/cli.md
Normal file
123
docs/src/en/guide/project/cli.md
Normal file
@@ -0,0 +1,123 @@
|
||||
---
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# CLI
|
||||
|
||||
In the project, some command-line tools are provided for common operations, located in `scripts`.
|
||||
|
||||
## vsh
|
||||
|
||||
Used for some project operations, such as cleaning the project, checking the project, etc.
|
||||
|
||||
### Usage
|
||||
|
||||
```bash
|
||||
pnpm vsh [command] [options]
|
||||
```
|
||||
|
||||
### vsh check-circular
|
||||
|
||||
Check for circular references throughout the project. If there are circular references, the modules involved will be output to the console.
|
||||
|
||||
#### Usage
|
||||
|
||||
```bash
|
||||
pnpm vsh check-circular
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description |
|
||||
| ---------- | --------------------------------------------------------- |
|
||||
| `--staged` | Only check files in the git staging area, default `false` |
|
||||
|
||||
### vsh check-dep
|
||||
|
||||
Check the dependency situation of the entire project and output `unused dependencies`, `uninstalled dependencies` information to the console.
|
||||
|
||||
#### Usage
|
||||
|
||||
```bash
|
||||
pnpm vsh check-dep
|
||||
```
|
||||
|
||||
### vsh clean
|
||||
|
||||
Delete the project's `node_modules`, `dist`, `.turbo` directories, etc., to clean the project.
|
||||
|
||||
#### Usage
|
||||
|
||||
```bash
|
||||
pnpm vsh clean
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description |
|
||||
| --- | --- |
|
||||
| `-r,--recursive` | Recursively delete the entire project, default `true` |
|
||||
| `--del-lock` | Whether to delete the `pnpm-lock.yaml` file, default `true` |
|
||||
|
||||
### vsh lint
|
||||
|
||||
Lint checks the project to see if the code in the project conforms to standards.
|
||||
|
||||
#### Usage
|
||||
|
||||
```bash
|
||||
pnpm vsh lint
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description |
|
||||
| ---------- | -------------------------------------------- |
|
||||
| `--format` | Check and try to fix errors, default `false` |
|
||||
|
||||
### vsh publint
|
||||
|
||||
Perform package standard checks on `Monorepo` projects to see if the packages in the project conform to standards.
|
||||
|
||||
#### Usage
|
||||
|
||||
```bash
|
||||
pnpm vsh publint
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description |
|
||||
| --------- | ------------------------------------ |
|
||||
| `--check` | Only perform checks, default `false` |
|
||||
|
||||
### vsh code-workspace
|
||||
|
||||
Generate `vben-admin.code-workspace` file. Currently, it does not need to be executed manually and will be executed automatically when code is committed.
|
||||
|
||||
#### Usage
|
||||
|
||||
```bash
|
||||
pnpm vsh code-workspace
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Description |
|
||||
| --------------- | --------------------------------------------------------- |
|
||||
| `--auto-commit` | Automatically commit during `git commit`, default `false` |
|
||||
| `--spaces` | Indentation format, default `2` spaces |
|
||||
|
||||
## turbo-run
|
||||
|
||||
Used to quickly execute scripts in the large repository and provide option-based interactive selection.
|
||||
|
||||
### Usage
|
||||
|
||||
```bash
|
||||
pnpm turbo-run [command]
|
||||
```
|
||||
|
||||
### turbo-run dev
|
||||
|
||||
Quickly execute the `dev` command and provide option-based interactive selection.
|
||||
68
docs/src/en/guide/project/dir.md
Normal file
68
docs/src/en/guide/project/dir.md
Normal file
@@ -0,0 +1,68 @@
|
||||
# Directory Explanation
|
||||
|
||||
The directory uses Monorepo management, and the project structure is as follows:
|
||||
|
||||
```bash
|
||||
.
|
||||
├── Dockerfile # Docker image build file
|
||||
├── README.md # Project documentation
|
||||
├── apps # Project applications directory
|
||||
│ ├── backend-mock # Backend mock service application
|
||||
│ ├── web-antd # Frontend application based on Ant Design Vue
|
||||
│ ├── web-ele # Frontend application based on Element Plus
|
||||
│ └── web-naive # Frontend application based on Naive UI
|
||||
├── build-local-docker-image.sh # Script for building Docker images locally
|
||||
├── cspell.json # CSpell configuration file
|
||||
├── docs # Project documentation directory
|
||||
├── eslint.config.mjs # ESLint configuration file
|
||||
├── internal # Internal tools directory
|
||||
│ ├── lint-configs # Code linting configurations
|
||||
│ │ ├── commitlint-config # Commitlint configuration
|
||||
│ │ ├── eslint-config # ESLint configuration
|
||||
│ │ ├── prettier-config # Prettier configuration
|
||||
│ │ └── stylelint-config # Stylelint configuration
|
||||
│ ├── node-utils # Node.js tools
|
||||
│ ├── tailwind-config # Tailwind configuration
|
||||
│ ├── tsconfig # Common tsconfig settings
|
||||
│ └── vite-config # Common Vite configuration
|
||||
├── package.json # Project dependency configuration
|
||||
├── packages # Project packages directory
|
||||
│ ├── @core # Core package
|
||||
│ │ ├── base # Base package
|
||||
│ │ │ ├── design # Design related
|
||||
│ │ │ ├── icons # Icons
|
||||
│ │ │ ├── shared # Shared
|
||||
│ │ │ └── typings # Type definitions
|
||||
│ │ ├── composables # Composable APIs
|
||||
│ │ ├── preferences # Preferences
|
||||
│ │ └── ui-kit # UI component collection
|
||||
│ │ ├── layout-ui # Layout UI
|
||||
│ │ ├── menu-ui # Menu UI
|
||||
│ │ ├── shadcn-ui # shadcn UI
|
||||
│ │ └── tabs-ui # Tabs UI
|
||||
│ ├── constants # Constants
|
||||
│ ├── effects # Effects related packages
|
||||
│ │ ├── access # Access control
|
||||
│ │ ├── chart-ui # Chart UI
|
||||
│ │ ├── common-ui # Common UI
|
||||
│ │ ├── hooks # Composable APIs
|
||||
│ │ ├── layouts # Layouts
|
||||
│ │ └── request # Request
|
||||
│ ├── icons # Icons
|
||||
│ ├── locales # Internationalization
|
||||
│ ├── preferences # Preferences
|
||||
│ ├── stores # State management
|
||||
│ ├── styles # Styles
|
||||
│ ├── types # Type definitions
|
||||
│ └── utils # Utilities
|
||||
├── playground # Demo directory
|
||||
├── pnpm-lock.yaml # pnpm lock file
|
||||
├── pnpm-workspace.yaml # pnpm workspace configuration file
|
||||
├── scripts # Scripts directory
|
||||
│ ├── turbo-run # Turbo run script
|
||||
│ └── vsh # VSH script
|
||||
├── stylelint.config.mjs # Stylelint configuration file
|
||||
├── turbo.json # Turbo configuration file
|
||||
├── vben-admin.code-workspace # VS Code workspace configuration file
|
||||
└── vitest.config.ts # Vite configuration file
|
||||
```
|
||||
165
docs/src/en/guide/project/standard.md
Normal file
165
docs/src/en/guide/project/standard.md
Normal file
@@ -0,0 +1,165 @@
|
||||
# Standards
|
||||
|
||||
::: tip Contributing Code
|
||||
|
||||
- If you want to contribute code to the project, please ensure your code complies with the project's coding standards.
|
||||
- If you are using `vscode`, you need to install the following plugins:
|
||||
|
||||
- [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) - Script code checking
|
||||
- [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) - Code formatting
|
||||
- [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) - Word syntax checking
|
||||
- [Stylelint](https://marketplace.visualstudio.com/items?itemName=stylelint.vscode-stylelint) - CSS formatting
|
||||
|
||||
:::
|
||||
|
||||
## Purpose
|
||||
|
||||
Students with basic engineering literacy always pay attention to coding standards, and code style checking (Code Linting, simply called Lint) is an important means to ensure the consistency of coding standards.
|
||||
|
||||
Following the corresponding coding standards has the following benefits:
|
||||
|
||||
- Lower bug error rate
|
||||
- Efficient development efficiency
|
||||
- Higher readability
|
||||
|
||||
## Tools
|
||||
|
||||
The project's configuration files are located in `internal/lint-configs`, where you can modify various lint configurations.
|
||||
|
||||
The project integrates the following code verification tools:
|
||||
|
||||
- [ESLint](https://eslint.org/) for JavaScript code checking
|
||||
- [Stylelint](https://stylelint.io/) for CSS style checking
|
||||
- [Prettier](https://prettier.io/) for code formatting
|
||||
- [Commitlint](https://commitlint.js.org/) for checking the standard of git commit messages
|
||||
- [Publint](https://publint.dev/) for checking the standard of npm packages
|
||||
- [Lint Staged](https://github.com/lint-staged/lint-staged) for running code verification before git commits
|
||||
- [Cspell](https://cspell.org/) for checking spelling errors
|
||||
|
||||
## ESLint
|
||||
|
||||
ESLint is a code standard and error checking tool used to identify and report syntax errors in TypeScript code.
|
||||
|
||||
### Command
|
||||
|
||||
```bash
|
||||
pnpm eslint .
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
The ESLint configuration file is `eslint.config.mjs`, with its core configuration located in the `internal/lint-configs/eslint-config` directory, which can be modified according to project needs.
|
||||
|
||||
## Stylelint
|
||||
|
||||
Stylelint is used to check the style of CSS within the project. Coupled with the editor's auto-fix feature, it can effectively unify the CSS style within the project.
|
||||
|
||||
### Command
|
||||
|
||||
```bash
|
||||
pnpm stylelint "**/*.{vue,css,less.scss}"
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
The Stylelint configuration file is `stylelint.config.mjs`, with its core configuration located in the `internal/lint-configs/stylelint-config` directory, which can be modified according to project needs.
|
||||
|
||||
## Prettier
|
||||
|
||||
Prettier Can be used to unify project code style, consistent indentation, single and double quotes, trailing commas, and other styles.
|
||||
|
||||
### Command
|
||||
|
||||
```bash
|
||||
pnpm prettier .
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
The Prettier configuration file is `.prettier.mjs`, with its core configuration located in the `internal/lint-configs/prettier-config` directory, which can be modified according to project needs.
|
||||
|
||||
## CommitLint
|
||||
|
||||
In a team, everyone's git commit messages can vary widely, making it difficult to ensure standardization without a mechanism. How can standardization be achieved? You might think of using git's hook mechanism to write shell scripts to implement this. Of course, this is possible, but actually, JavaScript has a great tool for implementing this template, which is commitlint (used for verifying the standard of git commit messages).
|
||||
|
||||
### Configuration
|
||||
|
||||
The CommitLint configuration file is `.commitlintrc.mjs`, with its core configuration located in the `internal/lint-configs/commitlint-config` directory, which can be modified according to project needs.
|
||||
|
||||
### Git Commit Standards
|
||||
|
||||
Refer to [Angular](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-angular)
|
||||
|
||||
- `feat` Add new features
|
||||
- `fix` Fix problems/BUGs
|
||||
- `style` Code style changes that do not affect the outcome
|
||||
- `perf` Optimization/performance improvement
|
||||
- `refactor` Refactoring
|
||||
- `revert` Revert changes
|
||||
- `test` Related to tests
|
||||
- `docs` Documentation/comments
|
||||
- `chore` Dependency updates/scaffold configuration modifications, etc.
|
||||
- `workflow` Workflow improvements
|
||||
- `ci` Continuous integration
|
||||
- `types` Type modifications
|
||||
|
||||
### Disabling Git Commit Standard Checks
|
||||
|
||||
If you want to disable Git commit standard checks, there are two ways:
|
||||
|
||||
::: code-group
|
||||
|
||||
```bash [Temporary disable]
|
||||
git commit -m 'feat: add home page' --no-verify
|
||||
```
|
||||
|
||||
```bash [Permanent closed]
|
||||
# Comment out the following code in .husky/commit-msg to disable
|
||||
pnpm exec commitlint --edit "$1" # [!code --]
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
## Publint
|
||||
|
||||
Publint is a tool for checking the standard of npm packages, which can check whether the package version conforms to the standard, whether it conforms to the standard ESM package specification, etc.
|
||||
|
||||
### Command
|
||||
|
||||
```bash
|
||||
pnpm vsh publint
|
||||
```
|
||||
|
||||
## Cspell
|
||||
|
||||
Cspell is a tool for checking spelling errors, which can check for spelling errors in the code, avoiding bugs caused by spelling errors.
|
||||
|
||||
### Command
|
||||
|
||||
```bash
|
||||
pnpm cspell lint \"**/*.ts\" \"**/README.md\" \".changeset/*.md\" --no-progress
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
The cspell configuration file is `cspell.json`, which can be modified according to project needs.
|
||||
|
||||
## Git Hook
|
||||
|
||||
Git hooks are generally combined with various lints to check code style during git commits. If the check fails, the commit will not proceed. Developers need to modify and resubmit.
|
||||
|
||||
### husky
|
||||
|
||||
One issue is that the check will verify all code, but we only want to check the code we are committing. This is where husky comes in.
|
||||
|
||||
The most effective solution is to perform Lint checks locally before committing. A common practice is to use husky or pre-commit to perform a Lint check before local submission.
|
||||
|
||||
The project defines corresponding hooks inside `.husky`.
|
||||
|
||||
#### How to Disable Husky
|
||||
|
||||
If you want to disable Husky, simply delete the .husky directory.
|
||||
|
||||
### lint-staged
|
||||
|
||||
Used for automatically fixing style issues of committed files. Its configuration file is `.lintstagedrc.mjs`, which can be modified according to project needs.
|
||||
13
docs/src/en/guide/project/tailwindcss.md
Normal file
13
docs/src/en/guide/project/tailwindcss.md
Normal file
@@ -0,0 +1,13 @@
|
||||
# Tailwind CSS
|
||||
|
||||
[Tailwind CSS](https://tailwindcss.com/) is a utility-first CSS framework for quickly building custom designs.
|
||||
|
||||
## Configuration
|
||||
|
||||
The project's configuration file is located in `internal/tailwind-config`, where you can modify the Tailwind CSS configuration.
|
||||
|
||||
::: tip Restrictions on using tailwindcss in packages
|
||||
|
||||
Tailwind CSS compilation will only be enabled if there is a `tailwind.config.mjs` file present in the corresponding package. Otherwise, Tailwind CSS will not be enabled. If you have a pure SDK package that does not require Tailwind CSS, you do not need to create a `tailwind.config.mjs` file.
|
||||
|
||||
:::
|
||||
33
docs/src/en/guide/project/test.md
Normal file
33
docs/src/en/guide/project/test.md
Normal file
@@ -0,0 +1,33 @@
|
||||
# Unit Testing
|
||||
|
||||
The project incorporates [Vitest](https://vitest.dev/) as the unit testing tool. Vitest is a test runner based on Vite, offering a simple API for writing test cases.
|
||||
|
||||
## Writing Test Cases
|
||||
|
||||
Within the project, we follow the convention of naming test files with a `.test.ts` suffix or placing them inside a `__tests__` directory. For example, if you create a `utils.ts` file, then you would create a corresponding `utils.spec.ts` file in the same directory,
|
||||
|
||||
```ts
|
||||
// utils.test.ts
|
||||
import { expect, test } from 'vitest';
|
||||
import { sum } from './sum';
|
||||
|
||||
test('adds 1 + 2 to equal 3', () => {
|
||||
expect(sum(1, 2)).toBe(3);
|
||||
});
|
||||
```
|
||||
|
||||
## Running Tests
|
||||
|
||||
To run the tests, execute the following command at the root of the monorepo:
|
||||
|
||||
```bash
|
||||
pnpm test:unit
|
||||
```
|
||||
|
||||
## Existing Unit Tests
|
||||
|
||||
There are already some unit test cases in the project. You can search for files ending with .test.ts to view them. When you make changes to related code, you can run the unit tests to ensure the correctness of your code. It is recommended to maintain the coverage of unit tests during the development process and to run unit tests as part of the CI/CD process to ensure tests pass before deploying the project.
|
||||
|
||||
Existing unit test status:
|
||||
|
||||
|
||||
33
docs/src/en/guide/project/vite.md
Normal file
33
docs/src/en/guide/project/vite.md
Normal file
@@ -0,0 +1,33 @@
|
||||
# Vite Config
|
||||
|
||||
The project encapsulates a layer of Vite configuration and integrates some plugins for easy reuse across multiple packages and applications. The usage is as follows:
|
||||
|
||||
## Application
|
||||
|
||||
```ts
|
||||
// vite.config.mts
|
||||
import { defineConfig } from '@vben/vite-config';
|
||||
|
||||
export default defineConfig(async () => {
|
||||
return {
|
||||
application: {},
|
||||
// Vite configuration, override according to the official Vite documentation
|
||||
vite: {},
|
||||
};
|
||||
});
|
||||
```
|
||||
|
||||
## Package
|
||||
|
||||
```ts
|
||||
// vite.config.mts
|
||||
import { defineConfig } from '@vben/vite-config';
|
||||
|
||||
export default defineConfig(async () => {
|
||||
return {
|
||||
library: {},
|
||||
// Vite configuration, override according to the official Vite documentation
|
||||
vite: {},
|
||||
};
|
||||
});
|
||||
```
|
||||
Reference in New Issue
Block a user