RenderCV locale 字段完全指南：多语言简历的本地化、日期格式与自定义方法

RenderCV locale 字段完全指南：多语言简历的本地化、日期格式与自定义方法

【免费下载链接】rendercvResume builder for academics and engineers项目地址: https://gitcode.com/GitHub_Trending/re/rendercv

locale是 RenderCV YAML 输入文件中四个顶层字段之一，它负责让同一份简历内容以任意语言呈现——包括月份名称、日期格式、页脚"最后更新"文案以及条目模板中的语言特定短语。本文以 docs/user_guide/yaml_input_structure/locale.md 为骨架，结合src/rendercv/schema/models/locale/下的模型源码与src/rendercv/renderer/templater/date.py等渲染管线，完整讲解内置语言的使用、逐字段覆盖、完全自定义 locale，以及 locale 在底层是如何被加载、校验并参与日期与条目模板渲染的。读完本文，你将能在一分钟内生成德文、法文、日文乃至阿拉伯文（RTL）简历，也能为任何语言定制出一套精确的月份、时态与学位短语翻译。

locale 字段在 YAML 输入文件中的位置

RenderCV 使用单个 YAML 文件描述整份简历，顶层包含四个字段：cv、design、locale、settings，其中只有cv是必需的，其余均有合理的默认值（见 docs/user_guide/yaml_input_structure/index.md）：

cv: # 简历内容（姓名、section、条目） design: # 视觉样式（主题、颜色、字体、间距） locale: # 语言字符串（月份名称、"present" 等） settings: # RenderCV 行为（当前日期、关键词加粗等）

locale的核心作用是"把语言相关的文本与 CV 内容解耦"：简历里的日期、教育经历中的学位描述、页眉页脚的生成时间，都会先经过 locale 的本地化处理，再交给模板渲染。

内置语言：一行配置切换简历语言

原文档明确指出：RenderCV 内置了多种语言的翻译，只需指定language即可启用：

locale: language: german

文档中的"可用语言列表"由模板占位符<< available_locales >>动态渲染。以当前仓库源码为准，内置语言由两部分构成：

• 内置的英语（EnglishLocale基类）；
• src/rendercv/schema/models/locale/other_locales/ 目录下的 21 个 YAML 语言文件：arabic、danish、dutch、french、german、hebrew、hindi、hungarian、indonesian、italian、japanese、korean、mandarin_chinese、norwegian_bokmål、norwegian_nynorsk、persian、portuguese、russian、spanish、turkish、vietnamese，合计22 种语言。

以德语（german.yaml）为例，完整文件内容如下：

# yaml-language-server: $schema=../../../../../../schema.json locale: language: german last_updated: Zuletzt aktualisiert month: Monat months: Monate year: Jahr years: Jahre present: gegenwärtig phrases: degree_with_area: DEGREE in AREA month_abbreviations: - Jan - Feb - Mär - Apr - Mai - Jun - Jul - Aug - Sep - Okt - Nov - Dez month_names: - Januar - Februar - März - April - Mai - Juni - Juli - August - September - Oktober - November - Dezember

可以看到，每个语言文件都完整覆盖了last_updated、单复数月份/年份、present（表示"至今"）、phrases.degree_with_area、12 个月份缩写与 12 个月份全称。

locale 字段逐项详解

locale的字段结构定义在 src/rendercv/schema/models/locale/english_locale.py 的EnglishLocale模型中，各字段含义与默认值如下：

值得注意的约束：month_abbreviations与month_names必须恰好为 12 个元素，源码中通过annotated_types.Len(min_length=12, max_length=12)在模型层强校验（见english_locale.py第 60、79 行）。月份索引是 1 基的——month_names[month - 1]对应第month个月，这与 Pythondatetime的取值约定保持一致。

复数的语义差异

month/months、year/years并不只是"抄写翻译"，它们被用于自动计算的时间跨度（time span）。在 date.py 的compute_time_span_string中，渲染管线会根据年数/月数选择单复数形式：时长为 1 年时用locale.year，否则用locale.years；月数同理。例如英语默认输出2 years 3 months，而时长恰为 1 年时输出1 year。这也解释了为什么mandarin_chinese.yaml中month与months都是个月、year与years都是年——中文没有严格单复数形态，翻译者按语言习惯自由处理即可。

覆盖单个字段：微调翻译

原文档强调，locale的全部字段都支持逐项覆盖，无需重写整份翻译。最常见的场景是更换 "present" 的措辞：

locale: language: german present: jetzt # 仅覆盖这一个字段

由于每个语言文件都是基于EnglishLocale的"带默认值变体"，YAML 中未出现的字段会回落到该语言的内置默认值。这意味着你可以在保留德语全部默认翻译的前提下，单独把present从gegenwärtig改为更口语化的jetzt。

创建完全自定义的 locale

若内置语言没有你需要的（例如某地方言，或希望使用完全不同的日期措辞），可以在language基础上显式给出全部字段，构造一个专属 locale。原文档给出的完整示例：

locale: language: english last_updated: Last updated in month: month months: months year: year years: years present: present month_abbreviations: - Jan - Feb - Mar - Apr - May - June - July - Aug - Sept - Oct - Nov - Dec month_names: - January - February - March - April - May - June - July - August - September - October - November - December

这套 YAML 与EnglishLocale的默认值一一对应，是"自定义翻译"的完整模板。你可以复制它并替换每个字段的取值。注意language字段仍必须填写（例如english），它作为判别字段决定 locale 的类型归属（见下文源码机制），同时language_iso_639_1等派生属性依赖它映射到正确的语言代码。

自定义 locale 中的 phrases

自定义时也可以覆盖phrases.degree_with_area。该短语是"学位（DEGREE）与专业方向（AREA）"的组合模板，内含DEGREE、AREA两个占位符。英语默认值为DEGREE in AREA，德语为DEGREE in AREA，简体中文（mandarin_chinese.yaml）则使用AREA DEGREE（语序反转），阿拉伯语为"DEGREE في AREA"。若你的语言存在不同的语序习惯，例如法语惯用DEGREE en AREA，可自定义为：

locale: language: french phrases: degree_with_area: "DEGREE en AREA"

源码机制：locale 是如何被加载与校验的

理解底层实现有助于判断"我可以覆盖到什么程度"。locale 的加载逻辑集中在 locale.py：

1. 自动发现（Auto-discovery）。discover_other_locales()会扫描other_locales/目录下的所有*.yaml文件，逐个调用create_variant_pydantic_model动态生成对应的 Pydantic 模型：以文件名作为变体名、以 YAML 中locale键的内容作为默认值、以EnglishLocale作为基类。这意味着新增一种语言只需要在other_locales/下放一个 YAML 文件，无需改动核心代码——这正是社区贡献翻译的入口方式。

2. 判别式联合（Discriminated Union）。所有语言模型通过pydantic.Field(discriminator="language")合并成一个联合类型Locale。因此language字段不仅是翻译标识，更是 Pydantic 用来判定"该用哪套默认值"的判别字段：YAML 中写了language: german，模型就会使用德语变体并校验其余字段。

3. 可用语言列表。文件末尾的available_locales从联合类型的每个分支提取language默认值，构成动态的可用语言清单（文档中的<< available_locales >>占位符即由此渲染）。

语言代码、国旗与 RTL 的派生属性

EnglishLocale还通过functools.cached_property提供三个只读派生属性（见english_locale.py）：

• language_iso_639_1：返回 ISO 639-1 双字母语言代码（如de、fr、ja、zh）。该代码被用于 Typst 的lang参数（控制断字 hyphenation、智能引号与无障碍朗读）以及 HTML 导出的lang属性。Typst 主题包中的locale-catalog-language即取自该映射。
• flag_emoji：返回语言对应的主国家旗帜 emoji（如英语🇬🇧），用于 UI 中语言名称旁的展示。
• is_rtl：判断是否为从右到左书写的语言。当前rtl_languages = {"arabic", "hebrew", "persian"}，即阿拉伯语、希伯来语、波斯语会被标记为 RTL。在 lib.typ 中，text-direction参数据此决定排版方向，网格、内边距、section 标题与顶部备注都会正确镜像（相关说明见 rendercv_typst/CHANGELOG.md 的 RTL 支持条目）。

locale 与日期格式化管线

locale最频繁的消费方是日期渲染。在 date.py 中，build_date_placeholders把某个具体日期展开为 8 个占位符：

日期显示格式本身由design字段中的templates决定（见 classic_theme.py 第 770–840 行的Templates模型），locale 与设计模板的分工是：locale 提供"词汇"（月份名、present、年/月单复数），design.templates提供"句式"。三个核心模板的默认值：

• single_date:MONTH_ABBREVIATION YEAR→ 德语环境下渲染为Mär 2025；
• date_range:START_DATE – END_DATE，其中END_DATE为present时会被替换为locale.present；
• time_span:HOW_MANY_YEARS YEARS HOW_MANY_MONTHS MONTHS，其中YEARS/MONTHS取locale的单复数形式。

format_single_date还保留了一个重要行为：如果日期值是"自定义字符串"（如Spring 2024），无法被解析为标准日期，则原样透传，不强制本地化——这为某些无法用月份模板表达的特殊日期留了口子。

顶部备注与页脚同样消费 locale：render_top_note_template与render_footer_template（见 footer_and_top_note.py）会取locale.last_updated作为LAST_UPDATED占位符的值。因此德语简历的顶部默认呈现Zuletzt aktualisiert Mär 2025而非Last updated in Mar 2025。

phrases 与条目模板的联动

locale.phrases并不仅仅是文档字符串，它会被真正展开进教育经历条目的模板。在 entry_templates_from_input.py 第 136–146 行，渲染管线先把短语占位符（如DEGREE_WITH_AREA）替换为locale.phrases中的对应文本，再让DEGREE、AREA作为普通占位符继续参与后续替换。以mandarin_chinese为例，教育条目中DEGREE_WITH_AREA会被展开为AREA DEGREE（学位与专业语序对调），实现真正的本地化句式，而不是机械翻译。

entry_templates_from_input.py的render_entry_templates是 locale 进入条目渲染的入口：它同时接收templates（来自design）与locale，统一处理DATE、START_DATE、END_DATE占位符（调用process_date，内部串联format_date_range/format_single_date/compute_time_span_string）。整体调用链可概括为：locale模型 →entry_templates_from_input.render_entry_templates→date.py各格式化函数 → 最终由 templater.py 渲染进 Typst / HTML / Markdown 模板。

实操建议与配置验证

1. 优先使用内置语言 + 最小覆盖：绝大多数场景只需locale: { language: xxx }，再按需覆盖一两个字段，避免维护冗长的月份列表。
2. 确认语言标识：language必须是注册过的标识（如mandarin_chinese、norwegian_bokmål，注意中文用下划线而非zh/cn）。如果写错，Pydantic 判别联合会抛出校验错误，错误信息会列出可用语言。
3. 利用 JSON Schema 获得自动补全：仓库根目录的 schema.json 覆盖全部四个顶层字段，docs/user_guide/yaml_input_structure/index.md 介绍了在 VS Code（文件名以_CV.yaml结尾自动激活）或其他编辑器（文件首行声明yaml-language-server: $schema=）中的配置方式。编辑locale时可直接获得字段提示、默认值说明与 12 元素列表的即时校验。
4. RTL 语言无需额外配置：选择arabic、hebrew或persian后，is_rtl会自动驱动 Typst 的text-direction: rtl，简历整体排版镜像为从右到左。

通过"内置语言 + 逐字段覆盖 + 完全自定义"三级用法，配合design.templates中的日期模板，locale让 RenderCV 的简历输出真正做到"内容一次编写、语言随时切换"。

【免费下载链接】rendercvResume builder for academics and engineers项目地址: https://gitcode.com/GitHub_Trending/re/rendercv