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:

\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 的補丁，不是獨立的 bibliography style。

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

它解決什麼

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

兩個軸，兩套機制

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

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

安裝

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

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/"

用法

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

中文文獻在 .bib 裡標 langid：

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

選項

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

實測輸出

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

& 與 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）三份。只覆寫預設的話，括號式引用與參考文獻表會維持原樣——半套的結果比全沒改更難發現。

1. \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 test/run-tests.sh                # 全部固件
bash test/run-tests.sh chinese-prose  # 單一固件

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

斷言寫在 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 上傳需要的東西

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

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

上傳前該做的事

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

授權

LPPL 1.3c。見 LICENSE。