Character Encoding
Reference
XWiki reads, stores and serves text as UTF-8, and the distribution ships that way: the character encoding filter in xwiki/WEB-INF/web.xml and the xwiki.encoding parameter in xwiki/WEB-INF/xwiki.cfg are both set to UTF-8, and there is nothing to change in the wiki administration. What can still corrupt characters is the stack around it.
| Layer | What it has to do | What you have to do |
|---|---|---|
| XWiki | Read and write every request, page and attachment as UTF-8 | Nothing. |
| Servlet container | Decode request URIs as UTF-8 | Nothing on a supported container. Tomcat decodes them as UTF-8 by default. |
| Reverse proxy | Pass on the character set XWiki declares | Nothing by default. Apache's AddDefaultCharset directive can add one of its own, see Apache Server Key Configurations. |
| Database | Store text in a UTF-8 character set | Set the character set when you create the database, as described for each supported database. |
| Operating system | Give the XWiki process a UTF-8 locale | Set it when the server runs in the C or POSIX locale, see below. |
Operating System Locale
The Java virtual machine decodes file contents as UTF-8, but the character set it uses for file names, sun.jnu.encoding, follows the operating system locale. A server left in the C or POSIX locale therefore reads and writes file names as ASCII, and a path holding any other character stops resolving: XWiki cannot open its permanent directory or its configuration files when one of the directories leading to them has a non-ASCII name. Give the account that runs XWiki a UTF-8 locale:
LANG=C.UTF-8Values of a Running Instance
The Admin Tools Application reports the encoding configuration parameters an instance is actually using.
FAQ
Do I still have to set xwiki.encoding in xwiki.cfg?
No. Documentation written before UTF-8 became the shipped default asked for the parameter to be changed by hand, and that instruction no longer applies.
Does Jetty need a file.encoding setting?
No. That instruction comes from documentation written for older Java versions, whose default character set depended on the platform they ran on. The start_xwiki.sh and start_xwiki.bat scripts of the standalone distribution still pass the option, where it now has no effect.
Does Tomcat's connector need a URIEncoding attribute?
No. Tomcat's HTTP connector attributes documentation gives the default for decoding request URIs as UTF-8, on every version XWiki supports. Instructions to set the attribute, or to keep the org.apache.catalina.STRICT_SERVLET_COMPLIANCE system property unset because it made Tomcat fall back to ISO-8859-1, were written for Tomcat 8.5 and earlier.
Can XWiki run with a character set other than UTF-8?
No. XWiki assumes UTF-8 throughout, and the container, the database and the wiki all have to agree on it.
