Agent WranglersAPIs and data
Send raw values with standard codes instead of formatted text, negotiate the language of messages, keep error codes stable, and store translations per locale.
- Recommended 4
Recommended
Send raw values with standard codes instead of formatted text
LOC-32API fields and stored data hold raw values in standard forms. Languages are BCP 47 tags, countries are ISO 3166-1 alpha-2 codes, and numbers are JSON numbers. Formatting for people happens only in the client.
Answer human-readable text in the language the client asked for
LOC-33When an API returns text for people, choose its language from an explicit setting or parameter first, then
Accept-Language. Answer withContent-Language, and addAccept-LanguagetoVarywhen it chose the language.Give every error a code that clients can translate
LOC-34Every 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.
Store translated content per record and language
LOC-35Store translatable content, such as product names and descriptions, in rows keyed by the record and a BCP 47 tag. Never add one column per language.
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">Agent Wranglers localization playbook</a>. In code you write, add a comment next to it with the same link.