# biblatex-apa-zh

**Version 0.2.0 — Licence: LPPL 1.3c — Author: Che Cheng**

## Abstract (English)

`biblatex-apa-zh` is a companion package for `biblatex-apa`. It adapts APA 7
citation rendering to **Traditional Chinese** prose.

`biblatex-apa` ships localisation files for more than twenty languages but none
for Chinese. Writing in Chinese while citing Western sources therefore produces
half-width parentheses and commas where Chinese typographic convention requires
full-width ones, and the `andothers` string cannot be switched per entry when a
bibliography mixes Chinese and Western works.

The package separates two axes that are easy to conflate. The **language of the
running text** determines citation punctuation and is a document-level option
(`prose=chinese|english`). The **language of each cited work** determines name
strings and bibliography punctuation, and is taken from the `langid` field of
each entry, so a single reference list may mix both.

Unlike `biblatex`'s native `autolang` mechanism, it does not require `babel` or
`polyglossia`, which makes it usable in the common `xeCJK` setup.

Usage:

```latex
\usepackage[style=apa, backend=biber]{biblatex}
\usepackage[prose=chinese]{biblatex-apa-zh}   % must come after biblatex
```

The strings and bibliography punctuation follow Traditional Chinese academic
convention as used in Taiwan. Simplified Chinese conventions differ and are not
covered by this release.

Documentation: `doc/biblatex-apa-zh.pdf` (English abstract, Chinese body).
A test suite (`test/run-tests.sh`) asserts on the rendered output and exits
non-zero on any mismatch.

---

## 中文說明

**繁體中文**行文的 APA 7 引用呈現層。這是 [`biblatex-apa`](https://ctan.org/pkg/biblatex-apa) 的補丁，不是獨立的 bibliography style。

字串與書目標點採**臺灣**的學術慣例（教育部與中華心理學刊）。簡體中文的慣例不同（例如最後兩位作者之間的連接詞），本版不涵蓋。

## 它解決什麼

`biblatex-apa` 實作 APA 7，在地化檔（`.lbx`）出了二十幾種語言（德、法、西、俄、土、匈、羅⋯），**就是沒有中文**。用中文寫作、引用外文文獻時會出現三個問題：

| 問題 | 現象 | 中文規範 |
|---|---|---|
| 括號式引用印半形 | `(Meehl & Hathaway, 1946)` | `（Meehl & Hathaway，1946）` |
| `et al.` / `&` 無法逐筆切換 | `andothers` 是全域字串，中英混排時兩邊被套成同一種 | 中文文獻要「等人」「與」 |
| 中文文獻的書目沿用英文標點 | `王四與李五. (2021). ... 52(3), 45–68.` | `王四與李五（2021）。⋯52(3)，45–68。` |

## 兩個軸，兩套機制

這是本套件的核心設計。兩件事看起來都是「語言」，但它們的層級不同：

| 軸 | 決定什麼 | 機制 | 層級 |
|---|---|---|---|
| **內文語言** | 標點：括號、逗號全形或半形 | 套件選項 `prose` | **文件層**（一份 PDF 只有一種內文語言）|
| **文獻語言** | 字串與姓名：`et al.`／等人、`&`／與、頓號 | `.bib` 的 `langid` 欄位 | **逐筆條目**（同一份文獻表可中英並存）|

biblatex 原生的逐筆切換（`autolang=langname` + `\DeclareLanguageMapping`）依賴 babel／polyglossia。**用 `xeCJK` 而不載 babel 的文件**（中文 LaTeX 的常見組態）沒有那條路，所以本套件改成直接判斷 `langid` 欄位，不要求 babel。

## 安裝

尚未上 CTAN。把 `biblatex-apa-zh.sty` 放在文件同目錄，或放進 `TEXMFHOME`：

```bash
mkdir -p "$(kpsewhich -var-value TEXMFHOME)/tex/latex/biblatex-apa-zh"
cp biblatex-apa-zh.sty "$(kpsewhich -var-value TEXMFHOME)/tex/latex/biblatex-apa-zh/"
```

## 用法

```latex
\usepackage[style=apa, backend=biber]{biblatex}
\usepackage[prose=chinese]{biblatex-apa-zh}   % 必須在 biblatex 之後
\addbibresource{refs.bib}
```

中文文獻在 `.bib` 裡標 `langid`：

```bibtex
@article{chen2019,
  author = {陳一 and 林二 and 黃三},
  title  = {中文閱讀理解測驗的編製與信效度分析},
  ...
  langid = {chinese},
}
```

### 選項

| 選項 | 值 | 預設 | 說明 |
|---|---|---|---|
| `prose` | `chinese` / `english` | `chinese` | 內文語言，決定引用標點的全形半形 |
| `foreignandothers` | `etal` / `zh` | `etal` | 中文行文中，**外文**文獻的 `et al.` 印英文還是「等人」 |

`foreignandothers` 預設 `etal` 是刻意保守：既有文件升級到本套件時，外文引用的輸出一個字都不會變，不會憑空產生一批需要勘誤的差異。中文文獻（`langid=chinese`）一律用「等人」「與」，不受這個選項影響。

## 實測輸出

`test/fixtures/chinese-prose.tex`，`prose=chinese`、`foreignandothers=etal`：

| | `\parencite` | `\textcite` |
|---|---|---|
| 外文 2 人 | （Meehl & Hathaway，1946） | Meehl and Hathaway（1946） |
| 外文 3+ 人 | （Haladyna et al.，2002） | Haladyna et al.（2002） |
| 中文 2 人 | （王四與李五，2021） | 王四與李五（2021） |
| 中文 3+ 人 | （陳一等人，2019） | 陳一等人（2019） |

`&` 與 `and` 的分工是 APA 本身的規定（括號式用 `&`、敘述式用 `and`），本套件保留。

## 中文文獻的書目格式（v0.2 起）

中文條目用中文標點，英文條目維持 APA 原樣，兩者在同一份文獻表裡並存：

```
王四與李五（2021）。學習動機量表的跨年級測量恆等性。教育心理學報，52(3)，45–68。

Gregory, R. J. (2015). Psychological testing: History, principles, and applications
    (7th ed.). Pearson.
```

逐筆切換靠 `\AtEveryBibitem` 內的局部重定義，實測確認侷限在該筆條目內。英文條目**不會**被中文規則波及這一點，有專門的斷言守著——那是「逐筆」這個核心設計唯一的直接證據。

## 已知限制

- **條目型別覆蓋**：中文書目格式目前針對期刊論文與專書的常見欄位調校過。會議論文集、學位論文、法規等較少見的型別尚未逐一處理。
- **排序**：中英混排的文獻表依 `biblatex` 預設規則排序，沒有實作依筆畫或注音的中文排序。
- **中文姓名**：不倒置、不縮寫（本來就不該做），但沒有處理複姓等特殊情況。
- **簡體中文**：本套件輸出的是繁體字串（「等人」「與」「、」）。簡體的書目慣例不同，需要的話應該做成一個 `variant` 選項，目前沒有。

## 已知陷阱（給後續維護者）

這兩個都實際踩過，症狀都是**安靜地沒有效果**，不會報錯：

1. **`\DeclareFieldFormat{parens}` 對 `\parencite` 無效。** `\parencite` 的外框走 `\mkbibparens` → `\bibopenparen`，不吃那個 field format。要改必須重寫整個 `\DeclareCiteCommand`。
2. **delimiter 要在三個 context 各宣告一次。** `biblatex-apa` 對 `finalnamedelim` 宣告了預設、`[parencite]`（`apa.cbx:477`）、`[bib,biblist]`（`apa.bbx:704`）三份。只覆寫預設的話，括號式引用與參考文獻表會維持原樣——半套的結果比全沒改更難發現。

3. **`\autocite` 不需要「重新綁定」。** 這一條記的是一個**錯誤診斷**，不是陷阱本身。

   v0.1 曾在套件裡加一行 `\ExecuteBibliographyOptions{autocite=inline}`，依據是「biblatex 在處理選項當下就把 `\autocite` 綁到當時的 `\parencite`，之後重定義無效」。那個依據是錯的：`biblatex.sty:15906` 的 `\letcs\autocite{blx@acite@inline}` 綁的是中介巨集，而 `biblatex.def:2667` 的 `\DeclareAutoCiteCommand{inline}{\parencite}` 讓它在**使用時**才去找 `\parencite`。所以重定義本來就會傳導。

   拆穿它的正是 `autocite` 固件：把那行註解掉，測試照樣全綠。真正的原因單純得多——手寫補丁的 `\parencite` 用了半形的 `\mkbibparens`。

   **留著這條紀錄是因為錯誤的診斷會再長回來。** 下一個人看到 `\autocite` 出問題時，很可能會再加一次那行，然後以為是它修好的。

另外：**不要**整個重定義 `\bibopenparen` 成全形。那會連參考文獻表裡的 `(2002)`、`15(3)` 一起改掉，而那些屬於英文書目格式，APA 要求半形。

## 測試

```bash
bash test/run-tests.sh                # 全部固件
bash test/run-tests.sh chinese-prose  # 單一固件
```

全數通過 exit 0，任一條斷言不符 exit 1，可以直接掛在 CI 或 pre-commit 上。目前 4 個固件、47 條斷言。

| 固件 | 守什麼 |
|---|---|
| `chinese-prose` | 內文四象限、中文姓名無贅空格、參考文獻表維持半形、跨行正規化 |
| `english-prose` | `prose=english` 時回到半形；且 `langid` 決定的字串不受 `prose` 影響 |
| `autocite` | `\autocite` 與 `\parencite` 產出一致 |
| `maxprtauth` | 作者被截斷時的分隔符行為與上游一致 |

斷言寫在 `test/expected/<固件>.txt`，`+` 為必須出現、`-` 為必須不出現。

**兩件關於斷言的紀律**（都是實測踩出來的）：

- **比對前必須正規化空白。** `pdftotext` 會硬斷行，同一個引用可能被切成兩行；不正規化的話斷言會因為與套件行為無關的換行位置而失敗。
- **負向斷言要盯住「會壞的那個字元」，不要寫完整字串。** 把 `\parencite` 改回 `\mkbibparens` 之後，輸出是 `(Meehl & Hathaway，1946)` 這種半形括號配全形逗號的**混合**形式；寫完整字串的負向斷言兩種都不命中，缺陷被引入了測試卻全綠。

相依：`xelatex`、`biber`、`pdftotext`（poppler）。CJK 字型由 `test/fixtures/_cjkfont.tex` 依序偵測（PingFang TC → Noto Sans/Serif CJK TC → Source Han Sans TC → Microsoft JhengHei），都找不到才報錯並列出該裝哪一個。

## 要發布到 CTAN 的話

上游 `biblatex-apa` 的維護者明說歡迎在地化貢獻（未翻譯字串都標 `%FIXME`），所以有兩條路，**建議兩條都走但有先後**：

**先做獨立套件**（本 repo）。本套件做的事超出 `.lbx` 的範圍——`.lbx` 只能放字串，而全形括號與 delimiter context 要改的是 cite command 與 delimiter 宣告，那不屬於在地化檔。

**之後再送 `chinese-apa.lbx` 給上游**當補充，把純字串的部分（`andothers`、`and`、`in`、`editor`、`translator` 等）交給上游維護。

### CTAN 上傳需要的東西

| 項目 | 狀態 | 說明 |
|---|---|---|
| 套件檔 | ✅ `biblatex-apa-zh.sty` | |
| 授權 | ✅ LPPL 1.3c | LaTeX 套件的標準授權，CTAN 接受度最高 |
| `README` | ✅ 本檔 | 要寫明名稱、版本、作者、用途、安裝、授權 |
| 說明文件 PDF | ✅ `doc/biblatex-apa-zh.pdf` | 3 頁，英文摘要 + 中文正文 |
| 版本與日期 | ✅ `.sty` 的 `\ProvidesPackage` | 每次上傳都要遞增 |
| 測試套件 | ✅ `test/run-tests.sh` | 4 固件、47 條斷言，含兩個回歸固件；兩者都已驗證「缺陷重新引入時會紅」 |
| TDS zip | ✅ 內附於主 archive 頂層 | CTAN 明寫「不接受只有 .tds.zip 的上傳」、每個套件都必須出現在未壓縮的那一份，所以是附在裡面而非另外送 |

上傳在 <https://ctan.org/upload>，填套件名、版本、授權、作者、一句話摘要，附 zip。通過之後會自動流進 TeX Live 與 MiKTeX。

**`.dtx`／`.ins` 不是必要的。** 那是 docstrip 的文學式編程格式，CTAN 上很多套件用，但純 `.sty` + 獨立說明書一樣會被接受。以本套件的規模（不到 150 行）不值得為它多維護一層。

### 上傳前該做的事

1. 在 educator 專案內部實際用一季，確認沒有回歸（測試套件擋得住已知的兩個缺陷，擋不住還沒想到的）
2. 決定 `foreignandothers` 的預設要不要改（目前保守設 `etal`）
3. 擴充較少見的條目型別（會議論文集、學位論文），或在說明書裡明寫本版不涵蓋


## 授權

LPPL 1.3c。見 `LICENSE`。