支持多种语言

Doxygen 内置支持多种语言。这意味着 Doxygen 生成的文本片段可以以英语（默认）以外的语言生成。输出语言通过配置文件（默认名称为 Doxyfile）中的配置选项 OUTPUT_LANGUAGE 选择。要在评论块内切换语言，可以使用 \~ 命令。

目前（版本 1.15.0），支持 42 种语言（按字母顺序排序）：南非语、阿拉伯语、亚美尼亚语、巴西葡萄牙语、保加利亚语、加泰罗尼亚语、中文、繁体中文、克罗地亚语、捷克语、丹麦语、荷兰语、英语、世界语、芬兰语、法语、德语、希腊语、印地语、匈牙利语、印度尼西亚语、意大利语、日语（+英语）、韩语（+英语）、拉脱维亚语、立陶宛语、马其顿语、挪威语、波斯语、波兰语、葡萄牙语、罗马尼亚语、俄语、塞尔维亚语、西里尔语塞尔维亚语、斯洛伐克语、斯洛文尼亚语、西班牙语、瑞典语、土耳其语、乌克兰语和越南语。

下面是支持语言相关信息表。它按字母顺序排序。状态列是从源代码生成的，显示了翻译人员最后更新的大致版本。

语言	维护者	联系地址（替换 at 和 dot）	状态
南非语	Johan Prinsloo	johan at zippysnoek dot com	1.6.0
阿拉伯语	Moaz Reyad Muhammad Bashir Al-Noimi	[已辞职] mbnoimi at gmail dot com	1.4.6
亚美尼亚语	Armen Tangamyan	armen dot tangamyan at anu dot edu dot au	1.8.0
巴西葡萄牙语	Fabio "FJTC" Jun Takada Chino	jun-chino at uol dot com dot br	最新
保加利亚语	Kiril Kirilov	kpkirilov at abv dot bg	1.9.4
加泰罗尼亚语	Maximiliano Pin Albert Mora	max dot pin at bitroit dot com [无法联系]	1.8.0
中文	连杨李道兵刘伟	lian dot yang dot cn at gmail dot com lidaobing at gmail dot com liuwei at asiainfo dot com	最新
繁体中文	Daniel YC Lin Gary Lee	dlin dot tw at gmail dot com garywlee at gmail dot com	1.8.15
克罗地亚语	Boris Bralo	boris dot bralo at gmail dot com	1.8.2
捷克语	Petr Přikryl	prikryl at atlas dot cz	1.9.6
丹麦语	Poul-Erik Hansen Erik Søe Sørensen	pouhan at gnotometrics dot dk eriksoe+doxygen at daimi dot au dot dk	1.8.0
荷兰语	Dimitri van Heesch	doxygen at gmail dot com	最新
英语	Dimitri van Heesch	doxygen at gmail dot com	最新
世界语	Ander Martínez	ander dot basaundi at gmail dot com	1.8.4
芬兰语	Antti Laine	antti dot a dot laine at tut dot fi	1.6.0
法语	David Martinet Xavier Outhier Benoît BROSSE	contact at e-concept-applications dot fr xouthier at yahoo dot fr Benoit dot BROSSE at ingenico dot com	1.9.5
德语	Peter Grotrian Jens Seidel	Peter dot Grotrian at pdv-FS dot de jensseidel at users dot sf dot net	最新
希腊语	Paul Gessos	gessos dot paul at yahoo dot gr	最新
印地语	Harsh Rathod	hrathore50 at ymail dot com	1.9.4
匈牙利语	Ákos Kiss Földvári György	akiss at users dot sourceforge dot net [无法联系]	1.8.15
印度尼西亚语	Hendy Irawan	ceefour at gauldong dot net	1.8.0
意大利语	Alessandro Falappa Ahmed Aldo Faisal	alex dot falappa at gmail dot com aaf23 at cam dot ac dot uk	1.8.15
日语	Suzumizaki-Kimikata Hiroki Iseri Ryunosuke Satoh Kenji Nagamatsu Iwasa Kazmi	szmml at h12u dot com goyoki at gmail dot com sun594 at hotmail dot com [无法联系] [无法联系]	1.8.15
日语（英语）	参见日语		基于英语
韩语	金泰东 SooYoung Jung Richard Kim	fly1004 at gmail dot com jung5000 at gmail dot com [无法联系]	1.8.15
韩语（英语）	参见韩语		基于英语
拉脱维亚语	Lauris Fedosov Artyom Dmitrievich	lauris at nix dot lv artjomsfedosovs2 at gmail dot com	最新
立陶宛语	Tomas Simonaitis Mindaugas Radzius Aidas Berukstis ——寻找维护者——	[无法联系] [无法联系] [无法联系] [请帮忙寻找。]	1.4.6
马其顿语	Slave Jovanovski	slavejovanovski at yahoo dot com	1.6.0
挪威语	Lars Erik Jordet	lejordet at gmail dot com	1.4.6
波斯语	Ali Nadalizadeh	nadalizadeh at gmail dot com	1.7.5
波兰语	Piotr Kaminski Grzegorz Kowal Krzysztof Kral Marek Ledworowski	[无法联系] [无法联系] krzysztof dot kral at gmail dot com mledworo at gmail dot com	最新
葡萄牙语	Rui Godinho Lopes Fabio "FJTC" Jun Takada Chino	[已辞职] jun-chino at uol dot com dot br	最新
罗马尼亚语	Ionut Dumitrascu Alexandru Iosup	reddumy at yahoo dot com aiosup at yahoo dot com	1.8.15
俄语	Brilliantov Kirill Vladimirovich Alexandr Chelpanov	brilliantov at byterg dot ru cav at cryptopro dot ru	最新
塞尔维亚语	Dejan Milosavljevic	[无法联系]	1.6.0
西里尔语塞尔维亚语	Nedeljko Stefanovic	stenedjo at yahoo dot com	1.6.0
斯洛伐克语	Kali+Laco Švec Petr Přikryl	[斯洛伐克语顾问] prikryl at atlas dot cz	1.8.15
斯洛文尼亚语	Matjaž Ostroveršnik	matjaz dot ostroversnik at ostri dot org	1.4.6
西班牙语	Bartomeu Francisco Oltra Thennet David Vaquero	bartomeu at loteria3cornella dot com [无法联系] david at grupoikusnet dot com	1.9.6
瑞典语	Björn Palmqvist	bjorn dot palmqvist at aidium dot se	1.9.6
土耳其语	Emin Ilker Cetinbas	niw3 at yahoo dot com	1.7.5
乌克兰语	Olexij Tkatchenko Petro Yermolenko	[已辞职] python at i dot ua	1.8.4
越南语	Dang Minh Tuan	tuanvietkey at gmail dot com	1.6.0

列表中大多数人都表示他们也很忙，所以如果您想加快速度，请告知他们（或我）。

如果您想添加尚未列出的语言支持，请阅读下一节。

向 doxygen 添加新语言

这份简短的操作指南解释了如何向 doxygen 添加新语言支持

只需遵循以下步骤

告诉我您想添加哪种语言（例如 YourLanguage）的支持。如果还没有其他人正在开发该语言的支持，您将被指定为该语言的维护者。
在文件 doxygen/src/config.xml 中，在 OUTPUT_LANGUAGE 部分的适当位置添加以下行
```
      <value name='YourLanguage'/>
```
创建 doxygen/src/translator_en.h 的副本，并将其命名为 doxygen/src/translator_<your_2_letter_country_code>.h。在本文档的其余部分，我将使用 xx（大写版本使用 XX）。

编辑 doxygen/src/language.cpp：添加以下代码

#include<translator_xx.h>

现在，在 setTranslator() 中添加

case OUTPUT_LANGUAGE_t::YourLanguage: theTranslator = new TranslatorYourLanguage; break;

编辑 doxygen/src/translator_xx.h
- 使用支持 UTF-8 的编辑器，并以 UTF-8 模式（非 BOM 模式）打开文件。
- 将 TRANSLATOR_EN_H 重命名为 TRANSLATOR_XX_H 两次（即在文件开头的 #ifndef 和 #define 预处理器命令中）。
- 将 TranslatorEnglish 重命名为 TranslatorYourLanguage
- 在成员 idLanguage() 中，将 "english" 更改为您的语言名称（只使用小写字母）。根据语言，您可能还需要更改成员函数 latexLanguageSupportCommand() 和其他（您在开始工作时会认出它们）。
- 编辑所有以 tr 开头的成员函数返回的字符串。尝试匹配标点符号和大小写！要输入特殊字符（带重音符号），您可以
  - 如果您的键盘支持，则直接输入。请记住，文本应使用 UTF-8 编码保存。Doxygen 会将字符转换为正确的 ${\LaTeX}$ 格式，并将 HTML 和手册页输出保留为 UTF-8。
  - 使用 HTML 代码，例如 &auml; 代表带 umlaut 的 a (即 ä)。请参阅 HTML 规范获取代码。
编辑 doxygen/doc/maintainers.txt 并将自己添加到维护者列表中，如下所示
TranslatorYourLanguage

<你的名字>: <你的电子邮件地址（dot 替换为 .，at 替换为 @）>
通过给出适当的构建命令（例如：make docs）来构建文档。
现在您可以在配置文件中使用 OUTPUT_LANGUAGE = your_language_name 来生成您的语言输出。
首选方式是在 GitHub 上克隆 doxygen 存储库并提交拉取请求。或者将 translator_xx.h 发送给我，以便我将其添加到 doxygen。同时发送您的姓名和电子邮件地址，以便包含在 maintainers.txt 列表中。

维护语言

Doxygen 的新版本可能会使用新的翻译句子。在这种情况下，Translator 类需要实现新的方法——其接口会发生变化。当然，英语句子需要翻译成其他语言。至少，语言相关的翻译器类必须实现新方法；否则，doxygen 甚至无法编译。等到所有语言维护者都翻译完新句子并发送结果是不太实际的。以下文本描述了翻译器适配器的使用来解决这个问题。

翻译器适配器的作用。 每当 Translator 类接口在新版本中发生变化时，新的类 TranslatorAdapter_x_y_z 将被添加到 translator_adapter.h 文件中（这里 x、y 和 z 是与 doxygen 当前官方版本对应的数字）。所有以前从 Translator 类派生的翻译器现在都从这个适配器类派生。

TranslatorAdapter_x_y_z 类实现了新的、必需的方法。如果新方法替换了某些类似但已过时的方法（例如，如果参数数量发生变化和/或旧方法的功能发生变化或丰富），TranslatorAdapter_x_y_z 类可以使用过时方法来获取目标语言中尽可能接近旧结果的结果。如果不可能，则使用英文翻译器（根据定义，始终是最新的）获取结果（默认翻译）。

例如，当引入带有参数（用于确定首字母大小写和单复数形式）的新 trFile() 方法以替换不带参数的旧方法 trFiles() 时，以下代码出现在其中一个翻译器适配器类中

    /*! This is the default implementation of the obsolete method
     * used in the documentation of a group before the list of
     * links to documented files.  This is possibly localized.
     */
    virtual QCString trFiles()
    { return "Files"; }

    /*! This is the localized implementation of newer equivalent
     * using the obsolete method trFiles().
     */
    virtual QCString trFile(bool first_capital, bool singular)
    {
      if (first_capital && !singular)
        return trFiles();  // possibly localized, obsolete method
      else
        return english.trFile(first_capital, singular);
    }

trFiles() 不存在于 TranslatorEnglish 类中，因为它已被删除为过时。然而，它一直被使用，其调用已被替换为

    trFile(true, false)

在 doxygen 源文件中。可能许多语言翻译器都实现了过时的方法，因此在这些情况下使用相同的语言相关结果是完全有意义的。TranslatorEnglish 不实现旧方法。它派生自抽象的 Translator 类。另一方面，不同语言的旧翻译器不实现新的 trFile() 方法。因此，它派生自另一个基类——TranslatorAdapter_x_y_z。TranslatorAdapter_x_y_z 类必须实现新的、必需的 trFile() 方法。然而，如果 trFiles() 方法未实现，翻译器适配器将不会编译。这是在翻译器适配器类中实现旧方法（使用与从 TranslatorEnglish 中删除的相同代码）的原因。

最简单的方法是将参数传递给英文翻译器并返回其结果。相反，适配器在一种特殊情况下使用旧的 trFiles()——当调用新的 trFile(true, false) 时。这是在引入新方法时最常用的情况——参见上文。虽然这可能看起来过于复杂，但这种技术允许核心源代码开发人员更改 Translator 接口，而用户甚至可能不会注意到更改。当然，当新的 trFile() 与不同的参数一起使用时，将返回英文结果，非英语用户会注意到这一点。此时，语言翻译器的维护者应至少实现那个特定的方法。

语言翻译器的基类说明了什么？ 如果语言翻译器类继承自任何适配器类，则需要维护。在这种情况下，语言翻译器被认为不是最新的。另一方面，如果语言翻译器直接派生自抽象类 Translator，则语言翻译器是最新的。

翻译器适配器类是链式的，因此旧的翻译器适配器类使用一步更新的翻译器适配器作为基类。更新的适配器比旧的适配器做的“适配”工作更少。最旧的适配器类（间接）派生自所有适配器类。适配器类的名称选择使其后缀派生自不需要适配器的 doxygen 以前的官方版本。这样，可以大致说明语言翻译器类最后更新的时间——详见下文。

最新的翻译器适配器派生自抽象的 TranslatorAdapterBase 类，该类直接派生自抽象的 Translator 类。它只添加了私有英文翻译器成员，以便在适配器类内部轻松实现默认翻译，并且它还强制实现一个方法，用于通知用户语言翻译不是最新的（因此生成的文件中可能会出现一些英文句子）。

一旦最旧的适配器类不再被任何语言翻译器使用，就可以将其从 doxygen 项目中删除。维护者应该尝试达到适配器类数量最少的状态。

为了简化对支持语言的语言翻译器类的维护， 开发了 translator.py Python 脚本（位于 doxygen/doc 目录）。它从每个语言的源文件中提取有关过时和新方法的重要信息。这些信息存储在翻译器报告 ASCII 文件 (translator_report.txt) 中。

您可以找到此文件，链接为 translator_report.txt。

通过查看语言翻译器的基类，脚本还会猜测翻译器的状态——参见上面语言表的最后一列。当生成 doxygen 文档时，会自动调用 translator.py。您也可以随时手动运行该脚本，只要您觉得它能帮助您。当然，您不必使用脚本的结果。您可以通过查看适配器类及其基类找到相同的信息。

我应该如何更新我的语言翻译器？ 首先，您应该成为该语言的维护者，或者您应该让他/她了解这些更改。以下文本是为语言维护者撰写的，作为主要受众。

更新语言时有几种方法。如果您不是特别忙，您应该始终选择最彻底的方法。如果更新花费的时间比您预期的时间长得多，您随时可以决定使用合适的翻译器适配器稍后完成更改，并使您的翻译器仍然可以工作。

更新语言翻译器最彻底的方法 是让您的翻译器类直接派生自抽象类 Translator，并为需要实现的方法提供翻译——如果您忘记实现其中一些，编译器会告诉您。如果您有疑问，可以查看 TranslatorEnglish 类以识别已实现方法的用途。查看以前使用的适配器类有时可能会对您有所帮助，但也可能具有误导性，因为适配器类也实现了过时的方法（请参阅前面的 trFiles() 示例）。

换句话说，最新的语言翻译器根本不需要 TranslatorAdapter_x_y_z 类，您也无需实现除 Translator 类所需方法（即 Translator 的纯虚方法——它们以 =0; 结尾）之外的任何内容。

如果一切编译顺利，尝试运行 translator.py，并在 doxygen/doc 目录下查看翻译器报告（ASCII 文件）。只有当脚本没有检测到任何特殊情况时，您的翻译器才会被标记为最新。如果翻译器使用 Translator 基类，可能仍有一些与您的源代码相关的备注。在这种情况下，翻译器被标记为“几乎最新”。具体来说，未使用的过时方法可能会列在您的语言部分。只需删除它们的代码（并再次运行 translator.py）。此外，当您忘记将翻译器类的基类更改为某些更新的适配器类或直接更改为 Translator 类时，您将收到通知。

如果您没有时间完成所有更新， 您仍然应该从上面描述的最彻底的方法开始。您可以随时将基类更改为实现所有尚未实现方法的翻译器适配器类。

如果您更喜欢逐步更新您的翻译器， 请查看 TranslatorEnglish（translator_en.h 文件）。在其中，您会发现诸如 new since 1.2.4 的注释，它们总是分隔一组在所述版本中实现的方法。请实现位于使用与您的翻译器适配器类相同版本号的注释下方的这组方法。（例如，您的翻译器类必须使用 TranslatorAdapter_1_2_4，如果它没有实现注释 new since 1.2.4 下方的方法。当您实现它们时，您的类应该使用更新的翻译器适配器。）

偶尔运行 translator.py 脚本并提供您的 xx 标识（来自 translator_xx.h），以缩短翻译器报告（也生成更快）——它将只包含与您的翻译器相关的信息。一旦您达到基类应更改为某个更新适配器的状态，您将在翻译器报告中看到该注释。

警告：不要忘记编译 doxygen 以发现它是否可编译。translator.py 不检查编译器是否一切正常。因此，它有时可能在必要的基类方面说谎。

最过时的语言翻译器 将导致实现过于复杂的适配器。因此，doxygen 开发人员可能会决定让这些翻译器派生自 TranslatorEnglish 类，该类根据定义始终是最新的。

这样做时，所有缺失的方法都将替换为英文翻译。这意味着未实现的方法将始终返回英文结果。此类翻译器使用 obsolete 一词标记。您应该将其理解为真正过时。无法猜测上次更新的时间。

通常，可以从过时的方法中构建出更好的结果。因此，如果可能，应使用翻译器适配器类。另一方面，为真正过时的翻译器实现适配器会带来过多的维护和运行时开销。

转到下一节或返回索引。