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.
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 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. 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.
The most simple case is when you have a term and its definition:
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:
;定義する用語 :''別名 '''その他の用語''''' :定義
- 別名 その他の用語
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.
;定義する用語 :''別名 '''その他の用語'''、'''同義語'''、'''同義語2''''' :定義
It is possible to add a second 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.
Translate tags will allow people to translate the page. All components must be translated.
;<translate>定義する用語</translate> :''<translate>別名 '''その他の用語'''、'''同義語'''、'''同義語2'''</translate>'' :<translate>定義</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: