Improve i18n and UI text templating support of error messages
- Dominant language
- Python
- Stars
- 670
- Forks
- 183
- Avg merge
- 17h 7m
- Merged PRs (30d)
- 358
Description
## Historical Background
The GUI (including our WebUI) usually comes with an i18n subsystem to provide various UI texts in multiple languages. Such subsystem could be also used to abstract/wrap the low-level error messages to a more user-friendly texts. In contrast, the CLI often just prints the server-provided error messages as-is.
To allow GUI to provide localized and 'softened' user-friendly error messages, it should have its own text resources mapped with individual error messages from the server. This means we need a structured code system to identify all error messages case by case in the client side.
So far, we have adopted the idea of [RFC-7807](https://www.rfc-editor.org/rfc/rfc7807) and its successor [RFC-9457](https://www.rfc-editor.org/rfc/rfc9457) as abstracted as subclasses of `aiohttp.web.HTTPError` in [ai.backend.manager.api.exceptions](https://github.com/lablup/backend.ai/blob/main/src/ai/backend/manager/api/exceptions.py) using the _problem identifiers_ (the `type` field) like `https://api.backend.ai/probs/`.
An example from RFC-9457:
```Java
HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
Content-Language: en
{
"type": "https://example.com/probs/out-of-credit",
"title": "You do not have enough credit.",
"detail": "Your current balance is 30, but that costs 50.",
"instance": "/account/12345/msgs/abc",
"balance": 30,
"accounts": ["/account/12345",
"/account/67890"]
}
```
## Problem
As time goes on, there arose many cases that the frontend UI wants to use its own translation and writing of the error messages instead of directly displaying the `title` and `detail` fields of the problem JSON data. Also, the server-side code also began to reuse and share the same problem class (e.g., `VFolderOperationFailed`) to represent multiple different errors by changing the `title` and `detail` fields only.
This has made a confusing situation for both users and our frontend developers because there is no single source of the error message texts to refer and override.
## Solution and Direction
We need to divide the shared/reused problem classes and assign explicit, individual problem identifiers to all different `raise` of API handler errors.
- There will be too many subclasses. We could shrink the number of subclasses to one by introducing a common implementation of RFC-9457.
- Generate/preserve the `title` and `detail` fields in the server-side for the clients who does not have UI text mapping subsystems (e.g., CLI).
- Like the above example problem JSON, include error arguments like the target instance ID, related object references, etc. so that the clients who have a UI text mapping subsystem could implement a templated mapping to interpolate them in error message displays.\* The GUI should fall back to the original `title` and `detail` fields if it is not in the text template mapping.
- Make (auto-generate preferably) the full list of all problem identifier occurrences to refer in the documentation.\* Scan all Python source files and analyze/scan the AST?
- Consider the plugin codes that are not included in the monorepo.
- Devise a hierarchical naming rule of the problem identifiers, e.g., `{target-object-type}-{action}-{problem`}.
- Define several common user-defined problem JSON fields to indicate the source of errors (e.g., manager / agent / user workload) and the request ID (#1678).
JIRA Issue: BA-128
Contributor guide
Assessment
This issue has not been assessed yet.