Help:Glossaries/en

Glossaries are very important to 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 their equivalent in an other language than the one they are reading (on this wiki, mostly English).

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

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

Pages have to be made with a common design, that will help for future improvements. We will avoid to use 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. Polish a term to use the best English is less useful than work on the definition itself. The definition is the most important thing because it will allow 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. Use such definition lists will structure data a minima and increase accessibility.

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

Define a term
The most simple case is when you have a term and its 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 know as" and format it differently:

Rendered as


 * Term to define
 * Also known as other term
 * Definition

The synonyms are identified by italics, synonyms 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.

Add a second definition
It is possible to add a second definition:

Rendered as


 * Term to define
 * Definition
 * Other definition

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

Mark for translation
See also: 

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

; &lt;translate> Term to define &lt;/translate> : &lt;translate> &lt;/translate> : &lt;translate> Definition &lt;/translate>

Translation for the synonyms line is done as one line, not as separated terms. That allows an easy translation for RTL languages and offer the opportunity to add other 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, which displays the following message: