mirror of
https://gitea.com/gitea/docs.git
synced 2026-07-22 02:37:42 +00:00
Update zh tw languages and fix some broken links (#455)
--------- Co-authored-by: silverwind <me@silverwind.io> Co-authored-by: silverwind <2021+silverwind@noreply.gitea.com> Reviewed-on: https://gitea.com/gitea/docs/pulls/455 Reviewed-by: silverwind <2021+silverwind@noreply.gitea.com>
This commit is contained in:
Lunny Xiao
@@ -28,9 +28,9 @@ Gitea 使用 Golang 作為後端程式語言。它使用了許多第三方套件
|
||||
- `models`: 包含由 xorm 用來構建資料庫表格的資料結構。它也包含查詢和更新資料庫的函數。應避免依賴其他 Gitea 程式碼。可以在某些情況下例外，例如記錄。
|
||||
- `models/db`: 基本的資料庫操作。所有其他 `models/xxx` 套件應依賴此套件。`GetEngine` 函數應僅從 `models/` 調用。
|
||||
- `models/fixtures`: 單元測試和整合測試中使用的樣本資料。一個 `yml` 文件代表一個表格，測試開始時會將其載入資料庫。
|
||||
- `models/migrations`: 存儲版本之間的資料庫遷移。更改資料庫結構的 PR **必須** 也有遷移步驟。
|
||||
- `models/migrations`: 儲存版本之間的資料庫遷移。更改資料庫結構的 PR **必須** 也有遷移步驟。
|
||||
- `modules`: 處理 Gitea 中特定功能的不同模組。進行中：其中一些應移動到 `services`，特別是那些依賴於 models 的，因為它們依賴於資料庫。
|
||||
- `modules/setting`: 存儲從 ini 文件讀取的所有系統配置，並已被各處引用。但應盡可能作為函數參數使用。
|
||||
- `modules/setting`: 儲存從 ini 文件讀取的所有系統設定，並已被各處引用。但應盡可能作為函數參數使用。
|
||||
- `modules/git`: 與 `Git` 命令行或 Gogit 套件互動的套件。
|
||||
- `public`: 編譯後的前端文件（javascript、圖片、css 等）。
|
||||
- `routers`: 處理伺服器請求。由於它使用其他 Gitea 套件來處理請求，其他套件（models、modules 或 services）不得依賴 routers。
|
||||
@@ -38,12 +38,12 @@ Gitea 使用 Golang 作為後端程式語言。它使用了許多第三方套件
|
||||
- `routers/install` 僅在系統處於安裝模式（INSTALL_LOCK=false）時響應。
|
||||
- `routers/private` 只會被內部子命令調用，特別是 `serv` 和 `hooks`。
|
||||
- `routers/web` 會處理來自網頁瀏覽器或 Git SMART HTTP 協議的 HTTP 請求。
|
||||
- `services`: 支持常見路由操作或命令執行的函數。使用 `models` 和 `modules` 來處理請求。
|
||||
- `services`: 支援常見路由操作或命令執行的函數。使用 `models` 和 `modules` 來處理請求。
|
||||
- `templates`: 用於生成 html 輸出的 Golang 模板。
|
||||
|
||||
### 套件依賴
|
||||
|
||||
由於 Golang 不支持導入循環，我們必須仔細決定套件依賴關係。這些套件之間有一些層次。以下是理想的套件依賴方向。
|
||||
由於 Golang 不支援導入循環，我們必須仔細決定套件依賴關係。這些套件之間有一些層次。以下是理想的套件依賴方向。
|
||||
|
||||
`cmd` -> `routers` -> `services` -> `models` -> `modules`
|
||||
|
||||
@@ -52,7 +52,7 @@ Gitea 使用 Golang 作為後端程式語言。它使用了許多第三方套件
|
||||
:::warning
|
||||
為什麼我們需要在 `models` 之外的資料庫交易？以及如何實現？
|
||||
某些操作應允許在資料庫記錄插入/更新/刪除失敗時回滾。
|
||||
因此，services 必須允許創建資料庫交易。這裡有一些例子，
|
||||
因此，services 必須允許建立資料庫交易。這裡有一些例子，
|
||||
|
||||
```go
|
||||
// services/repository/repository.go
|
||||
@@ -112,6 +112,6 @@ func UpdateIssue(ctx context.Context, repoID int64) error {
|
||||
|
||||
目前，我們正在進行一些重構，以完成以下事情：
|
||||
|
||||
- 修正不符合規則的代碼。
|
||||
- 修正不符合規則的程式碼。
|
||||
- `models` 中的文件太多了，所以我們正在將其中一些移動到子套件 `models/xxx`。
|
||||
- 一些 `modules` 子套件應移動到 `services`，因為它們依賴於 `models`。
|
||||
|
||||
@@ -18,7 +18,7 @@ HTML 頁面由 [Go HTML Template](https://pkg.go.dev/html/template) 渲染。
|
||||
|
||||
- **CSS 樣式：** `web_src/css/`
|
||||
- **JavaScript 文件：** `web_src/js/`
|
||||
- **Vue 組件：** `web_src/js/components/`
|
||||
- **Vue 元件：** `web_src/js/components/`
|
||||
- **Go HTML 模板：** `templates/`
|
||||
|
||||
## 一般指南
|
||||
@@ -27,19 +27,19 @@ HTML 頁面由 [Go HTML Template](https://pkg.go.dev/html/template) 渲染。
|
||||
|
||||
### Gitea 特定指南
|
||||
|
||||
1. 每個功能（Fomantic-UI/jQuery 模塊）應該放在單獨的文件/目錄中。
|
||||
1. 每個功能（Fomantic-UI/jQuery 模組）應該放在單獨的文件/目錄中。
|
||||
2. HTML id 和 class 應該使用 kebab-case，最好包含 2-3 個與功能相關的關鍵詞。
|
||||
3. 在 JavaScript 中使用的 HTML id 和 class 應該在整個項目中是唯一的，並且應該包含 2-3 個與功能相關的關鍵詞。我們建議對僅在 JavaScript 中使用的 class 使用 `js-` 前綴。
|
||||
3. 在 JavaScript 中使用的 HTML id 和 class 應該在整個專案中是唯一的，並且應該包含 2-3 個與功能相關的關鍵詞。我們建議對僅在 JavaScript 中使用的 class 使用 `js-` 前綴。
|
||||
4. 不應覆蓋框架提供的 class 的 CSS 樣式。始終使用包含 2-3 個與功能相關的關鍵詞的新 class 名稱來覆蓋框架樣式。Gitea 的 `helpers.less` 中的輔助 CSS class 可能會有所幫助。
|
||||
5. 後端可以使用 `ctx.PageData["myModuleData"] = map[]{}` 將複雜數據傳遞給前端，但不要將整個模型暴露給前端，以避免洩露敏感數據。
|
||||
5. 後端可以使用 `ctx.PageData["myModuleData"] = map[]{}` 將複雜資料傳遞給前端，但不要將整個模型暴露給前端，以避免洩露敏感資料。
|
||||
6. 簡單頁面和與 SEO 相關的頁面使用 Go HTML Template 渲染生成靜態 Fomantic-UI HTML 輸出。複雜頁面可以使用 Vue3。
|
||||
7. 明確變量類型，優先使用 `elem.disabled = true` 而不是 `elem.setAttribute('disabled', 'anything')`，優先使用 `$el.prop('checked', var === 'yes')` 而不是 `$el.prop('checked', var)`。
|
||||
8. 使用語義化元素，優先使用 `<button class="ui button">` 而不是 `<div class="ui button">`。
|
||||
9. 避免在 CSS 中不必要的 `!important`，如果無法避免，請添加註釋解釋為什麼是必要的。
|
||||
10. 避免在一個事件監聽器中混合不同的事件，優先為每個事件使用單獨的事件監聽器。
|
||||
11. 自定義事件名稱建議使用 `ce-` 前綴。
|
||||
11. 自訂事件名稱建議使用 `ce-` 前綴。
|
||||
12. 優先使用 Tailwind CSS，通過 `tw-` 前綴可用，例如 `tw-relative`。Gitea 的輔助 CSS class 使用 `gt-` 前綴（`gt-ellipsis`），而 Gitea 自己的私有框架級 CSS class 使用 `g-` 前綴（`g-modal-confirm`）。
|
||||
13. 盡可能避免內聯腳本和樣式，建議將 JS 代碼放入 JS 文件並使用 CSS class。如果內聯腳本和樣式是不可避免的，請解釋為什麼無法避免。
|
||||
13. 盡可能避免內聯腳本和樣式，建議將 JS 程式碼放入 JS 文件並使用 CSS class。如果內聯腳本和樣式是不可避免的，請解釋為什麼無法避免。
|
||||
|
||||
### 無障礙 / ARIA
|
||||
|
||||
@@ -49,34 +49,34 @@ Gitea 使用一些補丁使 Fomantic UI 更加無障礙（見 `aria.md` 和相
|
||||
|
||||
### 框架使用
|
||||
|
||||
不建議混合使用不同的框架，這會使代碼難以維護。
|
||||
JavaScript 模塊應該遵循一個主要框架並遵循該框架的最佳實踐。
|
||||
不建議混合使用不同的框架，這會使程式碼難以維護。
|
||||
JavaScript 模組應該遵循一個主要框架並遵循該框架的最佳實踐。
|
||||
|
||||
推薦的實現：
|
||||
|
||||
- Vue + 原生 JS
|
||||
- Fomantic-UI (jQuery)
|
||||
- htmx（部分頁面重新加載，適用於靜態組件）
|
||||
- htmx（部分頁面重新加載，適用於靜態元件）
|
||||
- 原生 JS
|
||||
|
||||
不推薦的實現：
|
||||
|
||||
- Vue + Fomantic-UI (jQuery)
|
||||
- jQuery + 原生 JS
|
||||
- htmx + 任何需要大量 JS 代碼的框架，或不必要的功能如 htmx 腳本（`hx-on`）
|
||||
- htmx + 任何需要大量 JS 程式碼的框架，或不必要的功能如 htmx 腳本（`hx-on`）
|
||||
|
||||
為了使 UI 一致，Vue 組件可以使用 Fomantic-UI CSS class。
|
||||
我們使用 htmx 進行簡單的交互。你可以在這個 [PR](https://github.com/go-gitea/gitea/pull/28908) 中看到一個使用 htmx 進行簡單交互的示例。如果你需要更高級的反應性，請使用其他框架（Vue/原生 JS）。
|
||||
為了使 UI 一致，Vue 元件可以使用 Fomantic-UI CSS class。
|
||||
我們使用 htmx 進行簡單的交互。你可以在這個 [PR](https://github.com/go-gitea/gitea/pull/28908) 中看到一個使用 htmx 進行簡單交互的範例。如果你需要更高級的反應性，請使用其他框架（Vue/原生 JS）。
|
||||
雖然不建議混合使用不同的框架，
|
||||
但如果混合是必要的並且代碼設計良好且可維護，應該也是可行的。
|
||||
但如果混合是必要的並且程式碼設計良好且可維護，應該也是可行的。
|
||||
|
||||
### Typescript
|
||||
|
||||
Gitea 正在遷移到類型安全的 Typescript。以下是一些關於 Typescript 在代碼庫中的具體指南：
|
||||
Gitea 正在遷移到類型安全的 Typescript。以下是一些關於 Typescript 在程式碼庫中的具體指南：
|
||||
|
||||
#### 使用類型別名而不是接口
|
||||
#### 使用類型別名而不是介面
|
||||
|
||||
優先使用類型別名，因為它們可以表示任何類型，並且通常比接口更靈活。
|
||||
優先使用類型別名，因為它們可以表示任何類型，並且通常比介面更靈活。
|
||||
|
||||
#### 使用單獨的類型導入
|
||||
|
||||
@@ -91,7 +91,7 @@ Gitea 正在遷移到類型安全的 Typescript。以下是一些關於 Typescri
|
||||
只有在函數內部有 `await` 調用或返回 `Promise` 時，才將函數標記為 `async`。
|
||||
|
||||
不建議使用 `async` 事件監聽器，這可能會導致問題。
|
||||
原因是 `await` 之後的代碼在事件分派之外執行。
|
||||
原因是 `await` 之後的程式碼在事件分派之外執行。
|
||||
參考：https://github.com/github/eslint-plugin-github/blob/main/docs/rules/async-preventdefault.md
|
||||
|
||||
如果事件監聽器必須是 `async`，則 `e.preventDefault()` 應在任何 `await` 之前，
|
||||
@@ -102,29 +102,29 @@ Gitea 正在遷移到類型安全的 Typescript。以下是一些關於 Typescri
|
||||
這是故意這樣做的，我們想調用 `async` 函數並忽略 Promise。
|
||||
一些 lint 規則和 IDE 也會在未處理返回的 Promise 時發出警告。
|
||||
|
||||
### 獲取數據
|
||||
### 獲取資料
|
||||
|
||||
要獲取數據，請使用 `modules/fetch.js` 中的包裝函數 `GET`、`POST` 等。
|
||||
它們接受一個 `data` 選項作為內容，會自動設置 CSRF 令牌並返回一個 [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) 的 Promise。
|
||||
要獲取資料，請使用 `modules/fetch.js` 中的包裝函數 `GET`、`POST` 等。
|
||||
它們接受一個 `data` 選項作為內容，會自動設定 CSRF 令牌並返回一個 [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) 的 Promise。
|
||||
|
||||
### HTML 屬性和 `dataset`
|
||||
|
||||
禁止使用 `dataset`，其駝峰命名行為使得很難 grep 屬性。
|
||||
然而，仍然存在一些特殊情況，所以目前的指南是：
|
||||
|
||||
- 對於遺留代碼：
|
||||
- 對於遺留程式碼：
|
||||
|
||||
- `$.data()` 應重構為 `$.attr()`。
|
||||
- `$.data()` 可以在罕見情況下用於將一些非字符串數據綁定到元素，但這是高度不建議的。
|
||||
- `$.data()` 可以在罕見情況下用於將一些非字符串資料綁定到元素，但這是高度不建議的。
|
||||
|
||||
- 對於新代碼：
|
||||
- 對於新程式碼：
|
||||
- 不應使用 `node.dataset`，應使用 `node.getAttribute`。
|
||||
- 永遠不要將任何用戶數據綁定到 DOM 節點，應使用合適的設計模式來描述節點和數據之間的關係。
|
||||
- 永遠不要將任何使用者資料綁定到 DOM 節點，應使用合適的設計模式來描述節點和資料之間的關係。
|
||||
|
||||
### 顯示/隱藏元素
|
||||
|
||||
- Vue 組件建議使用 `v-if` 和 `v-show` 來顯示/隱藏元素。
|
||||
- Go 模板代碼應使用 `.tw-hidden` 和 `showElem()/hideElem()/toggleElem()`，詳情見 `.tw-hidden` 的註釋。
|
||||
- Vue 元件建議使用 `v-if` 和 `v-show` 來顯示/隱藏元素。
|
||||
- Go 模板程式碼應使用 `.tw-hidden` 和 `showElem()/hideElem()/toggleElem()`，詳情見 `.tw-hidden` 的註釋。
|
||||
|
||||
### Go HTML 模板中的樣式和屬性
|
||||
|
||||
@@ -149,16 +149,16 @@ Gitea 正在遷移到類型安全的 Typescript。以下是一些關於 Typescri
|
||||
></div>
|
||||
```
|
||||
|
||||
以使代碼更具可讀性。
|
||||
以使程式碼更具可讀性。
|
||||
|
||||
### 遺留代碼
|
||||
### 遺留程式碼
|
||||
|
||||
在撰寫本文檔之前，已經存在許多遺留代碼。建議重構遺留代碼以遵循這些指南。
|
||||
在撰寫本文件之前，已經存在許多遺留程式碼。建議重構遺留程式碼以遵循這些指南。
|
||||
|
||||
### Vue3 和 JSX
|
||||
|
||||
Gitea 現在使用 Vue3。我們決定不引入 JSX，以保持 HTML 和 JavaScript 代碼分離。
|
||||
Gitea 現在使用 Vue3。我們決定不引入 JSX，以保持 HTML 和 JavaScript 程式碼分離。
|
||||
|
||||
### UI 示例
|
||||
### UI 範例
|
||||
|
||||
Gitea 使用一些自製的 UI 元素並自定義其他元素，以更好地將它們集成到整體 UI 方法中。當 Gitea 在開發模式下運行時（`RUN_MODE=dev`），可以在 `http(s)://your-gitea-url:port/devtest` 下訪問一些標準化的 UI 示例頁面。
|
||||
Gitea 使用一些自製的 UI 元素並自訂其他元素，以更好地將它們整合到整體 UI 方法中。當 Gitea 在開發模式下運行時（`RUN_MODE=dev`），可以在 `http(s)://your-gitea-url:port/devtest` 下訪問一些標準化的 UI 範例頁面。
|
||||
|
||||
@@ -10,12 +10,12 @@ aliases:
|
||||
|
||||
## 背景
|
||||
|
||||
自 2014 年 2 月 12 日編寫第一行代碼以來，Gitea 已經成長為一個大型項目。
|
||||
因此，代碼庫變得越來越大。代碼庫越大，維護起來就越困難。
|
||||
存在許多過時的機制，許多框架混合在一起，一些遺留代碼可能會導致錯誤並阻礙新功能。
|
||||
為了使代碼庫更易於維護並使 Gitea 更好，開發人員應牢記使用現代機制來重構舊代碼。
|
||||
自 2014 年 2 月 12 日編寫第一行程式碼以來，Gitea 已經成長為一個大型專案。
|
||||
因此，程式碼庫變得越來越大。程式碼庫越大，維護起來就越困難。
|
||||
存在許多過時的機制，許多框架混合在一起，一些遺留程式碼可能會導致錯誤並阻礙新功能。
|
||||
為了使程式碼庫更易於維護並使 Gitea 更好，開發人員應牢記使用現代機制來重構舊程式碼。
|
||||
|
||||
本文檔是重構代碼庫的指南集合。
|
||||
本文件是重構程式碼庫的指南集合。
|
||||
|
||||
## 重構建議
|
||||
|
||||
|
||||
@@ -8,18 +8,18 @@ aliases:
|
||||
|
||||
# 本地化
|
||||
|
||||
Gitea 的本地化通過我們的 [Crowdin 項目](https://crowdin.com/project/gitea) 進行。
|
||||
Gitea 的本地化通過我們的 [Crowdin 專案](https://crowdin.com/project/gitea) 進行。
|
||||
|
||||
對 **英文** 翻譯的更改，可以通過拉取請求更改
|
||||
對 **英文** 翻譯的更改，可以透過拉取請求更改
|
||||
[英文語言文件](https://github.com/go-gitea/gitea/blob/main/options/locale/locale_en-US.ini) 中的相應鍵。
|
||||
|
||||
對 **非英文** 翻譯的更改，請參考上面的 Crowdin 項目。
|
||||
對 **非英文** 翻譯的更改，請參考上面的 Crowdin 專案。
|
||||
|
||||
## 支持的語言
|
||||
## 支援的語言
|
||||
|
||||
只要翻譯完成度達到 25% 或以上，Crowdin 項目中列出的任何語言都將被支持。
|
||||
只要翻譯完成度達到 25% 或以上，Crowdin 專案中列出的任何語言都將被支援。
|
||||
|
||||
翻譯被接受後，將在下一次 Crowdin 同步後反映在主存儲庫中，通常是在任何 PR 合併後。
|
||||
翻譯被接受後，將在下一次 Crowdin 同步後反映在主儲存庫中，通常是在任何 PR 合併後。
|
||||
|
||||
在撰寫本文時，這意味著更改的翻譯可能不會出現在隨後的 Gitea 發布之前。
|
||||
|
||||
@@ -27,4 +27,4 @@ Gitea 的本地化通過我們的 [Crowdin 項目](https://crowdin.com/project/g
|
||||
|
||||
## 如何貢獻
|
||||
|
||||
不同語言有不同的翻譯指南。請訪問相應的頁面以獲取更多信息。
|
||||
不同語言有不同的翻譯指南。請前往相應的頁面以獲取更多資訊。
|
||||
|
||||
Reference in New Issue
Block a user