docs: add zh-tw folder (#195)

Signed-off-by: appleboy <[email protected]>
Reviewed-on: https://gitea.com/gitea/docs/pulls/195
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: appleboy <[email protected]>
Co-committed-by: appleboy <[email protected]>

i18n/zh-tw/docusaurus-plugin-content-docs/version-1.23/contributing/guidelines-backend.md

@@ -0,0 +1,150 @@
+---
+date: "2021-11-01T23:41:00+08:00"
+slug: "guidelines-backend"
+sidebar_position: 20
+aliases:
+  - /zh-tw/guidelines-backend
+---
+
+# 後端開發指南
+
+## 背景
+
+Gitea 使用 Golang 作為後端編程語言。它使用了許多第三方包，也自己編寫了一些包。
+例如，Gitea 使用 [Chi](https://github.com/go-chi/chi) 作為基本的 Web 框架。[Xorm](https://xorm.io) 是一個 ORM 框架，用於與數據庫交互。
+因此，管理這些包非常重要。在開始編寫後端代碼之前，請遵循以下指南。
+
+## 包設計指南
+
+### 包列表
+
+為了保持代碼的可理解性並避免循環依賴，擁有良好的代碼結構非常重要。Gitea 後端分為以下幾個部分：
+
+- `build`: 幫助構建 Gitea 的腳本。
+- `cmd`: 所有 Gitea 的實際子命令，包括 web、doctor、serv、hooks、admin 等等。`web` 將啟動 Web 服務。`serv` 和 `hooks` 將由 Git 或 OpenSSH 調用。其他子命令可以幫助維護 Gitea。
+- `tests`: 常見的測試工具函數
+  - `tests/integration`: 集成測試，用於測試後端回歸
+  - `tests/e2e`: 端到端測試，用於測試前端和後端的兼容性和視覺回歸。
+- `models`: 包含由 xorm 用於構建數據庫表的數據結構。它還包含查詢和更新數據庫的函數。應避免依賴其他 Gitea 代碼。可以在某些情況下例外，例如日誌記錄。
+  - `models/db`: 基本的數據庫操作。所有其他 `models/xxx` 包應依賴於此包。`GetEngine` 函數應僅從 `models/` 調用。
+  - `models/fixtures`: 單元測試和集成測試中使用的示
+
+---
+
+date: "2021-11-01T23:41:00+08:00"
+slug: "guidelines-backend"
+sidebar_position: 20
+aliases:
+
+- /zh-tw/guidelines-backend
+
+---
+
+# Guidelines for Backend Development
+
+## Background
+
+Gitea uses Golang as the backend programming language. It uses many third-party packages and also write some itself.
+For example, Gitea uses [Chi](https://github.com/go-chi/chi) as basic web framework. [Xorm](https://xorm.io) is an ORM framework that is used to interact with the database.
+So it's very important to manage these packages. Please take the below guidelines before you start to write backend code.
+
+## Package Design Guideline
+
+### Packages List
+
+To maintain understandable code and avoid circular dependencies it is important to have a good code structure. The Gitea backend is divided into the following parts:
+
+- `build`: Scripts to help build Gitea.
+- `cmd`: All Gitea actual sub commands includes web, doctor, serv, hooks, admin and etc. `web` will start the web service. `serv` and `hooks` will be invoked by Git or OpenSSH. Other sub commands could help to maintain Gitea.
+- `tests`: Common test utility functions
+  - `tests/integration`: Integration tests, to test back-end regressions
+  - `tests/e2e`: E2e tests, to test front-end and back-end compatibility and visual regressions.
+- `models`: Contains the data structures used by xorm to construct database tables. It also contains functions to query and update the database. Dependencies to other Gitea code should be avoided. You can make exceptions in cases such as logging.
+  - `models/db`: Basic database operations. All other `models/xxx` packages should depend on this package. The `GetEngine` function should only be invoked from `models/`.
+  - `models/fixtures`: Sample data used in unit tests and integration tests. One `yml` file means one table which will be loaded into database when beginning the tests.
+  - `models/migrations`: Stores database migrations between versions. PRs that change a database structure **MUST** also have a migration step.
+- `modules`: Different modules to handle specific functionality in Gitea. Work in Progress: Some of them should be moved to `services`, in particular those that depend on models because they rely on the database.
+  - `modules/setting`: Store all system configurations read from ini files and has been referenced by everywhere. But they should be used as function parameters when possible.
+  - `modules/git`: Package to interactive with `Git` command line or Gogit package.
+- `public`: Compiled frontend files (javascript, images, css, etc.)
+- `routers`: Handling of server requests. As it uses other Gitea packages to serve the request, other packages (models, modules or services) must not depend on routers.
+  - `routers/api` Contains routers for `/api/v1` aims to handle RESTful API requests.
+  - `routers/install` Could only respond when system is in INSTALL mode (INSTALL_LOCK=false).
+  - `routers/private` will only be invoked by internal sub commands, especially `serv` and `hooks`.
+  - `routers/web` will handle HTTP requests from web browsers or Git SMART HTTP protocols.
+- `services`: Support functions for common routing operations or command executions. Uses `models` and `modules` to handle the requests.
+- `templates`: Golang templates for generating the html output.
+
+### Package Dependencies
+
+Since Golang doesn't support import cycles, we have to decide the package dependencies carefully. There are some levels between those packages. Below is the ideal package dependencies direction.
+
+`cmd` -> `routers` -> `services` -> `models` -> `modules`
+
+From left to right, left packages could depend on right packages, but right packages MUST not depend on left packages. The sub packages on the same level could depend on according this level's rules.
+
+:::warning
+Why do we need database transactions outside of `models`? And how?
+Some actions should allow for rollback when database record insertion/update/deletion failed.
+So services must be allowed to create a database transaction. Here is some example,
+
+```go
+// services/repository/repository.go
+func CreateXXXX() error {
+    return db.WithTx(func(ctx context.Context) error {
+        // do something, if err is returned, it will rollback automatically
+        if err := issues.UpdateIssue(ctx, repoID); err != nil {
+            // ...
+            return err
+        }
+        // ...
+        return nil
+    })
+}
+```
+
+You should **not** use `db.GetEngine(ctx)` in `services` directly, but just write a function under `models/`.
+If the function will be used in the transaction, just let `context.Context` as the function's first parameter.
+
+```go
+// models/issues/issue.go
+func UpdateIssue(ctx context.Context, repoID int64) error {
+    e := db.GetEngine(ctx)
+
+    // ...
+}
+```
+
+:::
+
+### Package Name
+
+For the top level package, use a plural as package name, i.e. `services`, `models`, for sub packages, use singular,
+i.e. `services/user`, `models/repository`.
+
+### Import Alias
+
+Since there are some packages which use the same package name, it is possible that you find packages like `modules/user`, `models/user`, and `services/user`. When these packages are imported in one Go file, it's difficult to know which package we are using and if it's a variable name or an import name. So, we always recommend to use import aliases. To differ from package variables which are commonly in camelCase, just use **snake_case** for import aliases.
+i.e. `import user_service "code.gitea.io/gitea/services/user"`
+
+### Implementing `io.Closer`
+
+If a type implements `io.Closer`, calling `Close` multiple times must not fail or `panic` but return an error or `nil`.
+
+### Important Gotchas
+
+- Never write `x.Update(exemplar)` without an explicit `WHERE` clause:
+  - This will cause all rows in the table to be updated with the non-zero values of the exemplar - including IDs.
+  - You should usually write `x.ID(id).Update(exemplar)`.
+- If during a migration you are inserting into a table using `x.Insert(exemplar)` where the ID is preset:
+  - You will need to `` SET IDENTITY_INSERT `table` ON `` for the MSSQL variant (the migration will fail otherwise)
+  - However, you will also need to update the id sequence for postgres - the migration will silently pass here but later insertions will fail:
+    `` SELECT setval('table_name_id_seq', COALESCE((SELECT MAX(id)+1 FROM `table_name`), 1), false) ``
+
+### Future Tasks
+
+Currently, we are creating some refactors to do the following things:
+
+- Correct that codes which doesn't follow the rules.
+- There are too many files in `models`, so we are moving some of them into a sub package `models/xxx`.
+- Some `modules` sub packages should be moved to `services` because they depend on `models`.

i18n/zh-tw/docusaurus-plugin-content-docs/version-1.23/contributing/guidelines-frontend.md

@@ -0,0 +1,166 @@
+---
+date: "2021-10-13T16:00:00+02:00"
+slug: "guidelines-frontend"
+sidebar_position: 30
+aliases:
+  - /zh-tw/guidelines-frontend
+---
+
+# Guidelines for Frontend Development
+
+## Background
+
+Gitea uses [Fomantic-UI](https://fomantic-ui.com/introduction/getting-started.html) (based on [jQuery](https://api.jquery.com)) and [Vue3](https://vuejs.org/) for its frontend.
+
+The HTML pages are rendered by [Go HTML Template](https://pkg.go.dev/html/template).
+
+The source files can be found in the following directories:
+
+- **CSS styles:** `web_src/css/`
+- **JavaScript files:** `web_src/js/`
+- **Vue components:** `web_src/js/components/`
+- **Go HTML templates:** `templates/`
+
+## General Guidelines
+
+We recommend [Google HTML/CSS Style Guide](https://google.github.io/styleguide/htmlcssguide.html) and [Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html)
+
+### Gitea specific guidelines
+
+1. Every feature (Fomantic-UI/jQuery module) should be put in separate files/directories.
+2. HTML ids and classes should use kebab-case, it's preferred to contain 2-3 feature related keywords.
+3. HTML ids and classes used in JavaScript should be unique for the whole project, and should contain 2-3 feature related keywords. We recommend to use the `js-` prefix for classes that are only used in JavaScript.
+4. CSS styling for classes provided by frameworks should not be overwritten. Always use new class names with 2-3 feature related keywords to overwrite framework styles. Gitea's helper CSS classes in `helpers.less` could be helpful.
+5. The backend can pass complex data to the frontend by using `ctx.PageData["myModuleData"] = map[]{}`, but do not expose whole models to the frontend to avoid leaking sensitive data.
+6. Simple pages and SEO-related pages use Go HTML Template render to generate static Fomantic-UI HTML output. Complex pages can use Vue3.
+7. Clarify variable types, prefer `elem.disabled = true` instead of `elem.setAttribute('disabled', 'anything')`, prefer `$el.prop('checked', var === 'yes')` instead of `$el.prop('checked', var)`.
+8. Use semantic elements, prefer `<button class="ui button">` instead of `<div class="ui button">`.
+9. Avoid unnecessary `!important` in CSS, add comments to explain why it's necessary if it can't be avoided.
+10. Avoid mixing different events in one event listener, prefer to use individual event listeners for every event.
+11. Custom event names are recommended to use `ce-` prefix.
+12. Prefer using Tailwind CSS which is available via `tw-` prefix, e.g. `tw-relative`. Gitea's helper CSS classes use `gt-` prefix (`gt-ellipsis`), while Gitea's own private framework-level CSS classes use `g-` prefix (`g-modal-confirm`).
+13. Avoid inline scripts & styles as much as possible, it's recommended to put JS code into JS files and use CSS classes. If inline scripts & styles are unavoidable, explain the reason why it can't be avoided.
+
+### Accessibility / ARIA
+
+In history, Gitea heavily uses Fomantic UI which is not an accessibility-friendly framework.
+Gitea uses some patches to make Fomantic UI more accessible (see `aria.md` and related JS files),
+but there are still many problems which need a lot of work and time to fix.
+
+### Framework Usage
+
+Mixing different frameworks together is discouraged, it makes the code difficult to be maintained.
+A JavaScript module should follow one major framework and follow the framework's best practice.
+
+Recommended implementations:
+
+- Vue + Vanilla JS
+- Fomantic-UI (jQuery)
+- htmx (partial page reloads for otherwise static components)
+- Vanilla JS
+
+Discouraged implementations:
+
+- Vue + Fomantic-UI (jQuery)
+- jQuery + Vanilla JS
+- htmx + any other framework which requires heavy JS code, or unnecessary features like htmx scripting (`hx-on`)
+
+To make UI consistent, Vue components can use Fomantic-UI CSS classes.
+We use htmx for simple interactions. You can see an example for simple interactions where htmx should be used in this [PR](https://github.com/go-gitea/gitea/pull/28908). Do not use htmx if you require more advanced reactivity, use another framework (Vue/Vanilla JS).
+Although mixing different frameworks is discouraged,
+it should also work if the mixing is necessary and the code is well-designed and maintainable.
+
+### Typescript
+
+Gitea is in the process of migrating to type-safe Typescript. Here are some specific guidelines regarding Typescript in the codebase:
+
+#### Use type aliases instead of interfaces
+
+Prefer to use type aliases because they can represent any type and are generally more flexible to use than interfaces.
+
+#### Use separate type imports
+
+We use `verbatimModuleSyntax` so type and non-type imports from the same file must be split into two `import type` statements. This enables the typescript compiler to completely eliminate the type import statements during compilation.
+
+#### Use `@ts-expect-error` instead of `@ts-ignore`
+
+Both annotations should be avoided, but if you have to use them, use `@ts-expect-error` because it will not leave ineffective statements after the issue is fixed.
+
+### `async` Functions
+
+Only mark a function as `async` if and only if there are `await` calls
+or `Promise` returns inside the function.
+
+It's not recommended to use `async` event listeners, which may lead to problems.
+The reason is that the code after await is executed outside the event dispatch.
+Reference: https://github.com/github/eslint-plugin-github/blob/main/docs/rules/async-preventdefault.md
+
+If an event listener must be `async`, the `e.preventDefault()` should be before any `await`,
+it's recommended to put it at the beginning of the function.
+
+If we want to call an `async` function in a non-async context,
+it's recommended to use `const _promise = asyncFoo()` to tell readers
+that this is done by purpose, we want to call the async function and ignore the Promise.
+Some lint rules and IDEs also have warnings if the returned Promise is not handled.
+
+### Fetching data
+
+To fetch data, use the wrapper functions `GET`, `POST` etc. from `modules/fetch.js`. They
+accept a `data` option for the content, will automatically set CSRF token and return a
+Promise for a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response).
+
+### HTML Attributes and `dataset`
+
+The usage of `dataset` is forbidden, its camel-casing behaviour makes it hard to grep for attributes.
+However, there are still some special cases, so the current guideline is:
+
+- For legacy code:
+
+  - `$.data()` should be refactored to `$.attr()`.
+  - `$.data()` can be used to bind some non-string data to elements in rare cases, but it is highly discouraged.
+
+- For new code:
+  - `node.dataset` should not be used, use `node.getAttribute` instead.
+  - never bind any user data to a DOM node, use a suitable design pattern to describe the relation between node and data.
+
+### Show/Hide Elements
+
+- Vue components are recommended to use `v-if` and `v-show` to show/hide elements.
+- Go template code should use `.tw-hidden` and `showElem()/hideElem()/toggleElem()`, see more details in `.tw-hidden`'s comment.
+
+### Styles and Attributes in Go HTML Template
+
+It's recommended to use:
+
+```html
+<div
+  class="gt-name1 gt-name2 {{if .IsFoo}}gt-foo{{end}}"
+  {{if
+  .IsFoo}}data-foo{{end}}
+></div>
+```
+
+instead of:
+
+```html
+<div
+  class="gt-name1 gt-name2{{if .IsFoo}} gt-foo{{end}}"
+  {{if
+  .IsFoo}}
+  data-foo{{end}}
+></div>
+```
+
+to make the code more readable.
+
+### Legacy Code
+
+A lot of legacy code already existed before this document's written. It's recommended to refactor legacy code to follow the guidelines.
+
+### Vue3 and JSX
+
+Gitea is using Vue3 now. We decided not to introduce JSX to keep the HTML and the JavaScript code separated.
+
+### UI Examples
+
+Gitea uses some self-made UI elements and customizes others to integrate them better into the general UI approach. When running Gitea in development mode (`RUN_MODE=dev`), a page with some standardized UI examples is available under `http(s)://your-gitea-url:port/devtest`.

i18n/zh-tw/docusaurus-plugin-content-docs/version-1.23/contributing/guidelines-refactoring.md

@@ -0,0 +1,40 @@
+---
+date: "2023-02-14T00:00:00+00:00"
+slug: "guidelines-refactoring"
+sidebar_position: 40
+aliases:
+  - /zh-tw/guidelines-refactoring
+---
+
+# 重構指南
+
+## 背景
+
+自 2014 年 2 月 12 日編寫第一行代碼以來，Gitea 已經成長為一個大型項目。
+因此，代碼庫變得越來越大。代碼庫越大，維護起來就越困難。
+存在許多過時的機制，許多框架混合在一起，一些遺留代碼可能會導致錯誤並阻礙新功能。
+為了使代碼庫更易於維護並使 Gitea 更好，開發人員應牢記使用現代機制來重構舊代碼。
+
+本文檔是重構代碼庫的指南集合。
+
+## 重構建議
+
+- 更多地考慮未來，而不僅僅解決當前問題。
+- 減少模糊性，減少衝突，提高可維護性。
+- 描述重構，例如：
+  - 為什麼需要重構。
+  - 如何解決遺留問題。
+  - 重構的優缺點。
+- 僅進行必要的更改，盡可能保持舊邏輯。
+- 引入一些中間步驟，使重構更易於審查，完整的重構計劃可以在幾個 PR 中完成。
+- 如果存在分歧，應邀請 TOC（技術監督委員會）幫助做出決定。
+- 添加必要的測試以確保重構正確。
+- 非錯誤重構優先在里程碑的開始進行，這樣在發布之前更容易發現問題。
+
+## 審查和合併建議
+
+- 重構 PR 不應長時間保持打開狀態（通常為 7 天），應盡快審查。
+- 重構 PR 應盡快合併，不應被其他 PR 阻塞。
+- 如果 TOC 沒有異議，重構 PR 可以在 7 天後由一名核心成員批准（非作者）後合併。
+- 容忍一些臟/臨時的中間步驟，如果最終結果是好的。
+- 如果重構是必要的，容忍一些回歸錯誤，並盡快修復錯誤。

i18n/zh-tw/docusaurus-plugin-content-docs/version-1.23/contributing/localization.md

@@ -0,0 +1,30 @@
+---
+date: "2016-12-01T16:00:00+02:00"
+slug: "localization"
+sidebar_position: 70
+aliases:
+  - /zh-tw/localization
+---
+
+# 本地化
+
+Gitea 的本地化通過我們的 [Crowdin 項目](https://crowdin.com/project/gitea) 進行。
+
+對 **英文** 翻譯的更改，可以通過拉取請求更改
+[英文語言文件](https://github.com/go-gitea/gitea/blob/main/options/locale/locale_en-US.ini) 中的相應鍵。
+
+對 **非英文** 翻譯的更改，請參考上面的 Crowdin 項目。
+
+## 支持的語言
+
+只要翻譯完成度達到 25% 或以上，Crowdin 項目中列出的任何語言都將被支持。
+
+翻譯被接受後，將在下一次 Crowdin 同步後反映在主存儲庫中，通常是在任何 PR 合併後。
+
+在撰寫本文時，這意味著更改的翻譯可能不會出現在隨後的 Gitea 發布之前。
+
+如果您使用的是最新的構建，則應在同步更改後的更新中出現。
+
+## 如何貢獻
+
+不同語言有不同的翻譯指南。請訪問相應的頁面以獲取更多信息。