添加新语言

翻译系统架构

下图说明了 Stirling-PDF 中的国际化系统如何工作

来源： src/main/resources/templates/fragments/languages.html scripts/ignore_translation.toml .github/scripts/check_language_properties.py .github/workflows/sync_files.yml .github/workflows/check_properties.yml

添加新语言

添加新语言的过程包括创建新的属性文件、添加翻译以及将语言集成到用户界面中。

来源： README.md src/main/resources/templates/fragments/languages.html

1. 创建语言属性文件

首先在 src/main/resources 目录下创建一个新文件，遵循命名约定 messages_LANG_REGION.properties，其中

LANG 是 ISO 639-1 语言代码（2 个字符）
REGION 是 ISO 3166-1 区域代码（2 个字符）

例如

messages_fr_FR.properties 对应法语（法国）
messages_es_ES.properties 对应西班牙语（西班牙）
messages_de_DE.properties 对应德语（德国）

最简单的开始方法是复制参考英文文件

messages_en_GB.properties → messages_XX_YY.properties

来源： README.md112-158

2. 翻译文件内容

创建文件后，翻译所有文本值，同时保持键不变。文件遵循标准的 Java 属性格式，采用 key=value 对。

示例

# Original in messages_en_GB.properties
navbar.convert=Convert
navbar.security=Security

# Translated in messages_fr_FR.properties
navbar.convert=Convertir
navbar.security=Sécurité

重要指南

保持所有键与参考文件中的键完全一致
在翻译文本中保留任何占位符（例如， {0}, {1} ）
如果值中包含 HTML 标签，请保持其完整性
保持与参考文件相同的行序和注释

来源： .github/scripts/check_language_properties.py15-102

3. 将语言添加到用户界面

要在用户界面中启用您的语言，请在 src/main/resources/templates/fragments/languages.html 中添加一个新条目。

替换

xx_YY 使用您的语言和区域代码（例如， fr_FR ）
Native Language Name 使用该语言的本机名称（例如， Français ）

请根据本机语言名称的字母顺序添加此条目。

来源： src/main/resources/templates/fragments/languages.html1-43

4. 测试您的翻译

在提交您的贡献之前，请在本地测试您的翻译

使用您的新语言文件构建并运行 Stirling-PDF
在用户界面中切换到您的语言
浏览不同页面以确保所有翻译正确显示
验证用户界面元素是否保持正确的格式和布局

您还可以使用验证脚本来检查您的翻译文件

此脚本将识别您的翻译文件中任何缺失的键、多余的键或格式问题。

来源： .github/scripts/check_language_properties.py133-171 .github/workflows/check_properties.yml20-250

处理缺失的翻译和被忽略的键

翻译忽略列表

某些语言可能有意跳过某些翻译。这通过 scripts/ignore_translation.toml 文件进行管理。如果您的语言需要从验证中排除某些键，您可以将它们添加到此文件。

仅在绝对必要时才将键添加到忽略列表，例如：

该键仅针对特定语言（例如，RTL 方向指示符）
英语术语在您的语言中常用
直接翻译会使用户感到困惑

来源： scripts/ignore_translation.toml1-269

从右到左语言支持

对于阿拉伯语或希伯来语等从右到左 (RTL) 语言，请将以下条目添加到您的属性文件

language.direction=rtl

对于从左到右 (LTR) 语言，请将其设置为 ltr 或将该键添加到您的忽略列表。

来源： scripts/ignore_translation.toml1-10

CI/CD 和验证

当您提交包含翻译更改的拉取请求时，将运行多项自动化检查

check_properties.yml 工作流会根据参考文件验证您的翻译文件
系统会检查以下内容：
- 缺失或多余的键
- 行数不匹配
- 重复条目
- 格式错误

任何验证问题都将作为评论报告在您的 PR 上，您需要在合并您的贡献之前解决这些问题。

sync_files.yml 工作流将在您的贡献合并后自动更新 README.md 文件中的语言进度表。

来源： .github/workflows/check_properties.yml1-251 .github/workflows/sync_files.yml1-146

翻译维护

翻译进度

翻译进度会在 README.md 文件中自动计算并显示。进度以百分比显示，表示参考文件中有多少键已被翻译。

如果您的语言翻译覆盖率低于 75%，请考虑更新它，以确保一致的用户体验。

更新翻译

当 Stirling-PDF 添加新功能时，可能会引入新的翻译键。为了保持您的语言最新：

检查参考文件（messages_en_GB.properties）的更改
为所有新键添加翻译
提交包含您的更新的 PR

系统将自动识别缺失的翻译，并可以帮助您将您的语言文件与参考文件同步。

来源： README.md113-158 .github/workflows/sync_files.yml79-104

翻译最佳实践

保持一致性：在您的翻译中始终使用一致的术语
尊重语境：考虑文本在用户界面中出现的语境
保持相似长度：尽量保持相似的文本长度，以防止用户界面布局问题
进行视觉测试：确保您的翻译在用户界面布局中显示良好
保留格式：保持占位符、HTML 标签和特殊格式完整无损
使用自然语言：以目标语言的清晰度和自然性进行翻译
保持技术准确性：确保技术术语翻译准确

来源： .github/pull_request_template.md15-27

总结

为 Stirling-PDF 添加新语言是一个直接的过程，包括创建属性文件、翻译内容以及在用户界面语言菜单中添加一个条目。自动化验证工具可帮助确保所有翻译的质量和一致性。

您的贡献有助于使 Stirling-PDF 对全球用户更具可访问性。如果您在翻译过程中遇到任何问题，请随时通过 GitHub issues 或 Discord 社区联系开发团队。

添加新语言

翻译系统架构