Wiki source code of Language Resolution
Last modified by Eleni Cojocariu on 2026/09/15 17:02
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | XWiki resolves the language of every request the same way: it walks an ordered list of candidates and stops at the first one it can use. Knowing that order explains why a wiki whose default language is French can still greet a reader in English, and why setting a default language sometimes appears to have no effect. | ||
| 2 | |||
| 3 | == The order of the candidates == | ||
| 4 | |||
| 5 | {{plantuml}} | ||
| 6 | @startuml | ||
| 7 | !theme bluegray | ||
| 8 | start | ||
| 9 | :A request arrives; | ||
| 10 | if (a locale already resolved for this request?) then (yes) | ||
| 11 | :Use it; | ||
| 12 | stop | ||
| 13 | endif | ||
| 14 | if (the wiki is multilingual?) then (no) | ||
| 15 | :Use the wiki default locale; | ||
| 16 | stop | ||
| 17 | endif | ||
| 18 | if (a "language" request parameter?) then (yes) | ||
| 19 | if (its value is "default"?) then (yes) | ||
| 20 | :Forget the language cookie; | ||
| 21 | :Use the wiki default locale; | ||
| 22 | stop | ||
| 23 | endif | ||
| 24 | :Remember it in a language cookie; | ||
| 25 | :Use it; | ||
| 26 | stop | ||
| 27 | endif | ||
| 28 | if (a language cookie?) then (yes) | ||
| 29 | :Use it; | ||
| 30 | stop | ||
| 31 | endif | ||
| 32 | if (the wiki default language is preferred?) then (yes) | ||
| 33 | :Use the wiki default locale; | ||
| 34 | stop | ||
| 35 | endif | ||
| 36 | if (the browser sent Accept-Language?) then (yes) | ||
| 37 | :Use the first of its locales that is accepted; | ||
| 38 | stop | ||
| 39 | endif | ||
| 40 | :Use the wiki default locale; | ||
| 41 | stop | ||
| 42 | @enduml | ||
| 43 | {{/plantuml}} | ||
| 44 | |||
| 45 | What each candidate is: | ||
| 46 | |||
| 47 | 1. **The locale already resolved for the request.** Whatever settled the language earlier in the same request keeps it. | ||
| 48 | 1. **The wiki default locale, for a wiki that is not multilingual.** There is no choice to offer, so no other candidate is examined. The default locale is the "Default Language" of the wiki administration, or English when that field is empty. | ||
| 49 | 1. **The ##language## parameter of the request.** This is what a language switch in the interface sends. The value ##default## selects the wiki default locale and forgets the reader's earlier choice; any other value is remembered in a ##language## cookie. | ||
| 50 | 1. **The ##language## cookie**, which is how that choice survives the following requests. | ||
| 51 | 1. **The wiki default locale, when it is preferred.** This candidate exists only if ##xwiki.language.preferDefault## or ##preferDefaultLanguage## is enabled, and it is skipped for a reader who has asked for a language explicitly. See [[Language Parameters>>doc:documentation.xs.admin.language.parameters.WebHome]]. | ||
| 52 | 1. **The locales of the browser's ##Accept-Language## header**, in the order the browser sent them. | ||
| 53 | 1. **The wiki default locale**, as the final fallback. | ||
| 54 | |||
| 55 | == Languages outside the supported list == | ||
| 56 | |||
| 57 | ##xwiki.language.forceSupported## cuts across all of it. While it is enabled, which is the default, a candidate that is not one of the wiki's supported languages is not used: the resolution simply moves on to the next candidate. A reader whose browser asks for a language the wiki does not support therefore sees the wiki default language rather than an untranslated interface. |
