中文汉化

frontend/README.md

@@ -1,153 +1,152 @@
-# FastAPI Project - Frontend
+# FastAPI 项目 - 前端（Frontend）
 
-The frontend is built with [Vite](https://vitejs.dev/), [React](https://reactjs.org/), [TypeScript](https://www.typescriptlang.org/), [TanStack Query](https://tanstack.com/query), [TanStack Router](https://tanstack.com/router) and [Tailwind CSS](https://tailwindcss.com/).
+前端基于 [Vite](https://vitejs.dev/)、[React](https://reactjs.org/)、[TypeScript](https://www.typescriptlang.org/)、[TanStack Query](https://tanstack.com/query)、[TanStack Router](https://tanstack.com/router) 与 [Tailwind CSS](https://tailwindcss.com/) 构建。
 
-## Frontend development
+## 前端开发
 
-Before you begin, ensure that you have either the Node Version Manager (nvm) or Fast Node Manager (fnm) installed on your system.
+在开始之前，请确保系统中安装了 Node 版本管理工具：Node Version Manager（nvm）或 Fast Node Manager（fnm）。
 
-* To install fnm follow the [official fnm guide](https://github.com/Schniz/fnm#installation). If you prefer nvm, you can install it using the [official nvm guide](https://github.com/nvm-sh/nvm#installing-and-updating).
+* 安装 fnm 可参考 [官方文档](https://github.com/Schniz/fnm#installation)；如果你更喜欢 nvm，可参考 [nvm 官方文档](https://github.com/nvm-sh/nvm#installing-and-updating)。
 
-* After installing either nvm or fnm, proceed to the `frontend` directory:
+* 安装好 nvm 或 fnm 后，进入 `frontend` 目录：
 
 ```bash
 cd frontend
 ```
-* If the Node.js version specified in the `.nvmrc` file isn't installed on your system, you can install it using the appropriate command:
+
+* 如果系统尚未安装 `.nvmrc` 中指定的 Node.js 版本，可以运行对应命令进行安装：
 
 ```bash
-# If using fnm
+# 使用 fnm 时
 fnm install
 
-# If using nvm
+# 使用 nvm 时
 nvm install
 ```
 
-* Once the installation is complete, switch to the installed version:
+* 安装完成后，切换到该版本的 Node.js：
 
 ```bash
-# If using fnm
+# 使用 fnm 时
 fnm use
 
-# If using nvm
+# 使用 nvm 时
 nvm use
 ```
 
-* Within the `frontend` directory, install the necessary NPM packages:
+* 在 `frontend` 目录中安装依赖：
 
 ```bash
 npm install
 ```
 
-* And start the live server with the following `npm` script:
+* 使用下面的脚本启动本地开发服务器（支持热更新）：
 
 ```bash
 npm run dev
 ```
 
-* Then open your browser at http://localhost:5173/.
+* 然后在浏览器中打开 `http://localhost:5173/`。
 
-Notice that this live server is not running inside Docker, it's for local development, and that is the recommended workflow. Once you are happy with your frontend, you can build the frontend Docker image and start it, to test it in a production-like environment. But building the image at every change will not be as productive as running the local development server with live reload.
+注意：这个开发服务器是在本机直接运行的，不在 Docker 容器中。这是推荐的前端开发方式：在本地使用 Vite 的热更新体验进行快速迭代；当前端就绪后，再构建前端 Docker 镜像，在接近生产环境的 Docker 中做最终验证。频繁为每次改动重建 Docker 镜像，会远不如直接用本地开发服务器高效。
 
-Check the file `package.json` to see other available options.
+更多可用的 npm 脚本与命令可以查看 `package.json`。
 
-### Removing the frontend
+### 移除前端
 
-If you are developing an API-only app and want to remove the frontend, you can do it easily:
+如果你只需要开发纯 API（仅后端），想要彻底移除前端，可以按照下面步骤操作：
 
-* Remove the `./frontend` directory.
+* 删除整个 `./frontend` 目录。
 
-* In the `docker-compose.yml` file, remove the whole service / section `frontend`.
+* 在 `docker-compose.yml` 中删除 `frontend` 服务（整个 service 区块）。
 
-* In the `docker-compose.override.yml` file, remove the whole service / section `frontend` and `playwright`.
+* 在 `docker-compose.override.yml` 中删除 `frontend` 与 `playwright` 两个服务的配置。
 
-Done, you have a frontend-less (api-only) app. 🤓
+完成后，你就获得了一个“无前端”（仅 API）的应用。🤓
 
 ---
 
-If you want, you can also remove the `FRONTEND` environment variables from:
+如果你愿意，还可以从以下位置删除与 `FRONTEND` 相关的环境变量，仅用于清理配置（保留它们也不会产生实际影响）：
 
 * `.env`
 * `./scripts/*.sh`
 
-But it would be only to clean them up, leaving them won't really have any effect either way.
+## 生成前端客户端（API Client）
 
-## Generate Client
+### 自动方式
 
-### Automatically
-
-* Activate the backend virtual environment.
-* From the top level project directory, run the script:
+* 激活后端虚拟环境。
+* 在项目根目录执行脚本：
 
 ```bash
 ./scripts/generate-client.sh
 ```
 
-* Commit the changes.
+* 将生成的变更提交到仓库。
 
-### Manually
+### 手动方式
 
-* Start the Docker Compose stack.
+* 启动 Docker Compose stack。
 
-* Download the OpenAPI JSON file from `http://localhost/api/v1/openapi.json` and copy it to a new file `openapi.json` at the root of the `frontend` directory.
+* 从 `http://localhost/api/v1/openapi.json` 下载 OpenAPI JSON 文件，并将其保存为 `frontend` 目录根下的 `openapi.json`。
 
-* To generate the frontend client, run:
+* 生成前端客户端：
 
 ```bash
 npm run generate-client
 ```
 
-* Commit the changes.
+* 将生成的变更提交到仓库。
 
-Notice that everytime the backend changes (changing the OpenAPI schema), you should follow these steps again to update the frontend client.
+请注意，每当后端发生影响 OpenAPI Schema 的变更时，都需要重新执行上述步骤以更新前端客户端。
 
-## Using a Remote API
+## 使用远程 API
 
-If you want to use a remote API, you can set the environment variable `VITE_API_URL` to the URL of the remote API. For example, you can set it in the `frontend/.env` file:
+如果你希望前端调用远程环境的 API，可以设置环境变量 `VITE_API_URL` 为远程 API 的基础 URL，例如在 `frontend/.env` 中配置：
 
 ```env
 VITE_API_URL=https://api.my-domain.example.com
 ```
 
-Then, when you run the frontend, it will use that URL as the base URL for the API.
+之后启动前端时，它会将该地址作为 API 请求的基础 URL。
 
-## Code Structure
+## 代码结构
 
-The frontend code is structured as follows:
+前端代码结构大致如下：
 
-* `frontend/src` - The main frontend code.
-* `frontend/src/assets` - Static assets.
-* `frontend/src/client` - The generated OpenAPI client.
-* `frontend/src/components` -  The different components of the frontend.
-* `frontend/src/hooks` - Custom hooks.
-* `frontend/src/routes` - The different routes of the frontend which include the pages.
+* `frontend/src` - 前端主要源代码。
+* `frontend/src/assets` - 静态资源。
+* `frontend/src/client` - 通过 OpenAPI 生成的前端客户端代码。
+* `frontend/src/components` - 各种通用组件与业务组件。
+* `frontend/src/hooks` - 自定义 Hooks。
+* `frontend/src/routes` - 路由定义及页面组件。
 
-## End-to-End Testing with Playwright
+## 使用 Playwright 做端到端测试（E2E）
 
-The frontend includes initial end-to-end tests using Playwright. To run the tests, you need to have the Docker Compose stack running. Start the stack with the following command:
+前端中预置了基于 Playwright 的端到端测试。要运行测试，需要先启动 Docker Compose stack。可以使用如下命令启动（至少需要后端）：
 
 ```bash
 docker compose up -d --wait backend
 ```
 
-Then, you can run the tests with the following command:
+然后运行 Playwright 测试：
 
 ```bash
 npx playwright test
 ```
 
-You can also run your tests in UI mode to see the browser and interact with it running:
+你也可以使用 UI 模式运行测试，以便查看浏览器界面并与之交互：
 
 ```bash
 npx playwright test --ui
 ```
 
-To stop and remove the Docker Compose stack and clean the data created in tests, use the following command:
+测试完成后，如果希望停止并移除 Docker Compose stack，同时清理测试期间创建的数据，可运行：
 
 ```bash
 docker compose down -v
 ```
 
-To update the tests, navigate to the tests directory and modify the existing test files or add new ones as needed.
+如需更新或新增 E2E 测试用例，只需到 `frontend/tests` 目录中修改现有测试文件或新增文件。
 
-For more information on writing and running Playwright tests, refer to the official [Playwright documentation](https://playwright.dev/docs/intro).
+更多关于编写与运行 Playwright 测试的说明，可参考官方文档：[Playwright documentation](https://playwright.dev/docs/intro)。