Agent Wranglers

LOC-34Recommended

Give every error a code that clients can translate

Every error carries a stable code and the values a client needs to build its own message. The code never changes with the language, and only the human text is translated.

By Agent Wranglers. Updated .

How to do it

A mobile app shows errors in the user's language, which may not be the language the server chose. Give it the problem type from Keep error types stable, the field pointer and named values such as max. RFC 9457 lets title change only for localization, so translate title and detail but keep type fixed. The client looks the code up in its own message file, written as Translate whole sentences says.

Examples

JSON example

{
  "type": "https://api.example.com/problems/too-long",
  "title": "Der Wert ist zu lang",
  "status": 422,
  "errors": [{ "pointer": "#/name", "code": "too-long", "max": 80 }]
}

JavaScript example

// Client: build the message from the code and the values
const text = intl.formatMessage(messages[error.code], { max: error.max });

Python example

# Client: build the message from the code and the values
text = translations.gettext(error["code"]).format(max=error["max"])

How to check

A test triggers each error with Accept-Language: en and with de. The type, pointer and values are equal in both answers, and only title and detail differ.

Sources

For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/localization/apis-and-data/error-codes-for-translation">Agent Wranglers localization playbook</a>. In code you write, add a comment next to it with the same link.