翻译内容¶

虽然英语是软件开发人员的常用语言，但也有很多开发人员不会说英语或英语说得不流利。对于开发人员来说，这是一个可访问性问题，因此我们希望提供尽可能多语言的文档。

遗憾的是，BeeWare 的核心团队大部分成员都只会说英语。我们需要您的帮助，将我们的文档翻译成其他语言。

我们使用 Weblate 来管理我们的翻译工作。Weblate 是一种工具，可让我们将文档中的每一段内容都视为待办事项清单，一次完成一项。

我们使用 DeepL 进行机器翻译，以生成初稿译文。机器翻译远非完美，但作为初稿通常已经足够好了。我们希望对这些机器翻译进行必要的编辑、审核和改进。

提供翻译¶

翻译内容

开始翻译¶

如果您想为BeeWare的翻译工作做出贡献，您需要在Weblate上注册一个账户。如果您目前没有账户，请创建一个新账户；然后让我们知道您有兴趣帮助翻译工作。

有两种方式可以让我们知道您愿意帮助翻译：

如果您在 Discord 上，请加入 BeeWare 服务器，并前往 #translations 频道。
如果您不在 Discord 上，可以在 BeeWare 存储库中创建新问题。

在这两种情况下，请留言，包括以下信息：

您的 Weblate 用户名
您计划将内容翻译成的语言

一旦我们获得这些信息，就会将您加入团队。

添加新译文¶

如果您计划提供帮助的语言还不存在，那么在开始之前还需要一些额外的步骤：

创建包含特定语言内容的 /docs/mkdocs.language-code.yml 文件。
更新 tox.ini 以包含新的语言构建命令。
更新 /docs/config.yml，在 extra: alternate: 中包含语言。

下面以德语为例说明必要的更改；德语翻译已经存在；请替换对德语、"de "或其他目标语言内容的引用。

新的 MkDocs 配置文件¶

首先，在 docs 目录中新建一个名为 mkdocs.de.yml 的文件，内容如下：

INHERIT: config.yml
site_name: BeeWare Dokumentation
site_url: https://beeware.org/de
docs_dir: de

theme:
  language: de

extra:
  translation_type: machine

下面是这个文件的内容：

该文件继承了 config.yml 中的配置内容。
网站名称 "值将被翻译。
site_url "值是项目网站的 URL，后面是语言代码。
docs_dir "应为语言代码。
theme:language:值应该是[MkDocs Material theme指定的](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/)语言代码。对于大多数语言来说，这与docs_dir语言代码相同；但对于某些语言（尤其是像zh_CN` 这样有本地化变体的语言）来说，则存在差异。
在翻译首次达到 100% 之前，"extra: translation_type: "应为 "machine"，此时应为 "human"。如果低于 90%，它将从 "人 "返回到 "机器"。

更新 `tox.ini¶

您需要对 tox.ini 文件进行几处修改。

您可以添加以下内容：

新语言代码环境标志到以 [testenv:docs]开头的页眉行，语言代码前加 -，不含空格，例如 -de。
新语言代码不包括第一条命令，该命令以 !lint 开头，前面加上 -!，不含空格，例如 -!de。
将新语言代码添加到以 translate : build_po_translations 开头的行尾。
在以 translate : update_machine_translations 开头的一行末尾添加新的语言代码
在其他现有的特定语言命令之后，添加一条新命令，例如，德语命令以 de : build_md_translations 开头，将这些命令的内容与新的语言代码相匹配。
将新语言代码添加到以 "all,serve :`"开头的行尾。

更新 `config.yml`¶

将语言添加到 config.yml 中，使其显示在页眉的语言选择器中。找到以 extra: 开头的部分，然后找到以 alternate: 开头的小节。对于德语，您可以添加以下内容：

    - name: Deutsch
      link: /de/
      lang: de

语言名称应翻译成该语言。链接必须包括 /。

新语言现在可以开始翻译了。

翻译指南¶

加入团队后，您就可以登录 Weblate 并开始翻译字符串。

语气翻译与逐字翻译¶

保持英文文本的语气比一字不差地翻译更重要。我们在内容上尽量友好，有点口语化；在翻译中尽量保持这种精神。

如果英文文本中包含一个很强的英语习惯用语，如果您的语言中也有类似的习惯用语，请不要觉得必须保留该习惯用语。如果英文文本中的术语或短语是一个特别成语或俚语，不要害怕告诉我们应该考虑进行修改。即使对英语使用者来说，成语和俚语也会造成困难。有时，我们需要对英文文本进行修改，以便让译者和读者都能更直观地理解。

我应该翻译吗？¶

以下项目不应翻译或更新：

命令。例如，在 "You should run `briefcase create`." 中，只需翻译 "You should run"。
命名空间，例如类名、方法名或属性名。
链接URL。标准的Markdown链接在Weblate中应显示为[链接文本]{1}，其中1是链接在字符串中的位置，与其他可能的链接相对应。如果字符串中包含完整的URL，如[链接文本](https://example.com)，则在翻译时应跳过该URL。
** 包含类名、方法名或属性名的引用链接**。这些链接应保持原样，包括反标。此处所示示例链接的每一部分都不会被翻译。
```
[`Class.attribute`][Class.attribute]
```
引用链接的链接内容。例如，在以下内容中，link-content 将被跳过：
```
[Link text][link-content]
```
忍者指令。这是指包在两对匹配的大括号内的任何内容，或一对匹配的单个大括号内的任何内容，两端均带有百分号。注：在此处包含语法示例会导致 Macros 插件尝试呈现该语法；有关示例，请参阅 Macros 文档。
自定义锚点。它们位于标题之后或某些内容之上，格式为 { #anchor }。
训诫语法。在下面的例子中，"训诫 "一词不应翻译。这适用于所有类型的训诫，包括注释、警告等。有关翻译其余内容的信息，请参阅下一节。
```
/// admonition | Page Title

Content.

///
```
反标。它们应保持为反标；用于格式化内联代码和代码块。
包含外部内容的语法。这是指与 -8<- 在同一行的任何内容，或在两个独立行的 -8<- 之间的任何内容。

下列项目_应该_翻译：

链接文本。在链接语法中，文本位于URL之前，并用括号括起来，如[链接文本](URL)。标准的Markdown链接在Weblate中应显示为[链接文本]{1}，其中1是链接在字符串中的位置，与其他可能的链接相对应。
参考链接文本。例如，Link text将在以下内容中被翻译：
```
[Link text][link-content]
```
告诫标题和内容。在前面的训诫示例中，应翻译 "页面标题 "和 "内容"。

网络版¶

我们使用 Weblate 进行内容翻译。当我们添加新的翻译时，我们会使用 DeepL 进行机器翻译，以生成第一遍翻译。这意味着，通常情况下，您要翻译的内容已经过机器翻译。我们希望您作为译员能够审阅、编辑和改进现有的机器翻译。

Weblate 以字符串为单位处理所有内容。它对更改进行批量处理，每隔几个小时就会提交一次批量提交，其中包括在该时间段内更改过的所有字符串。因此，您的更改可能需要几个小时才能显示在网站上，但您可以期待更新在四个小时内出现。

若在此之后您的修改仍未显示，很可能是标记错误导致该语言的文档构建失败。任何字符串中的标记问题都会阻碍整个翻译版本的发布。您可随时查看您语言的构建页面，确认是否构建成功。链接格式与法语构建页面类似：https://app.readthedocs.org/projects/beewareorg/; 将语言代码替换为您对应的语言代码即可查看该语言的构建页面。该页面将显示网站最近一次构建的状态。若构建失败，请查阅构建日志以定位问题根源。