-
Notifications
You must be signed in to change notification settings - Fork 2
/
readme.txt
307 lines (256 loc) · 10.3 KB
/
readme.txt
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
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
=== WPML JSON API ===
Contributors: dzachary
Donate link: https://store.lettersandlight.org
Tags: json, api, i18n, cms, wpml, multilingual, translation
Requires at least: 2.8
Tested up to: 3.4
Stable tag: 0.1.4
An extension to JSON-API for sites using the WPML Multilingual CMS plugin.
== Description ==
This plugin filters the response content of requests made to the WordPress [JSON-API](http://wordpress.org/extend/plugins/json-api) to include data for translations created through the [WPML Multilingual CMS](http://wpml.org) plugin. One may also request the translation of response objects to a supported target language.
[The Office of Letters and Light](http://www.lettersandlight.org) uses this plugin to integrate WordPress and [WPML](http://wpml.org) with its Rails-built [National Novel Writing Month](http://www.nanowrimo.org) event-site application. We use WordPress to manage all back-end site content and our [Kiosk Ruby gem](http://github.com/lettersandlight/kiosk) for consuming, caching, searching, and serving the content through Rails. This could not have been so easily accomplished without the well-built and extensible [JSON-API](http://wordpress.org/extend/plugins/json-api) for which we are grateful. And without the [WPML](http://wpml.org) plugin, we would not have such an intuitive and capable CMS i18n interface.
== Installation ==
1. Upload the `wpml-json-api` folder to the `/wp-content/plugins/` directory or install directly through the plugin installer.
2. Activate the plugin through the 'Plugins' menu in WordPress or by using the link provided by the plugin installer.
== Usage ==
Please be familiar with the
[JSON-API](http://wordpress.org/extend/plugins/json-api).
1. Augmented response objects
* 1.1. Language
* 1.2. Translations
2. Filtering response objects by language
* 2.1. Specifying the language
* 2.2. Filtered results
3. Response object translation
* 3.1 Specifying the target language
* 3.2 Translated results
* 3.3 Translatable objects and properties
== 1. Augmented response objects ==
== 1.1. Language ==
After enabling the WPML JSON-API plugin, response objects will contain the
language in which the object content was written.
Let's take a look at an example response to a request made to `http://wordpress.site.example/api/get_page/?dev=1&id=127`.
{
"status": "ok",
"page": {
"id": 127,
"type": "page",
"slug": "the-best-page",
"url": "http:\/\/wordpress.site.example\/the-best-page\/",
"status": "publish",
"title": "The Best Page",
"title_plain": "The Best Page",
"content": "<p>This is the best page ever created.<\/p>\n<blockquote><p>Best damn page ever. – Dan<\/p><\/blockquote>\n",
"excerpt": "This is the best page ever created. Best damn page ever. – Dan",
"date": "2011-09-22 18:48:09",
"modified": "2011-09-22 18:54:55",
"categories": [],
"tags": [],
"author": {
"id": 4,
"slug": "dzachary",
"name": "Daniel Duvall",
"first_name": "Daniel",
"last_name": "Duvall",
"nickname": "Daniel Duvall",
"url": "",
"description": ""
},
"comments": [],
"attachments": [],
"comment_count": 0,
"comment_status": "open",
"translations": {
"en": {
"post_title": "The Best Page",
"post_status": "publish",
"id": 21,
"language_code": "en",
"is_original": true,
"resource_id": 127
},
"es": {
"post_title": "La P\u00e1gina Mejor",
"post_status": "publish",
"id": 22,
"language_code": "es",
"is_original": false,
"resource_id": 131
}
},
"language": "en"
}
}
The `language` property specifies the code of the language in which the page
was written—pretty simple.
== 1.2. Translations ==
The `translations` objects of the same example response given in Section 1.1.
include data for each *published* resource that comprises a translation of
its parent object.
"translations": {
"en": {
"post_title": "The Best Page",
"post_status": "publish",
"id": 21,
"language_code": "en",
"is_original": true,
"resource_id": 127
},
"es": {
"post_title": "La P\u00e1gina Mejor",
"post_status": "publish",
"id": 22,
"language_code": "es",
"is_original": false,
"resource_id": 131
}
Properties included in each member of the `translations` object depend on the
type of parent object.
All `post` and `page` objects will include the following.
* `id` - The ID of the translation object.
* `language_code` - The code of the language in which the translation is written. Each translation object is also keyed by this value.
* `is_original` - Specifies whether the language of this translation is the language in which the original work was written.
* `resource_id` - The ID of the translated version of the parent object.
* `post_title` - The title of the translated post/page.
* `post_status` - The status of the translated post/page. Always 'publish'.
* `post_id` - Redundancy of `resource_id`.
All `category` objects will include the following.
* `id` - The ID of the translation object.
* `language_code` - The code of the language to which the category was translated.
* `is_original` - Specifies whether the language of this translation is the language of the original category.
* `resource_id` - The ID of the translated version of the parent object.
* `name` - The translated category name.
* `term_id` - Redundancy of `resource_id`.
* `post_count` - The number of posts tagged with the translated category.
== 2. Filtering response objects by language ==
You may tell the API to only return objects for a specific language by using
the `language` parameter.
== 2.1. Specifying the language ==
The `language` parameter should be one of the supported language codes.
Example:
* `http://wordpress.site.example/api/get_category_index/?language=es&dev=1`
== 2.2. Filtered results ==
Following is a example response to the example request in Section 2.1.
{
"status": "ok",
"count": 2,
"categories": [
{
"id": 13,
"slug": "noticias-de-ultima-hora-2",
"title": "Noticias de \u00daltima Hora",
"description": "",
"parent": 0,
"post_count": 1,
"translations": {
"en": {
"name": "Breaking News",
"term_id": 4,
"post_count": 2,
"id": 9,
"language_code": "en",
"is_original": true,
"resource_id": 4
},
"es": {
"name": "Noticias de \u00daltima Hora",
"term_id": 13,
"post_count": 1,
"id": 26,
"language_code": "es",
"is_original": false,
"resource_id": 13
}
},
"language": "es"
}
]
}
== 3. Response object translation ==
You can request objects to be translated before they are returned. This may
save you some requests if you have the slug or ID and just need the object in
a specific language.
== 3.1. Specifying the target language ==
The target language can be specified by passing a `to_language` parameter. The
value should be one of the supported language codes.
Example:
* `http://wordpress.site.example/api/get_page/?slug=the-best-page&to_language=es&dev=1`
== 3.2. Translated results ==
Following is an example response to the example request in Section 3.1.
{
"status": "ok",
"page": {
"id": 127,
"type": "page",
"slug": "la-pagina-mejor",
"url": "http:\/\/wordpress.site.example\/the-best-page\/",
"status": "publish",
"title": "La P\u00e1gina Mejor",
"title_plain": "La P\u00e1gina Mejor",
"content": "<p>Esta es la p\u00e1gina mejor se haya creado.<\/p>\n<blockquote><p>Best damn page ever. – Dan<\/p><\/blockquote>\n",
"excerpt": "Esta es la p\u00e1gina mejor se haya creado. Best damn page ever. – Dan",
"date": "2011-09-22 18:48:09",
"modified": "2011-09-22 18:54:55",
"categories": [],
"tags": [],
"author": {
"id": 4,
"slug": "dzachary",
"name": "Daniel Duvall",
"first_name": "Daniel",
"last_name": "Duvall",
"nickname": "Daniel Duvall",
"url": "",
"description": ""
},
"comments": [],
"attachments": [],
"comment_count": 0,
"comment_status": "open",
"translations": {
"en": {
"post_id": 127,
"post_title": "The Best Page",
"post_status": "publish",
"id": 21,
"language_code": "en",
"is_original": true,
"resource_id": 127
},
"es": {
"post_id": 131,
"post_title": "La P\u00e1gina Mejor",
"post_status": "publish",
"id": 22,
"language_code": "es",
"is_original": false,
"resource_id": 131
}
},
"language": "es",
"translated": true,
"original_slug": "the-best-page",
"original_title": "The Best Page",
"original_title_plain": "The Best Page"
}
}
As you can see the `slug`, `title`, `title_plain`, `excerpt`, and `content`
properties have been rewritten with the Spanish translation. In addition, the
original properties have been prefixed with `original_`. This is always the
case for all properties except for `excerpt` and `content`. In an effort to
save on response size, the latter have been omitted.
== 3.3. Translatable objects and properties ==
Here are all of the translatable object types and their translatable
properties, those that can be rewritten as described in Section 3.2.
Objects `post` and `page`:
* `slug`
* `title`
* `title_plain`
* `excerpt`
* `content`
Objects `tag` and `category`:
* `slug`
* `title`
* `description`
== Changelog ==
Please see the [GitHub project page](https://github.com/marxarelli/wpml-json-api) for a comprehensive list of changes.