feat: en

.scripts/ai-trans/main.go

@@ -16,9 +16,11 @@ const (
     zhDocPath = `/Users/john/Workspace/github/gogf/gf-site/docs`
     enDocPath = `/Users/john/Workspace/github/gogf/gf-site/i18n/en/docusaurus-plugin-content-docs/current`
     initAIMsg = `
-我在给docusaurus的站点文档做翻译，我给你markdown中文内容，你翻译为英文。
-不要在外层给我包装markdown标签，不要改变内容中的任何标签，只将中文翻译为英文。
+我在给docusaurus的站点文档做翻译，我给你markdown文件内容，你翻译为英文。
+不要使用markdown标签包括返回内容，不要改变内容中的任何标签，只将中文翻译为英文。
 如果文件顶部的front matter中的description内容中含有单引号，那么将description的值由单引号改为双引号包裹。
+不要对顶部的front matter内容使用代码标签包括。
+不能删除markdown内容中的图片展示标签内容。
 `
 )
 
@@ -67,6 +69,18 @@ func main() {
             g.Log().Warningf(ctx, "doAITrans empty content")
             continue
         }
+        // 内容检测，图片及连接数量是否相等
+        var (
+            resourceLinkCount    = gstr.Count(content, `](`)
+            resourceLinkCountNew = gstr.Count(newContent, `](`)
+        )
+        if resourceLinkCount != resourceLinkCountNew {
+            g.Log().Warningf(
+                ctx,
+                "resource link count not equal: %d != %d", resourceLinkCount, resourceLinkCountNew,
+            )
+            continue
+        }
         _ = gfile.PutContents(enFilePath, newContent)
     }
 }

i18n/en/docusaurus-plugin-content-docs/current/course/starbook/第一章-基础信息/1.1.项目介绍.md

@@ -0,0 +1,51 @@
+---
+title: '1.1.Project Introduction'
+hide_title: true
+slug: '/course/starbook/about-intro'
+keywords: [Project Requirements, Star English Book, User Registration, Word Management, Proficiency Setting, Front-end and Back-end Separation, Web Application, Front-end Framework, JSON Format, GoFrame Framework]
+description: "Star English Book is a demonstration project using GoFrame to help users learn and manage English vocabulary, including registration and login features, and provides random review and proficiency settings. The project adopts a front-end and back-end separation model, using the GoFrame framework for development, outputting standard JSON format data for the front end to fetch and build pages through HTTP requests."
+---
+Before developing a real project, it is essential to understand the project requirements as they form the foundation for subsequent development. If the foundation is not solid, everything built upon it will be shaky.
+
+**Star English Book** is lightweight software designed to help users learn English vocabulary and provides the following features:
+- User registration;
+- Manage their vocabulary after logging in;
+- Randomly retrieve several words for review;
+- Ability to set the proficiency level of words.
+
+Starting from the feature points, we can create a more intuitive mind map:
+![Feature List](../assets/svg/功能清单.svg)
+
+## Front-end and Back-end Separation
+---
+As previously mentioned, this project does not involve any front-end development, so it is necessary to explain how the front end should handle it.
+
+For a web application, the front end and back end are two vital components. The front end refers to the interactive pages users can operate, typically built with `HTML`, `CSS`, and `JavaScript`; it represents the face of the software program. The front end doesn't provide any data; it is merely a tool for displaying data, with the data source being the back end. The back end supplies all the application data and processes it, serving as the core of the software program.
+
+Many years ago, there was no clear boundary between the front end and back end, and typically back-end programming languages would directly output `HTML` pages. As the internet developed, front-end pages became increasingly complex, placing a heavy burden on back-end programmers. Thus, front-end and back-end separation gradually became mainstream, and many frameworks emerged on the front end, such as `Vue`, `React`, `Angular`, etc., which help better manage front-end projects.
+
+The design purpose of **Star English Book** is to enable readers to quickly master `GoFrame`, so it also adopts the front-end and back-end separation model. All developed content does not directly output `HTML`, but bypasses the front end, directly outputting standard `JSON` format data.
+
+### JSON
+`JSON` is currently the most mainstream data format for front-end and back-end interaction. Data returned by a standard interface is as follows:
+```json
+{
+    "code": 0,
+    "message": "",
+    "data": {
+        "id": 1,
+        "uid": 1,
+        "word": "example",
+        "definition": "A representative form or pattern.",
+        "exampleSentence": "This is an example sentence.",
+        "chineseTranslation": "例子",
+        "pronunciation": "ɪɡˈzɑːmp(ə)l",
+        "proficiencyLevel": 3,
+        "createdAt": "2024-11-12 15:38:50",
+        "updatedAt": "2024-11-13 14:42:19"
+    }
+}
+```
+`code` represents the status code, where `0` means success; `message` is a custom message, and `data` is the response data.
+
+Once the front-end developers retrieve the `JSON` data through an `HTTP` request, they can then fully utilize their expertise to construct specific pages.

i18n/en/docusaurus-plugin-content-docs/current/course/starbook/第一章-基础信息/1.2.MVC.md

@@ -0,0 +1,18 @@
+---
+title: '1.2.MVC'
+hide_title: true
+slug: '/course/starbook/about-mvc'
+keywords: [MVC,Model,View,Controller,GoFrame,程序设计架构,前后端分离,数据管理,用户界面,业务逻辑]
+description: "Learn about the MVC (Model-View-Controller) design architecture, where the Model handles application data and business logic, managing data and database interactions; the View is responsible for data display and the user interface, interacting with users to present data; and the Controller processes user input and requests, acting as an intermediary between the model and the view. In a front-end and back-end separation, focus on the Controller and Model layers."
+---
+If you are already familiar with `MVC`, you can skip this section. If you are a beginner, you need to understand the `MVC (Model-View-Controller)` design architecture.
+
+`MVC` divides an application into three main components: Model, View, and Controller.
+
+![mvc](../assets/mvc.png)
+
+- **Model**: Responsible for the application's data and business logic. Directly manages data, logic, and rules. Interacts with the database to handle data storage and retrieval.
+- **View**: Responsible for data display and the user interface. Directly interacts with the user, presenting data and receiving user input. Updates the display to reflect the latest state of the model.
+- **Controller**: Responsible for processing user input and requests. Receives input from the view, processes it, and updates the model or view. Acts as an intermediary between the model and view, orchestrating their interaction.
+
+Since we have separated the front-end and back-end, the `View` layer is actually handled by the front-end. We only need to focus on the `Controller` and `Model` layers. It should be noted that `MVC` is just a design concept, and there is no need to delve too deeply into it.

i18n/en/docusaurus-plugin-content-docs/current/course/starbook/第一章-基础信息/1.3.写作约定.md

@@ -0,0 +1,35 @@
+---
+title: '1.3.Writing Conventions'
+hide_title: true
+slug: '/course/starbook/about-convention'
+keywords: [command line, GoFrame, GoFrame framework, code omission, output command, terminal, prompt, clean code, program example, Go language]
+description: "This book uses the command line in some parts, with the dollar symbol as a prompt. It outputs information to the terminal, omitting unnecessary code to maintain cleanliness. Examples show how to perform basic output operations and code writing techniques using the GoFrame framework."
+---
+## Command Line
+---
+This book will use the command line in some places. I will use the `$` symbol as a prompt, and you do not need to type this symbol. For example, if I write `$ echo "Hello, GoFrame!"`, you only need to type `echo "Hello, GoFrame!"`.
+
+```bash
+$ echo "Hello, GoFrame!"
+Hello, GoFrame!
+```
+
+`echo` is an output command, which outputs `Hello, GoFrame!` to the terminal.
+
+## Code Omission
+---
+To maintain neatness, I will use `...` to omit code in unnecessary vertical code blocks.
+
+```go
+package main
+
+import "fmt"
+
+...
+
+func main() {
+    fmt.Println("Hello GoFrame")
+}
+
+...
+```

i18n/en/docusaurus-plugin-content-docs/current/course/starbook/第一章-基础信息/1.4.环境准备.md

@@ -0,0 +1,155 @@
+---
+title: '1.4 Environment Preparation'
+hide_title: true
+slug: '/course/starbook/about-environment'
+keywords: [GoFrame,Go,MySQL,Database,API Testing,Postman,Project Initialization,Project Directory,GF CLI,IDEA Plugin]
+description: "GoFrame is a web backend framework based on the Go language, requiring Go version 1.20 or above. The project development needs database support, and the examples use MySQL, which is compatible with various databases such as MariaDB and TiDB. It is recommended to use Postman or other tools for API testing. This document also introduces the GF CLI installation and project initialization process, providing a detailed explanation of the project directory structure."
+---
+## Basic Environment
+---
+### Go Environment
+`GoFrame` is a web backend framework based on the `Go` language. First, we need a `Go` development environment to proceed with further learning. Ensure that your `Go` version is above `1.20`.
+```bash
+$ go version
+go version go1.22.2 windows/amd64
+```
+
+### Database
+During software usage, numerous data are generated and eventually need to be stored in a database. You need to prepare a database, and this book uses `MySQL` as an example, with the database name of the sample project being `star`.
+
+Besides `MySQL`, `GoFrame` also supports various databases like `MariaDB`, `TiDB`, `PostgreSQL`, `SQL Server`, `SQLite`, `Oracle`, `ClickHouse`, and `DM`. A simple modification of configurations and the introduction of related drivers are enough, which will be explained in detail during usage.
+
+### API Testing Tools
+After the development of APIs, I use the `curl` command to test if the APIs meet expectations. However, command-line testing can be inconvenient, so it is recommended to prepare an API testing tool to transform `curl` commands into tests within the tool. Popular testing tools like `Postman`, `Apifox`, and `Apipost` have similar functionalities, allowing you to choose based on personal preference.
+
+## Install GF CLI Tool
+---
+The `GoFrame` framework offers powerful development assistance tools, which are an essential part of the framework. These tools help with project creation, code generation, project running, etc. The latest version of `GF CLI` can be installed with the following command:
+```bash
+$ go install github.com/gogf/gf/cmd/gf/v2@latest
+```
+
+After this, run the following command to check if the installation was successful:
+```bash
+$ gf version
+v2.8.0
+Welcome to GoFrame!
+Env Detail:
+  Go Version: go1.22.2 windows/amd64
+  GF Version(go.mod): cannot find go.mod
+...
+```
+
+> The development environment used in this book is `Go 1.22.2` and `GoFrame v2.8.0`. Even if your versions differ, there's no need to worry as `Go` and `GoFrame` boast strong backward compatibility.
+
+### Unable to Access Github
+Due to network issues within China, accessing `Github` might fail, a common problem for domestic programmers. You can look for a usable `Github` mirror or use other proxy tools online to resolve this issue.
+
+## Project Initialization
+---
+Once the environment is ready, we can officially initialize the project. Find the directory where you want to store your program and execute the following command:
+```bash
+$ gf init star
+initializing...
+initialization done!
+you can now run "cd star && gf run main.go" to start your journey, enjoy!
+```
+
+`star` is the project name, meaning StarBook in English, but you can choose any name you prefer. Next, enter the directory and run the project.
+
+```bash
+$ cd star && gf run main.go
+build: .\main.go
+go build -o .\main.exe  .\main.go
+.\main.exe 
+build running pid: 13628
+2024-11-06 16:45:46.015 [INFO] pid[13628]: http server started listening on [:8000]
+2024-11-06 16:45:46.015 [INFO] {4c9b7c33a654051860769a5fdef82a84} swagger ui is serving at address: http://127.0.0.1:8000/swagger/
+2024-11-06 16:45:46.015 [INFO] {4c9b7c33a654051860769a5fdef82a84} openapi specification is serving at address: http://127.0.0.1:8000/api.json
+
+  ADDRESS | METHOD |   ROUTE    |                        HANDLER                        |           MIDDLEWARE
+----------|--------|------------|-------------------------------------------------------|----------------------------------
+  :8000   | ALL    | /api.json  | github.com/gogf/gf/v2/net/ghttp.(*Server).openapiSpec |
+----------|--------|------------|-------------------------------------------------------|----------------------------------
+  :8000   | GET    | /hello     | star/internal/controller/hello.(*ControllerV1).Hello  | ghttp.MiddlewareHandlerResponse
+----------|--------|------------|-------------------------------------------------------|----------------------------------
+  :8000   | ALL    | /swagger/* | github.com/gogf/gf/v2/net/ghttp.(*Server).swaggerUI   | HOOK_BEFORE_SERVE
+----------|--------|------------|-------------------------------------------------------|----------------------------------
+```
+As the demonstration uses a `Windows` system, a `main.exe` file is generated. If you're using a `Mac/Linux` system, a `main` file is generated.
+
+Then enter [http://127.0.0.1:8000/hello](http://127.0.0.1:8000/hello) in the browser or access it using an API testing tool. Seeing `Hello, GoFrame!` indicates that you have successfully launched a `GoFrame` project. Congratulations on taking the first step into great programming!
+
+> If you are using the `IntelliJ IDEA` or `GoLand` editor, you can install the [GoFrame Helper](https://plugins.jetbrains.com/plugin/23324-goframe-helper) plugin for better code suggestions and auto-completion features.
+
+### Upgrade Project
+The default installed `GoFrame` may not be the latest version; you can upgrade in the project directory using the `up` command:
+```bash
+$ gf up
+```
+
+## Project Directory Structure
+---
+After initializing the project, let's look at the project's directory structure:
+
+| Directory/File Name                                       | Type       | Description                                                                   |
+| -------------------------------------------------------- | --------- | ---------------------------------------------------------------------------- |
+| `api`                                                    | API       | Definition of input/output data structures for providing external services. Due to version management needs, it often exists as `api/xxx/v1...`.           |
+| `hack`                                                   | Tools     | Directory for project development tools and scripts, such as CLI tool configurations, various shell/bat scripts, etc.       |
+| `internal`                                               | Logic     | Directory for business logic. It hides visibility from the outside using Golang’s `internal` feature.                |
+|     `cmd`                            | Commands  | Command-line management directory, can manage and maintain multiple command lines.     |
+|     `consts`                         | Constants | Directory for all project constants.                                                  |
+|     `controller`                     | Controller | Layer for receiving/parsing user input parameters, the entrance/interface layer.         |
+|     `dao`                            | Data Access | Data Access Objects, an abstraction layer for interacting with the underlying database and only includes the most basic CRUD methods. |
+|     `logic`                          | Logic     | Management and encapsulation of business logic, often the most complex part of the project.   |
+|     `model`                          | Model     | Data structure management module, managing data entities, and input/output data structure definitions.  |
+|         `do`     | Domain Objects | Models for converting between business models and instance models within DAO operations. Maintained by tools, not editable by users.  |
+|         `entity` | Entity    | Data models represent a one-to-one relationship between a model and a data set. Maintained by tools, not editable by users.  |
+|     `service`                        | Service   | Interface definition layer for business module decoupling. Specific interface implementations are injected in logic.  |
+| `manifest`                                               | Manifest  | Includes files for compiling, deploying, running, and configuring the program. Common contents include: |
+|     `config`                         | Config    | Directory for storing configuration files.                                             |
+|     `docker`                         | Docker    | Files related to Docker images, such as dependence files, and script files.                   |
+|     `deploy`                         | Deploy    | Files related to deployment. By default, Kubernetes’ yaml templates for cluster deployment managed by kustomize are provided. |
+|     `protobuf`                       | Protobuf  | Protobuf protocol definition files used in GRPC protocol, compiled into go files in the api directory.          |
+| `resource`                                               | Resource  | Static resources files. These files can often be injected into published files through resource packaging/image compilation. |
+| `go.mod`                                                 | Dependency Management | Description file for dependency management, using Go Module package management.          |
+| `main.go`                                                | Entry File | Program entry file.                                                      |
+
+It may seem confusing at first, but don't worry, the important directories will be used gradually later.
+
+Now, let's delete all initial sample files, leaving a blank environment for subsequent development. Press `CTRL+C` to terminate project operation and delete all files in the following directories:
+```text
+api/*
+internal/controller/*
+```
+
+Edit the `cmd` file to remove unnecessary code.
+
+*internal/cmd/cmd.go*
+```go
+package cmd
+
+import (
+    "context"
+
+    "github.com/gogf/gf/v2/frame/g"
+    "github.com/gogf/gf/v2/net/ghttp"
+    "github.com/gogf/gf/v2/os/gcmd"
+)
+
+var (
+    Main = gcmd.Command{
+        Name:  "main",
+        Usage: "main",
+        Brief: "start http server",
+        Func: func(ctx context.Context, parser *gcmd.Parser) (err error) {
+            s := g.Server()
+            s.Group("/", func(group *ghttp.RouterGroup) {
+                group.Middleware(ghttp.MiddlewareHandlerResponse)
+            })
+            s.Run()
+            return nil
+        },
+    }
+)
+```