Editing properties files

Implementation details

There are some implementation details of the Java properties files that are quite unusual and unknown.

Encoding

Properties files are read in ISO-8859-1.

Source: http://download.oracle.com/javase/6/docs/api/java/util/Properties.html

Properties files have to be converted using the native2ascii tool provided by Java, in order to "Unicode escape" accents.

Sources:

• native2ascii: http://download.oracle.com/javase/6/docs/technotes/tools/solaris/native2ascii.html

• Unicode escape: http://java.oracle.com/docs/books/jls/third_edition/html/lexical.html#3.3

Escaping special characters

Key-value separation

Key-value pairs can be separated by a ' :' (colon), ' =' (equals sign) or even ' ' (space), with optional extra spaces around. However, the most commonly used format is to be preferred:

key=value

The key-value separators can be used in the key by escaping them with a ' \' (backslash). Any backslash must be escaped in both the key and the value by adding another backslash. Examples:

key\:with\:colons=value: with a colon
key\ with\ spaces=value with spaces
key\=with\=equals=value with equals = like this
key\\with\\slash=value with a \\ in it

Apostrophes

Apostrophes ( ') have to be doubled ( '') when they are used with brackets ( {}) in the same property value.

Blank characters

Any line that ends in a single ' \' continues on the next line. This holds in both keys and in values, and can be used to split very long keys and/or values over multiple lines. For example, the following two properties are equivalent:

my.key.with.many.characters=a value with many characters

my.key.with\
.many.characters=a value\
 with many characters

Tab and newline characters are written as ' \n' and ' \t', just like in Java Strings.

Comments

Lines that start with a ' #' or ' !' character are ignored, and can be used for inline comments. These characters have to be escaped with a ' \' when used as the first character in a key.

IDE support

Your IDE has to be configured properly in order to handle these files in ISO-8859-1 (and not in UTF-8 like every other file), and if possible to "automagically" handle the native2ascii conversion.

If you know about the native2ascii support provided by Netbeans, please feel free to contribute to this page...

IntelliJ IDEA

For IntelliJ users, here is an article about the setup: http://blog.trifork.com/2010/11/04/encoding-problems-with-properties-files-and-intellij/.

Eclipse

For Eclipse users, you can use this plugin: http://propedit.sourceforge.jp/index_en.html

Fixing properties files

You can use this Linux command to fix (encoding and Unicode escaping) all properties files at once:

find . -name "*.properties" -exec native2ascii {} {} \;