企业官网建设流程全解析

• 桌面应用

本篇技术指南围绕 QOwnNotes 官方在 2020 年 11 月启动的“网页翻译（Webpage translation）”计划展开，系统讲解该项目如何借助 Crowdin 平台组织社区协作翻译、如何通过翻译规范保证译文质量，以及下载翻译、修复译文、生成变更日志等环节如何由仓库脚本自动化完成。读完本文，你将掌握 QOwnNotes 网页翻译的整体架构、参与翻译与校对的具体方法，以及一套可复用的“Crowdin 协作 + 脚本自动化 + Playwright 回归验证”的多语言站点运维方案。

背景：从桌面应用翻译到网页翻译

QOwnNotes 是一个纯文本笔记与待办事项管理软件（支持 Markdown 与 Nextcloud / ownCloud 集成），其多语言生态由来已久：早在 2016 年 2 月，项目就宣布应用本体可以在 Crowdin 上翻译；截至 2020 年，src/languages 目录下已经积累了数十种语言的 Qt 翻译文件（.ts）。

2020 年 11 月 10 日的官方博客公告《Webpage translation》标志着这一协作模式被正式扩展到官方网站本身：

• 团队花费约一周时间，在 Crowdin 上启动了网页内容的翻译；
• 德语翻译率先以“work in progress（进行中）”的状态上线；
• 官方公开邀请社区成员参与德语翻译的翻译与校对，也欢迎为其他语言贡献力量。

这篇公告实际上宣告了 QOwnNotes 网站从单一英语内容走向社区驱动多语言化的转折点。后续事实证明这条路线是可持续的：2022 年 10 月，波兰语翻译被正式集成进网页，进一步验证了该协作流程的可扩展性。

网页翻译的整体架构：以 Crowdin 为中心

Crowdin 承担的角色

Crowdin 是一种面向移动应用、网页、桌面软件及相关素材的本地化管理平台。在 QOwnNotes 项目中，它承担了两个核心任务：

1. 应用本体翻译：源文件为 src/languages/QOwnNotes_en.ts，翻译产出为各语言.ts文件，最终经lrelease编译为.qm供 Qt 程序加载；
2. 网页内容翻译：以 webpage/src 下的 Markdown 文档为源文件，翻译产出为各语言子目录中的同名 Markdown 文件。

Crowdin 配置文件解析

仓库根目录的 crowdin.yaml 完整定义了文件映射关系：

project_identifier: qownnotes project_id: 158883 # the api token has to be provided by ~/.crowdin.yaml # generate a personal token on https://crowdin.com/settings#api-key #api_token: XXXX preserve_hierarchy: true files: - # source files filter source: "/src/languages/QOwnNotes_en.ts" # where translations live translation: "/src/languages/QOwnNotes_%locale_with_underscore%.ts" dest: "/QOwnNotes_en.ts" - source: "/webpage/src/index.md" translation: "/webpage/src/%two_letters_code%/%original_file_name%" - source: "/webpage/src/contributing/*.md" translation: "/webpage/src/%two_letters_code%/contributing/%original_file_name%" - source: "/webpage/src/editor/*.md" translation: "/webpage/src/%two_letters_code%/editor/%original_file_name%" - source: "/webpage/src/faq/*.md" translation: "/webpage/src/%two_letters_code%/faq/%original_file_name%" - source: "/webpage/src/getting-started/*.md" translation: "/webpage/src/%two_letters_code%/getting-started/%original_file_name%" - source: "/webpage/src/installation/*.md" translation: "/webpage/src/%two_letters_code%/installation/%original_file_name%" - source: "/webpage/src/scripting/*.md" translation: "/webpage/src/%two_letters_code%/scripting/%original_file_name%"

关键要点：

• preserve_hierarchy: true：保留源目录层级，确保翻译文件落入与源文件对应的子目录；
• 应用翻译使用%locale_with_underscore%占位符（如QOwnNotes_de_DE.ts），网页翻译则使用%two_letters_code%（如de），这与后续脚本中“先把带国家代码的文件重命名为纯语言代码”的处理一一对应；
• API token 不写入版本库，而是由~/.crowdin.yaml提供，或通过环境变量注入（见下文 changelog 脚本）。

仓库中所有语言子目录（如 webpage/src/de、ar、es、fa、fr、it、ko、nl、pl等）都严格按照这一映射生成。

如何参与网页翻译与校对

参与入口与完整规范记录在 网页翻译参与指南 中，这里给出要点。

加入翻译

• 注册 Crowdin 账户并加入 QOwnNotes 项目即可开始翻译；
• 已有语言：可直接为现有语言补充或修正翻译，无需额外申请；
• 新增语言：需联系项目所有者（Patrizio / pbek）申请添加新语言。

成为校对者

如果某种语言已完成翻译但尚未校对，且你是该语言的母语或接近母语水平者，可以申请校对权限。校对者的职责是核查并修正未经批准的译文，使软件与网站的使用体验更可靠、更一致。权限需要向项目所有者提出申请，获得批准后方可开始校对。

重要警告：不要直接编辑翻译文件

网页翻译参与指南 明确警告：

Please don't attempt to edit the translation files insrc/languagesdirectly. They are all generated automatically via Crowdin.

即src/languages下的.ts翻译文件全部由 Crowdin 自动生成，手工编辑会被覆盖，所有翻译工作都应通过 Crowdin 平台完成。

翻译规范：保证质量的关键约定

网页与软件翻译共享同一套质量规范，核心原则如下：

准确（Accuracy）

在保证目标语言流畅的前提下，尽可能做到最准确的本地化。

精确（Precision）

译文必须与源字符串完全对应，不得省略或添加任何部分。

上下文（Context）

遇到难以确定的字符串时，可以切换语言查看其他译者的处理方式，或在页面右侧留言请求澄清。

高频术语一致性（Frequently used key terms）

高频关键词必须全程使用同一译法。例如note永远只使用一个统一翻译；如果trashed notes在德语中是gelöschte Dateien，那么每次出现都应沿用该表达（除非语法上必须变通）。可以通过 Crowdin 的搜索功能核对同一术语的所有出现位置是否一致，不一致时可以提出更优翻译并投票支持正确版本。

复数形式（Plural forms）

复数需在每个对应区块中分别填入适当的翻译。

变量（Variables）

%1这类占位变量必须紧贴书写、不留空格；在从右到左（RTL）语言中，既可以从原文插入变量，也可以写进译文内部。

访问键（Access keys）

在需要用作快捷键的字母前使用&前缀；可以与原文相同，也可以不同。

自定义容器（Custom containers）

文档中的::: tip、::: warning、::: info是 VuePress 的自定义容器标记，不应翻译。仓库的下载脚本专门针对翻译者误译容器类型做了大量自动修复（详见下文），可见这一约定在实战中确实容易被破坏。

其他不应翻译的内容

• 代码与链接：代码、链接、标签一律保持原样（且不得插入空格——机器翻译常犯此错）；
• 日期与时间：留空不译；
• 引用（references）：QOwnNotes 文档中包含大量引用条目，直接跳过不译。

翻译下载与质量修复的自动化

网页翻译并不只是“译完上传”就结束。仓库通过 scripts/download_translations.sh 把“从 Crowdin 拉取翻译 → 规整文件名 → 清理噪音 → 修复机器翻译常见错误”全流程自动化。

下载与文件名规整

脚本首先调用crowdin download拉取全部翻译，然后将 Crowdin 返回的带国家代码文件名（如QOwnNotes_de_DE.ts）批量重命名为纯语言代码（如QOwnNotes_de.ts），与 src/languages 的实际文件命名保持一致。

清理与压缩

• 删除翻译文件中的locationXML 标签块（占用大量空间且每次下载都在变化）；
• 去除除源文件QOwnNotes_en.ts外所有翻译文件的每行前导空白，以减小体积。

修复 Crowdin 翻译 bug（fixCrowdinTranslationProblems）

这是脚本中最有信息量的一段，它以sed/perl逐条修复翻译者常见的错误模式：

• 修复缺失空格的容器标记：:::tip→::: tip；
• 把被翻译成各语言的容器类型恢复为英文关键字：::: Tip、::: tipp、::: suggerimento、::: Trinkgeld、::: Warnung、韩文的::: 팁、::: 경고等统一还原为::: tip/::: warning；
• 修复::: warning等行内容器后缺少换行的问题；
• 把<a href="url">text</a>形式的 HTML 链接转换为 Markdown 链接text，并修复缺失>的畸形标签（如<a href="url"text</a>）；
• 把<code>text</code>转换为反引号代码片段`text`，清理孤立的<li>、<p>等标签及<0>、<1>这类数字占位标签（它们会破坏 Vue 模板编译）；
• 修复代码片段中被 Crowdin 转义的>（->被错误编码）与<。

这些修复应用于所有活跃语言目录（de|nl|fa|hu|es|fr|it|ar|pl|ko）下的 Markdown 文件，是保证翻译页面可正常编译构建的最后一道防线。

翻译协作的配套自动化工具

自动生成翻译变更日志

scripts/crowdin_translation_changelog.py 是一个完整的 Crowdin API v2 客户端脚本，职责是自动为 CHANGELOG.md 追加翻译贡献记录：

• 默认以“最近一次成功的翻译构建”到当前时间为贡献窗口，也可用--from/--to显式指定；
• 从 crowdin.yaml 读取project_id，通过环境变量（CROWDIN_API_TOKEN等）或~/.crowdin.yaml读取 API token；
• 创建top-members报告（CSV），轮询等待报告完成，再下载并解析；
• 汇总贡献语言与贡献者，生成形如- Added more de, fr translation (thank you, ...)的行，追加到最新版本块末尾（已存在则跳过）。

添加新语言的一键脚本

scripts/add_translation.py 演示了新增一种语言时需要触碰的全部位置：它会在 crowdin.yaml、scripts/download_translations.sh、src/CMakeLists.txt、src/QOwnNotes.pro、src/debian/qownnotes.install 以及 CHANGELOG.md 中自动插入新语言的配置行，并提醒开发者把语言添加进src/dialogs/settingsdialog.ui的语言选择器。

早期方案：合并 Markdown 供翻译

webpage/scripts/compile-md-files.sh 保留了一段早期历史：它曾把所有网页 Markdown 合并成单个english.txt以便整体翻译，文件头注释标明“Deprecated: Is now done with Crowdin directly!”——即该方案已被 Crowdin 直接翻译取代，从侧面印证了网页翻译流程在 2020 年前后完成了向 Crowdin 的迁移。

翻译质量的自动化回归验证

网页翻译的质量不仅靠人工校对，还通过 Playwright 端到端测试把关。仓库中的 webpage/tests/translations.spec.js 对德语与波斯语页面做了系统性断言：

• 页面可达性：/de/、/fa/首页返回 200，标题为 “QOwnNotes”；
• 内容语言正确：德语页断言导航链接 “Loslegen”“Installation”“Spenden”、特性标题 “Besitze deine Notizen”“Kleiner Fußabdruck”“Anpassung”、页脚 “Erstellt von Patrizio Bekerle mit ❤️”；波斯语页断言 “شروع”“نصب”“حمایت مالی” 等；
• RSS 链接：断言 “Blog RSS”“Veröffentlichungen RSS” 等本地化链接存在；
• URL 模式与语言属性：断言 URL 包含/de/、/fa/，且document.documentElement.lang分别为de-DE与fa-IR。

这些测试保证了翻译上线后页面结构完整、语言正确、lang 属性规范，是对“翻译已上线（work in progress）”状态的可量化验收标准。

现状与社区参与

自 2020 年 11 月德语翻译率先上线后，该协作模式持续运转：2022 年 10 月波兰语翻译被正式集成进网页并发布公告，阿拉伯语、西班牙语、波斯语、法语、匈牙利语、意大利语、韩语、荷兰语等语言目录也持续活跃在 webpage/src 中。

如果你想参与 QOwnNotes 网页或应用本身的翻译与校对，可以遵循以下路径：

1. 阅读 网页翻译参与指南，了解加入方式与全部翻译规范；
2. 加入 Crowdin 项目，选择已有语言直接翻译，或联系项目所有者申请新语言 / 校对权限；
3. 注意不要直接修改 src/languages 下的.ts文件，一切以 Crowdin 为准；
4. 翻译完成后，由仓库脚本下载、规整并修复译文，再由 Playwright 测试与人工校对共同把关后随版本发布。

这套“社区翻译 + 平台协作 + 脚本自动化 + 测试回归”的流程，正是 QOwnNotes 多语言生态持续壮大的工程基础，也是同类开源项目搭建多语言站点时可以借鉴的完整范本。

• 桌面应用