Jump to content

Manual:$wgCategoryCollation

From mediawiki.org
Translate this page
Languages:
Category: $wgCategoryCollation
What collation categories use to sort with
Introduced in version:1.17.0 (r72308)
Removed in version:Still in use
Allowed values:(string)
Default value:'uppercase'
Other settings: Alphabetical | By function

Details

The setting determines what collation[1] algorithm should be used to sort category listings.

As an example, to use the Spanish collation, you'd write $wgCategoryCollation = 'uca-es'; in LocalSettings.php and then run updateCollation.php for your change to take effect.

Currently supported are:

Collation algorithm MW version Description
uppercase default make everything uppercase, then sort by binary value of string when stored as UTF-8. Essentially case-insensitive sort by code point.
numeric MW 1.28+ Same as uppercase, but with numeric sorting.
identity MW 1.18+ sort by binary value of string when stored as UTF-8 (without converting to uppercase). Essentially sort by code point.
uca-default MW 1.17+ Unicode collation algorithm – complex, much more multilingual-friendly category collation.
uca-default-u-kn MW 1.28+ uca-default with numeric sorting.
uca-<langcode> MW 1.21+ uca-default with language-specific adjustments. See below.
uca-<langcode>-u-kn MW 1.28+ uca-<langcode> with numeric sorting. See additional parameters.
xx-uca-ckb MW 1.23+ (deprecated in 1.44) Central Kurdish; replaced by uppercase-ckb.
xx-uca-et MW 1.24-1.31 (removed in 1.32) Estonian but with W and V being considered separate letters.
xx-uca-fa MW 1.30-1.31 (removed in 1.32) Persian
uppercase-ab MW 1.31+ Abkhazian
uppercase-ba MW 1.30+ Bashkir
uppercase-ckb MW 1.44+ Central Kurdish
uppercase-se MW 1.31 (removed in 1.32) Northern Sami
uppercase-smn MW 1.44+ Inari Sami
pinyin-zh[<uca-modifiers>] MW 1.46+ Tailored Pinyin collation based on the UCA ordering, with Pinyin initials and Latin characters grouped for the correct first-letter order. Supports collations with optional UCA modifiers, like pinyin-zh@colNumeric=yes;colReorder=latn-hani or equivalently, pinyin-zh-u-kn-kr-latn-hani
For example, if uca-zh@collation=pinyin;colReorder=latn-hani were used, when the "A" header contains only Chinese character page names and the "B" header contains Latin alphabet page names, the "A" header would be sorted after the "B" header. Given this issue, you should replace that collation with pinyin-zh@colReorder=latn-hani.

Since MediaWiki 1.18, extensions can add extra collations via the Collation::factory hook.

The value is also stored inside the categorylinks table to determine which rows need updating when the collation algorithm changes.

Setup instructions

  • After changing this option, you must run updateCollation.php to recompute sort keys for all pages, or your categories will be sorted inconsistently.
  • Updating collations is slow and may take several hours on large wikis.
  • uca-default/uca-xx collations require the PHP intl extension.
  • If you are using Varnish, Squid or file cache, you may have to purge category pages after running updateCollation.php to see the results.
  • If you update or recompile your version of PHP, you must run updateCollation.php --force.

Language-specific collations

MediaWiki also supports many collations designed for specific languages. These are based on the Unicode collation algorithm (UCA) uca-default and have the same requirements; they are named uca-<langcode>, where <langcode> is one of: 

af, am, ar, as, ast, az, be, be-tarask, bg, bn, bn@collation=traditional, bo, br, bs, bs-Cyrl, ca, chr, co, cs, cy, da, de, de-AT@collation=phonebook, dsb, ee, el, en, eo, es, et, eu, fa, fi, fil, fo, fr, fr-CA, fur, fy, ga, gd, gl, gu, ha, haw, he, hi, hr, hsb, hu, hy, id, ig, is, it, ka, kk, kl, km, kn, kok, ku, ky, la, lb, lkt, ln, lo, lt, lv, mk, ml, mn, mo, mr, ms, mt, nb, ne, nl, nn, no, oc, om, or, pa, pl, pt, rm, ro, ru, rup, sco, se, si, sk, sl, smn, sq, sr, sr-Latn, sv, sv@collation=standard, sw, ta, te, th, tk, tl, to, tr, tt, uk, uz, vi, vo, yi, yo, zh@collation=pinyin, zh@collation=stroke, zh@collation=unihan, zh@collation=zhuyin, zu

For example, to use a collation for Spanish, one would use the uca-es collation.

Using these collations provides both correct sorting order for given language and proper headings for first letters of article titles. Earlier versions of MediaWiki might not support all of these language codes.

Additional parameters

You can add parameters to uca-<langcode> to meet more specific requirements. The order of parameters is arbitrary.

Starting with MediaWiki 1.46 (T411940), parameters can also be specified using the complete BCP-47 format. MediaWiki will convert the BCP-47 format into ICU locale keywords format. However, BCP-47 and ICU locale keywords formats cannot be mixed together.

Purpose Unicode locale extension (BCP-47) ICU locale keywords
Format of language-specific collations with parameters. uca-<langcode>-u-<parameter>-<parameter>
<parameter>s separated by -.
 uca-<langcode>@<parameter>;<parameter>
<parameter>s separated by ;.
Specify the actual collation. See above. Because Some languages have multiple collations. co-<type>
≥ 1.46
collation=<type>
≥ 1.17
Specify the order of different scripts.
<scriptcode>s are ISO 15924 codes or special keywords (space, punct, symbol, currency, digit and others). They separated by -.
For zh, the ICU library orders the Hani script before other writing systems such as Latn.
 kr-<scriptcode>-<scriptcode>
≥ 1.46
colReorder=<scriptcode>-<scriptcode>
≥ 1.46
Numeric sorting. kn
≥ 1.28
colNumeric=yes or colNumeric=no
≥ 1.46
kn-true or kn-false
≥ 1.46

For example, a Chinese collation sort by Kangxi radical and number of strokes, enable numeric sorting:

  • BCP-47: uca-zh-u-co-unihan-kr-latn-hani-kn
  • ICU: uca-zh@collation=unihan;colReorder=latn-hani;colNumeric=yes

Getting new collations added

There are two parts to having a new language supported:

  • It being supported by the International Components for Unicode library (the list of language codes it supports is available at [1]).
    • Note, however, that Wikimedia's production servers do not use the latest version of the ICU library. As of MediWiki 1.46 in 2026, they use version 72.1.
  • It being additionally supported by MediaWiki itself (this basically requires listing the additional characters, or character groups, that are considered separate letters in the given language, in addition to the basic alphabet) – the always up-to-date list of currently supported ones is available at includes/Collation/IcuCollation.php.

It might also be the case that the default ICU ordering (uca-default collation) orders the titles correctly, but does not correctly separate the letters – it can be used for the first step in that case.

If your language is related to another language, that language's letter ordering may work for yours as well. When this happens, you can sometimes define a custom collation by reusing that ordering.

Numeric sorting

Comparison between regular sorting (top) and numeric sorting (bottom)

Under numeric sorting, pages will be sorted as such: 1, 2, 9, 10, 11, 20, 21, 99, 100. Under regular (non-numeric) sorting, pages will be sorted as text: 1, 10, 100, 11, 2, 20, 21, 9, 99. If numeric sorting is used, all pages starting with a number will be sorted together under a single header: "0–9". If regular sorting is used, pages starting with a number will be sorted under separate headers for whichever number each title begins with: "0", "1", "2", etc. For more information about numeric sorting, see the Unicode Technical Standard #10. To test numeric sorting, see the ICU Collation Demo. Note that numeric sorting only works for unbroken sequences of digits. Digits separated by commas, periods, or spaces are treated as separate numbers.

See also

References

  1. ↑ Collation refers to how data is sorted according to its set of characters, applying defined sorts criterias (i.e. alphabetic or reverse sort, case dependent or not, etc.)
Retrieved from "https://www.mediawiki.org/w/index.php?title=Manual:$wgCategoryCollation&oldid=8661911"