Skip to content

[i18nIgnore] i18n(zh-TW): Rearrange i18n guide #12667

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Nov 10, 2025
+100 −168
Merged

[i18nIgnore] i18n(zh-TW): Rearrange i18n guide #12667

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
a4b6540
i18n(zh-TW): Rearrange i18n guide
lumynou5 Nov 5, 2025
170abcd
i18n(zh-TW): Make wording uniform
lumynou5 Nov 5, 2025
ccb91a1
i18n(zh-TW): Make guide more clear
lumynou5 Nov 6, 2025
873fa86
i18n(zh-TW): Fix ununiform wording
lumynou5 Nov 7, 2025
aff63de
Merge branch 'main' into main
mingjunlu Nov 8, 2025
27ee189
Merge branch 'main' into main
yanthomasdev Nov 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
230 changes: 81 additions & 149 deletions i18n-guides/正體中文.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,154 +1,86 @@
# Astro Docs 中文翻譯指南

感謝你有興趣對 Astro 文件翻譯做出貢獻！
提交改動前，別忘了閱讀 [i18n 指南](https://contribute.docs.astro.build/guides/i18n/)，裡面包含了貢獻過程中需要知道的內容。
也歡迎加入 Astro 的 [Discord 社群](https://astro.build/chat)與其他貢獻者們交流！

本指南旨在整理一份統一的格式及風格指南，使文件讀起來更流暢並易於理解。

編撰時參考了 [Vue 中文文档指南](https://github.com/vuejs-translations/docs-zh-cn/wiki/%E7%BF%BB%E8%AF%91%E9%A1%BB%E7%9F%A5)。



## 1. 術語和用詞

### 1.1 術語表
> 部分參考：
> - [《重編國語辭典修訂本》](https://dict.revised.moe.edu.tw/index.jsp)
> - [臺灣在地化社群詞彙對照表](https://hackmd.io/@l10n-tw/glossaries)
> - [大陸台灣計算機術語對照表](https://zh.wikibooks.org/zh-tw/大陸台灣計算機術語對照表)

|原文 |推薦翻譯 |備註 |
|----------------------|---------------------|-----------------------|
|library |程式庫／函式庫 | |
|integration |整合 | |
|import |引入／匯入 | |
|package |套件／軟體包 | |
|routing |路由 | |
|architecture |架構 | |
|framework |框架 | |
|reference |參考 | |
|build |建構／建置 | |
|deploy |部署 | |
|component |元件 | |
|migration |遷移 | |
|asset |資產 | |
|docs |文件 | |
|documentation |說明文件／技術文件 | |
|project |專案 | |
|configuration |組態／設定 | |
|community |社群 | |
|hydration |水合 | |
|islands |群島 |特指 Astro Islands |
|escape |跳脫 |特指 Escape Character |
|reactive |反應式 | |
|responsive |響應式 | |
|repository |儲存庫 | |
|experimental |實驗性 | |
|middleware |中介層 | |
|adapter |配接器 | |
|CLI |命令列 | |
|terminal |終端機 | |
|codebase |程式碼庫 | |
|changelog |變更日誌 | |
|recipe |操作指南 | |
|server-side rendering |伺服器端算繪 | |
|call |呼叫 | |


### 1.2 中文用詞
> 部分參考[《重編國語辭典修訂本》](https://dict.revised.moe.edu.tw/index.jsp)及[《異體字字典》](https://dict.variants.moe.edu.tw/variants/rbt/home.do)

|中文 |說明 |
|----------------|-------------------|
|你 |而不使用「您」 |
|應用程式 |而不使用「應用」 |
|舉例來說 |而不使用「舉個例子」等 |
|其他 |並無「其它」一詞 |


### 1.3 特指名詞及品牌名稱
- 「JavaScript」或「ECMAScript」等詞語應**保留風格化寫法**，而非「Javascript」或「Ecmascript」
- 「npm」及「webpack」等產品 / 品牌名稱的應**保留風格化寫法**，而非「Npm」或「Webpack」


### 1.4 關於 MDN 中可查詢的前端術語
# Astro Docs 正體中文翻譯指南

感謝你有興趣對 Astro 文件翻譯做出貢獻！

提交改動前，別忘了閱讀 [i18n 指南](https://contribute.docs.astro.build/guides/i18n/)，裡面包含了貢獻過程中需要知道的內容。

此外，[Discord `docs-i18n` 頻道中的 `i18n-crew-zh` 討論串](https://discord.com/channels/830184174198718474/973149689610371093)是中文翻譯的討論區（目前未區分地區），歡迎先參與討論，避免重複其他人正在翻譯的頁面。

## 本指南的目的

本指南旨在定義書寫規範和統一的用語，讓讀者能流暢地理解內容，也使譯者能更簡單地完成翻譯。

## 中文書寫規範

- 使用全形標點符號，使用直角引號。
- 斜線因全形在不同字體的外形差異較大，應使用半形，並於前後插入空格。
- 拉丁字母、數字不使用全形。
- 使用「你」而非「您」。
- 選用臺灣正體漢字，例如「為」而非「爲」。
- 專有名詞保留大小寫，無論出現於句中何處，例如「JavaScript」。

### 英數前後空格

中文書寫時採用「[盤古之白](https://github.com/vinta/pangu.js)」，即中文和英文、數字間插入一個半形空格。

行內程式碼（`code`）前後也適用。

- 在漢字和拉丁字母、數字間插入一個半形空格。
- 全形標點符號前後不應有空格。
- 超連結前後不必加入空格，除非文字以半形字元開頭或結尾。
- Markdown 標記開頭和結尾如要加上空格，應加在標記外部。

## 術語表

參考：
- [臺灣在地化社群《詞彙對照表》](https://hackmd.io/@l10n-tw/glossaries)
- [《資訊科技詞彙翻譯》](https://hackmd.io/@sysprog/it-vocabulary)

| 原文 | 譯文 | 備註 |
| --------------------- | ------------ | --------------------- |
| adapter | 配接器 | |
| architecture | 架構 | |
| asset | 資產 | |
| build | 建置 | |
| call | 呼叫 | |
| changelog | 變更日誌 | |
| CLI | 命令列 | |
| codebase | 程式碼庫 | |
| community | 社群 | |
| component | 元件 | |
| configuration | 組態 | |
| deploy | 部署 | |
| docs | 文件 | |
| documentation | 文件 | |
| escape | 跳脫 | 特指 escape character |
| experimental | 實驗性 | |
| framework | 框架 | |
| hydration | 水合 | |
| import | 匯入 | |
| integration | 整合 | |
| islands | 群島 | 特指 Astro islands |
| library | 函式庫 | |
| middleware | 中介層 | |
| migration | 遷移 | |
| package | 軟體包 | |
| project | 專案 | |
| reactive | 反應式 | |
| recipe | 操作指南 | |
| reference | 參考 | |
| repository | 儲存庫 | |
| responsive | 響應式 | |
| routing | 路由 | |
| server-side rendering | 伺服器端算繪 | |
| terminal | 終端機 | |

### MDN 中可查詢的前端術語

- 原則上，前端專業術語的翻譯優先**參考 MDN 中文譯文**，若無中文則**保留原文**。
- 原文中的 MDN 文件連結建議轉換為 MDN 的中文譯文連結，但是鑒於 MDN 的中文翻譯也並不完善，所以：
- 當條目有中文譯文時，將其手動**變更為 MDN 中文連結**，其餘則**保留原文連結**



## 2. 譯文格式

### 2.1 標點符號
> 參考[《重訂標點符號手冊》](https://language.moe.gov.tw/001/upload/files/site_content/m0001/hau/c2.htm)及[《W3C 中文排版需求》](https://w3c.github.io/clreq/#line_composition_rules_for_punctuation_marks)
- 除特殊情況外，所有中文標點符號應為**全形字元**
- 考慮到 `／` 在不同字體下算繪結果差異較大，分隔號應為前後包含空格的 `/`，如：`你好 / 世界`


### 2.2 行內程式碼與關鍵字
請使用**反單引號**（`）標記，例：
```md
呼叫 `window` 的 `alert()` 函式
```


### 2.3 中西文混排
> 部分參考[《W3C 中文排版需求》](https://w3c.github.io/clreq/#chinese_and_western_mixed_text_composition)
- 中文和英文之間**應**插入一個**半形空格**。如：`你好 Hello 世界`
- 全形標點與英文之間**不須**插入空格。如：`你好世界（Hello World）`
- 注意使用 Markdown 標記（如*斜體*、**粗體**或[超連結](#)等）時，應保證空格出現在欲分隔字詞的**外部**。如：
```md
遵守 **JavaScript 程式碼規範**非常重要
遵守 [JavaScript 程式碼規範](#foo)非常重要
詳見*中文 MDN* 的參考頁面
詳見[中文 MDN](#bar) 的參考頁面
```


### 2.4 程式碼片段
- 程式碼片段中的**註解應翻譯為中文**，其餘部分應**保留原文**
- 日誌及執行結果等也應**保留原文**，以便和程式碼邏輯保持一致



## 3. 翻譯建議

### 3.1 調整語序為中文習慣
例如：
> So far we've only been binding to simple property keys in our templates. But Vue.js actually supports the full power of JavaScript expressions inside all data bindings.

以上例句可譯為：「目前我們都只是在模板中綁定簡單的屬性鍵，但事實上 Vue.js 支援在任何資料綁定中使用 JavaScript 表達式」。


### 3.2 省略部分在原文中僅作完成句式的詞語
例如：
> When Vue is updating a list of elements rendered with v-for, by default it uses an "in-place patch" strategy. If the order of the data items has changed, instead of moving the DOM elements to match the order of the items, Vue will patch each element in-place and make sure it reflects what should be rendered at that particular index.

像是「to match the order of the items」這樣的短語可以在**保證語意不變**的情況下簡化。

以上例句可譯為：「Vue 預設按照『就地更新』的策略來更新透過 `v-for` 算繪的元素列表。當資料的順序改變時，Vue 不會隨之移動 DOM 元素的順序，而是就地更新每個元素，確保它反映應在指定索引位置上算繪的內容」。


### 3.3 補充連接詞使句子更加連貫
例如：
> The mustache tag will be replaced with the value of the msg property from the corresponding component instance. It will also be updated whenever the msg property changes.

可在句中加入如「然而」、「並且」或「即使……也……」等連接詞來使句子更加連貫。

以上例句的後半句可譯為：「每當 `msg` 屬性發生改變時，綁定處的內容便會隨之更新」。


### 3.4 在尊重原文的前提下使讀者更容易理解

> TODO

### 3.5 譯文及原文行號應相對應
由於 Astro 文件以 Markdown 撰寫，每一行形成一個自然段落，因此原則上應保持譯文及原文行號應相對應，以保證後續更新時不造成混淆。
- 當條目有中文譯文時，將其手動**變更為 MDN 中文連結**，其餘則**保留原文連結**

## 更新本指南

本指南是現時社群翻譯貢獻者的共識，如有任何意見，歡迎在 Discord 的 `i18n-crew-zh` 討論串提出。

## 4. 關於本指南
本指南**並非**硬性規定，而是代表中文文件翻譯團隊共識的建議。
如果你對本指南有任何想法或勘誤建議，歡迎發起 Issue 或是加入 [Discord 社群](https://astro.build/chat)中的 `#i18n-crew-zh` 頻道參與討論！
術語表加入新項目時請依原文字母序排序，並保持原文全小寫，除非是縮寫。格式化表格時漢字視為 2 個半形字元寬。
2 changes: 1 addition & 1 deletion src/content/docs/zh-tw/basics/layouts.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -243,7 +243,7 @@ const { title, fancyJsHelper } = Astro.props;
</html>
```

不論是經由 frontmatter `layout` 屬性，還是引入版面，要使用任何版面，你必須在版面裡納入 `<meta charset="utf-8">` 標籤，因為 Astro 將不再自動將它加入 MDX 頁面。
不論是經由 frontmatter `layout` 屬性，還是匯入版面，要使用任何版面，你必須在版面裡納入 `<meta charset="utf-8">` 標籤，因為 Astro 將不再自動將它加入 MDX 頁面。

<ReadMore>關於 Astro 對 Markdown 和 MDX 的支援，請參考 [Markdown 指南](/zh-tw/guides/markdown-content/)。</ReadMore>

Expand Down
14 changes: 7 additions & 7 deletions src/content/docs/zh-tw/basics/project-structure.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,8 @@ Astro 為你的專案準備固有的資料夾安排。每個 Astro 專案的根
- `src/*` - 你的專案原始碼（元件、頁面、樣式、圖片等）。
- `public/*` - 你的非程式碼、未處理的資源（字體、圖示等）。
- `package.json` - 一個專案列表。
- `astro.config.mjs` - 一個 Astro 設定檔（建議）。
- `tsconfig.json` - 一個 TypeScript 設定檔（建議）。
- `astro.config.mjs` - 一個 Astro 組態檔（建議）。
- `tsconfig.json` - 一個 TypeScript 組態檔（建議）。

### 範例專案樹狀圖

Expand Down Expand Up @@ -98,7 +98,7 @@ Astro 會處理、最佳化並將你的 `src/` 捆起來建立最後瀏覽器會

### `src/styles`

這是一個普遍的慣例作法來儲存你的 CSS 或 Sass 檔案到一個 `src/styles` 目錄，但並非必須。只要你的樣式被存放在 `src/` 目錄內，並且有正確地引入，Astro 就會處理並最佳化這些檔案。
這是一個普遍的慣例作法來儲存你的 CSS 或 Sass 檔案到一個 `src/styles` 目錄，但並非必須。只要你的樣式被存放在 `src/` 目錄內，並且有正確地匯入，Astro 就會處理並最佳化這些檔案。

### `public/`

Expand All @@ -124,14 +124,14 @@ Astro 會處理、最佳化並將你的 `src/` 捆起來建立最後瀏覽器會

這個檔案會在每個入門範本建立且其包含了你 Astro 專案的設定選項。在此你可以指定用哪些整合、建立選項、伺服選項等等。

Astro 的 JavaScript 設定檔案支援幾個檔案格式：`astro.config.js`、`astro.config.mjs`、`astro.config.cjs` 以及 `astro.config.ts`。我們推薦在多數情況下使用 `.mjs`，或者如果你想要用 TypeScript 寫設定檔案的話就用 `.ts`。
Astro 的 JavaScript 組態檔支援幾個檔案格式：`astro.config.js`、`astro.config.mjs`、`astro.config.cjs` 以及 `astro.config.ts`。我們推薦在多數情況下使用 `.mjs`，或者如果你想要用 TypeScript 寫組態檔的話就用 `.ts`。

TypeScript 設定檔案的讀取是透過 [`tsm`](https://github.com/lukeed/tsm) 處理的，並且會遵循你的專案的 tsconfig 選項。
TypeScript 組態檔的讀取是透過 [`tsm`](https://github.com/lukeed/tsm) 處理的，並且會遵循你的專案的 tsconfig 選項。

查看[設定參考](/zh-tw/reference/configuration-reference/)來了解完整的細節。
查看[組態參考](/zh-tw/reference/configuration-reference/)來了解完整的細節。

### `tsconfig.json`

這個檔案會在每個入門範本建立且其包含了你 Astro 專案的 TypeScript 設定選項。若沒有 `tsconfig.json` 這個檔案的話，部分功能（像是 npm 套件引入）在編輯器中不會被全部支援。
這個檔案會在每個入門範本建立且其包含了你 Astro 專案的 TypeScript 設定選項。若沒有 `tsconfig.json` 這個檔案的話，部分功能（像是 npm 軟體包匯入）在編輯器中不會被全部支援。

查看 [TypeScript 指南](/zh-tw/guides/typescript/)來了解更多設定細節。
8 changes: 4 additions & 4 deletions src/content/docs/zh-tw/editor-setup.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ import ReadMore from '~/components/ReadMore.astro';

### Stylelint

[Stylelint](https://stylelint.io/) 是一種流行的 CSS linter。[社群維護的 Stylelint 設定](https://github.com/ota-meshi/stylelint-config-html) 提供 Astro 支援。
[Stylelint](https://stylelint.io/) 是一種流行的 CSS linter。[社群維護的 Stylelint 組態](https://github.com/ota-meshi/stylelint-config-html) 提供 Astro 支援。

安裝說明、編輯器整合和其他資訊可以在專案的 README 文件中找到。

Expand Down Expand Up @@ -102,7 +102,7 @@ import ReadMore from '~/components/ReadMore.astro';
</Fragment>
</PackageManagerTabs>

2. 在專案最上層新增 `.prettierrc` 設定檔（或 `.prettierrc.json`、`.prettierrc.mjs` 或[其他支援格式](https://prettier.io/docs/configuration)），然後在檔案加上 `prettier-plugin-astro`。
2. 在專案最上層新增 `.prettierrc` 組態檔（或 `.prettierrc.json`、`.prettierrc.mjs` 或[其他支援格式](https://prettier.io/docs/configuration)），然後在檔案加上 `prettier-plugin-astro`。

也在這個檔案手動指定 Astro 檔案用的剖析器。

Expand All @@ -120,7 +120,7 @@ import ReadMore from '~/components/ReadMore.astro';
}
```

3. 你可以選擇為專案安裝其他 Prettier 外掛，並加進設定檔。加上的這些外掛可能需要以特定順序列出。舉例來說，如果你使用 Tailwind，`prettier-plugin-tailwindcss` 必須是 [plugins 陣列的最後一個 Prettier 外掛](https://github.com/tailwindlabs/prettier-plugin-tailwindcss#compatibility-with-other-prettier-plugins)。
3. 你可以選擇為專案安裝其他 Prettier 外掛，並加進組態檔。加上的這些外掛可能需要以特定順序列出。舉例來說，如果你使用 Tailwind，`prettier-plugin-tailwindcss` 必須是 [plugins 陣列的最後一個 Prettier 外掛](https://github.com/tailwindlabs/prettier-plugin-tailwindcss#compatibility-with-other-prettier-plugins)。

```json title=".prettierrc"
{
Expand Down Expand Up @@ -164,4 +164,4 @@ import ReadMore from '~/components/ReadMore.astro';

### dprint

[dprint](https://dprint.dev/) 是高度可設定的格式化工具，支援 JavaScript, TypeScript, CSS 及更多程式語言。可以使用 [markup_fmt plugin](https://github.com/g-plane/markup_fmt) 增加對 `.astro` 檔案的支援。
[dprint](https://dprint.dev/) 是高度可設定的格式化工具，支援 JavaScript, TypeScript, CSS 及更多程式語言。可以使用 [markup_fmt plugin](https://github.com/g-plane/markup_fmt) 增加對 `.astro` 檔案的支援。
2 changes: 1 addition & 1 deletion src/content/docs/zh-tw/guides/deploy/github.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Astro 官方提供的 `withastro/action` 可以只使用極少的設定就部署

### 部署至 `github.io` 網址

請在 `astro.config.mjs` 的設定檔中設定 [`site`](/zh-tw/reference/configuration-reference/#site) 與 [`base`](/zh-tw/reference/configuration-reference/#base) 兩個選項。
請在 `astro.config.mjs` 組態檔中設定 [`site`](/zh-tw/reference/configuration-reference/#site) 與 [`base`](/zh-tw/reference/configuration-reference/#base) 兩個選項。

```js title="astro.config.mjs" ins={4-5}
import { defineConfig } from 'astro/config'
Expand Down
Loading