Translate Java .properties files

What are Java .properties files?

Java .properties files are one of the language files used to localize Java applications. The file format is monolingual and contains pairs of keys and their translation.

WebTranslateIt is a software localization platform that can help localize Java .properties files.

java .properties file example

Here’s an example of Java .properties file. WebTranslateIt will import each key-value pair a segment. The comments in the properties files will be imported as instructions.

WebTranslateIt supports entries with double quotes, single quotes and without quotes. This example highlights how strings can be laid out.

# Double quotes:
key = "A simple segment."
# Single quotes:
key2 = 'Another segment.'
# No quotes:
key3 = hello
# A multi-line segment with quotes:
multiLine="first line
second line
another line"
# A multi-line segment with no quotes:
message = Welcome to \

Keys can contain spaces but spaces must be escaped by a backslash (\).

key\ with\ spaces = hi!

Key-values can be separated by an equal sign (=) or by a colon (:).

key = value
key3: hey!
key4 : hello!

Translator instructions can start by a # or !.

# this is a developer instruction
key = value
! The exclamation mark can also mark text as an instruction.
key2 = value
# You can also write instructions
# On several lines
key3 = value

Magic Comments

This file handler support the following magic comments:

  • Comments containing [MAXCHAR=xx] will set a max character limit to xx. Example: #. [MAXCHAR=20]
  • Comments containing [LABEL=xxxx] will assign the label to xxxx. Example: #. [LABEL=new feature]
  • The top comment in the header can be used to set the encoding (see bellow).


If you upload a file encoded as ISO-8859-1 WebTranslateIt will generate files encoded in ISO-8859-1, which special characters using UTF escape codes. If your file is encoded as UTF-8 WebTranslateIt will generate files encoded in UTF-8 containing UTF-8 characters.

WebTranslateIt does its best to detect the encoding of files but it’s not very reliable when working with English files which do not contain any foreign characters. For now it isn’t safe to assume that .properties files are UTF-8 encoded.

You can force the encoding of the files by adding a special comment at the very top of your master file and uploading it to WebTranslateIt:

# encoding: UTF-8
key_1 = text
key_2 = text
key_3 = text

Single quotes escaping

Using ResourceBundle

ResourceBundle is a class used for localizing message strings while MessageFormat can be used to replace variable placeholders within string messages. The typical usage of ResourceBundle and MessageFormat looks like this:

myMessage=Hello {0}

Java code:

ResourceBundle bundle = ResourceBundle.getBundle("messages");
String pattern = bundle.getString("myMessage");         // Hello {0}
String message = MessageFormat.format(pattern, "John"); // Hello John

The single quote is used to represent a section within the message pattern that will not be formatted. If you want to display a single quote, it must be escaped by another single quote: ''.

It is easier to understand by looking at examples:

test.message1=test {0} {1} {2}
test.message2=test {0} '{1}' {2}
test.message3=test {0} ''{1}'' {2}
test.message4=test {0} '''{1}''' {2}
test.message5=test {0} '{1} {2}
test.message6=test {0} ''{1} {2}

Java code:

for (int i = 1; i <= 6; i++) {
  String pattern = bundle.getString("test.message" + i);
  String message = MessageFormat.format(pattern, 'A', 'B', 'C');


test A B C
test A {1} C
test A 'B' C
test A '{1}' C
test A {1} {2}
test A 'B C

Placeholders between two simple single quotes are not replaced . Single quotes not escaped by another single quote don’t show up in the output.

Using ResourceBundleMessageSource

Single quote escaping is trickier if you are building a Spring application that makes use of Spring’s ResourceBundleMessageSource class. If you have properly set up a ResourceBundleMessageSource bean it can be used to retrieve string messages like this:

myMessage=Hello {0}

Java code:

Object[] args = new Object[] { "John" };
Locale locale = new Locale("en");
String message = messageSource.getMessage("myMessage", args, locale); // Hello John

Internally ResourceBundleMessageSource uses Java’s Resourcebundle and MessageFormat for receiving string messages. However, ResourceBundleMessageSource does a small optimization by default. It will only parse a message through MessageFormat if one or more arguments have been passed in for the message. If no message arguments are passed to getMessage() the message text will be returned as-is. This means that the rules for escaping single quotes only need to be applied if the message takes any arguments.

Here’s another example:

test.message1=John's message
test.message2={0}'s message
test.message3=John's {0}

Java code:

private void printMessage(String code, Object... args) {
  Locale locale = new Locale("en");
  String message = messageSource.getMessage(code, args, locale);
printMessage("test.message2", "John");
printMessage("test.message3", "message");


John's message
Johns message
Johns {0}

The first message does not take any arguments, so no MessageFormat is applied and the single quote does not need to be escaped. The second and third messages, however, are formatted by a MesssageFormat which processes the single quote characters. In these messages the single quotes should better be escaped with another single quote character otherwise they won’t show up in the output.

From a developer point of view the rules for escaping single quotes might make sense. However, you will have a hard time explaining these rules to localizers who have only a very basic technical knowledge. It just won’t work!

Luckily ResourceBundleMessageSource has a very useful flag called alwaysUseMessageFormat that can be enabled if all messages should be parsed by MessageFormat. If this flag is set to true (default value is false) all single quotes need to be escaped.

You can configure it in your resource bundle with:

    <property name="alwaysUseMessageFormat" value="true" />


Standard Java .properties files don’t support pluralization, but we do support a different flavour of .properties files used by the Web L10N library.

How to Translate a Java properties File?

It is easy to translate a Java properties file with WebTranslateIt. In a project, upload your source Android XML file in the File Manager and translate it on the Translation Interface.

The tools included in WebTranslateIt, such as Batch Operations, the Translation Memory or Machine Translation can help you translate that file automatically, faster and cost effectively.

Related File Formats

Related Platforms