# 為 Weblate 說明文件作出貢獻

歡迎您改進您選擇的文件頁面。透過點選頁面右上角的 在 GitHub 上編輯 按鈕輕鬆完成此操作。

## 說明文件指導原則

請在寫作時尊重這些指導原則：

1. 請勿刪除仍然有效的說明文件內容。
2. 請使用清楚易懂的語言。您撰寫的是技術文件，不是詩作。並非所有讀者都以文件語言為母語，請體貼讀者。
3. 不確定時，請放心提問。若編輯期間必須詢問某項功能，請先取得答案，再變更其說明文件。也就是說：變更或提問，兩者不要同時進行。
4. 請依照說明文件實際執行其中描述的操作，以驗證您的變更。
5. 請將變更分成小批次提交 PR，讓審閱與合併更容易、更快速。
6. 如果要重寫並變更大文章的結構，請分兩步執行以下操作：
   1. 重寫
   2. 內容重寫經過審閱、潤飾及合併後，再於另一個 PR 中變更段落結構。
7. 標題下方與上方裝飾線的長度，必須與標題來源文字的長度一致，包含其中的行內標記。pre-commit 檢查會強制要求長度相符。

## 本機建置說明文件

說明檔案也可以在本機編輯及建置；所需的 Python 套件位於 `pyproject.toml` 的 `docs` 相依套件群組。若已使用完整開發環境，執行 `uv sync --all-extras --dev` 即可；若只處理說明檔案，執行 `uv sync --group docs` 即可。

建議的本機工作流程是：

```sh
make -C docs update-docs
./ci/run-docs
```

**ci/run-docs** 包裝程式會建置說明文件，並將警告視為錯誤。

CI 的文件、版本資訊及連結檢查建置會重複使用已快取的 Intersphinx 索引清單。Intersphinx inventories 工作流程會每天更新這些清單，也可在 GitHub Actions 中從預設分支手動執行。若更新失敗，會保留上次有效的索引清單，並將工作流程回報為失敗。

索引清單存放在 `docs/_build/intersphinx`。若沒有本機副本，建置時會使用上游清單，包括 CI 快取遭清除或新增清單網址的情況。本機與 Read the Docs 建置不需要這份快取。如要更新所有文件語言的本機副本，請執行：

```sh
languages=$(uv run --no-project scripts/list-documentation-languages.py)
uv run python docs/_ext/intersphinx_cache.py --languages "${languages#languages=}"
```

索引清單快取無法省去連結檢查建置時，為了檢查目標頁面而發出的網路請求。

#### HINT
您還需要安裝 **graphviz** 來建置文件。

## 翻譯說明文件

您可以 [翻譯說明文件](https://hosted.weblate.org/projects/weblate/documentation/).

## 更新自動產生的說明文件片段

部分說明文件章節使用由程式碼產生的範本。建議使用下列方式重新產生：

```sh
make -C docs update-docs
```

此目標重新產生文件目前使用的文字片段，包括：

* 附加元件事件、內建附加元件、常見附加元件引數
* 機器翻譯服務
* 檔案格式引數和檔案格式特性表
* 權限和內建角色
* 檢查和檢查標記

請將人工維護的文字保留在上層說明檔案頁面，不要加入自動產生的片段。例如，[附加元件](https://docs.weblate.org/zh-tw/latest/admin/addons.md) 會納入三個自動產生的檔案，分別包含事件、內建附加元件與常用附加元件參數；過時附加元件則直接在頁面中維護。

若只需重新產生其中一部分，個別管理指令記載於 [管理指令](https://docs.weblate.org/zh-tw/latest/admin/management.md)，`update-docs` 使用的確切指令則列於 `docs/Makefile`。