如何为OpenHarmony贡献（14）：内容应面向全球

我们的文档面向全球的开发者。通常比较可靠的做法是假定我们的内容将在许多国家以及被非英语母语的读者阅读，而且有些内容甚至可能会被翻译成其他语言或进行本地化。

1.1 图片

在翻译过程中，我们应依据以下准则来创建或选择面向全球读者，且合法、无偏见的图片。

颜色

颜色可能具有宗教、文化或政治意义，特别是用于国旗或特定国家或地区节日的颜色。除非有特别需要，一般建议使用中性颜色。

此外，在使用颜色时，应注意以下两点：

l   红绿色盲人群难以区分红色和绿色。

l   文本颜色与背景颜色构成足够的对比度。

图片

选择在全球范围内通用的图片。避免：

l   体现特定地区假日或季节性的图片。

l   使用可能受到法律保护或与政治、宗教有关的重大地标和知名建筑。

l   使用手势。

l   使用基于中英语习语的图片。

受限使用在线图形和动画。在某些国家或地区，长时间的页面加载可能会导致昂贵的流量资费。

尽量保证图形中文本是可编辑的。否则，自动翻译/阅读软件（例如，视觉障碍人士辅助阅读软件）无法对其内容进行翻译。如果可能，尽量通过标题或文字描述图形。

为图片创建描述性Alt text，特别是按钮图像，因为部分读者可能无法理解这些图片。

检查是否涉及国家或地区对特定内容的限制。要特别小心地图，这可能会受到政府监管。在一些国家，对有争议地区的不当处置可能是非法的。

如需使用界面截图，应确保截图中并没有真实密码和用户名等个人信息。

1.2 币种

货币名称

通常情况下，货币名称小写，但对国家或地区的引用大写。

示例：

US dollar

Canadian dollar

Hong Kong SAR dollar

Brazilian real

South African rand

在一个结构化的列表里，例如一个比较可用定价选项的表格中，可以将货币的名称大写。

特定货币金额

当提及某个国家或地区的货币名称本身时，推荐使用“国家或地区名称+空格+货币名称”的样式。

示例：

US dollar

Canadian dollar

当提及特定金额时，推荐使用ISO货币代码，即“货币代码+空格+金额”。

示例：

The computer is priced at USD 200.

A price of USD 3 million was agreed upon by both firms.

Teenage consumers account for an annual market of some EUR 15 billion.

1.3 示例

使用全球化的示例和用例。虚构的例子，包括人员、地点或组织名称，是潜在的敏感性信息。对特定客户与产品、服务或技术交互的详细描述亦是如此。

敏感谨慎地对待用例场景在其他文化中可能被理解的方式。社会状况、政治、宗教、事件、节日、体育、传统、法律和商业惯例在全世界都各不相同。例如，茶馆在世界上许多地方并不常见，而在某些文化中，男女在公共场合不会接触，甚至不会握手。

避免使用特定国家的标准作为全球通用的技术和标准的替代。国际标准和国家标准是不同的，例如纸张大小、字符集和文本方向。

1.4 命名

不要在示例中使用真实的域名、电子邮件地址或人名。

特殊情况下，可提供诸如域名、电子邮件地址、人名或电话号码之类的虚构示例，但在大部分情况下，最好使用占位符变量，如客户身份或邮件地址。

客户信息

创建收集个人信息的真实或示例表单时，请遵循以下准则。

称呼

使用头衔，而不是称号，来描述诸如Mr.（先生）和Mrs（夫人）之类的词语。并非所有的文化都有与美国使用的某些头衔意义相等的称号，如Ms。

地址

使用国家或地区，而不是仅仅使用国家来概括有争议的领土。如果空间有限，可以使用国家/地区。

名称

在某些市场和文化中，用姓名称呼客户是不合适的，例如在电子邮件中或产品主页上。请根据客户所在的地区使用适合该地区的称谓格式。

域名地址

当需要在示例中使用通用域名时，请使用example.com、example.org或example.net。

电邮地址

在示例中需要通用电子邮件地址时，请使用用户名长度小于6个字母的Gmail地址。因为Gmail不允许过短的用户名，这种方法可以确保不会意外地给出一个真正存在的用户名。例如：[email protected]或[email protected]。

人名

当编写的文本中出现使用人名例子时，我们应确保该例子是使用非版权书籍中虚构人物的名字。否则，我们应确保使用世界著名的人物，从而减少翻译的困难。

如果我们想不出一个没有版权的著名的虚构角色，那么我们可以编造名字。但是，如果这样做，请谨慎地包括反映真实世界多样性的不同名称。

一个例外是，如果您正在编写有关安全性的概念文档。在这种情况下，通常使用Alice、Bob、Eve等名字。有关更多信息，请参阅维基百科中的Alice and Bob。

公司名称

示例中需要公司名称时，请使用示例公司。如果您需要区分两个不同的虚构公司，您可以添加描述的公司名称。例如，可以使用ExampleCompanyA和ExampleCompanyB。

非必要情况下，避免直接引用特定的公司名称。

电话号码

示例中不要使用真实电话号码。

北美电话号码

要格式化美国、加拿大和其他北美编号计划国家的电话号码：将区号括在括号内，后面跟一个空格，然后用三位交换局号码连接四位数字线路号码。

示例：

(415) 555-0123

美国的电话号码请使用(800) 555-0100至(800) 555-0199范围内号码。这个范围的电话号码专用于电话号码示例和小说场景。有关更多信息，请参阅维基百科说明：

555 (telephone number)

https://en.wikipedia.org/wiki/555_(telephone_number)

 在极少情况下，当我们需要提供真实电话号码与真实的人联系时，根据号码是在北美或是其他地方，使用以下格式。

国际电话号码

要格式化非北美编号计划国家或地区的电话号码：在号码中包括国家或地区的代码。数字组之间用空格隔开。在国家代码前面插入一个加号（没有空格）；加号代表一个称之为“exit code”的前缀，它允许您向国外拨号。每个国家都有不同的exit code。

有关更多信息，请参阅ITU document on standardized formatting for phone numbers。

示例：

+1 415 555 0123

下面是电话号码格式的一些示例：

IP地址

在例子中（如日志里）需要IP地址时，请使用RFC 5737地址之一，以适用于文档目的。这些地址并不在Internet上使用。包括：

192.0.2.1

198.51.100.1

203.0.113.1

地址范围：

192.0.2.0/24

198.51.100.0/24

203.0.113.0/24

1.5 文件

在书写文件类型时，优先使用正式文件类型名称。（文件类型名称通常在所有大写字母中，因为许多文件类型名称都是首字母的缩写。）如情况允许，避免使用文件扩展名来泛指文件的类型。

示例：

下表列出了可以使用的文件扩展名和相应的文件类型名称的示例。

1.6 语言

语言名称由两个字符的代码表示。

l   国际权威机构：国际标准化组织（ISO），http://www.iso.org

l   标准：ISO 639

l   用法：语言在表格、列或行中用两个字符的代码表示，明确表示该代码代表一种语言。

下表显示了语言代码的示例。

在某些情况下，您可能需要在代码中添加一个扩展部分以表示特定的本地化。

1.7 国家

国家名称用两个字符的代码表示。

l   国际权威机构：国际标准化组织（ISO），http://www.iso.org

l   标准：ISO 3166

l   用途：国家在表、列或行中用两个字符的代码表示，明确表示该代码代表一个国家。

下表显示了国家代码的示例。

1.8 商标和产品名称

遵循商标所有者提供的使用指南。除界面或表格抬头等空间限制特殊场景，在可行的情况下尽量使用完整的产品名称，而不是缩写。

注：本文观点参考了业界风格指南，包括但不限于微软风格指南、Google开发者资料风格指南等。