Skip to content

Commit

Permalink
AIP-193: Update the rationale around LocalizedMessage
Browse files Browse the repository at this point in the history
Note: this removes the idea that LocalizedMessage is for "end users" as a distinction between that and Status.message being for developers. If we still want that distinction, we should talk about it more and clarify it - in particular, if we're using LocalizedMessage as an alternative for Status.message where the latter can't be changed, they can't really cater for different audiences.
  • Loading branch information
jskeet committed Oct 8, 2024
1 parent d090531 commit 623c023
Showing 1 changed file with 20 additions and 20 deletions.
40 changes: 20 additions & 20 deletions aip/general/0193.md
Original file line number Diff line number Diff line change
Expand Up @@ -392,28 +392,28 @@ variable information, so there needs to be machine-readable component of
*every* error response that enables clients to use such information
programmatically.

### LocalizedMessage
### Including LocalizedMessage

`LocalizedMessage` was selected as the location to present alternate
error messages. This is desirable when clients need to display a crafted
error message directly to end users. `LocalizedMessage` can be used with
a static `locale`. This may seem misleading, but it allows the service
to eventually localize without having to duplicate or move the error
message, which would be a backwards incompatible change.

Reasons to present the same error message in both locations include the following:

- The service plans to localize either immediately or in the near future. See,
"[Localization](#localization)".
- This practice enables clients to find an error message consistently in one
location, `LocalizedMessaage.message`, across all methods of the API Service.

Reasons to present an error message in `LocalizedMessage.message` that
differs from `Status.message` include the following:

- The service requires an end-user-facing error message that differs
from the "debug message".
- Ongoing, iterative error message improvements are expected.
error messages. While `LocalizedMessage` **may** use a locale specified
in the request, a service **may** provide a `LocalizedMessage` even without
a user-specified locale, typically to provide a better error message in
[situations where `Status.message` cannot be changed](updating-statusmessage).
Where the locale is not specified by the user, it **should** be `en-US`
(US English).

A service **may** include `LocalizedMessage` even when the same message is
provided in `Status.message` and when localization into a user-specified locale
is not supported. Reasons for this include:

- An intention to support user-specified localization in the near future, allowing
clients to consistently use `LocalizedMessage` and not change their error-reporting
code when the functionality is introduced.
- Consistency across all RPCs within a service: if some RPCs include
`LocalizedMessage` and some only use `Status.message` for error messages, clients
have to be aware of which RPCs will do what, or implement a fall-back mechanism.
Providing `LocalizedMessage` on all RPCs allows simple and consistent client code
to be written.

### Updating Status.message

Expand Down

0 comments on commit 623c023

Please sign in to comment.