Should exception messages be localized?

This article should help to decide if exception messages should be localized. The focus here are .NET applications. It is interesting to see that Microsoft has decided to go with localized exception messages. This decision is documented in the MSDN:

Include a localized description string in every exception. The error message that the user sees is derived from the description string of the exception that was thrown, and not from the exception class. [1]

Should a .NET application, library or framework follow the same strategy?

Exception messages targets developers to help them finding the bug. Users should see a different error message which is less technical and provides information how to solve the error. But I see it often that exception messages are directly shown to users because this saves development time. In this case a localized exception message can help a non-English speaking user to understand the error.

Another argument to go with localized exception messages is that it is consistent with the runtime environment (.NET Framework). Microsoft promotes to use localized messages in the Framework Design Guidelines:

Do localize exception messages. [2, 3]

On the other side, exception messages should always be readable by the developers. If the message is shown in a foreign language then the developer might not understand it. Furthermore, exceptions are often used within logging and diagnostics. In this case the messages should not be localized because as a developer I have to understand the log file independent of the user’s language.

Error messages from third party components are often used as search text to find more details in the internet. This works well as long the message is not localized. Otherwise, finding web pages with detailed information (e.g. Forums) is difficult.

Error codes

Unique error codes can solve the dilemma that we need different error messages for the developer and the user. The developer works with the error code and the message can target the user. Unfortunately, ensuring that error codes are unique over the whole system which might consist of independent libraries and modules is difficult and error prone. Furthermore, the Exception base class does not contain a property for an error code. So introducing them is just for the own code but not for 3rd party components.

I agree with Microsoft’s design decision that error codes should be avoided:

DO NOT return error codes. [4]

Conclusion

In my opinion exception messages should not be localized. These messages ought to provide information for developers and not the users.

I use a separate Exception base class if the exception should contain a user-friendly error message as well. It can be less effort to use the LocalizableException base class than to introduce error handling code that interprets the exception types and provides user-friendly error messages.

[Serializable]
public abstract class LocalizableException : Exception
{
    private readonly string displayMessage;

    protected LocalizableException() : this(null, null, null) { }

    protected LocalizableException(string message, string displayMessage) 
        : this(message, displayMessage, null) { }

    protected LocalizableException(string message, string displayMessage, 
        Exception innerException) 
        : base(message, innerException)
    {
        this.displayMessage = displayMessage;
    }

    protected LocalizableException(SerializationInfo info, 
        StreamingContext context)
        : base(info, context)
    {
        displayMessage = info.GetString("DisplayMessage");
    }

    public string DisplayMessage { get { return displayMessage; } }

    public override void GetObjectData(SerializationInfo info, 
        StreamingContext context)
    {
        base.GetObjectData(info, context);
        info.AddValue("DisplayMessage", displayMessage);
    }
}

Further readings

1. Best Practices for Exceptions
2. Framework Design Guidelines (Second Edition) - 7.2.1 Error Message Design
3. Brad Abrams Blog: Design Guidelines Update: Exception Message Guidelines
4. Framework Design Guidelines – Exception Throwing