On May 17, 2016, at 11:15 AM, Simon Hanna wrote:

Theoretically the core could translate the messages before passing them to postorius. This would require core to know about the language it should translate to. I don't think this is a very good approach because we would have to make sure we offer the same languages for core and postorius and I'm not sure how we would pass the languages to core...

Probably Accept-Language could be used to specify that, but I (think I) agree it's not the right approach. My only hesitation is to remember that Postorius isn't technically the only web front-end that could be connected to the core. If some homegrown ui also wanted translations, it's not clear how much they could leverage of existing work if all the translations lived in Postorius.

I propose core to return an error code with each request. That way postorius can add strings for all the errors that it cares about and translate them accordingly. This would require an api change. Since 3.1 would change the api anyway, it would be nice to include the changes there.

If we're going to return an application-specific error code (in addition to the HTTP response code we already return), then I think it means we'll be returning a JSON structure even on error conditions. Right now, JSON is only returned on success, and strings are returned on errors.

If we say in API 3.1 that JSON is always returned, then we have some additional options. What makes the most sense to me would be to always return a dictionary with some well-defined keys. That at least gives us a chance to evolve the API probably without having to rev the API version in the future.

One problem with returning Mailman-specific error codes is that we'll need *a lot* of them. Essentially one for every error condition in the REST API. I've always found such arrangements a nightmare to maintain and debug. Error codes have no obvious meaning so the mapping of code to meaning always has to be looked up. We could segment the error space so that there's some semantic equivalence (e.g. 01xx means a list-specific error, 02xx means a membership-specific error, etc.) but there's always some twisting that goes on the keep those up-to-date and meaningful within the semantics we give them.

And it's still not enough, because as you point out, there is always going to be variable data that has to be associated with the error. A good example is when a mailing list is created within a nonexistent domain. The error reason is something like:

'Domain does not exist: example.net'

which gets interpolated on the server side. So obviously an error code like 0135 won't help because you could only translate that to 'Domain does not exist' without also knowing the name of the domain that failed.

So now we also have to include some variable data in the JSON response. Which leads me to think, why do we need error codes when we already have a format perfectly suited to the cause, and which we already use internally for other translatable contexts, i.e. PEP 292 strings ($-strings).

Thus, our error responses could be something like:

{ 'reason': 'Domain does not exist: example.net', 'template': 'Domain does not exist: $domain', 'data': { 'domain': 'example.net', }, }

'reason' would always be the interpolated English (i.e. source) string. 'template', and 'data' should be obvious. We need a separate namespace for the interpolation data.

A front-end could just use the English reason, or it could translate the template and interpolate the data dictionary into it.

Making this change would be a lot of work, but it could be done in several branches.

One branch would provide the infrastructure to return JSON error responses. These would only be done for API 3.1, and possibly you'd also want to check the Accept header to make sure the client is prepared to accept JSON. Then all of the error reporting call sites would have to be changed to pass in the template and data dictionaries, with the helpers doing the interpolation for 'reason' and the setting up of the response correctly. Then tests and documentation. :)

If you like the general approach we can hash out implementation details. Given however that Pycon is near and I *really* want to get 3.1 out during Pycon and there are already at least two big features that still have to be added (unsubscription workflow and template support), it might be better to defer this to core 3.2 and API 3.2. That way, we can get it right without rushing it in.

Cheers, -Barry