Help:Glossaries

Glossaries are very important to users and translators. They give accurate and polished definitions of terms that are used by an extension and by the associated documentation. By reading the glossary, a user can understand the different terms used, and a translator can think about the equivalent term(s) in another language than the one they are reading (on this wiki, mostly English).

This page lists best practices that should be used in glossaries on mediawiki.org.

Best practices

Glossaries must be easy to maintain, to translate, and of course to read, especially concerning accessibility.

Pages should be made with a common design, to ease future improvements. We will avoid the use of templates which also need documentation, maintenance, and are sometimes problematic concerning RTL/LTR translations.

Translatability must be possible and easy. Add terms that are not the equivalent of the official terms used of synonyms must be possible. Polishing a term to use the best English word, is less useful than work on the definition itself. The definition is the most important thing because it allows translators to find an equivalent and accurate term in their language.

Definitions are standardized by W3C as "descriptions lists" or "definition lists". MediaWiki implements definition lists. Using such definition lists will structure data a minima and increase accessibility.

When you create a glossary, sort the terms that are the most important and used, first. Alphabetical order in English will not be an alphabetical order in another language.

How to

Define a term

The most simple case is when you have a term and its definition:

;Term to define
:Definition

Rendered as:

Term to define

Definition

Add synonyms

Synonyms are terms that are not the official term, but that can be used by people or in certain cases. There is no standard to add synonyms to a definition list. We are using the best equivalent we have found: add a definition, and label it as "also known as", and format it differently:

;Term to define
:''Also known as '''other term'''''
:Definition

Rendered as:

Term to define

Also known as other term

Definition

The synonyms line is identified by italics, and synonymous terms are in bold to have a visual equivalent of the primary term. On text browsers, that will highlight the synonym.

It is possible to have multiples synonyms, separated by commas.

;Term to define
:''Also known as '''other term''', '''that equivalent''', '''synonym'''''
:Definition

Add a second definition

It is possible to add a second definition:

;Term to define
:Definition
:Other definition

Rendered as:

Term to define

Definition

Other definition

However, having two definitions for one term may be a source of confusion. Plus, a term in one language that has two meanings, may need two separated terms in another language.

Mark for translation

See also: Help:Extension:Translate/Page translation example

Translate tags will allow people to translate the page. All components must be translated.

;<translate>Term to define</translate>
:''<translate>Also known as '''other term''', '''that equivalent''', '''synonym'''</translate>''
:<translate>Definition</translate>

Translation for the synonyms line is done as one line, not as separated terms. This allows an easy translation for RTL languages and simplifies the addition of more synonymous terms.

The following task is only possible when the page has been marked for translations:

To encourage translators to add words used in their language, each translation item related to synonyms (the "qqq" message) must be documented with Template:Adapt translation/core , which displays the following message:

Please adapt this translation to reflect terms in use in your language. Terms in English can be inspirational.