docs(assist): fix README markdown formatting and document English-only image descriptions#1628
Merged
Merged
Conversation
…descriptions Pass the configured translate.document.languageField as languagePath to the generate-caption task (both the automatic generation triggered on image change, and the manual 'Generate image description' field action), so generated alt text/captions are written in the document's language instead of always defaulting to English. Fixes #1606
🦋 Changeset detectedLatest commit: 56dbebd The changes in this PR will be included in the next version bump. This PR includes changesets to release 4 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
stipsan
marked this pull request as ready for review
July 17, 2026 09:21
stipsan
requested review from
Copilot and
pedrobonamin
and removed request for
a team and
Copilot
July 17, 2026 09:21
stipsan
enabled auto-merge (squash)
July 17, 2026 09:21
Testing against the live AI Assist backend confirms that the generate-caption task currently always writes descriptions in English, regardless of the languagePath sent from the client (this matches Sanity's own documentation, which states the automatic image description feature is English-only today and recommends the Transform Agent Action's image-description operation as a workaround). Update the changeset and README to accurately describe the change as forward-compatible plumbing rather than a full fix, and point users at the documented workaround for non-English alt text today.
cursor
Bot
changed the title
Compute languagePath from config.translate.document.languageField once inside useGenerateCaption itself (via useAiAssistanceConfig), instead of requiring every call site to read the config and thread it through as an argument. This removes the duplicated config lookup from both ImageContextProvider and generateCaptionsActions, and matches the cleaner approach used in #1627. Also documents in translate/types.ts JSDoc that languageField is reused for image description generation.
stipsan
disabled auto-merge
July 17, 2026 10:16
stipsan
marked this pull request as draft
July 17, 2026 10:16
The README relied on markdown block elements (headings, lists, code fences, images) interrupting paragraphs without blank lines between them. GitHub tolerates this, but stricter renderers (e.g. the plugin listing on sanity.io) join everything into unreadable walls of text with literal '### Heading' and '- list item' fragments inline. - Separate all block elements with blank lines throughout - Add a 'Known limitations' section documenting that image descriptions are always generated in English regardless of translate.document.languageField (backend limitation, see #1606), with Transform Agent Action and translate-after workarounds - Fix broken links: empty-href heading, HOW-TO-USE pointing at the old standalone repo layout, LICENSE pointing at a non-existent file - Fix broken bold markup in the 'Enabling the AI Assist API' steps and the useExampleFieldActions TOC anchor - Add missing TOC entries (Known limitations, Caveats, Third party sub-processors) Also reverts the languagePath client plumbing from this branch: the backend ignores it, so the plugin change had no effect. This PR is now docs-only.
cursor
Bot
changed the title
stipsan
marked this pull request as ready for review
July 17, 2026 11:30
Merged
Contributor
There was a problem hiding this comment.
Pull request overview
Docs-only update to @sanity/assist aimed at fixing broken README rendering in stricter CommonMark environments (e.g. sanity.io plugin listing) and clearly documenting a backend limitation where image descriptions are generated in English regardless of document language configuration (refs #1606).
Changes:
- Normalize README markdown formatting by adding blank-line separation between block elements, fixing several broken/incorrect links and TOC anchors.
- Add a Known limitations section documenting the English-only image description behavior and suggested workarounds.
- Add a changeset to ship the README/documentation update as a patch release for
@sanity/assist.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| plugins/@sanity/assist/README.md | Markdown rendering fixes, TOC/link corrections, and new “Known limitations” documentation about English-only image descriptions. |
| .changeset/assist-caption-language-GH-1606.md | Patch changeset describing the README formatting fix and the documented image-description language limitation. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ##### Example | ||
| Starting from v3.0.0, AI Assist can write to date and datetime fields. Instructions can use language like "tomorrow at noon" or | ||
| "next year", and when Assist writes to the field, it will be converted to a field-compatible value. | ||
| Language about time is locale and timeZone dependant. By default instructions will use the locale and timezone provided |
|
|
||
| By providing a function to `translate.field.translationOutputs`, you have complete control over which fields belong to which language. | ||
| `translationOutputs` is used when an editor uses the **Translate fields** instruction. | ||
| It determines the relationships between document paths: Given a document path and a language, it should return the approriate sibling paths into which translations are output. |
| The action will: | ||
|
|
||
| - create the document as a draft if it does not exist, respecting initial values (`targetDocument`) | ||
| - use existing document state to determine what should be put in the the field (`instruction`, `instructionParams`) |
|
|
||
| - create the document as a draft if it does not exist, respecting initial values (`targetDocument`) | ||
| - use existing document state to determine what should be put in the the field (`instruction`, `instructionParams`) | ||
| - pass the current readOnly and hidden state currently use by the document form to the Agent Action, so it respects it (`conditionalPaths`) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Docs-only PR addressing #1606 and the broken README rendering on sanity.io.
Why docs-only: end-to-end testing against the hosted AI Assist backend showed the
generate-captiontask always writes English descriptions, no matter what the client sends (languagePath, ad-hocinstructionoverrides — all ignored). Since the backend won't be changed, the earlier client-sidelanguagePathplumbing from this branch has been reverted; documenting the limitation clearly is the fix.README cleanup
The README relied on markdown block elements (headings, lists, code fences, images) interrupting paragraphs without blank lines. GitHub renders that fine, but stricter renderers (like the plugin listing on sanity.io) join everything into walls of text with literal
### Configureand- list itemfragments inline. Changes:translate.document.languageField, linking AI assist Image description generation language #1606, with two workarounds: the Transform Agent Actionimage-descriptionoperation with a custom instruction, or translating the generated English description via the existing document/field translation actions[### Full field translation configuration example]()heading,HOW-TO-USEpointing at the old standalone-repo layout (../studio/...),LICENSEpointing at a file that doesn't exist in the plugin directory, and the#usefieldactionTOC anchor\*the sparkle icon\*\*) in the setup steps, added missing TOC entries for Caveats and Third party sub-processorsRendering before/after (strict CommonMark renderer)
New Known limitations section:
Known limitations section
Testing
### Configure/ list fragments inline in paragraphs; after renders proper headings, lists, and code blocks (screenshots above)pnpm format(no diff),pnpm lint,pnpm --filter @sanity/assist build,pnpm vitest run --project '@sanity/assist'(33 tests),pnpm knipgenerate-captionproduced identical English captions for the same image onlanguage: "en"andlanguage: "fr"documents, withlanguagePathandinstructionrequest fields ignored by the APITo show artifacts inline, enable in settings.