Unicode Properties Files in IntelliJ IDEA

November 16th 2018 IntelliJ IDEA Java

In Java, .properties files are used for storing key-value pairs, most typically for text localization. However, by default they are saved in ISO-8859-1 encoding, not in Unicode. Since many languages use characters not included in this encoding, these characters will need to be expressed using Unicode escape sequences.

This means that the following contents using Unicode literals would not be valid for a .properties file in ISO-8859-1 encoding:


To be correctly interpreted, these characters must be represented with Unicode escape sequences:


Of course, such files are inconvenient to read and edit.

Fortunately, IntelliJ IDEA can automatically handle conversion between the Unicode literals and their corresponding escape sequences. The feature is named Transparent native-to-ascii conversion and is not enabled by default. It is located on the Editor > File Encodings page of the Settings window.

Transparent native-to-ascii conversion

When this setting is enabled, Unicode escape sequences in .properties files will be rendered as regular Unicode literals, but they will still be saved as escape sequences so that the Java code will be able to interpret them correctly.

Since Java 1.6, it's also possible to specify the encoding when loading the contents from a .properties file by using the Properties.load method overload accepting a Reader) instead of passing it the InputStream directly:

Properties properties = new Properties();
InputStream stream = Thread.currentThread().getContextClassLoader()
InputStreamReader reader = new InputStreamReader(stream, StandardCharsets.UTF_8);

If you use this approach, you'll still need to specify the correct encoding for .properties files in IntelliJ IDEA settings:

Default encoding for properties files

Of course, this is only an option if you're starting a new project and have the whole stack under your control, i.e. you are writing the code for loading the .properties files yourself. Otherwise, you'll be stuck with ISO-8859-1 encoding and will have to use IntelliJ IDEA's transparent conversion feature.

Get notified when a new blog post is published (usually every Friday):

If you're looking for online one-on-one mentorship on a related topic, you can find me on Codementor.
If you need a team of experienced software engineers to help you with a project, contact us at Razum.
Creative Commons License