@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 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
- # Temporary Holding Version
1
+ # @textunited/sanity-plugin
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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).