Pandoc 多语言文档转 LaTeXbabel 语言标注与 \foreignlanguage 生成机制解析【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc导读在撰写跨语言技术文档如德语为主、夹杂法语与英语引文的学术论文时Pandoc 需要把 Markdown 中声明的语言信息BCP 47 语言码准确转换为 LaTeX/babel 能理解的语言命令。本文以仓库测试用例 9472.md 为核心完整拆解lang元数据、行内{lang...}标注如何被 LaTeX 写入器 映射为\documentclass[...]选项、\foreignlanguage{...}命令与\hypersetup{pdflang{...}}并给出可复现的命令行验证方式。读完本文你将掌握 Pandoc 多语言 LaTeX 输出的完整链路以及语言码到 babel 名称的映射规则。一、测试用例 9472.md 的全貌该测试位于 Pandoc 的 golden 测试体系中输入是一个带 YAML 元数据与行内语言标注的 Markdown 文档命令为% pandoc -t latex -s --- lang: de-DE --- More text in English. [Zitat auf Deutsch.]{langde} [Bonjour]{langfr} [café]{langfr-FR} ^D注意这里的% ...与^D是测试驱动语法%表示执行的命令行-t latex -s即输出独立 LaTeX 文档^D表示标准输入结束。该输入含三个语言要素元数据lang: de-DE声明全文主语言为德语德国地区用于设置 babel 主语言、pdflang等。行内标注[Zitat auf Deutsch.]{langde}一段德语引文外层是 Markdown 引号...会被转换为智能引号。行内标注[Bonjour]{langfr}与[café]{langfr-FR}两个法语单词分别使用fr与更精确的fr-FR。该用例要验证的核心行为是主语言进入\documentclass选项行内语言进入\foreignlanguage且所有语言都经过 babel 名称规范化de-DE → ngermanfr / fr-FR → french。二、语言码收集docLangs 与主语言判定在 LaTeX 写入器 中pandoc 先收集文档内所有语言docLangs - catMaybes $ mapM (toLang . Just) (nubOrd (query (extract lang) blocks)) mblang - toLang $ case getLang options meta of Just l - Just l Nothing | null docLangs - Nothing | otherwise - Just enquery (extract lang) blocks会从整个文档树中提取所有lang属性既包括 YAML 元数据也包括行内{lang...}的键值对经nubOrd去重后得到docLangs。主语言mblang优先取元数据lang若元数据缺失但文档中存在行内语言标注则默认主语言为en这也是为什么 9472 用例中lang: de-DE是决定性输入。对 9472 而言docLangs包含de-DE、de、fr、fr-FR四个语言码mblang为de-DE。三、toBabel从 BCP 47 到 babel 语言名的映射pandoc 并不把语言码原样塞进 LaTeX而是通过 Text.Pandoc.Writers.LaTeX.Lang 中的toBabel将其转换为 babel 语言名。该模块的注释明确指出其依据是 CTAN 上的 babel 文档与 hyph-utf8 连字表。对于de-DE德语、德国地区、无扩展变量命中如下分支toBabel (Lang de _ _ vars _ _) | 1901 elem vars Just german | otherwise Just ngerman即de-DE默认映射为ngerman新正字法德语。而fr/fr-FR无地区特判落入commonFromBcp47的 ISO 639 对照表fromIso fr Just french统一映射为french——这正是输出中两个法语 span 都生成\foreignlanguage{french}{...}的原因。toBabel还内置了大量地区与变体特判理解这些规则有助于预判输出BCP 47 输入babel 输出触发条件de-AT无1901变量naustrian奥地利德语de-AT1901austrian传统正字法de-CH/de-CH1901nswissgerman/swissgerman瑞士德语de-DE/de-DE1901ngerman/german德语主分支en-GB、en-UKbritish英式英语en-USamerican美式英语en-AU、en-CA、en-NZaustralian/canadian/newzealand地区英语fr-CAfrench加拿大法语仍用frenchpt-BRbrazilian巴西葡萄牙语zh-Hans/zh-Hantchinese-hans/chinese-hant简繁体zh-Hant-HKchinese-hant-hk香港繁体中文字形elpolytonpolytonicgreek带音调符号的希腊语lax-classicclassiclatin古典拉丁语sr-Cyrlserbianc塞尔维亚语西里尔zh-Latnpinyinpinyin拼音罗马化slslovene斯洛文尼亚语非 ISO 同名dsb/hsblowersorbian/uppersorbian下/上索布语其余语言af、ar、ru、ja等一百余种通过commonFromBcp47的 ISO 639 对照表直接映射查不到的语言返回Nothing。这一映射层同时服务于 Babel 与 Polyglossia是跨引擎语言支持的基础。四、模板注入babel-otherlangs 与 babel-lang收集到的语言在 LaTeX 写入器 中被组织成模板变量let babelLang mblang toBabel let context maybe id (\l - defField lang (literal $ renderLang l)) mblang $ maybe id (\l - defField babel-lang (literal l)) babelLang $ (case babelLang of -- see #8283 Just l | l notElem ldfLanguages - defField babeloptions (provide* :: Text) _ - id) $ defField babel-otherlangs (map literal (filter (elem ldfLanguages) . nubOrd . catMaybes . filter (/ babelLang) $ map toBabel docLangs)) $ defField latex-dir-rtl ...关键逻辑有三babel-lang主语言的 babel 名9472 中为ngerman。babel-otherlangs其余语言映射结果中属于ldfLanguages白名单的去重列表9472 中为[french]。白名单ldfLanguages定义于 LaTeX.hs 第 1311 行起覆盖ngerman、french、english、magyar、croatian、greek等拉丁与西里尔字母欧洲语言依据 babel 官方建议“通常应对拉丁/西里尔文字与越南语做此处理”。babeloptions若主语言不在ldfLanguages白名单内则注入provide*见 issue #8283让 babel 按需加载语言定义避免预加载全部.ldf。随后 default.latex 模板 把这两个变量渲染进\documentclass选项\documentclass[ $for(babel-otherlangs)$ $babel-otherlangs$, $endfor$ $if(babel-lang)$ $babel-lang$, $endif$ ... ]{$documentclass$}对应到 9472 的期望输出\documentclass[ french, ngerman, ]{article}顺序值得注意frenchbabel-otherlangs排在ngermanbabel-lang之前且两者都以逗号结尾模板中的换行与$sep$机制所致这是 babel 语言选项的合法写法。五、行内语言标注生成 \foreignlanguage行内[Bonjour]{langfr}在 AST 中是一个带lang键值对的Span。LaTeX 写入器 处理 Span 时读取该属性inlineToLaTeX (Span (id,classes,kvs) ils) do linkAnchor - hypertarget id lang - toLang $ lookup lang kvs ... langCmds case lang toBabel of Just l - [foreignlanguage{ l }] Nothing - [] ... (if null cmds then braces contents else foldr inCmd contents cmds)langde→toBabel→ngerman→ 生成\foreignlanguage{ngerman}{...}。langfr与langfr-FR→french→ 生成\foreignlanguage{french}{...}引号写法在 YAML/属性解析中等价最终均输出french。若无lang属性或映射失败Nothing则退化为普通花括号分组不影响排版。同时Span 的其他属性也会组合进命令链dirrtl/dirltr映射为\RL/\LRcsl-*类名映射为\textup、\CSLBlock等。多个命令通过foldr inCmd嵌套包裹。对应到期望输出More text in English. \foreignlanguage{ngerman}{Zitat auf Deutsch.} \foreignlanguage{french}{Bonjour} \foreignlanguage{french}{café}引号...已被 Pandoc 智能引号机制转为弯引号...并在\foreignlanguage内保持原样café中的重音字符é依赖模板加载的inputenc/fontspec字体设置见下文。六、pdflang 与文档级语言元数据除正文语言命令外pandoc 还会把主语言写入 PDF 元数据。模板末尾的\hypersetup块9472 期望输出为\hypersetup{ pdflang{de-DE}, hidelinks, pdfcreator{LaTeX via pandoc}}这里pdflang使用原始 BCP 47 码de-DE而非 babel 名ngerman因为它面向 PDF 阅读器而非排版引擎pdfcreator则标识生成工具。这由 hypersetup.latex 模板片段渲染是 pandoc 确保生成的 PDF 具备正确语言标记、提升无障碍与检索友好性的关键一环。七、引擎差异与字体设置9472 输出中的模板前言还体现了 pandoc LaTeX 模板对引擎的适配这一部分来自 fonts.latex、font-settings.latex 等公共片段\ifPDFTeX \usepackage[T1]{fontenc} \usepackage[utf8]{inputenc} \usepackage{textcomp} % provide euro and other symbols \else % if luatex or xetex \usepackage{unicode-math} % this also loads fontspec \defaultfontfeatures{ScaleMatchLowercase} \defaultfontfeatures[\rmfamily]{LigaturesTeX,Scale1} \fiPDFTeX 路径显式加载fontenc/inputenc/textcomp保证café、德语引号等字符可用。XeTeX/LuaTeX 路径走unicode-math与fontspec的\defaultfontfeatures直接使用系统字体。无论哪个引擎都会统一加载babel\ifLuaTeX ... \else ... \fi中按引擎选择bidibasic或bididefault并关闭shorthands、selnolig仅 LuaTeX用于禁用非法连字、microtype、bookmark、xurl等辅助包并以\setlength{\emergencystretch}{3em}缓解 overfull 问题。八、手动复现与验证在当前仓库工作目录下可直接复现该测试需要已构建的 pandoc 二进制pandoc -t latex -s EOF --- lang: de-DE --- More text in English. [Zitat auf Deutsch.]{langde} [Bonjour]{langfr} [café]{langfr-FR} EOF输出应与 9472 的期望完全一致\documentclass[french, ngerman]{article}、两个\foreignlanguage、\hypersetup{pdflang{de-DE}}。若去掉元数据中的lang则主语言退化为enmblang的兜底逻辑babel-lang变为english可作为对照实验观察差异。继续深入可阅读语言映射实现src/Text/Pandoc/Writers/LaTeX/Lang.hs语言收集与模板变量注入src/Text/Pandoc/Writers/LaTeX.hs 与 第 313-333 行模板变量渲染位置data/templates/default.latexldfLanguages白名单src/Text/Pandoc/Writers/LaTeX.hs小结从lang: de-DE到\documentclass[..., ngerman]从{langfr}到\foreignlanguage{french}{...}再到pdflang{de-DE}9472 测试串起了 Pandoc LaTeX 写入器多语言处理的完整链路toBabel负责语言名规范化babel-otherlangs/babel-lang决定文档类选项行内 Span 生成\foreignlanguage模板负责引擎差异与 PDF 语言元数据。理解这条链路你就能精确预测并控制任何多语言文档的 LaTeX 输出。【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Pandoc 多语言文档转 LaTeX：babel 语言标注与 \foreignlanguage 生成机制解析
Pandoc 多语言文档转 LaTeXbabel 语言标注与 \foreignlanguage 生成机制解析【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc导读在撰写跨语言技术文档如德语为主、夹杂法语与英语引文的学术论文时Pandoc 需要把 Markdown 中声明的语言信息BCP 47 语言码准确转换为 LaTeX/babel 能理解的语言命令。本文以仓库测试用例 9472.md 为核心完整拆解lang元数据、行内{lang...}标注如何被 LaTeX 写入器 映射为\documentclass[...]选项、\foreignlanguage{...}命令与\hypersetup{pdflang{...}}并给出可复现的命令行验证方式。读完本文你将掌握 Pandoc 多语言 LaTeX 输出的完整链路以及语言码到 babel 名称的映射规则。一、测试用例 9472.md 的全貌该测试位于 Pandoc 的 golden 测试体系中输入是一个带 YAML 元数据与行内语言标注的 Markdown 文档命令为% pandoc -t latex -s --- lang: de-DE --- More text in English. [Zitat auf Deutsch.]{langde} [Bonjour]{langfr} [café]{langfr-FR} ^D注意这里的% ...与^D是测试驱动语法%表示执行的命令行-t latex -s即输出独立 LaTeX 文档^D表示标准输入结束。该输入含三个语言要素元数据lang: de-DE声明全文主语言为德语德国地区用于设置 babel 主语言、pdflang等。行内标注[Zitat auf Deutsch.]{langde}一段德语引文外层是 Markdown 引号...会被转换为智能引号。行内标注[Bonjour]{langfr}与[café]{langfr-FR}两个法语单词分别使用fr与更精确的fr-FR。该用例要验证的核心行为是主语言进入\documentclass选项行内语言进入\foreignlanguage且所有语言都经过 babel 名称规范化de-DE → ngermanfr / fr-FR → french。二、语言码收集docLangs 与主语言判定在 LaTeX 写入器 中pandoc 先收集文档内所有语言docLangs - catMaybes $ mapM (toLang . Just) (nubOrd (query (extract lang) blocks)) mblang - toLang $ case getLang options meta of Just l - Just l Nothing | null docLangs - Nothing | otherwise - Just enquery (extract lang) blocks会从整个文档树中提取所有lang属性既包括 YAML 元数据也包括行内{lang...}的键值对经nubOrd去重后得到docLangs。主语言mblang优先取元数据lang若元数据缺失但文档中存在行内语言标注则默认主语言为en这也是为什么 9472 用例中lang: de-DE是决定性输入。对 9472 而言docLangs包含de-DE、de、fr、fr-FR四个语言码mblang为de-DE。三、toBabel从 BCP 47 到 babel 语言名的映射pandoc 并不把语言码原样塞进 LaTeX而是通过 Text.Pandoc.Writers.LaTeX.Lang 中的toBabel将其转换为 babel 语言名。该模块的注释明确指出其依据是 CTAN 上的 babel 文档与 hyph-utf8 连字表。对于de-DE德语、德国地区、无扩展变量命中如下分支toBabel (Lang de _ _ vars _ _) | 1901 elem vars Just german | otherwise Just ngerman即de-DE默认映射为ngerman新正字法德语。而fr/fr-FR无地区特判落入commonFromBcp47的 ISO 639 对照表fromIso fr Just french统一映射为french——这正是输出中两个法语 span 都生成\foreignlanguage{french}{...}的原因。toBabel还内置了大量地区与变体特判理解这些规则有助于预判输出BCP 47 输入babel 输出触发条件de-AT无1901变量naustrian奥地利德语de-AT1901austrian传统正字法de-CH/de-CH1901nswissgerman/swissgerman瑞士德语de-DE/de-DE1901ngerman/german德语主分支en-GB、en-UKbritish英式英语en-USamerican美式英语en-AU、en-CA、en-NZaustralian/canadian/newzealand地区英语fr-CAfrench加拿大法语仍用frenchpt-BRbrazilian巴西葡萄牙语zh-Hans/zh-Hantchinese-hans/chinese-hant简繁体zh-Hant-HKchinese-hant-hk香港繁体中文字形elpolytonpolytonicgreek带音调符号的希腊语lax-classicclassiclatin古典拉丁语sr-Cyrlserbianc塞尔维亚语西里尔zh-Latnpinyinpinyin拼音罗马化slslovene斯洛文尼亚语非 ISO 同名dsb/hsblowersorbian/uppersorbian下/上索布语其余语言af、ar、ru、ja等一百余种通过commonFromBcp47的 ISO 639 对照表直接映射查不到的语言返回Nothing。这一映射层同时服务于 Babel 与 Polyglossia是跨引擎语言支持的基础。四、模板注入babel-otherlangs 与 babel-lang收集到的语言在 LaTeX 写入器 中被组织成模板变量let babelLang mblang toBabel let context maybe id (\l - defField lang (literal $ renderLang l)) mblang $ maybe id (\l - defField babel-lang (literal l)) babelLang $ (case babelLang of -- see #8283 Just l | l notElem ldfLanguages - defField babeloptions (provide* :: Text) _ - id) $ defField babel-otherlangs (map literal (filter (elem ldfLanguages) . nubOrd . catMaybes . filter (/ babelLang) $ map toBabel docLangs)) $ defField latex-dir-rtl ...关键逻辑有三babel-lang主语言的 babel 名9472 中为ngerman。babel-otherlangs其余语言映射结果中属于ldfLanguages白名单的去重列表9472 中为[french]。白名单ldfLanguages定义于 LaTeX.hs 第 1311 行起覆盖ngerman、french、english、magyar、croatian、greek等拉丁与西里尔字母欧洲语言依据 babel 官方建议“通常应对拉丁/西里尔文字与越南语做此处理”。babeloptions若主语言不在ldfLanguages白名单内则注入provide*见 issue #8283让 babel 按需加载语言定义避免预加载全部.ldf。随后 default.latex 模板 把这两个变量渲染进\documentclass选项\documentclass[ $for(babel-otherlangs)$ $babel-otherlangs$, $endfor$ $if(babel-lang)$ $babel-lang$, $endif$ ... ]{$documentclass$}对应到 9472 的期望输出\documentclass[ french, ngerman, ]{article}顺序值得注意frenchbabel-otherlangs排在ngermanbabel-lang之前且两者都以逗号结尾模板中的换行与$sep$机制所致这是 babel 语言选项的合法写法。五、行内语言标注生成 \foreignlanguage行内[Bonjour]{langfr}在 AST 中是一个带lang键值对的Span。LaTeX 写入器 处理 Span 时读取该属性inlineToLaTeX (Span (id,classes,kvs) ils) do linkAnchor - hypertarget id lang - toLang $ lookup lang kvs ... langCmds case lang toBabel of Just l - [foreignlanguage{ l }] Nothing - [] ... (if null cmds then braces contents else foldr inCmd contents cmds)langde→toBabel→ngerman→ 生成\foreignlanguage{ngerman}{...}。langfr与langfr-FR→french→ 生成\foreignlanguage{french}{...}引号写法在 YAML/属性解析中等价最终均输出french。若无lang属性或映射失败Nothing则退化为普通花括号分组不影响排版。同时Span 的其他属性也会组合进命令链dirrtl/dirltr映射为\RL/\LRcsl-*类名映射为\textup、\CSLBlock等。多个命令通过foldr inCmd嵌套包裹。对应到期望输出More text in English. \foreignlanguage{ngerman}{Zitat auf Deutsch.} \foreignlanguage{french}{Bonjour} \foreignlanguage{french}{café}引号...已被 Pandoc 智能引号机制转为弯引号...并在\foreignlanguage内保持原样café中的重音字符é依赖模板加载的inputenc/fontspec字体设置见下文。六、pdflang 与文档级语言元数据除正文语言命令外pandoc 还会把主语言写入 PDF 元数据。模板末尾的\hypersetup块9472 期望输出为\hypersetup{ pdflang{de-DE}, hidelinks, pdfcreator{LaTeX via pandoc}}这里pdflang使用原始 BCP 47 码de-DE而非 babel 名ngerman因为它面向 PDF 阅读器而非排版引擎pdfcreator则标识生成工具。这由 hypersetup.latex 模板片段渲染是 pandoc 确保生成的 PDF 具备正确语言标记、提升无障碍与检索友好性的关键一环。七、引擎差异与字体设置9472 输出中的模板前言还体现了 pandoc LaTeX 模板对引擎的适配这一部分来自 fonts.latex、font-settings.latex 等公共片段\ifPDFTeX \usepackage[T1]{fontenc} \usepackage[utf8]{inputenc} \usepackage{textcomp} % provide euro and other symbols \else % if luatex or xetex \usepackage{unicode-math} % this also loads fontspec \defaultfontfeatures{ScaleMatchLowercase} \defaultfontfeatures[\rmfamily]{LigaturesTeX,Scale1} \fiPDFTeX 路径显式加载fontenc/inputenc/textcomp保证café、德语引号等字符可用。XeTeX/LuaTeX 路径走unicode-math与fontspec的\defaultfontfeatures直接使用系统字体。无论哪个引擎都会统一加载babel\ifLuaTeX ... \else ... \fi中按引擎选择bidibasic或bididefault并关闭shorthands、selnolig仅 LuaTeX用于禁用非法连字、microtype、bookmark、xurl等辅助包并以\setlength{\emergencystretch}{3em}缓解 overfull 问题。八、手动复现与验证在当前仓库工作目录下可直接复现该测试需要已构建的 pandoc 二进制pandoc -t latex -s EOF --- lang: de-DE --- More text in English. [Zitat auf Deutsch.]{langde} [Bonjour]{langfr} [café]{langfr-FR} EOF输出应与 9472 的期望完全一致\documentclass[french, ngerman]{article}、两个\foreignlanguage、\hypersetup{pdflang{de-DE}}。若去掉元数据中的lang则主语言退化为enmblang的兜底逻辑babel-lang变为english可作为对照实验观察差异。继续深入可阅读语言映射实现src/Text/Pandoc/Writers/LaTeX/Lang.hs语言收集与模板变量注入src/Text/Pandoc/Writers/LaTeX.hs 与 第 313-333 行模板变量渲染位置data/templates/default.latexldfLanguages白名单src/Text/Pandoc/Writers/LaTeX.hs小结从lang: de-DE到\documentclass[..., ngerman]从{langfr}到\foreignlanguage{french}{...}再到pdflang{de-DE}9472 测试串起了 Pandoc LaTeX 写入器多语言处理的完整链路toBabel负责语言名规范化babel-otherlangs/babel-lang决定文档类选项行内 Span 生成\foreignlanguage模板负责引擎差异与 PDF 语言元数据。理解这条链路你就能精确预测并控制任何多语言文档的 LaTeX 输出。【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考