Proposal: don't translate exceptions, don't display exceptions directly

[CharpentierLucas]

Hello!

Context

On XWIKI-23771 / PR #5830, an error message shown when a field gets an invalid value was translated. That raised a question: do we actually have a rule on translating exception messages? We do not yet, and we should agree on a standard way to answer this. Today, some exception messages reach the user completely untouched, for example rendering macro errors, so there’s no consistent practice either way.

Problem

An exception’s message can end up in two very different places: the logs, and sometimes directly in front of a user. Those two places want different things. Logs are technical by nature, they should stay in a fixed, unambiguous form so they’re actually useful for debugging, whoever ends up reading them. Anything in the UI, on the other hand, should be translated like any other user-facing text. Translating the exception’s own message tries to serve both at once and doesn’t really work for either.

Proposal

Keep exception messages technical always. Whatever code catches an exception and needs to show something in the UI should build its own translated message there, instead of relaying the exception’s message directly.

Opinion

+1 from me for this proposal .

Conclusion

Did I miss a critical aspect of this proposal? Do you agree with what’s proposed?

Whatever we land on, I think it should be written down as an actual practice so we can agree on it quickly in upcoming improvements. I’ll close this topic in a week if it doesn’t spur a larger discussion, and add it to the Translation Best Practices section. I’m not sure it’s the best place for this, is there any other page where this code practice would fit better?

Thank you for your interest in the topic! I’m looking forward to your answers
Lucas C.

[mleduc]

@CharpentierLucas

An exception’s message can end up in two very different places: the logs, and sometimes directly in front of a user. Those two places want different things. Logs are technical by nature, they should stay in a fixed, unambiguous form so they’re actually useful for debugging, whoever ends up reading them. Anything in the UI, on the other hand, should be translated like any other user-facing text. Translating the exception’s own message tries to serve both at once and doesn’t really work for either.

+1 on the general principle

@CharpentierLucas

and add it to the Translation Best Practices section

-1, I would instead put this in our coding best practices next to the other error handling best practices.

Also, some things to have in mind:

• The place where the exception is thrown might not always have access to the local of the end user (e.g., asynchronous job)
• We sometime want to display technical details (always in English) the advanced users in the UI

With that in mind, I think the best pattern is to have the following information held in the exception:

• The technical message in English. This on is printed in the logs
• The parent exception if any
• The localization key
• The list of localization parameters

That way, all the data needs to proceed to the translation is available, and can be translated using the relevant locale at rendering time.
In terms of implementation, we could provide a shared abstract exception class with the mandatory fields (to be explored).

Also (brainstorming), I wonder if a unique “error type” fields could be interesting, to help receivers of an exception know in which sub-error case they are, without relying on dozens of sub-classes.
In the same way HTTP status code works.

[tmortagne]

@mleduc

In terms of implementation, we could provide a shared abstract exception class with the mandatory fields (to be explored).

Feels like you are proposing to introduce xwiki-commons/xwiki-commons-core/xwiki-commons-logging/xwiki-commons-logging-api/src/main/java/org/xwiki/logging/AbstractMessageException.java at master · xwiki/xwiki-commons · GitHub (yes, messages/logs are translatable)