Should I localize log messages?
Ok, I’ve got an open question for which I would like your opinion.
Should you localize log messages? To be clear, by localize I mean instead of a literal string value, should I instead look up a message defined by a ResourceBundle such that the message can be localized to the user’s locale if desired.
One argument says that the log is intended to be useful to the user in the case of abnormal behavior and is certainly accessible to the user and therefore just like all user-facing text (on a GUI, in an error message, etc), it should be localized.
An opposing argument could say that the log is primarily useful for support of the product and is thus only useful when created in a locale that the developers and support members actually can read. If I as a developer get a bug report from the field with a log localized in Japanese, I’m not going to be able to use that to track down the problem, thus negating the intended usefulness of the log in the first place.
What if the same message is both logged AND thrown back to the user? In this case, should you localize the message thrown to the user but log the unlocalized version? What if you localize an exception message which is later logged higher up the stack?
Is your answer different for different log levels (ERROR, WARN, INFO, DEBUG)? I think DEBUG messages should never be localized as they are never intended for user consumption, only for developer consumption. Do you agree? What about the other levels?
Hi! My name is Alex Miller and I live in St. Louis. I write code for a living and currently work for 
I suppose the way to best support the user while getting information to the support staff is to use error numbers/codes in conjunction with a localized message. The code is what will be important to the support staff, while the message can be read by the local user. The trouble with this is that you have to have a clear scheme for error codes and you have to publish a dictionary of these schemes.
I suggest keeping two logs by adding an appender to your log4j logger. One appender is non-localized, one is localized, and then show only localized messages to the user. As long as you don’t run out of disk space then you have the best of both options.
IMHO, everything above the INFO level might need to be localized. Everything below that level (= FINE/FINER/FINEST) shoudn’t. The idea of keeping two logs suggested by Hamlet above does appeal to me, but in the localized log I would only spit out messages above the INFO level. And if you can convince your customers/marketing that localization is not needed you’ll be all the more happy: maintaining localized message catalogs is a real pain… Something that might push all developers to always use the default “something went wrong” error: writing good english is difficult enough ;-)
I was just thinking about this a few days ago. I implemented something to make the logs easily displayable in the gui (http://be-java.blogspot.com/2007/07/easy-log4j-logs-display-in-gui.html).
I agree that at or above the warn level, the messages should be localized if presented to the user, but its a pain to maintain :(
I cannot honestly see a way to make all our log messages localized, not even INFO level only. They would have to be translated to at least 5 languages, which not only is barely possible due to frequent additions but would also become quite expensive. Error messages put upfront usually get localized, but detailed views on log messages are not. As stated, logging usually is for maintaining or help desk, who would not have a clue on a log-file returned in russian or spanish.
Since these questions are interdependent, so are their answers. You need to determine who is the target ‘consumer’ of your log messages first: the application’s end user? an application administrator at the customer site? your own support and/or development staff? Unless you know who you expect to be reading the log message, you can’t answer how it should be presented.
Each type of log consumer probably has different needs, so you may need to write multiple logs with different levels of detail. Then localize/internationalize each log stream according to the expectations of the target consumer.
It’s also worth noting that there is a difference between localization (L10N) and internationalization (I18N); you could localize everything up-front and decide which log messages to internationalize (provide translations of) at a later stage.
The important part is ensuring your log messages are targeted appropriately.
IS there anybody in the target audience for these messages for whom having a localized log file makes the log file meaningful whereas it wouldn’t otherwise be? And if there is, what value does that understanding add?
Log messages are not novels, not paragraphs, and seldom even sentences. They are a bunch of highly technical terms sometimes strung together with a smattering of natural language artifacts. I suspect for almost anyone who can add value by understanding the log messages, changing the smattering of natural language artifacts to their mother tongue probably adds less value than is lost by delaying delivery of the product (or adding to its cost – or both) due to localization efforts.
And another thought. Posting this blog in English is unlikely to get you a realistic answer!
I for one hate localized log messages when I see them in other products. Living in Denmark and being a Dane, I sometimes see linux installations where they have been localized so not only the UI is danish, but also messages from tools like cd, ls, ln, tar, … and it is absolutely *horrible*.
Another thing: It makes it harder to write tools that searches logs for stuff, when the messages are (can be) localized in different installations.
About exception messages being presented to the user: Isn’t that a bad idea? I believe in catching exception in code and then — if the user is to be notified — showing a translated/localized message from some resource bundle.
@Keith: I’ve been down the error code path before and doing that for all log and error messages is madness. That is only feasible and maintainable in the case of exceptions thrown through a very well-controlled API with a reasonably small error space.
@Hamlet: This implies that I can localize in the appender somehow. If I’m using log4j for example, I would need to actually log a localization key, then have appenders that would know how to look up a localized message to go to one log and a hard-coded message to go to another. I don’t think such a thing exists, although it wouldn’t be too hard to write one. I actually went down a path similar to this years ago and found it to be a big mistake. It made logging and exception handling way more complicated.
@Stefan: I think I’ve generally come to the same conclusion that localizing log messages is not worth the effort. I can envision a system where some specialized kinds of logs (audit logs) may be useful to localize but in general it seems like more trouble than its worth.
@Laurie: Good points. I think I’d be willing to say at this point that the log’s value is only for support and thus should not be localized. I think it’s also worth noting on your l10n/i18n comment that even localizing code has a big impact on your code base. Localizing makes code harder to read (as you have message keys, not messages in it), harder to maintain (refactoring often requires being sensitive to the location of messages in various bundles), and localizing when you don’t need to can make the process of i18n much more complicated for your translators as they need to know what messages do and do not need to be i18n’ed. So, there is much value in NOT localizing stuff that doesn’t need to be.
@Devil’sAdvocate: Good points all. I’d say that even though your point about message content is generally true, it would still be a lot more difficult to understand what’s happening in a log written in a different language, particularly if the variables being filled in are also in the other language.
@Per: On the last point, there is a certain class of exception whose purpose is to notify the user of a problem in user input and in that case, the exception message should be created for the purpose of display to a user. But I agree that that is hopefully a small subset of the total number of exception messages in a product. The rest are probably “unexpected” error conditions. However, all exception messages have a way of “bubbling up” to the top of the app and getting seen by a user. My general experience has been that the state of the practice in this area is far from the ideal, for the underestandable reason that it’s a lot harder to manage than any sane person would expect.
@Laurie, @Alex – you have “localisation” and “internationalisation” backwards. “Localisation” means adapting to a specific locale, by providing translations/formats/whatever appropriate to that place. “Internationalisation” is the step that comes first, making it possible to localise by removing hardcoded strings/whatever.
@Al: Ooops! Guess you’re right.
>> What if the same message is both logged AND thrown back to the user?
If the application is internationalized and localized in many languages, then using the same exception to log and show on the UI will not be that easy. Getting the locale, that the message needs to be localized in, to the business layer would also be cumbersome. It can be done however using Filters and ThreadLocals. A filter can pull up the locale from the user profile or the request headers and insert that Locale in to a ThreadLocal for later the business layer can use it, but for reasons others already mentioned, I think it will be better to just use English text in exceptions and log them and have some exception mapping facility, typically available in the MVCs now-a-days, to show the localized message in the UI.
Struts, and I think I have seen some other Apache projects, uses LocalStrings.properties and localizes messages based on the System default locale.