@textunited/sanity-plugin 0.0.0-stage → 0.1.1
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/CHANGELOG.md +28 -0
- package/LICENSE.md +21 -0
- package/README.md +182 -2
- package/dist/chunk-BC676THN.cjs +1059 -0
- package/dist/chunk-BC676THN.cjs.map +1 -0
- package/dist/chunk-BEHPJRZM.cjs +870 -0
- package/dist/chunk-BEHPJRZM.cjs.map +1 -0
- package/dist/chunk-L37ROFN6.js +1052 -0
- package/dist/chunk-L37ROFN6.js.map +1 -0
- package/dist/chunk-TA5JUFXP.js +833 -0
- package/dist/chunk-TA5JUFXP.js.map +1 -0
- package/dist/config-Dcl8jU4S.d.cts +43 -0
- package/dist/config-Dcl8jU4S.d.ts +43 -0
- package/dist/next/index.cjs +18 -0
- package/dist/next/index.cjs.map +1 -0
- package/dist/next/index.d.cts +21 -0
- package/dist/next/index.d.ts +21 -0
- package/dist/next/index.js +16 -0
- package/dist/next/index.js.map +1 -0
- package/dist/server/index.cjs +33 -0
- package/dist/server/index.cjs.map +1 -0
- package/dist/server/index.d.cts +329 -0
- package/dist/server/index.d.ts +329 -0
- package/dist/server/index.js +4 -0
- package/dist/server/index.js.map +1 -0
- package/dist/studio/index.cjs +1005 -0
- package/dist/studio/index.cjs.map +1 -0
- package/dist/studio/index.d.cts +41 -0
- package/dist/studio/index.d.ts +41 -0
- package/dist/studio/index.js +1003 -0
- package/dist/studio/index.js.map +1 -0
- package/package.json +89 -4
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.1.1 – 2026-11-11
|
|
4
|
+
|
|
5
|
+
- Fix: a new translation lost what is not text. A blog post translated into a new language
|
|
6
|
+
kept only the alt text of its main image (no file), which broke the translated page; rich
|
|
7
|
+
text in a new language lost its blocks without text (images, code, tables). New
|
|
8
|
+
translations now start as a copy of the source, with the texts replaced by their
|
|
9
|
+
translations; canonical URLs are not copied, so the translation does not point search
|
|
10
|
+
engines to the source page.
|
|
11
|
+
|
|
12
|
+
## 0.1.0 – 2026-11-10
|
|
13
|
+
|
|
14
|
+
First release.
|
|
15
|
+
|
|
16
|
+
- Translate Sanity documents with TextUnited from a panel in the Studio: what needs translation
|
|
17
|
+
with a word count, one button to send, review progress per language, a badge in the document
|
|
18
|
+
footer, links to the TextUnited projects, history.
|
|
19
|
+
- One permanent TextUnited project per document; later changes are added as new tasks
|
|
20
|
+
(`appendContent`), only the new and changed texts.
|
|
21
|
+
- Field-level (Internationalized Array) and document-level (Document Internationalization)
|
|
22
|
+
localization, Portable Text with marks.
|
|
23
|
+
- Outsourced and in-house projects, with the team picked from the TextUnited account.
|
|
24
|
+
- Languages added later are ordered as a separate project; reset to a new project; stop and
|
|
25
|
+
resume a language per document.
|
|
26
|
+
- Notifications from TextUnited and a periodic check write reviewed translations to drafts;
|
|
27
|
+
translations edited by hand in Sanity are kept.
|
|
28
|
+
- Checks of the setup (localization plugins, language ids, TextUnited language codes).
|
package/LICENSE.md
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 TextUnited
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,183 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @textunited/sanity-plugin
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Translate Sanity content with TextUnited. One package with three entry points:
|
|
4
|
+
|
|
5
|
+
| Import | Runs in | Purpose |
|
|
6
|
+
|---|---|---|
|
|
7
|
+
| `@textunited/sanity-plugin/studio` | Sanity Studio (browser) | Translate action and translation status in the Studio |
|
|
8
|
+
| `@textunited/sanity-plugin/server` | the customer's server | Framework-independent handler (web `Request`/`Response`) that talks to TextUnited and writes translations to Sanity |
|
|
9
|
+
| `@textunited/sanity-plugin/next` | Next.js App Router | Thin adapter around the server handler |
|
|
10
|
+
|
|
11
|
+
The TextUnited access token and the Sanity write token are used only on the server. The Studio
|
|
12
|
+
entry never contains server code.
|
|
13
|
+
|
|
14
|
+
## Status
|
|
15
|
+
|
|
16
|
+
Published on npm as `@textunited/sanity-plugin` (first release 0.1.0). Changes are listed in
|
|
17
|
+
[CHANGELOG.md](https://github.com/TextUnited/textunited-sanity-plugin/blob/main/CHANGELOG.md).
|
|
18
|
+
|
|
19
|
+
Done:
|
|
20
|
+
- package layout, build (ESM + CJS + types), tests
|
|
21
|
+
- TextUnited Segments API client (personal access token or company id + API key)
|
|
22
|
+
- stable identifiers: one TextUnited project per Sanity document, one task per part of the
|
|
23
|
+
document (each page-builder section, each rich-text field, all short fields together),
|
|
24
|
+
segment ids derived from the path to the text
|
|
25
|
+
- extracting translatable values for field-level (internationalized arrays) and
|
|
26
|
+
document-level localization, including Portable Text with marks and long-text chunks
|
|
27
|
+
- modes `missing`, `changed` and `all`, deciding which tasks to send
|
|
28
|
+
- writing translations back: missing values are filled, the plugin's own earlier translations
|
|
29
|
+
are updated, values edited by hand in Sanity are kept unless `all` is requested
|
|
30
|
+
|
|
31
|
+
- translation requests on the server (`POST {basePath}/jobs`): the Studio creates a
|
|
32
|
+
`textunited.translationRequest` document and sends its id (allowed Studio origins only), or a
|
|
33
|
+
signed Sanity webhook does; the server creates the TextUnited project once, then replaces only
|
|
34
|
+
the changed tasks, writes the instant machine translation to drafts, and keeps the state in a
|
|
35
|
+
private `textunited.state.<document id>` document
|
|
36
|
+
- documentLevel: new translations are created as drafts with a slug from the translated title
|
|
37
|
+
and linked in the translation metadata
|
|
38
|
+
- a translation whose source changed is replaced; one edited by hand is kept otherwise
|
|
39
|
+
|
|
40
|
+
- TextUnited notifications (`{basePath}/events?doc=…&sig=…`): the URL is stable per document
|
|
41
|
+
and signed; each notification fetches the document's segments from TextUnited and writes
|
|
42
|
+
reviewed translations to the drafts. Translations of a source edited after sending are not
|
|
43
|
+
applied. Concurrent notifications are safe (revision check on the state, with retries).
|
|
44
|
+
- periodic check (`{basePath}/sync`, `Authorization: Bearer <cronSecret>`): syncs documents
|
|
45
|
+
that may still receive translations, which also covers TextUnited's "approve all", which sends
|
|
46
|
+
no notification. Run it from a cron job, e.g. every 15 minutes.
|
|
47
|
+
|
|
48
|
+
- several TextUnited projects per document: languages added later get a project of their own
|
|
49
|
+
(`-2`, `-3`… after the document's custom id); a change of the text is sent to every project
|
|
50
|
+
with a requested language, and notifications read every project. "Start a new TextUnited
|
|
51
|
+
project" (reset) archives the current projects and sends the whole document to a new one.
|
|
52
|
+
States from the single-project format are read and migrated.
|
|
53
|
+
- stop and resume a language per document ("Stop French"): the plugin no longer sends, writes or
|
|
54
|
+
restores it; the language stays in its TextUnited project. Stored in the state as `stopped`.
|
|
55
|
+
- Studio: a TextUnited panel (document inspector) next to the configured types, opened from
|
|
56
|
+
the document header or the "Translate" action. It shows how many texts need translation
|
|
57
|
+
(changed or not translated yet, with a word count) and sends them with one button, the review
|
|
58
|
+
progress per language, a link to the project in the TextUnited portal (`projectUrl` option),
|
|
59
|
+
and the last requests. A badge in the document footer shows the progress (e.g.
|
|
60
|
+
"DE 5/7 · PL 7/7"), and a message appears when reviewed translations arrive. In-house team
|
|
61
|
+
roles are remembered in the browser.
|
|
62
|
+
|
|
63
|
+
- outsourced or in-house projects: for a new project the editor picks who translates. In-house
|
|
64
|
+
lists the people of the TextUnited account (`GET /accounts/Users` and `/accounts/Collaborators`,
|
|
65
|
+
same token scopes) and sends the chosen team with roles. The list is returned only for a fresh
|
|
66
|
+
`textunited.teamQuery.*` document, so it is not public.
|
|
67
|
+
- TextUnited calls time out after 90 s; a task that did not answer counts as sent and its
|
|
68
|
+
translations arrive through notifications or the periodic check.
|
|
69
|
+
|
|
70
|
+
Tried on the TextUnited website (local Studio + Next.js, test documents): pages, a blog post,
|
|
71
|
+
outsourced and in-house projects.
|
|
72
|
+
|
|
73
|
+
- append mode (default): the project is created with the texts that need
|
|
74
|
+
translation as task `content`; each later request sends only its new and changed texts as one
|
|
75
|
+
new task `update-<UTC date>-<time>-<random>`, and nothing in the project is replaced. The state
|
|
76
|
+
remembers the task each text was last sent in, and translations are read only from that task.
|
|
77
|
+
|
|
78
|
+
Tried against the TextUnited production API (November 2026): new project, appended changes with
|
|
79
|
+
formatted text, a language added as a new project, stop and resume, a blog post, reviewed
|
|
80
|
+
translations received.
|
|
81
|
+
|
|
82
|
+
## Installation
|
|
83
|
+
|
|
84
|
+
Step-by-step guide for customers: [docs/INSTALL.md](https://github.com/TextUnited/textunited-sanity-plugin/blob/main/docs/INSTALL.md).
|
|
85
|
+
|
|
86
|
+
## Usage
|
|
87
|
+
|
|
88
|
+
Shared configuration, imported by both the Studio and the site:
|
|
89
|
+
|
|
90
|
+
```ts
|
|
91
|
+
// translation.config.ts
|
|
92
|
+
import type {TranslationConfig} from '@textunited/sanity-plugin/server'
|
|
93
|
+
|
|
94
|
+
export const translationConfig: TranslationConfig = {
|
|
95
|
+
sourceLanguage: {id: 'en', title: 'English', textUnitedCode: 'en-us'},
|
|
96
|
+
targetLanguages: [
|
|
97
|
+
{id: 'de', title: 'German', textUnitedCode: 'de-de'},
|
|
98
|
+
{id: 'pl', title: 'Polish', textUnitedCode: 'pl-pl'},
|
|
99
|
+
],
|
|
100
|
+
documentTypes: [
|
|
101
|
+
{type: 'page', model: 'fieldLevel'},
|
|
102
|
+
{type: 'post', model: 'documentLevel', fields: ['title', 'excerpt', 'body', 'seo']},
|
|
103
|
+
],
|
|
104
|
+
}
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
Studio:
|
|
108
|
+
|
|
109
|
+
```ts
|
|
110
|
+
import {textUnitedTranslations} from '@textunited/sanity-plugin/studio'
|
|
111
|
+
|
|
112
|
+
plugins: [
|
|
113
|
+
textUnitedTranslations({
|
|
114
|
+
translation: translationConfig,
|
|
115
|
+
handlerUrl: 'https://www.example.com/api/textunited',
|
|
116
|
+
}),
|
|
117
|
+
]
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Next.js, `app/api/textunited/[...route]/route.ts`:
|
|
121
|
+
|
|
122
|
+
```ts
|
|
123
|
+
import {createTextUnitedRouteHandlers} from '@textunited/sanity-plugin/next'
|
|
124
|
+
|
|
125
|
+
export const runtime = 'nodejs'
|
|
126
|
+
export const maxDuration = 300
|
|
127
|
+
|
|
128
|
+
export const {GET, POST, OPTIONS} = createTextUnitedRouteHandlers({
|
|
129
|
+
translation: translationConfig,
|
|
130
|
+
textUnited: {auth: {type: 'pat', token: process.env.TEXTUNITED_TOKEN!}},
|
|
131
|
+
sanity: {projectId: 'abc123', dataset: 'production', token: process.env.SANITY_WRITE_TOKEN!},
|
|
132
|
+
publicBaseUrl: 'https://www.example.com',
|
|
133
|
+
basePath: '/api/textunited',
|
|
134
|
+
secret: process.env.TEXTUNITED_PLUGIN_SECRET!,
|
|
135
|
+
cronSecret: process.env.CRON_SECRET,
|
|
136
|
+
studioOrigins: ['https://example.sanity.studio', 'http://localhost:3333'],
|
|
137
|
+
})
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Periodic check, e.g. `vercel.json`: `{"crons": [{"path": "/api/textunited/sync", "schedule": "*/15 * * * *"}]}`.
|
|
141
|
+
|
|
142
|
+
Known limits:
|
|
143
|
+
- In field-level documents, text inside custom objects embedded in a localized rich-text field
|
|
144
|
+
is copied, not translated.
|
|
145
|
+
- Blocks removed from the source stay in existing translations until the next full update.
|
|
146
|
+
- TextUnited cannot add a language to an existing project; a language added later is ordered as
|
|
147
|
+
a separate project for that language (several projects per document).
|
|
148
|
+
- documentLevel: references in a new translation (author, categories) still point to the
|
|
149
|
+
source-language documents.
|
|
150
|
+
|
|
151
|
+
## TextUnited API today
|
|
152
|
+
|
|
153
|
+
`PUT /segments/projects` with `appendContent: true` adds the segments as a new task and leaves
|
|
154
|
+
existing tasks and their work untouched; the task id must be new (HTTP 400 otherwise). The
|
|
155
|
+
package uses it by default. Outdated copies of edited texts stay in the earlier tasks in
|
|
156
|
+
TextUnited; translators may still see them, the package ignores them.
|
|
157
|
+
|
|
158
|
+
For an API without it, `textUnited: {capabilities: {appendSegments: false}}` sends each changed
|
|
159
|
+
part of a document as its own task and replaces that task on every update.
|
|
160
|
+
|
|
161
|
+
## Setup on the customer's side
|
|
162
|
+
|
|
163
|
+
- TextUnited personal access token with the scopes `projects:read` and `projects:write`
|
|
164
|
+
- Sanity token with write access
|
|
165
|
+
- public HTTPS address of the site that hosts the server handler
|
|
166
|
+
- a random secret for signing notification URLs
|
|
167
|
+
|
|
168
|
+
## Development
|
|
169
|
+
|
|
170
|
+
```bash
|
|
171
|
+
npm install
|
|
172
|
+
npm test
|
|
173
|
+
npm run typecheck
|
|
174
|
+
npm run build
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
Releasing: set the version in `package.json`, add it to `CHANGELOG.md`, commit, tag (`v0.1.0`),
|
|
178
|
+
then `npm publish` (runs the type check, the tests and the build first; `publishConfig.access`
|
|
179
|
+
is `public`).
|
|
180
|
+
|
|
181
|
+
## License
|
|
182
|
+
|
|
183
|
+
MIT, see [LICENSE.md](https://github.com/TextUnited/textunited-sanity-plugin/blob/main/LICENSE.md).
|