1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
//! Translation keys on errors, and the negotiated locale on the response.
//!
//! An error's `title` and `detail` are English prose. That is fine for a log
//! and useless for a user interface that has to render the same failure in
//! whatever language its user reads, so a client is left matching on English
//! substrings — which breaks the moment the wording is improved.
//!
//! This crate does not translate. It emits a **stable key** and the **params**
//! the message interpolates, and the client renders them against its own
//! catalog:
//!
//! ```json
//! {
//! "status": "422",
//! "code": "invalid_attribute",
//! "title": "Invalid attribute",
//! "detail": "must be 80 characters or fewer",
//! "source": { "pointer": "/data/attributes/name" },
//! "meta": {
//! "i18n": {
//! "key": "todo.name.too_long",
//! "params": { "max": 80 }
//! }
//! }
//! }
//! ```
//!
//! `title` and `detail` stay exactly as they were — they are the fallback for
//! a client with no catalog, and dropping them would break every existing
//! consumer. The key is *additional*, which is also why it lives under `meta`:
//! JSON:API fixes the members an error object may carry, and `meta` is the
//! member it provides for everything else. A client that does not know about
//! it sees an ordinary error object.
//!
//! # Why the server does not translate
//!
//! Reading `Accept-Language` and returning German prose is the other way to
//! do this, and it is worse here: it puts a message catalog, a negotiation
//! table and a release cycle for every wording change inside the API server,
//! and it still cannot localize what the client composes around the message.
//! The client already has a catalog — it renders its own UI — so the useful
//! thing to send it is the key, not a second translation of it.
//!
//! What the server *does* do is record which locale the client asked for, on
//! the document's top-level `meta`, so a response is self-describing about
//! what it negotiated. See [`Locale`].
use BTreeMap;
use ;
/// A translation key and the params its message interpolates.
///
/// Attached to a [`JsonApiError`](crate::JsonApiError) with
/// [`translate`](crate::JsonApiError::translate), and serialized under the
/// error object's `meta.i18n`.
///
/// The key is yours: this crate never invents one, and never rewrites one.
/// Keep it stable across wording changes — that is the whole point of it —
/// and namespace it however your catalog is organized.
/// The locale the client asked for, as negotiated from `Accept-Language`.
///
/// Recorded on the response's top-level `meta.lang` so a response says which
/// locale it was produced for, and carried on the [`Context`](crate::Context)
/// so a handler that *does* have a catalog can consult it.
///
/// This is the client's request, not a promise: nothing in this crate
/// translates, so `lang` describes what was asked for and the
/// [`Translation`] keys are what make honouring it possible.
;
/// Whether a token is shaped like a language tag.
///
/// Deliberately strict: this value is echoed into a response body, so it is
/// restricted to what a tag may contain rather than reflected verbatim.
/// Length-capped for the same reason — a header is client-supplied input.