Jump to content

帮助:系统消息

From mediawiki.org
This page is a translated version of the page Help:System message and the translation is 58% complete.
Outdated translations are marked like this.
Languages:
PD 注意：當您編輯本頁面時，即同意以CC0協議授權您的貢獻。您可以在公有領域帮助页面找到更多信息。 PD
i18n文档
Special:Upload表单的标签示意图，显示各种系统消息。

系统消息是纯文本、wiki语法、CSS或JavaScript代码片段，可以用来自定义页面和每种语言的外观和行为和区域设置。 MediaWiki使用消息的任何面向用户界面的一部分，用于核心和扩展的MediaWiki UI的国际化和本地化。 MediaWiki中使用的所有消息都在 消息文件 中。

覆盖Wiki上的消息

您可以通过在wiki上编辑消息来覆盖消息的默认值。 每条消息在MediaWiki命名空间中都有一个wiki页面，其消息键作为页面的名称。 例如，“aboutsite”消息存储在MediaWiki:aboutsite中。 默认情况下，除非用户具有“editinterface”权限，否则此命名空间将被禁止编辑。 可以在Special:AllMessages上找到所有消息页面的列表。 编辑界面消息通常很简单，就像编辑普通的wiki页面一样，但它仅限于具有editinterface权限的用户，默认情况下这个权限会分配给管理员（和界面管理员）。

旧Special:AllMessages的示例行。

Special:AllMessages表包含两列：链接的接口名称和文本。 文本水平分割以显示上面的默认文本，以及下面的自定义文本。 如果自定义消息不存在，则仅显示默认消息。 要自定义消息，请单击左列中的上部链接（消息名称）。 如果正在使用默认文本，则此链接为红色，因为编辑页面为空。

左列单元格中的下部链接指向该消息的讨论页面。

只有在以下情况下，才建议覆盖维基上的消息：

  • 这条消息有一个严重的错误，必须尽快纠正。 在这种情况下，如果是英文的，建议在源代码中也修复这个错误，如果不是，建议在维基翻译网上的翻译中修复这个错误。 在部署更正时，应该删除具有本地自定义的页面。
  • 如果本地维基使用不同的术语。 例如，很多信息使用“页面（page）”一词，但英文维基百科经常使用“文章（article）”。
  • 本地消息正在尝试添加一些独特的功能，例如用于小工具或模板。 （在这种情况下，仍然建议考虑更改源消息或将此功能封装在扩展中，以便其他Wiki能够方便地使用它，而不必手动复制定制。）

查找消息和文档

根据消息文档指南，MediaWiki如何使用每条消息，可用的变量，使用的参数，限制等等可以在qqq伪语言的完整文档中找到解释。 对于旧版分类:界面消息 中的某些接口消息，可能存在一些较长的解释页面。

在translatewiki.net的Wiki基础中，qqq是用于保存消息的用户文档的页面（因为对所有读者显示的内容都是相同的）。

与/en /ge /fr ... /qqq相同，它是文章的子页面，可以直接查看。

从这个角度来看，qqq被认为是请求参数language=中的一种语言。
MediaWiki版本：
≥ 1.18

MediaWiki 1.18以后，你可以使用?uselang=qqx或者&uselang=qqx（如果已经存在?了）的URL指令来查看一个页面的系统消息来源（示例）。 所有引用自系统消息的内容都会被一个key代替，告诉你这个内容来自哪一个系统消息。 使用内容语言显示的消息不会使用qqx显示。

如果页面使用例如标签，例如 特殊页面设置，你必须在uselang参数后面添加标签，例如Special:Preferences?uselang=qqx#mw-prefsection-rendering。

MediaWiki版本：
≥ 1.38
Gerrit change 765385

Before MediaWiki 1.38, fallback message keys were not shown, which made it difficult to identify the source of some messages, notably the page navigation tabs. Since MediaWiki 1.38 fallback message keys are shown separated by slashes (/).

MediaWiki版本：
≥ 1.43
Gerrit change 1025837

Before MediaWiki 1.43, override message keys (using hooks like MessageCacheFetchOverrides ) were not shown either, which made it difficult to identify the source of messages overridden by extensions (such as WikimediaMessages ). Since MediaWiki 1.43 override message key is shown after an equals sign (=).

本地化文件格式

MediaWiki中使用的所有消息都在 消息文件(MediaWiki命名空间) 中定义。

MediaWiki中有两种类型的消息文件：JSON和PHP。 截至2014年4月，核心MediaWiki和大多数维护的扩展已迁移到JSON格式。 您应该将JSON用于所有新开发。 有关迁移到JSON的更多信息，请参见 Requests for comment/Localisation format

JSON

从2013年底开始，引入了一种新的消息文件格式：JSON。 JSON，非常常见的数据存数格式。 其中的每个键都是消息键，值是消息文本。 此外，特殊的 @metadata 键用于存储有关翻译的信息，如翻译作者。

使用JSON使本地化文件更安全，因为它是不可执行的（JSON是纯文本）。 它还与jquery.i18n兼容，jquery.i18n是作为Project Milkshake的一部分开发的JavaScript库，它提供类似MediaWiki的前端本地化功能，并被一些希望减少对MediaWiki的依赖的扩展使用，如可视化编辑器和语言选择器。

由于更广泛的国际化和本地化工具被称为“Project Milkshake”，一些人将这种形式称为“香蕉”。

消息文件的所在位置

在MediaWiki核心中，本地化文件放在languages/i18n目录中。 MediaWiki扩展通常将它们的扩展放在i18n/的子目录中。 如果一个项目中存在大量消息，为了便于维护，可能需要将这些消息拆分到两个或多个主题子目录中。 如果一个项目中存在大量消息，为了便于维护，可能需要将这些消息拆分到两个或多个主题子目录中。 以下是MediaWiki的 VisualEditor 扩展的一个例子： 

{
  "MessagesDirs": {
    "VisualEditor": [
      "lib/ve/modules/ve/i18n",
      "modules/ve-mw/i18n",
      "modules/ve-wmf/i18n",
      "lib/ve/lib/oojs-ui/i18n"
    ]
  }
}

您可以将新消息添加到英文“en”消息文件en.json，并使用特殊的伪语言代码“qqq”&ndash；qqq.json将它们记录在消息文档文件中。 请看: 添加新消息.

元数据

目前，文件中使用以下元数据字段：

authors
消息作者的JSON列表。 对于英文(en)和消息文档(qqq)，这些是在编辑消息文件时手动添加的。 对于所有其他语言，从translatewiki.net中导出消息文件时会自动插入此选项。 可以在translatewiki.net上编辑消息文档，文档编辑器也会自动插入到qqq.json文件中。
message-documentation
这是用于存储消息文档的伪语言代码。 对于MediaWiki，这始终是qqq。 (这出现在一些扩展中，但实际上没有以任何方式进行处理。

这不是强制性的。)

公约

转义诸如换行符之类的特殊字符("\n")。

用不同字母表示字母的Unicode字符被存储为实际字符，而不是字符代码，因为这些文件有时会被人们读取，而且这会使文件变小("誼"而不是"\u8ABC")。 在任何情况下，开发人员几乎没有理由编辑除英语以外的任何语言的消息，因为这些消息通常是通过Translatewiki.net编辑的。

HTML代码也没有转义，因此是"<strong>Warning</strong>"而不是"\u003cstrong\u003eWarning\u003c/strong\u003e"。

JSON文件使用制表符进行缩进。

PHP

This section refers to the use of MessagesXx.php files for localizing messages, which has been deprecated in 2014. However, the files are still used for other language-specific configuration .

较早的本地化文件格式是PHP。 这实质上是一个包含所有消息的PHP数组。 在核心MediaWiki中，每种语言都驻留在MediaWiki源代码的languages/message目录中的自己的文件中。 在扩展中，所有语言和消息文档(qqq)都在同一个文件中：ExtensionName.i18n.php，通常位于扩展的主目录中。

要将系统消息从PHP迁移到JSON，请使用generateJsonI18n.php 脚本。 它会将消息移动到JSON文件，并用指向JSON文件的填充程序替换PHP文件的文本。 此样板代码是向后兼容MediaWiki 1.19所必需的。 它不用于不需要MediaWiki 1.19兼容性的新扩展中。

使用消息

MediaWiki使用由代码中的键引用的消息的中央存储库。 这不同于例如gettext系统，后者从源文件中提取可翻译的字符串。 基于密钥的系统让一些事情变得更容易，比如提炼原始文本和跟踪消息的更改。 缺点是使用的消息列表和这些键的源文本列表可能不同步。 在实践中，这不是一个大问题，唯一重要的问题是，有时不再使用的额外消息仍在等待翻译。

要使消息键更易于管理和搜索，请始终完整地编写它们，不要太依赖于动态创建它们。 如果你觉得能给你的代码带来更好的结构，你可以把消息键的几个部分连接起来--但只有在肯定有多种可能性的情况下才这么做，[1]，并且确保在旁边放上注释和可能产生的键的列表。 例子如下： 

// 可在此处使用的消息：
// * myextension-connection-success
// * myextension-connection-warning
// * myextension-connection-error
$text = wfMessage( 'myextension-connection-' . $status )->parse();

另请参阅动态标识符编码约定。

要在JavaScript中使用消息，您必须在您的ResourceLoader模块的定义中的"messages"属性中列出他。

有关在PHP和JavaScript中使用消息函数的详细信息，请参阅Manual:Messages API 。 这是一个重要的文档页，您应该在编写使用消息的代码之前阅读它。

消息源码

代码从以下来源查找系统消息：

  • MediaWiki命名空间 这允许维基在标准消息不适合或不需要时采用或覆盖其所有消息。
    • MediaWiki:消息名 是默认的消息存储位置
    • MediaWiki：消息名/语言名是当用户选择了维基默认语言以外的语言时使用的消息。
  • 来自消息文件：
    • 核心MediaWiki本身和大多数当前维护的扩展名按语言使用一个文件，名为zyx.json，其中zyx是该语言的语言代码。
    • 一些较旧的扩展使用一个组合的消息文件来保存所有语言的所有消息，通常命名为MyExtensionName.i18n.php。
    • 许多Wikimedia Foundation维基访问来自维基媒体消息 扩展的一些消息，允许他们标准化WMF维基中的消息，而无需将它们强加给每个MediaWiki安装。
    • 一些扩展使用其他技术。

缓存内容

系统消息是MediaWiki较重要的组件之一，主要是因为它用于每个Web请求。 PHP消息文件很大，因为它们存储了数千个消息键和值。 加载该文件(如果用户的语言与内容语言不同，还可能加载多个文件)具有很大的内存和性能成本。 一个积极的、分层的缓存系统被用来降低这种性能影响。

MediaWiki内置了许多缓存机制，这使得代码更难理解。 从1.16开始，有了一个新的缓存系统，它将消息缓存到cdb文件或数据库中。 根据配置的不同，自定义消息缓存在文件系统和memcached（或备选）中。

下表概述了所涉及的设置：

缓存文件的位置 $wgLocalisationCacheConf
'store' => 'db'
 		 'store' => 'detect'
(默认)		 'store' => 'files'
 		 'store' => 'array'
(从MediaWiki≥1.26开始试验)
$wgCacheDirectory = false
(默认) 		l10n cache table l10n cache table 错误 (未定义路径) 错误 (未定义路径)
= path l10n cache table 本地文件系统 (CDB) 本地文件系统 (CDB) 本地文件系统（PHP 数组）
MediaWiki版本：
1.27.0 – 1.27.2
Gerrit #Id3e2d2

在MediaWiki 1.27.0和1.27.1中，自动检测已更改为有利于文件后端。 在'store' => 'detect'(默认)的情况下，文件后端与从$wgCacheDirectory 开始的路径一起使用。 如果未设置此值(这是默认设置)，则使用由操作系统确定的临时目录。 如果无法检测到临时目录，则使用数据库后端作为后备。 由于共享主机上的文件冲突和安全问题(请参见T127127和T161453)，已从1.27.2和1.28.0恢复。

函数回溯

为了更好地直观地描述缓存层，这里有一个函数回溯，说明在检索消息时调用了哪些方法。 有关每一层的说明，请参阅以下各节。

  • Message::fetchMessage()
  • MessageCache::get()
  • Language::getMessage()
  • LocalisationCache::getSubitem()
  • LCStore::get()

消息缓存

MessageCache类是消息的顶级缓存。 它从Message类中调用，并返回消息的最终原始内容。 该层处理以下逻辑：

最后一颗子弹很重要。 后被语言如果原始文档没有请求消息，则允许MediaWiki退回到另一种语言。 如下一节所述，大多数语言回退解析都发生在较低级别。 但是，只有MessageCache层检查数据库中是否有被覆盖的消息。 因此，这里完成了将被覆盖的消息从数据库集成到回退链中。 如果不使用数据库，则可以禁用整个层。

本地化缓存

请看LocalisationCache.php

LCStore

LCStore类只是LocalisationCache类用于实际缓存和检索消息的后端实现。 与在MediaWiki中用于通用缓存的BagOStuff类类似，有许多不同的缓存类型(使用$wgLocalisationCacheConf 配置)：

  • “db”(默认)-在数据库中缓存邮件
  • “文件”(如果设置了$wgCacheDirectory，则为默认值)-使用cdb将消息缓存到本地文件中
  • “Accel”-使用APC或其他操作码缓存来存储数据

“FILE”选项由维基媒体基金会使用，之所以推荐它，是因为它比访问数据库更快，比APC缓存更可靠，特别是因为APC与PHP5.5或更高版本不兼容。

添加新消息

选择消息前缀

请看： 手册:代码编写约定

消息密钥必须是全局唯一的。 这包括核心MediaWiki以及所有的扩展和皮肤。

在消息名称中坚持小写字母、数字和下划线；大多数其他字符不太实用或根本不起作用。 根据MediaWiki约定，第一个字符不区分大小写，其他字符区分大小写。

请遵循全球或本地的命名约定。 对于扩展名，请使用标准前缀，最好是小写的扩展名，后跟连字符(“-”)。 例外情况包括：

消息使用系统API
它们必须以apihelp-、apiwarn-、apierror-开头。 在此前缀之后加上扩展前缀。 (请注意，这些消息应该位于单独的文件中，通常位于includes/i18/api.下)
日志相关消息
它们必须以logentry-、log-name-、log-description开头。
用户访问权限
Special:ListGroupRights上显示的权限名称键必须以right-开头。 完成句子“因为以下原因，您没有权限$2：”的操作的名称必须以action-开头。
自定义的标签（详情参见Special:Tags）
自定义的标签必须使用前缀tag-。
特殊页面标题
特殊页面标题必须使用前缀special-。
Extension descriptions
Extension descriptions must begin with the extension name and end with -desc.

They appear in the table on Special:Version, and their content must briefly explain what the extension does.

Gender

English messages almost never need different words that change because of a user's gender. English only needs this in the third-person pronouns "he" and "she", but these are surprisingly rare in messages. When this is necessary, use he or they.

However, many other languages need different words depending on the user's gender, not only for third-person pronouns, but also for other pronouns, as well as for verbs in different tenses (e.g. "created", "deleted"), nouns (e.g. "mentor", "administrator"), adjectives (e.g. "new"), etc. It is therefore often useful to use GENDER in English messages, even when there's only English word. This gives translators a hint that GENDER can be used in a message. It also avoids warnings on translatewiki about missing parameters when an optional username parameter is missing (this happens especially often in log entry messages).

创建消息时需要注意的其他事项

  1. 确保您对消息使用了适当的处理(解析、{{替换、转义为HTML等)。
  2. 如果您的消息是核心的一部分，则通常应该将其添加到languages/i18n/en.json，尽管一些组件，如Installer、EXIF标记和ApiHelp有它们自己的消息文件。
  3. 如果您的消息是扩展名，请将其添加到相应子目录中的i18n/en.json文件或en.json文件中。 特别是，只有开发人员才能看到而大多数最终用户不能看到的API消息通常位于单独的文件中，如i18n/api/en.json。 如果扩展名有很多消息，您可以在i18n下创建子目录。 所有消息目录，包括默认的i18n/，必须在extension.json的MessagesDirs部分或$wgMessagesDirs 变量中列出。
  4. 暂停一下，考虑一下这条信息的措辞。 是不是越清楚越好？ 它会被误解吗？如果可能的话，征求其他开发人员或本地化人员的意见。 遵循国际化提示。
  5. 将文档添加到同一目录中的qqq.json。
  6. 文件中消息的顺序应该大致符合项目的特点。将来自同一功能的消息放在一起。这有助于翻译人员保持专注、高效和一致。
  7. 将预计最基本和最频繁使用的消息放在文件的开头，将较罕见和技术更先进的消息放在文件末尾。

不应翻译的消息

  1. “已屏蔽”消息是那些应该只以英文存在的消息消息文件。 它们是不需要翻译的消息，因为它们只引用其他消息或语言无关的功能，例如。

一条“{{SITENAME}}”的消息。

  1. 只有在以目标语言更改的情况下，才能翻译“可选”消息。

To flag such messages:

删除现有消息

从en.json和qqq.json中删除它。 不要费心学习其他语言。 从translatewiki.net 开始的更新将自动处理这些更新。

此外，检查消息是否出现在转换维基配置中的任何位置，例如，在可选或最常用的消息列表中(一个简单的git grep就足够了)。 如果需要，请将其从这些列表中删除。

更改现有消息

  1. 考虑更新消息文档。
  2. 如果旧的翻译不适合新的含义，请更改消息键。 这还包括消息处理(解析、转义、参数等)的更改。 在没有技术更改的情况下改进消息的措辞通常不是更改密钥的理由。 在translatewiki.net上，这些翻译将被标记为过时，以便翻译人员可以针对它们。 更改消息密钥不需要与I18N团队交谈或提交支持请求。 但是，如果您有特殊情况或问题，请询问#translatewiki 在线或在支持页面中询问translatewiki.net 。
  3. 如果translatewiki.net 支持扩展，请仅更改英文源消息和/或密钥，以及qqq.json中的附带条目。 If needed, the translatewiki.net team will take care of updating the translations, marking them as outdated, cleaning up the file or renaming keys where possible. This also applies when you're only changing things like HTML tags which you could change in other languages without speaking those languages. Most of these actions will take place in translatewiki.net and will reach Git with about one day of delay.

消息文档

有一个用于记录信息的伪语言代码qqq。 它是ISO 639专用代码之一。 在那里，我们不保留每条信息的译文，而是收集关于每条信息 的英文句子：告诉我们它在哪里被使用，提示我们如何翻译它，列举并描述它的参数、相关信息的链接等。 在translatewiki.net，这些提示会在译员编辑信息时显示。

程序员必须记录每一条信息。 消息文档是一项重要资源——不仅对于翻译人员，而且对于模块的所有维护人员都是如此。 每当在软件中添加一条信息时，必须同时添加相应的qqq条目；没有这样做的修订版会被标记为“V-1”，直到文档添加完毕。

只有在添加新信息或更改现有英文信息时才可以直接编辑qqq文件中的文档，例如添加或删除参数。 其他情况下，通常应在translatewiki中编辑文档。 每个文档字符串都可以在https://translatewiki.net/wiki/MediaWiki:message-key/qqq中访问，就像翻译一样。 这些编辑将与翻译一起导出到源代码库。

文件中应包含的有用信息包括：

  1. 信息处理（解析、转义、纯文本）。
  2. 参数类型及示例值。
  3. 信息的使用位置（页面、用户界面中的位置）。
  4. 信息在使用处如何使用（页面标题、按钮文本等）。
  5. 与此信息一同使用的其他信息，或此信息指向的其他信息。
  6. 其他任何在上下文中看到信息时可以理解，但在单独显示信息时无法理解的内容（翻译时就是这种情况）。
  7. 语法的注意事项，如果存在。 例如，英语中的“open”既可以是动词，也可以是形容词。 在许多其他语言中，单词是不同的，没有文献资料是无法猜测如何翻译的。
  8. 描述事物的形容词，如“disabled”、“open”或“blocked”，必须总是说明它们描述的是什么。 在许多语言中，形容词的性别必须与所描述的名词一致。 不同种类的事物也可能需要不同的形容词。
  9. 如果信息具有特殊属性，例如，它是否是一个页面名称，或者它是否不应该直译，而应该根据文化或项目进行调整。
  10. 信息是否出现在其他信息附近，例如在列表或菜单中。 措辞或语法特征可能应与附近的信息相似。 此外，列表中的项目可能必须与列表标题适当关联。
  11. 信息中不得翻译的部分，如通用命名空间名称、URL或标签。
  12. 对可能不清楚的词语的解释，例如缩写词，如“CTA”，或特定术语，如“templat”、"suppress "或 "stub"。 （注意最好首先避免使用此类词语！）。
  13. 截图很有用。 不要裁剪——显示信息的全屏图像可提供完整的上下文，并可在多条信息中重复使用。

一些其他提示：

  • 请记住，很多时候翻译人员翻译信息时并没有真正使用那个软件。
  • 通常情况下，翻译人员没有任何上下文信息，既不知道您的模块，也不知道模块中的其他信息。
  • 在大多数情况下，仅靠重新措辞的信息是没有用的。
  • 不要使用设计师的专业术语，如“hamburger”、“nav”，或“comps”。
  • 考虑编写术语表，介绍模块中使用的专业术语。 如果你这样做了，请将信息文档链接到它。

您可以使用{{msg-mw|message key}}链接到其他信息。 如果部分信息来自其他信息（如果无法避免），或者某些信息一起显示或在同一上下文中显示，请这样做。

translatewiki.net提供了一些默认的文档模板：

  • {{doc-action|[...]}} - 用于action-消息
  • {{doc-right|[...]}} - 用于right-消息
  • {{doc-group|[...]|[...]}} - 用于用户组相关（group, member, page, js和css）的消息
  • {{doc-accesskey|[...]}} - 用于accesskey-消息

查看模板页面了解更多信息。

Internationalisation hints

Besides documentation, translators ask developers to consider some hints so as to make their work easier and more efficient and to allow an actual and good localisation for all languages. Even if only adding or editing messages in English, one should be aware of the needs of all languages. Each message is translated into more than 300 languages and this should be done in the best possible way. Correct implementation of these hints will very often help you write better messages in English, too.

Localisation#Help and contact info lists the main places where you can find the assistance of experienced and knowledgeable people regarding i18n.

Use message parameters and switches properly

That's a prerequisite of a correct wording for your messages.

Avoid message re-use

The translators discourage message re-use. This may seem counter-intuitive, because copying and duplicating code is usually a bad practice, but in system messages it is often needed. Although two concepts can be expressed with the same word in English, this doesn't necessarily mean they can be expressed with the same word in every language. "OK" is a good example: in English this is used for a generic button label, but in some languages they prefer to use a button label related to the operation which will be performed by the button. Another example is practically any adjective: a word like "multiple" changes according to gender in many languages, so you cannot reuse it to describe several different things, and you must create several separate messages.

If you are adding multiple identical messages, please add message documentation to describe the differences in their contexts. Don't worry about the extra work for translators. Translation memory helps a lot in these while keeping the flexibility to have different translations if needed.

Avoid fragmented or "patchwork" messages

Languages have varying word orders, and complex grammatical and syntactic rules. Messages formed by multiple pieces of text, possibly with some indirection, also called "string concatenation", in code that cannot be directly controlled by translators, are called "lego" or "patchwork" messages in developers' jargon. It's practically impossible to translate "lego" messages correctly.

Make every message a complete phrase. Several sentences can usually be combined much more easily into a text block, if needed. When you want to combine several strings in one message, pass them in as parameters, as translators can order them correctly for their language when translating.

Messages quoting each other

主页面： Manual:Messages API#Referring to other messages

An exception from the rule may be messages referring to one another: 'Enter the original author's name in the field labelled "{{int:name}}" and click "{{int:proceed}}" when done'. This makes the message consistent when a software developer or wiki operator alters the messages "name" or "proceed" later. Without the int-trick, developers and operators would have to be aware of all related messages needing adjustment, when they alter one.

Write messages in natural language

As much as possible, write messages in natural, human language. Try reading the message aloud and think: is this something that sounds like correct, grammatical English that humans speak? If it's complex, hard to pronounce, or in any way unnatural in English, it will be even harder for translators and for users in other languages.

Avoid punctuation that is too technical or bureaucratic or that can't be read aloud. Slash (/) should usually be replaced with or. And/or should be replaced with and or or. Sentences with comma splice should be split into shorter sentences.

Don't use terms and templates that are specific to particular projects

MediaWiki is used by very diverse people, within the Wikimedia movement and outside of it. Even though it was originally built for an encyclopedia, it is now used for various kinds of content. Therefore, use general terms. For example, avoid terms like "article", and use "page" instead, unless you are absolutely sure that the feature you are developing will only be used on a site where pages are called "articles". Don't use "village pump", which is the name of an English Wikipedia community page, and use a generic term, such as "community discussion page", instead.

Don't assume that a certain template exists on all wikis. Templates are local to wikis. This applies to both the source messages and to their translations. If messages use templates, they will only work if a template is created on each wiki where the feature is deployed. It's best to avoid using templates in messages completely. If you really have to use them, you must document this clearly in the message documentation and in the extension installation instructions.

Separate times from dates in sentences

Some languages have to insert something between a date and a time which grammatically depends on other words in a sentence. Thus, they will not be able to use date/time combined. Others may find the combination convenient, thus it is usually the best choice to supply three parameter values (date/time, date, time) in such cases, and in each translation leave either the first one or last two unused as needed.

Avoid {{SITENAME}} in messages

{{SITENAME}} has several disadvantages. It can be anything (acronym, word, short phrase, etc.) and, depending on language, may need the use of {{GRAMMAR}} on each occurrence. No matter what, each message having {{SITENAME}} will need review in most wiki languages for each new wiki on which your code is installed. In the majority of cases, when there is not a general GRAMMAR configuration for a language, wiki operators will have to add or amend PHP code so as to get {{GRAMMAR}} for {{SITENAME}} working. This requires both more skills, and more understanding, than otherwise. It is more convenient to have generic references like "this wiki". This does not keep installations from locally altering these messages to use {{SITENAME}}, but at least they don't have to, and they can postpone message adaption until the wiki is already running and used.

Avoid references to visual layout and positions

What is rendered where depends on skins. Most often screen layouts of languages written from left-to-right are mirrored compared to those used for languages written from right-to-left, but not always, and for some languages and wikis, not entirely. Handheld devices, narrow windows, and so on may show blocks underneath each other, that would appear side-by-side on larger displays. Since site- and user-written JavaScript scripts and gadgets can, and do, hide parts, or move things around in unpredictable ways, there is no reliable way of knowing the actual layout.

It is wrong to tie layout information to content languages, since the user interface language may not be the page's content language, and layout may be a mixture of the two depending on circumstances. Non-visual user agents like acoustic screen readers and other auxiliary devices do not even have a concept of visual layout. Thus, you should not refer to visual layout positions in the majority of cases, though semantic layout terms may still be used ("previous steps in the form", etc.).

MediaWiki does not support showing different messages or message fragments based on the current directionality of the interface (see T30997).

The upcoming browser and MediaWiki support for East and North Asian top-down writing[2] will make screen layouts even more unpredictable, with at least eight possible layouts (left/right starting position, top/bottom starting position, and which happens first).

Avoid references to screen colours

The colour in which something is rendered depends on many factors, including skins, site- and user-written JavaScript scripts and gadgets, and local user agent over-rides for reasons of accessibility or technological limitations. Non-visual user agents like acoustic screen readers and other auxiliary devices do not even have a concept of colour. Thus, you should not refer to screen colours. (You should also not rely on colour alone as a mechanism for informing the user of state, for the same reason.)

Avoid markup that doesn't need to be translated

HTML markup not requiring translation, such as enclosing ‎<div> tags, rulers above or below, and similar, should usually not be part of messages. It's an unnecessary burden on translators, and is often accidentally altered or skipped in the translation process. The translation interface has no syntax highlighting or validation, and mistakes are common.

Avoid complex wikitext markup as well. Wikitext is sometimes terser than writing the same thing in PHP, and it's tempting to write something like:

MediaWiki:Revreview-basic/en
This is the [[{{MediaWiki:Validationpage}}|stable version]], [{{fullurl:{{#Special:Log}}|type=review&page={{FULLPAGENAMEE}}}} checked] on <i>$2</i>.
[{{fullurl:{{FULLPAGENAMEE}}|oldid=$1&diff=cur}} $3 pending {{PLURAL:$3|change|changes}}] {{PLURAL:$3|awaits|await}} review.

However, this is difficult for translators, especially when translating to right-to-left languages, because parts of the message must remain in English, resulting in text direction changing many times in one line:

MediaWiki:Revreview-basic/ar
هذه هي [[{{MediaWiki:Validationpage}}|النسخة المستقرة]]، [{{fullurl:{{#Special:Log}}|type=review&page={{FULLPAGENAMEE}}}} المفحوصة] في <i>$2</i>.
[{{fullurl:{{FULLPAGENAMEE}}|oldid=$1&diff=cur}} {{PLURAL:$3||تغيير واحد معلق|تغييران معلقان|$3 تغييرات معلقة|$3 تغييرا معلقا|$3 تغيير معلق}}] {{PLURAL:$3||ينتظر|ينتظران|تنتظر|ينتظر}} المراجعة.

It's best to pass any link targets as message parameters, and use only simple markup like [$1 Label] and [[$1|Label]].

Translated messages are often longer than you think!

Skimming foreign language message files, you almost never find translated messages shorter than Chinese ones and rarely shorter than English ones. However, you will often find translations that are much longer than English ones.

Especially in forms, in front of input fields, English messages tend to be terse, and short. That is often not kept in translations. Languages may lack the technical vocabulary present in English, and may require multiple words or even complete sentences to explain some concepts. For example, the brief English message "TSV file:" may have to be translated in a language as literally:

Please type a name here which denotes a collection of computer data that is comprised of a sequentially organised series of typewritten lines which themselves are organised as a series of informational fields each, where said fields of information are fenced, and the fences between them are single signs of the kind that slips a typewriter carriage forward to the next predefined position each. Here we go: _____ (thank you)

This is, admittedly, an extreme example, but you get the trait. Imagine this sentence in a column in a form where each word occupies a line of its own, and the input field is vertically centered in the next column. :-(

Avoid using very close, similar, or identical words to denote different things, or concepts

For example, pages may have older revisions (of a specific date, time, and edit), comprising past versions of said page. The words revision, and version can be used interchangeably. A problem arises, when versioned pages are revised, and the revision, i.e. the process of revising them, is being mentioned, too. This may not pose a serious problem when the two synonyms of "revision" have different translations. Do not rely on that, however. It is better to avoid the use of "revision" aka "version" altogether, then, so as to avoid it being misinterpreted.

Basic words may have unforeseen connotations, or not exist at all

There are some words that are hard to translate because of their very specific use in MediaWiki. Some may not be translated at all. For example, there is no word "user" relating to "someone who uses something" in several languages. Similarly, in Kölsch the English words "namespace" and "apartment" translate the same word. Also, in Kölsch, they say "corroborator and participant" in one word since any reference to "use" would too strongly imply "abuse". The term "wiki farm" is translated as "stable full of wikis", since a single-crop farm would be a contradiction in terms in the language, and not understood, etc..

Use ‎<code>, ‎<var>, and ‎<kbd> tags where needed

When talking about technical parameters, values, or keyboard inputs, mark them appropriately as such using the HTML tags ‎<code>, ‎<var>, or ‎<kbd>. Thus they are typographically set off form the normal text. That clarifies their sense to readers, avoiding confusion, errors and mis-representations. Ensure that your message handler allows such markup.

Symbols, colons, brackets, etc. are parts of messages

Many symbols are localisable, too. Some scripts have other kinds of brackets than the Latin script has. A colon may not be appropriate after a label or input prompt in some languages. Having those symbols included in messages helps to make better and less Anglo-centric translations, and also reduces code clutter.

For example, there are different quotation mark conventions used in «Norwegian», ”Swedish”, »Danish«, „German”, and 「Japanese」.[3]

If you need to wrap some text in localized parentheses, brackets, or quotation marks, you can use the parentheses ($1) or brackets [$1] or quotation-marks "$1" messages like so: 

wfMessage( 'parentheses' )->rawParams( /* text to go inside parentheses */ )->escaped()
wfMessage( 'brackets' )->rawParams( /* text to go inside brackets */ )->escaped()
wfMessage( 'quotation-marks' )->rawParams( /* text to go inside quotation marks */ )->escaped()

Do not expect symbols and punctuation to survive translation

Languages written from right to left (as opposed to English) usually swap arrow symbols being presented with "next" and "previous" links, and their placement relative to a message text may, or may not, be inverted as well. Ellipsis may be translated to "etc.", or to words. Question marks, exclamation marks, colons will be placed other than at the end of a sentence, not at all, or twice. As a consequence, always include all of those in the text of your messages, and never try to insert them programmatically.

Use full stops

Do terminate normal sentences with full stops. This is often the only indicator for a translator to know that they are not headlines or list items, which may need to be translated differently.

Make sure that the anchor describes the target page well. Always avoid commonplace and generic words. For example, "Click here" is an absolute no-go,[4] since target pages are almost never about "click here". Instead, Use precise action words telling what a user will get to when following the link, such as "You can upload a file if you wish."

See also Help users predict where they are going, and mystery meat navigation, and The main reasons why we shouldn't use click here as link text.

Avoid jargon and slang

Avoid developer and power user jargon in messages. Try to use a simple language whenever possible. Avoid saying "success", "successfully", "fail", "error occurred while", etc., when you want to notify the user that something happened or didn't happen. This comes from developers' perspective of seeing everything as true or false, but users usually just want to know what actually happened or didn't, and what they should do about it (if at all). So:

  • "The file was successfully renamed" -> "The file was renamed"
  • "File renaming failed" -> "There is a file with this name already. Please choose a different name."

Be aware of whitespace and line breaks

MediaWiki's localised messages usually get edited within the wiki, either by wiki operations on live wikis, or by the translators on translatewiki.net. You should be aware of how whitespace, especially at the beginning or end of your message, will affect editors:

  • Spaces and line breaks (newlines) at the end of the message are always automatically removed by the wikitext editor. Your message must not end with a space or line break, as it will be lost when it's edited on the wiki.
  • Spaces and line breaks at the beginning are not automatically removed, but they are likely to be removed by accident during editing, and should be avoided.

Start and end your message with active text; if you need a newline or paragraph break around it, your surrounding code should deal with adding it to the returned text.

There are some messages which require a space at the end, such as 'word-separator' (which consists of just a space character in most languages). To support such use cases, the following HTML entities are allowed in messages and transformed to the actual characters, even if the message otherwise doesn't allow wikitext or HTML formatting:[5]

On a related note, any other syntax elements affected by pre-save transforms also must not be used in messages, as they will be transformed when the message is edited on the wiki.

Use standard capitalisation

Capitalisation gives hints to translators as to what they are translating, such as single words, list or menu items, phrases, or full sentences. Correct (standard) capitalisation may also play a role in search engines' assessment of your pages. MediaWiki uses sentence case (The quick brown fox jumps over the lazy dog) in interface messages.

Always remember that many writing systems don't have capital letters at all, and some of those that do have them, use them differently from English. Therefore, don't use ALL-CAPS for emphasis. Use CSS, or HTML ‎<em> or ‎<strong> per below:

Emphasis

In normal text, emphasis like boldface or italics and similar should be part of message texts. Local conventions on emphasis often vary, especially some Asian scripts have their own. Translators must be able to adjust emphasis to their target languages and areas. Try to use "‎<em>" and "‎<strong>" in your user interface to allow mark-up on a per language or per script basis.

In modern screen layouts of English and European styles, emphasis becomes less used. Do convey it in your #Message documentation still, as it may give valuable hints as to how to translate. Emphasis can and should be used in other cultural contexts as appropriate, provided that translators know about it.


请看

Notes

  1. ↑ 一些链接器会拒绝只有一项的消息列表，例如：mediawiki/msg-doc不接受具有一项的有效文档。
  2. ↑ http://dev.w3.org/csswg/css3-writing-modes/
  3. ↑ w:Quotation_mark#Summary_table
  4. ↑ http://www.w3.org/QA/Tips/noClickHere
  5. ↑ https://github.com/wikimedia/mediawiki/blob/REL1_34/includes/cache/MessageCache.php#L887
Retrieved from "https://www.mediawiki.org/w/index.php?title=Help:System_message/zh&oldid=6880879"