From 623c02350f06b352c460c8a87446a883a5d10108 Mon Sep 17 00:00:00 2001 From: Jon Skeet Date: Tue, 8 Oct 2024 15:30:01 +0100 Subject: [PATCH] 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. --- aip/general/0193.md | 40 ++++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/aip/general/0193.md b/aip/general/0193.md index d222e2f94..4eb4d2d67 100644 --- a/aip/general/0193.md +++ b/aip/general/0193.md @@ -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