Skip to content

Commit be29028

Browse files
committed
AIP-193: Update the rationale around LocalizedMessage
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.
1 parent b79cee5 commit be29028

1 file changed

Lines changed: 20 additions & 20 deletions

File tree

aip/general/0193.md

Lines changed: 20 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -392,28 +392,28 @@ variable information, so there needs to be machine-readable component of
392392
*every* error response that enables clients to use such information
393393
programmatically.
394394

395-
### LocalizedMessage
395+
### Including LocalizedMessage
396396

397397
`LocalizedMessage` was selected as the location to present alternate
398-
error messages. This is desirable when clients need to display a crafted
399-
error message directly to end users. `LocalizedMessage` can be used with
400-
a static `locale`. This may seem misleading, but it allows the service
401-
to eventually localize without having to duplicate or move the error
402-
message, which would be a backwards incompatible change.
403-
404-
Reasons to present the same error message in both locations include the following:
405-
406-
- The service plans to localize either immediately or in the near future. See,
407-
"[Localization](#localization)".
408-
- This practice enables clients to find an error message consistently in one
409-
location, `LocalizedMessaage.message`, across all methods of the API Service.
410-
411-
Reasons to present an error message in `LocalizedMessage.message` that
412-
differs from `Status.message` include the following:
413-
414-
- The service requires an end-user-facing error message that differs
415-
from the "debug message".
416-
- Ongoing, iterative error message improvements are expected.
398+
error messages. While `LocalizedMessage` **may** use a locale specified
399+
in the request, a service **may** provide a `LocalizedMessage` even without
400+
a user-specified locale, typically to provide a better error message in
401+
[situations where `Status.message` cannot be changed](updating-statusmessage).
402+
Where the locale is not specified by the user, it **should** be `en-US`
403+
(US English).
404+
405+
A service **may** include `LocalizedMessage` even when the same message is
406+
provided in `Status.message` and when localization into a user-specified locale
407+
is not supported. Reasons for this include:
408+
409+
- An intention to support user-specified localization in the near future, allowing
410+
clients to consistently use `LocalizedMessage` and not change their error-reporting
411+
code when the functionality is introduced.
412+
- Consistency across all RPCs within a service: if some RPCs include
413+
`LocalizedMessage` and some only use `Status.message` for error messages, clients
414+
have to be aware of which RPCs will do what, or implement a fall-back mechanism.
415+
Providing `LocalizedMessage` on all RPCs allows simple and consistent client code
416+
to be written.
417417

418418
### Updating Status.message
419419

0 commit comments

Comments
 (0)