AIP-193: Update the LocalizedMessage section

Note that we don't currently (as far as I'm aware) have a good standardized way of letting users specify a locale. (Can they use Accept-Language, for example? What about in gRPC?) We can tackle that separately.

This commit changes the guidance in a couple of important ways:

- It says that the locale should be a user-specified one rather than a "service's native language"
- It calls out the ability to use LocalizedMessage even when we don't have a user-specified language, when Status.message can't be changed for compatibility reasons

This commit *doesn't* address the issue of the target audience of LocalizedMessage; later text claims this is aimed at end-users whereas Status.message is more aimed at developers. I'm not convinced by that at the moment.

Author: jskeet

aip/general/0193.md

@@ -172,55 +172,37 @@ The set of keys provided in each (reason, domain) pair is independent from other
 but services **should** aim for consistent key naming. For example, two error reasons
 within the same domain should not use metadata keys of `vmType` and `virtualMachineType`.
 
-#### Localization
-
-If a localized error message is required, the service **must** include
-[`google.rpc.LocalizedMessage`][LocalizedMessage] in `Status.details`.
-The value of the `Status.message` string **should** be presented in the
-service's native language in the `LocalizedMessage.message` string,
-while also ensuring that the `locale` string shows the correct language.
-
-#### LocalizedMessage payload
-
-The LocalizedMessage payload **should** contain the complete resolution
-to the error. If more information is needed than can fit in this
+#### LocalizedMessage
+
+[`google.rpc.LocalizedMessage`][LocalizedMessage] is used to provide an error
+message which **should** be localized to a user-specified locale where
+possible.
+
+If the [`Status.message`](#status-message) field has a sub-optimal value
+which cannot be changed due to the constraints in the
+[Changing Error Messages](#changing-error-messages) section, `LocalizedMessage`
+**may** be used to provide a better error message even when no user-specified
+locale is available.
+
+Regardless of how the locale for the message was determined, both the `locale`
+and `message` fields **must** be populated.
+
+The `locale` field specifies the locale of the message,
+following [IETF bcp47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) (Tags for
+Identifying Languages). Example values: `"en-US"`, `"fr-CH"`, `"es-MX"`.
+
+The `message` field contains the localized text itself. This
+**should** include a brief description of the error and a call to action
+to resolve the error. The message **should** include contextual information
+to make the message as specific as possible. Any contextual information
+in the message **must** be included in `ErrorInfo.metadata`. See
+[`ErrorInfo`](#errorinfo) for more details of how contextual information
+may be included in a message and the corresponding metadata.
+
+The `LocalizedMessage` payload **should** contain the complete resolution
+to the error. If more information is needed than can reasonably fit in this
 payload, then additional resolution information **must** be provided in
-the Help payload.  See the [Help payload](#help-payload)
-section for guidance.
-
-For pre-existing (brownfield) APIs, the content in this `message` string
-will differ from the `message` string in `google.rpc.status`.
-
-[LocalizedMessage Payload][LocalizedMessage]
-
-Details of this object are summarized in the following fields, field
-descriptions, and examples:
-
-- `locale string`
-  - The locale that follows the specification defined in [IETF
-    bcp47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) (Tags for
-    Identifying Languages).
-  - *Example*: **"en-US"**, **"fr-CH"**, **"es-MX"**
-- `message string`
-  - The error message that the customer will receive through their
-    chosen service, which **should** include a brief description of the
-    error and a call to action to resolve the error. The message
-    **should** include, where needed, data provided in other fields such
-    as metadata.
-  - Give users clear and concise instructions for resolving the error,
-    which **must** be explicit as possible; for example:
-
-    > Consider trying your request in the <AVAILABLE-ZONE-1>,
-    > <AVAILABLE-ZONE-N> zone(s), which currently has/have capacity to
-    > accommodate your request. Alternatively, you can try your request
-    > again with a different VM hardware configuration or at a later
-    > time.
-
-  - If the error resolution exceeds the number of characters supported in
-    the problem description (`message` string of `google.rpc.Status`),
-    or requires multiple troubleshooting steps, include the most
-    common resolution in the message and use the `Help` payload to
-    link to relevant documentation.
+a `Help` payload.  See the [Help](#help) section for guidance.
 
 #### Help payload