How to Translate Java .properties Files

Quick answer — A Java .properties file is key equals value, one per line. The traps are escaping — colons, equals signs and spaces need escaping in keys — the MessageFormat placeholders, and the strict locale suffix that decides which file the runtime loads.

The naming convention is functional

messages.properties is the default. messages_fr.properties is French, messages_pt_BR.properties is Brazilian Portuguese. The suffix is not a label, it is how the runtime resolves which bundle to load. Get the code wrong — messages_br instead of messages_pt_BR — and the file is simply never loaded. The application falls back to the default bundle and everything appears untranslated with no error anywhere.

Escaping is the quiet failure

In a properties file, =, : and leading whitespace are syntax. A key containing any of them needs escaping. So do line breaks, expressed as \n inside the value.

Historically these files were required to be Latin-1, with non-ASCII characters written as \uXXXX escapes. Modern loaders accept UTF-8, but plenty of codebases still contain escaped files, and mixing the two conventions in one bundle produces mojibake in exactly one language.

Check which convention the project uses before adding a file to it.

MessageFormat placeholders

Values commonly contain {0}, {1} and so on, substituted at runtime. They must survive exactly, and their order may need to change for the target language while the numbers stay bound to their arguments. {0} is not interchangeable with {1}. Swapping them to suit word order without understanding what each holds puts the wrong value in the wrong place.

Single quotes are the related trap: in MessageFormat a literal apostrophe must be doubled, so a French translation containing l'utilisateur will silently swallow following text unless it is written l''utilisateur.

Keys never change

Same rule as every other resource format. The key is what the code requests. The value is what a person reads.

Why release-by-release reuse matters

An enterprise application carries thousands of strings and changes tens of them per release. translation memory returns the unchanged ones untouched, so the translation work tracks the size of the change rather than the size of the bundle.

The route through

Upload the bundle, keep the key column locked, protect MessageFormat tokens, choose languages, and confirm the locale suffixes on export. document translation handles the format and quality control checks the placeholders and quoting.

Encoding and naming details are on the properties translation integration page.

Bundles inherit down a chain

Java resolves a bundle from most specific to least: country, then language, then default. A key missing from the Brazilian file falls back to the Portuguese one, and then to the base bundle in English.

That is a sensible design and a confusing one to debug, because a partly translated bundle produces a screen mixing three languages with nothing written to a log.

Ordering and diffs

Properties files have no required order, and some tools rewrite them alphabetically on save. That produces a diff touching every line, which buries the two strings that actually changed.

Fix the ordering convention once across the project. It costs nothing and it makes every subsequent translation review readable.

Where to start

Verify one translated bundle actually loads at runtime before translating the rest. A wrong locale suffix is invisible until somebody switches language.

FAQ

Why is my translated properties file not loading? Almost always the locale suffix. The runtime resolves bundles by name, so messages_br.properties instead of messages_pt_BR.properties is never loaded and the application silently falls back to the default.

What encoding should a properties file use? Whatever the project already uses. Older bundles are Latin-1 with \uXXXX escapes and modern loaders accept UTF-8, but mixing both conventions in one bundle produces corrupted characters in exactly one language.

How are MessageFormat placeholders handled? They must survive exactly, and the numbers stay bound to their arguments even if word order changes. Swapping 0 and 1 to suit the target sentence puts the wrong value in the wrong place.

Why does an apostrophe break a French translation? Because MessageFormat treats a single quote as an escape character. A literal apostrophe must be doubled, so l'utilisateur has to be written l''utilisateur or the text after it is swallowed.