sanity-plugin-transifex 2.0.3 → 2.0.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +60 -186
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,18 +1,49 @@
|
|
|
1
1
|
# Sanity + Transifex = 🌍
|
|
2
2
|
|
|
3
3
|
|
|
4
|
-
This plugin provides an in-studio integration with [Transifex](https://transifex.com). It allows your editors to send any document to Transifex with the click of a button, monitor ongoing translations, and import partial or complete translations back into the studio.
|
|
4
|
+
This plugin provides an in-studio integration with [Transifex](https://transifex.com). It allows your editors to send any document to Transifex with the click of a button, monitor ongoing translations, and import partial or complete translations back into the studio.
|
|
5
5
|
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
6
|
+
# Table of Contents
|
|
7
|
+
- [Plugin features](#plugin-features)
|
|
8
|
+
- [Assumptions](#assumptions)
|
|
9
|
+
- [Quickstart](#quickstart)
|
|
10
|
+
- [Studio experience](#studio-experience)
|
|
11
|
+
- [Overriding defaults](#overriding-defaults)
|
|
12
|
+
- [v1 to v2 changes](#v1-to-v2-changes)
|
|
12
13
|
|
|
13
|
-
So let's get started!
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
## Plugin features
|
|
16
|
+
|
|
17
|
+
This plugin comes with (and exposes to the developer) the following items:
|
|
18
|
+
- An `Adapter` that connects to the Transifex API with methods to create a new translation job, upload and assign a file to that translation job, check the progress of an ongoing translation, and retrieve a translated file.
|
|
19
|
+
- A `Serializer` that transforms your content into HTML (we found this was the most efficient way to maintain your document structure, no matter how deeply nested, while remaining readable to translators in Transifex). The `Serializer` takes in optional arguments: `stopTypes`, which prevents certain types from being sent to your translatiors and `customSerializers`, which are rules you can use to have full control over how individual fields on your document get serialized.
|
|
20
|
+
- A `Deserializer` that deserializes translated text back to Sanity's format.
|
|
21
|
+
- A `Patcher` which determines how your content gets patched back into its destination document or field.
|
|
22
|
+
- A `TranslationsTab`, a React element that allows a non-technical user to import, export, and monitor Transifex progress.
|
|
23
|
+
|
|
24
|
+
To make life easier, we also include `defaultFieldLevelConfig` and `defaultDocumentLevelConfig`, which bundles all of the above up to get you up and running quickly.
|
|
25
|
+
|
|
26
|
+
## Assumptions
|
|
27
|
+
To use the default config mentioned above, we assume that you are following the conventions we outline in [our documentation on localization](https://www.sanity.io/docs/localization).
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
### Field-level translations
|
|
31
|
+
If you are using field-level translation, we assume any fields you want translated exist in the multi-locale object form we recommend.
|
|
32
|
+
For example, on a document you don't want to be translated, you may have a "title" field that's a flat string: `title: 'My title is here.'` For a field you want to include many languages for, your title may look like
|
|
33
|
+
```
|
|
34
|
+
{ title: {
|
|
35
|
+
en: 'My title is here.',
|
|
36
|
+
es: 'Mi título está aquí.',
|
|
37
|
+
etc...
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
### Document level translations
|
|
43
|
+
Since we often find users want to use the [Document internationalization plugin](https://www.sanity.io/plugins/document-internationalization) if they're using document-level translations, we assume that any documents you want in different languages will follow the pattern `{id-of-base-language-document}__i18n_{locale}`
|
|
44
|
+
|
|
45
|
+
### Final note
|
|
46
|
+
It's okay if your data doesn't follow these patterns and you don't want to change them! You will simply have to override how the plugin gets and patches back information from your documents. Please see [Overriding defaults](#overriding-defaults).
|
|
16
47
|
|
|
17
48
|
## Quickstart
|
|
18
49
|
|
|
@@ -64,197 +95,40 @@ export const getDefaultDocumentNode = (props) => {
|
|
|
64
95
|
|
|
65
96
|
And that should do it! Go into your studio, click around, and check the document in Transifex (it should be under its Sanity `_id`). Once it's translated, check the import by clicking the `Import` button on your Transifex tab!
|
|
66
97
|
|
|
67
|
-
|
|
68
|
-
|
|
98
|
+
## Studio experience
|
|
99
|
+
By adding the `TranslationsTab` to your desk structure, your users should now have an additional view. The boxes at the top of the tab can be used to send translations off to Transifex, and once those jobs are started, they should see progress bars monitoring the progress of the jobs. They can import a partial or complete job back.
|
|
69
100
|
|
|
70
|
-
|
|
101
|
+
## Overriding defaults
|
|
71
102
|
|
|
72
|
-
|
|
73
|
-
* `
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
* `defaultFieldLevelConfig`:
|
|
77
|
-
* Your base language is English.
|
|
78
|
-
* Any fields you want translated exist in the multi-locale object form we recommend.
|
|
79
|
-
For example, on a document you don't want to be translated, you may have a "title" field that's a flat string: `title: 'My title is here.'` For a field you want to include many languages for, your title may look like
|
|
80
|
-
```
|
|
81
|
-
{ title: {
|
|
82
|
-
en: 'My title is here.',
|
|
83
|
-
es: 'Mi título está aquí.',
|
|
84
|
-
etc...
|
|
85
|
-
}
|
|
86
|
-
}
|
|
87
|
-
```
|
|
88
|
-
This config will look for the English values on all fields that look like this, and place translated values into their appropriate fields.
|
|
89
|
-
|
|
90
|
-
If your content models don't look like this, you can still run the defaults as an experiment -- you'll just likely get some funky results on import!
|
|
91
|
-
|
|
92
|
-
<br />
|
|
93
|
-
<br />
|
|
103
|
+
To personalize this configuration it's useful to know what arguments go into `TranslationsTab` as options (the `defaultConfigs` are just wrappers for these):
|
|
104
|
+
* `exportForTranslation`: a function that takes your document id and returns an object with `name`: the field you want to use identify your doc in Transifex (by default this is `_id` and `content`: a serialized HTML string of all the fields in your document to be translated.
|
|
105
|
+
* `importTranslation`: a function that takes in `id` (your document id) `localeId` (the locale of the imported language) and `document` the translated HTML from Transifex. It will deserialize your document back into an object that can be patched into your Sanity data, and then executes that patch.
|
|
106
|
+
* `Adapter`: An interface with methods to send things over to Transifex. You likely don't want to override this!
|
|
94
107
|
|
|
95
|
-
|
|
108
|
+
There are a number of reasons to override these functions. More general cases are often around ensuring documents serialize and deserialize correctly. Since the serialization fucntions are used across all our translation plugins currently, you can find some frequently encountered scenarios at [their repository here](https://github.com/sanity-io/sanity-naive-html-serializer), along with code examples for new config.
|
|
96
109
|
|
|
97
|
-
|
|
98
|
-
<br />
|
|
99
|
-
<br />
|
|
110
|
+
## V1 to V2 changes
|
|
100
111
|
|
|
101
|
-
|
|
102
|
-
First: this is often caused by not declaring types at the top level of your schema. Serialization introspects your schema files and can get a much better sense of what to do when objects are not "anonymous" (this is similar to how our GraphQL functions work -- more info on "strict" schemas [here](https://www.sanity.io/docs/graphql#33ec7103289a)) You can save yourself some development time by trying this first.
|
|
103
|
-
|
|
104
|
-
If that's still not doing the trick, you can add on to the serializer to ensure you have complete say over how an object gets serialized and deserialized. Under the hood, serialization is using Sanity's [blocks-to-html](https://github.com/sanity-io/block-content-to-html), and the same principles apply here. We strongly recommend you check that documentation to understand how to use these serialization rules. Here's how you might declare and use some custom serialization.
|
|
105
|
-
|
|
106
|
-
First, write your serialization rules:
|
|
112
|
+
Most users will not encounter issues in upgrading to v2. The breaking changes are as follows:
|
|
107
113
|
|
|
114
|
+
1. **Change to document-level localization id structure.** Since the [Internationalization input plugin](https://www.sanity.io/plugins/sanity-plugin-intl-input) was deprecated, the default pattern `i18n.{id-of-base-language-document}.{locale}` was deprecated in favor of `{id-of-base-language-document}__i18n_{locale}`. If you would like to maintain that pattern, please add the `idStructure` param to your tab config, like:
|
|
108
115
|
```javascript
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
const myCustomSerializerTypes = {
|
|
113
|
-
...customSerializers.types,
|
|
114
|
-
myType: (props) => {
|
|
115
|
-
const innerElements = //do things with the props
|
|
116
|
-
//className and id is VERY important!! don't forget them!!
|
|
117
|
-
return h('div', { className: props.node._type, id: props.node._key }, innerElements)
|
|
118
|
-
}
|
|
119
|
-
}
|
|
120
|
-
|
|
121
|
-
const myCustomSerializers = customSerializers
|
|
122
|
-
myCustomSerializers.types = myCustomSerializerTypes
|
|
123
|
-
|
|
124
|
-
const myCustomDeserializer = {
|
|
125
|
-
types: {
|
|
126
|
-
myType: (htmlString) => {
|
|
127
|
-
//parse it back out!
|
|
128
|
-
}
|
|
129
|
-
}
|
|
130
|
-
}
|
|
131
|
-
|
|
116
|
+
S.view.component(TranslationsTab).title('Transifex').options(
|
|
117
|
+
{...defaultDocumentLevelConfig, idStructure: 'subpath'}
|
|
118
|
+
)
|
|
132
119
|
```
|
|
133
|
-
|
|
134
|
-
If your object is inline, then you may need to use the deserialization rules in Sanity's [block-tools](https://github.com/sanity-io/sanity/tree/next/packages/@sanity/block-tools) (also used in deserialzation. So you might declare something like this:
|
|
135
|
-
|
|
136
|
-
```javascript
|
|
137
|
-
const myBlockDeserializationRules = [
|
|
138
|
-
{
|
|
139
|
-
deserialize(el, next, block) {
|
|
140
|
-
if (el.className.toLowerCase() != myType.toLowerCase()) {
|
|
141
|
-
return undefined
|
|
142
|
-
}
|
|
143
|
-
|
|
144
|
-
//do stuff with the HTML string
|
|
145
|
-
return {
|
|
146
|
-
_type: 'myType',
|
|
147
|
-
//all my other fields
|
|
148
|
-
})
|
|
149
|
-
}
|
|
150
|
-
]
|
|
151
|
-
```
|
|
152
|
-
|
|
153
|
-
Now, to bring it all together:
|
|
154
|
-
|
|
155
|
-
```javascript
|
|
156
|
-
import { TranslationTab, defaultDocumentLevelConfig, BaseDocumentSerializer, BaseDocumentDeserializer, BaseDocumentPatcher, defaultStopTypes } from "sanity-plugin-transifex"
|
|
157
|
-
|
|
158
|
-
const myCustomConfig = {
|
|
159
|
-
...defaultDocumentLevelConfig,
|
|
160
|
-
exportForTranslation: (id) =>
|
|
161
|
-
BaseDocumentSerializer.serializeDocument(
|
|
162
|
-
id,
|
|
163
|
-
'document',
|
|
164
|
-
'en',
|
|
165
|
-
defaultStopTypes,
|
|
166
|
-
myCustomSerializers),
|
|
167
|
-
importTranslation: (id, localeId, document) => {
|
|
168
|
-
return BaseDocumentDeserializer.deserializeDocument(
|
|
169
|
-
id,
|
|
170
|
-
document,
|
|
171
|
-
myCustomDeserializer,
|
|
172
|
-
myBlockDeserializationRules).then(
|
|
173
|
-
deserialized =>
|
|
174
|
-
BaseDocumentPatcher.documentLevelPatch(deserialized, id, localeId)
|
|
175
|
-
)
|
|
176
|
-
}
|
|
177
|
-
}
|
|
178
|
-
|
|
179
|
-
```
|
|
180
|
-
|
|
181
|
-
Then, in your document structure, just feed the config into your `TranslationTab`.
|
|
182
|
-
|
|
183
|
-
```javascript
|
|
184
|
-
S.view.component(TranslationTab).title('Transifex').options(
|
|
185
|
-
myCustomConfig
|
|
186
|
-
)
|
|
187
|
-
```
|
|
188
|
-
|
|
189
|
-
<br />
|
|
190
|
-
<br />
|
|
191
|
-
|
|
192
|
-
### Scenario: I want to have more granular control over how my documents get patched back to my dataset.
|
|
193
|
-
|
|
194
|
-
If all the serialization is working to your liking, but you have a different setup for how your document works, you can overwrite that patching logic.
|
|
195
|
-
|
|
120
|
+
2. **Underlying changes in serializers.** Serializers were updated to a) take advantage of the newer [Portable Text to HTML package](https://github.com/portabletext/to-html) and allow for explicit schema closures. If you were overriding serialization methods, that means invocation of `BaseDocumentSerializer` will change from:
|
|
196
121
|
```javascript
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
const myCustomConfig = {
|
|
200
|
-
...defaultDocumentLevelConfig,
|
|
201
|
-
importTranslation: (id, localeId, document) => {
|
|
202
|
-
return BaseDocumentDeserializer.deserializeDocument(id,document).then(
|
|
203
|
-
deserialized =>
|
|
204
|
-
//you should have an object of translated values here. Do things with them!
|
|
205
|
-
)
|
|
206
|
-
}
|
|
207
|
-
}
|
|
122
|
+
BaseDocumentSerializer.serializeDocument(id, 'serialization-level')
|
|
208
123
|
```
|
|
209
124
|
|
|
210
|
-
|
|
211
|
-
<br />
|
|
212
|
-
|
|
213
|
-
### Scenario: I want to ensure certain fields never get sent to my translators.
|
|
214
|
-
The serializer actually introspects your schema files. You can set `localize: false` on a schema and that field should not be sent off. Example:
|
|
125
|
+
to:
|
|
215
126
|
```javascript
|
|
216
|
-
|
|
217
|
-
name: 'categories',
|
|
218
|
-
type: 'array',
|
|
219
|
-
localize: false,
|
|
220
|
-
...
|
|
221
|
-
}]
|
|
222
|
-
```
|
|
223
|
-
|
|
224
|
-
<br />
|
|
225
|
-
<br />
|
|
226
|
-
|
|
227
|
-
### Scenario: I want to ensure certain types of objects never get serialized or sent to my translators.
|
|
228
|
-
|
|
229
|
-
This plugin ships with a specification called `stopTypes`. By default it ignores fields that don't have useful linguistic information -- dates, numbers, etc. You can add to it easily.
|
|
230
|
-
|
|
231
|
-
```javascript
|
|
232
|
-
import { TranslationTab, defaultDocumentLevelConfig, defaultStopTypes, BaseDocumentSerializer } from "sanity-plugin-transifex"
|
|
233
|
-
|
|
234
|
-
const myCustomStopTypes = [
|
|
235
|
-
...defaultStopTypes,
|
|
236
|
-
'listItem'
|
|
237
|
-
]
|
|
238
|
-
|
|
239
|
-
const myCustomConfig = {
|
|
240
|
-
...defaultDocumentLevelConfig,
|
|
241
|
-
exportForTranslation: (id) => BaseDocumentSerializer.serializeDocument(
|
|
242
|
-
id, 'document', 'en', myCustomStopTypes)
|
|
243
|
-
}
|
|
244
|
-
```
|
|
245
|
-
|
|
246
|
-
As above, feed the config into your `TranslationTab`.
|
|
247
|
-
|
|
248
|
-
```javascript
|
|
249
|
-
|
|
250
|
-
S.view.component(TranslationTab).title('Transifex').options(
|
|
251
|
-
myCustomConfig
|
|
252
|
-
)
|
|
127
|
+
import schemas from 'part:@sanity/base/schema'
|
|
253
128
|
|
|
129
|
+
BaseDocumentSerializer(schemas).serializeDocument(id, 'serialization-level')
|
|
254
130
|
```
|
|
255
131
|
|
|
256
|
-
There's a number of further possibilities here. Pretty much every interface provided can be partially or fully overwritten. Do write an issue if something seems to never work how you expect, or if you'd like a more elegant way of doing things.
|
|
257
132
|
|
|
258
|
-
This plugin is in early stages. We plan on improving some of the user-facing
|
|
133
|
+
This plugin is in early stages. We plan on improving some of the user-facing chrome, sorting out some quiet bugs, figuring out where things don't fail elegantly, etc. Please be a part of our development process!
|
|
259
134
|
|
|
260
|
-
|
package/package.json
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
{
|
|
2
|
-
"version": "2.0.
|
|
2
|
+
"version": "2.0.6",
|
|
3
3
|
"license": "MIT",
|
|
4
4
|
"main": "dist/index.js",
|
|
5
5
|
"typings": "dist/index.d.ts",
|
|
@@ -56,6 +56,6 @@
|
|
|
56
56
|
"typescript": "^4.0.5"
|
|
57
57
|
},
|
|
58
58
|
"dependencies": {
|
|
59
|
-
"sanity-translations-tab": "^2.0.
|
|
59
|
+
"sanity-translations-tab": "^2.0.8"
|
|
60
60
|
}
|
|
61
61
|
}
|