Fixing Badly Formatted .properties Files and Using LibreOffice/Excel to Make Them Translator Friendly.

October 4th, 2015 by zoltan · 2 Comments

Image Credit, boni_face

For those unfamiliar with them, .properties files are configuration files for Java. Among other things, one of their major uses are multi-language support in JSP pages. They are, however, not just restricted to Java — libraries exist for JavaScript, Ruby, Perl, Flex and a whole slew of other languages.

So many times, in my many dives into the Java world, I come across badly managed .properties files. In a mulit-developer shop, things quickly change from this: = Vérification de sécurité
account.not.available = Pas sélectionné
account.confirmation.password.updated = Votre mot de passe a été mis à jour.
search.empty.message = Nous n’avons pas trouvé de résultats pour {0}

to this:                 = V\u00e9rification de s\u00e9curit\u00e9
account.not.available=        Pas sélectionné
account.confirmation.password.updated       =         Votre mot de passe a été mis à jour.
search.empty.message    = Nous n\u2019avons pas trouvé de résultats pour {0}

Furthermore, you don’t want to give a .properties file to a translator. To a non-developer, they are quite unfriendly and, in my experience, translators will get confused and uncomfortable using them. In this article, you’ll see how you can quickly fix these issues with z4n a set of shell scripts I created to manage .properties files and includes tools for developers to extract translation data from Excel spreadsheets. Read on, and I’ll show you how to keep .properites files sane for all your web projects.

Download z4n to manage your .properties files from GitHub

How To Fix Badly Formatted/Managed .properties Files

In a large development shop, these files may start off well organized, but over time they become a rat’s nest of awful (as shown above). The example above shows how some developers like to use numeric entities, while some other use named entities and still others use ‘\u’-escaped Unicode characters. Furthermore, it seems that some developer like to add spaces at random around the equals sign that separates the key and the value.

This has happened so many times in my career, which is why z4n has removeEntitiesInProp to prettify .properties file by converting everything to UTF-8 (as God intended all modern web applications to use) and standardizing the spacing around the = symbol. In seconds, you .properties files will no longer make your eyes bleed and want to go through git blame to see who messed up everything.

How To Make Them More Translator Friendly

z4n‘s xls2prop command is my favourite part of this package, though. With it, you can give your translation department a nice Excel file like this:


They can fill it out like this:


Then you can run xls2prop and you can get nicely formatted results for languages like Russian … : = Имя
form.header.address = Адрес
form.header.postalcode = Почтовый индекс = Город
form.header.province = Область = Страна
registration.intro.copy = Пожалуйста, заполните форму ниже.

… and even Japanese: = 名前
form.header.address = 住所
form.header.postalcode = 郵便番号 = 都市
form.header.province = 県 = 国
registration.intro.copy = 下記のフォームに必要事項を記入してください

Notes and Caveats

  • The z4n tools are shell scripts have been tested under OSX and Windows using Cygwin. I have not tested them under Linux yet (they should work, though).
  • These tools use LibreOffice to convert a Microsoft Excel spreadsheet to a Unicode tab delimited format that the scripts can parse. Note that a translator (or anyone who is trying to fill out the language spreadsheet) can use either Micrsoft Excel or Libre Office to do so.
  • uni2ascii by Bill Poser. Since there was some issues compiling uni2ascii for Windows, I have included some Windows binaries that should work in the projects win directory, with instructions on how I did it.

Download z4n to manage your .properties files from GitHub

Tags: Internationalization · Localization · server side tech · utf8 · , , , , , , , , , , , , , , , ,

2 responses so far ↓
  • 1 Adam // Oct 7, 2015 at 5:38 pm

    Luckily Java now supports UTF-8 properties files natively, so the Unicode escapes area thing of the past.

    The Excel conversion scripts are cool. But, I recommend using a tool like Transifex to exchange property files with translators. Transifex provides a Web UI for translators with lots of great features like translation memory, a glossary, etc. It also can be scripted to automate the exchange of translations with developers, so that you are no longer exchanging versions of a file via email. Instead, you are pushing and pulling a data from Transifex. See

  • 2 zoltan // Oct 9, 2015 at 12:22 pm

    @Adam: Thanks for sharing information on Transifex. Since the application is payware, I have not looked to see how this compares with my solution (a “plus” about z4n is that it relies on all free/open-source software, which is something I personally like).

    However, it’s great to have multiple solutions for the same problem and have the reader decide which is the right tool for their job, so I hope this comment is useful to some readers of this blog.

Give Feedback

Don't be shy! Give feedback and join the discussion.

Please Note: If you are asking for help using the information on this page or if you are reporting a bug with the code featured here, please include a URL that shows the problem you are experiencing along with the browser/version number/operating system combination where the issue manifests itself. Without this information, I may not be able to respond.

An orange star denotes a required field.