Know your APIs – Lessons learned from ResourceBundle

Last week I spent some time hunting down an internationalization-issue that came along while developing for a recent project. Let me explain what happened:
Message-Lookup – of course – always stands together with Locales (java.util.Locale) of the client the message is resolved for. The problem was, that messages for the English users were not resolved to the English translation, but to the German one.
Within the project I am working on, there were the following message-files at that time:

  • (containing the english translation)
  • (containing the German translation)
  • (containing Italian translation)

Usually you provide a property-file per language containing all the translations. ResourceBundle uses a fallback-mechanism from the full locale down to more general ones (e.g. it first checks for to down to in the end, being the overall default).
This actually makes much sense because in this way you can provide values for stuff relevant for all languages in, English language specific values in and stuff that is different for different english speaking Countries in files like and and so on. The fallback works perfect, because  if you for example don’t specify US/UK specific files message-lookup for both en_US and en_UK result in resolving keys from Additionally, if would exist but the key-lookup fails (the file does not provide a translation for the key), the key gets also looked up from (which may also provide the key).
In my concrete case, resolving of German values (coming from worked well, but if you change the users locale to English, the keys also resolved to German values.
I did not create a because English should also be the overall fallback if no i18n for the requested language was available. I thought if the user had the locale fr the system would check for and then in, which would display English messages for the user because no French translation is available. I debugged a while, basically within our own framework and later down to Springs i18n related classes and I could not find the mistake.
Then, when I excluded all possible mistakes on our side and inside the Spring Framework where our application is based on,  my way lead me down to java.util.ResourceBundle. Since this class makes extensive use of caching (for good reasons of course) and static factory methods (which are almost impossible to debug) my way lead me to the API-Doc of ResourceBundle. Here I found the mistake that I made:

getBundle uses the base name, the specified locale, and the default locale (obtained from Locale.getDefault) to generate a sequence of candidate bundle names.

I forgot that ResourceBundle also looks up files for the JVMs Default-Locale before falling back to the base-file ( The Default-Locale of my JVM is de_DE, which lead to the following path:

  • (not found)
  • (not found)
  • (from Default-Locale, not found)
  • (from Default-Locale, FOUND)
  • ( was not checked because the key was found)

So the fix was easy. There are even several ways to fix it:

  • rename to (which leads to the French dude having to learn German).
  • copy to (this is copy paste but this could be solved within the build-process using mvn)
  • set the default-locale of the JVM to an English one by calling Locale.setDefault(englishLocale) early in application-boot
  • set the default-locale as commandline-argument of your JVM (e.g.  -Duser.language=en

And, last but not least:  What do we (or better I)  learn from this?

  • My usual approach “first think about whats happening, if you cannot figure out what leads to the problem immediately attach debugger” was obviously not the best approach in this case (although starting immediately to debug has turned out to be a very efficient way to hunt down bugs for me in general).
  • Code is not the only place where bugs can be found. A big problem is also understanding the basic APIs you use.
  • Even if you use high-level APIs (i18n in this case with about 5 delegates before the ResourceBundle was actually reached) you still need to know the very basics.

Reading APIs
earlier (ok, the whole hunting only took about 1-2 hours, but still)  or even (in a perfect world) know all your APIs you use directly or indirectly would have saved some time.


  1. >>
    Ah, good ol' Ukrainian English. A project of mine made the same slip - should be en_GB :-)