\documentclass[11pt,a4paper]{article}
\usepackage{xeCJK}
\input{../test/fixtures/_cjkfont}
\usepackage[margin=2.8cm]{geometry}
\usepackage{fontspec}
\usepackage{booktabs}
\usepackage{hyperref}
\hypersetup{hidelinks}
\usepackage{fancyvrb}
\usepackage{parskip}

\newcommand{\pkg}[1]{\texttt{#1}}
\newcommand{\opt}[1]{\texttt{#1}}

\title{\pkg{biblatex-apa-zh}\\[0.3em]\large 繁體中文行文的 APA 7 引用呈現層}
\author{Che Cheng}
\date{v0.2.0\quad 2026/08/15}

\begin{document}
\maketitle

\begin{abstract}
\noindent
\textbf{English summary.}\quad
\pkg{biblatex-apa-zh} is a companion package for \pkg{biblatex-apa}. It adapts APA 7
citation rendering to \textbf{Traditional Chinese} prose: full-width parentheses and commas in
citations, and per-entry switching of \texttt{et al.}/等人 and \texttt{\&}/與 driven by
the \texttt{langid} field. It also renders the bibliography entries of Chinese-language
works with Chinese punctuation. Unlike \pkg{biblatex}'s native \texttt{autolang}
mechanism, it does \emph{not} require \pkg{babel} or \pkg{polyglossia}, so it works in
the common \pkg{xeCJK} setup. Licence: LPPL~1.3c.
\end{abstract}

\section{這個套件解決什麼}

\pkg{biblatex-apa} 實作 APA 7，它的在地化檔（\texttt{.lbx}）出了二十幾種語言，
就是沒有中文。用中文寫作、引用外文文獻時會遇到三件事：

\begin{enumerate}
  \item 括號式引用印成半形 \verb|(Meehl & Hathaway, 1946)|，
        中文行文的標點規範要求全形「（Meehl \& Hathaway，1946）」。
  \item \texttt{andothers} 是全域字串，中英文獻混排時「等人」與 \texttt{et al.}
        無法逐筆切換。
  \item 中文文獻的書目條目沿用英文標點（句號、半形括號）。
\end{enumerate}

\section{核心設計：兩個軸}

看起來都是「語言」，但層級不同。分不開這兩者，就只能得到一個全域開關。

\begin{center}
\begin{tabular}{@{}lll@{}}
\toprule
\textbf{軸} & \textbf{決定什麼} & \textbf{層級} \\
\midrule
內文語言 & 引用的標點（括號、逗號全形或半形） & 文件層（套件選項 \opt{prose}）\\
文獻語言 & 字串與姓名、書目標點 & 逐筆條目（\texttt{.bib} 的 \texttt{langid}）\\
\bottomrule
\end{tabular}
\end{center}

一份 PDF 只有一種內文語言，所以那是選項；而同一份參考文獻表可以中英並存，
所以那必須是欄位。

\pkg{biblatex} 原生的逐筆切換（\texttt{autolang=langname} 搭配
\verb|\DeclareLanguageMapping|）依賴 \pkg{babel} 或 \pkg{polyglossia}。中文 LaTeX
常見的組態是只載 \pkg{xeCJK} 而不載 \pkg{babel}，那條路走不通，所以本套件改成
直接判斷 \texttt{langid} 欄位。

\section{用法}

\begin{Verbatim}[frame=single,fontsize=\small]
\usepackage[style=apa, backend=biber]{biblatex}
\usepackage[prose=chinese]{biblatex-apa-zh}   % 必須在 biblatex 之後
\addbibresource{refs.bib}
\end{Verbatim}

中文文獻在 \texttt{.bib} 裡標 \texttt{langid}：

\begin{Verbatim}[frame=single,fontsize=\small]
@article{chen2019,
  author = {陳一 and 林二 and 黃三},
  title  = {中文閱讀理解測驗的編製與信效度分析},
  ...
  langid = {chinese},
}
\end{Verbatim}

\subsection{選項}

\begin{center}
\begin{tabular}{@{}lll p{5.2cm}@{}}
\toprule
\textbf{選項} & \textbf{值} & \textbf{預設} & \textbf{說明} \\
\midrule
\opt{prose} & \texttt{chinese}／\texttt{english} & \texttt{chinese}
  & 內文語言，決定引用標點的全形半形 \\
\opt{foreignandothers} & \texttt{etal}／\texttt{zh} & \texttt{etal}
  & 中文行文中，\emph{外文}文獻的 \texttt{et al.} 印英文還是「等人」\\
\bottomrule
\end{tabular}
\end{center}

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

\section{輸出}

\subsection{內文引用}

\begin{center}
\begin{tabular}{@{}lll@{}}
\toprule
 & \verb|\parencite| & \verb|\textcite| \\
\midrule
外文 2 人   & （Meehl \& Hathaway，1946） & Meehl and Hathaway（1946）\\
外文 3 人以上 & （Haladyna et al.，2002）   & Haladyna et al.（2002）\\
中文 2 人   & （王四與李五，2021）        & 王四與李五（2021）\\
中文 3 人以上 & （陳一等人，2019）          & 陳一等人（2019）\\
\bottomrule
\end{tabular}
\end{center}

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

\subsection{參考文獻表}

中文條目用中文標點，英文條目維持 APA 原樣：

\begin{Verbatim}[frame=single,fontsize=\small]
王四與李五（2021）。學習動機量表的跨年級測量恆等性。教育心理學報，52(3)，45-68。

Gregory, R. J. (2015). Psychological testing: History, principles,
    and applications (7th ed.). Pearson.
\end{Verbatim}

英文條目的 \texttt{(7th ed.)}、\texttt{(pp.\ 1--3)} 依 APA 維持半形。中文的
全形規則不會外溢過去，這一點有測試守著。

\section{已知限制}

\begin{itemize}
  \item 中文書目格式目前涵蓋期刊論文與專書的常見欄位。較少見的條目型別
        （會議論文集、學位論文、法規）尚未逐一調校。
  \item 中文姓名不做倒置與縮寫（本來就不該做），但也沒有處理「複姓」等
        特殊情況。
  \item 排序：中英混排的文獻表目前依 \pkg{biblatex} 的預設規則排序，沒有
        另外實作依筆畫或注音的中文排序。
  \item 簡體中文：本套件輸出的是繁體字串（「等人」「與」「、」），書目標點
        採臺灣的學術慣例。簡體中文的慣例不同（例如最後兩位作者之間的連接詞），
        本版不涵蓋；需要的話應做成一個 \opt{variant} 選項。
\end{itemize}

\section{測試}

\begin{Verbatim}[frame=single,fontsize=\small]
bash test/run-tests.sh
\end{Verbatim}

4 個固件、47 條斷言，全過 \texttt{exit 0}、任一不符 \texttt{exit 1}。
其中兩個是回歸固件，都已驗證「把缺陷重新引入時會失敗」——一個固件若對
修好的與壞掉的版本都通過，它什麼都沒測到。

相依：\texttt{xelatex}、\texttt{biber}、\texttt{pdftotext}。

\section{授權}

LPPL 1.3c。原始碼與問題回報：
\url{https://github.com/kiki830621/biblatex-apa-zh}

\end{document}