@smartcat/sanity-plugin 1.0.0 → 1.1.0

package/src/tool/processing.ts

@@ -0,0 +1,839 @@
+import {uuid} from '@sanity/uuid'
+import {resolveDocumentTitle} from '../lib/documentTitle'
+import {ITEM_ID, itemDocDerefRespectingDraft} from '../lib/projectItems'
+import {
+  enumerateLeaves,
+  getTranslatableFields,
+  innerValueType,
+  isInternationalizedArrayType,
+  localizationMode,
+} from '../lib/locjson/fields'
+import {getAtPath, setAtPath} from '../lib/locjson/paths'
+import type {TranslatableField} from '../lib/locjson/types'
+import {serializeToLocjson} from '../lib/locjson/serialize'
+import {buildLocjsonFilename} from '../lib/locjson/filename'
+import {deserializeFromLocjson} from '../lib/locjson/deserialize'
+import {requireSourceLanguage} from '../lib/constants'
+import {buildLanguageMappings, findDuplicateSmartcatLanguages} from '../lib/languageMap'
+import type {LocalizationMode, LocJSON} from '../lib/locjson/types'
+import {summarizeCompletion, type DocProgress} from '../progress/core'
+import type {SmartcatLanguage} from '../types'
+import type {LogFn} from '../lib/log'
+
+/**
+ * Browser-side processing for the Smartcat workflow. All content transformation
+ * (Portable Text ⇄ HTML, field selection, variant creation) happens here in the
+ * Studio, where the real schema and a native DOM are available — so the Sanity
+ * Functions stay thin and dependency-free.
+ */
+
+/** A loosely-typed Sanity client (the Studio's `useClient` result satisfies this). */
+export interface ProcessingClient {
+  fetch<T = unknown>(query: string, params?: Record<string, unknown>): Promise<T>
+  create(doc: Record<string, unknown>): Promise<{_id: string}>
+  createIfNotExists(doc: Record<string, unknown>): Promise<{_id: string}>
+  patch(id: string): ProcessingPatch
+}
+interface ProcessingPatch {
+  set(attrs: Record<string, unknown>): ProcessingPatch
+  setIfMissing(attrs: Record<string, unknown>): ProcessingPatch
+  insert(at: 'before' | 'after' | 'replace', selector: string, items: unknown[]): ProcessingPatch
+  unset(keys: string[]): ProcessingPatch
+  commit(): Promise<unknown>
+}
+
+/** A compiled schema (the Studio's `useSchema` result satisfies this). */
+export interface ProcessingSchema {
+  get(typeName: string): unknown
+}
+
+const METADATA_TYPE = 'translation.metadata'
+const REFERENCE_VALUE_TYPE = 'internationalizedArrayReferenceValue'
+
+function parseHtml(html: string): Document {
+  return new DOMParser().parseFromString(html, 'text/html')
+}
+
+const VALUE_PREVIEW_CAP = 2000
+
+/** A capped, display-safe string for a field value (source or translated). */
+function valuePreview(value: unknown): string | undefined {
+  if (value === undefined || value === null) return undefined
+  const text = typeof value === 'string' ? value : JSON.stringify(value, null, 2)
+  if (!text) return undefined
+  return text.length > VALUE_PREVIEW_CAP ? `${text.slice(0, VALUE_PREVIEW_CAP)}…` : text
+}
+
+function errorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}
+
+/**
+ * For a field-level (internationalized-array) field, the member locales that
+ * actually carry content — so a "no source content" skip can say *which* locales
+ * exist ("I see only: en-GB") when the source-language member is simply missing,
+ * turning a silent source-language mismatch into a self-explaining log line.
+ */
+function memberLocalesWithContent(members: unknown, languageKey: string): string[] {
+  if (!Array.isArray(members)) return []
+  const locales: string[] = []
+  for (const member of members) {
+    if (!member || typeof member !== 'object') continue
+    const locale = (member as Record<string, unknown>)[languageKey]
+    const value = (member as {value?: unknown}).value
+    const hasContent =
+      typeof value === 'string' ? value.trim().length > 0 : Array.isArray(value) ? value.length > 0 : value != null
+    if (typeof locale === 'string' && hasContent) locales.push(locale)
+  }
+  return locales
+}
+
+/** Top-level, non-system schema field names for a type (for "not translatable" reporting). */
+function schemaFieldNames(schema: ProcessingSchema, type: string): string[] {
+  const compiled = schema.get(type) as {fields?: {name?: string}[]} | undefined
+  return (compiled?.fields ?? [])
+    .map((f) => f?.name)
+    .filter((n): n is string => typeof n === 'string' && !n.startsWith('_'))
+}
+
+function blockContentTypeFor(schema: ProcessingSchema, type: string, fieldPath: string): unknown {
+  const compiled = schema.get(type) as {fields?: {name: string; type: unknown}[]} | undefined
+  const fieldType = compiled?.fields?.find((f) => f.name === fieldPath)?.type
+  // Field-level Portable Text lives under the array member's `value`; resolve the
+  // inner block-content type rather than the internationalized-array wrapper.
+  if (isInternationalizedArrayType(fieldType as never)) {
+    return innerValueType(fieldType as never)
+  }
+  return fieldType
+}
+
+// ---------------------------------------------------------------------------
+// Export: serialize project items → outbox (LocJSON), set status = queued
+// ---------------------------------------------------------------------------
+
+/** An item the editor marked for deletion; carried to the export Function. */
+export interface PendingDeletion {
+  itemKey: string
+  sourceDocId: string
+  smartcatDocumentId?: string
+}
+
+export interface PrepareExportArgs {
+  client: ProcessingClient
+  schema: ProcessingSchema
+  projectId: string
+  targetLanguages: string[]
+  sourceLanguage: string
+  /** Configured languages, used to resolve each id → its Smartcat code. */
+  languages: SmartcatLanguage[]
+  /** Configured translatable types (undefined = all), logged in the config header. */
+  translatableTypes?: string[]
+  exclude?: string[]
+  /** How internationalized-array members identify their locale (field name or `'_key'`). */
+  fieldLanguageKey: string
+  /** Items to delete from Smartcat (and the project) on this export. */
+  deletions?: PendingDeletion[]
+  /** Streams per-document/per-field progress to the UI; no-op if omitted. */
+  onLog?: LogFn
+}
+
+const ITEMS_QUERY = `*[_id == $id][0]{
+  sourceLanguage,
+  items[]{
+    "docId": ${ITEM_ID},
+    "docType": docType,
+    "doc": ${itemDocDerefRespectingDraft()}
+  }
+}`
+
+export async function prepareExport({
+  client,
+  schema,
+  projectId,
+  targetLanguages,
+  sourceLanguage,
+  languages,
+  translatableTypes,
+  exclude,
+  fieldLanguageKey,
+  deletions = [],
+  onLog,
+}: PrepareExportArgs): Promise<{prepared: number; deleting: number}> {
+  const log: LogFn = onLog ?? (() => {})
+  const project = await client.fetch<{
+    sourceLanguage?: string
+    items?: {
+      docId?: string
+      docType?: string
+      doc: (Record<string, unknown> & {_id: string; _type: string}) | null
+    }[]
+  } | null>(ITEMS_QUERY, {id: projectId})
+
+  const source = project?.sourceLanguage || sourceLanguage
+
+  // Resolve the id → Smartcat-code mapping for this project's languages and
+  // stamp it on the project, so the Functions can map to/from Smartcat codes.
+  // Two targets resolving to the same code can't be routed back, so reject it.
+  const smartcatLanguages = buildLanguageMappings(languages, [source, ...targetLanguages])
+  const dups = findDuplicateSmartcatLanguages(
+    smartcatLanguages.filter((m) => targetLanguages.includes(m.sanityId)),
+  )
+  if (dups.length > 0) {
+    const detail = dups.map((d) => `${d.sanityIds.join(', ')} → ${d.smartcatLanguage}`).join('; ')
+    throw new Error(`Multiple target languages map to the same Smartcat language: ${detail}`)
+  }
+  // Don't re-upload documents that are being deleted this round.
+  const deletedDocIds = new Set(deletions.map((d) => d.sourceDocId))
+  // Resolve each project item to its (draft-or-published) document. An item that
+  // derefs to nothing — deleted, or expected published but never published — is
+  // reported below rather than silently dropped.
+  const items = (project?.items ?? []).filter(
+    (item) => !(item.docId && deletedDocIds.has(item.docId)),
+  )
+  const unresolved = items.filter((item) => !item.doc)
+  const docs = items
+    .map((item) => item.doc)
+    .filter((d): d is Record<string, unknown> & {_id: string; _type: string} => Boolean(d))
+
+  // The translatable field list is per-type, so compute it once per type even
+  // when a project holds many documents of the same type.
+  const fieldsByType = new Map<string, ReturnType<typeof getTranslatableFields>>()
+  const fieldsFor = (type: string) => {
+    let fields = fieldsByType.get(type)
+    if (!fields) {
+      fields = getTranslatableFields(schema.get(type), {exclude})
+      fieldsByType.set(type, fields)
+    }
+    return fields
+  }
+
+  // Config header — surfaces the resolved plugin config and this project's
+  // languages up front, so a "nothing serialized" run can be traced to a
+  // source-language or translatable-types mismatch straight from the log.
+  const configuredLanguages = languages.map((l) => l.id).join(', ') || '(none)'
+  const configuredTypes =
+    translatableTypes === undefined ? 'all types' : translatableTypes.join(', ') || '(none)'
+  log({level: 'info', message: `Config — source language: ${sourceLanguage}`})
+  log({level: 'info', indent: true, message: `languages: ${configuredLanguages}`})
+  log({level: 'info', indent: true, message: `translatable types: ${configuredTypes}`})
+  log({level: 'info', message: `Project — source: ${source} → targets: ${targetLanguages.join(', ') || '(no targets)'}`})
+  log({level: 'info', message: `Export — ${docs.length} document(s)`})
+
+  // Items that resolved to no document at all: don't drop them silently — the
+  // usual cause is a document that was never published (or was deleted).
+  for (const item of unresolved) {
+    log({
+      level: 'error',
+      message: `${item.docId ?? 'unknown document'} (${item.docType ?? 'unknown type'}): no document found — it may be unpublished or deleted; skipped`,
+    })
+  }
+
+  const outbox: {_key: string; sourceDocId: string; title?: string; filename: string; locjson: string}[] = []
+  for (const rawDoc of docs) {
+    // Serialize under the canonical (bare) id so identity, metadata and progress
+    // stay stable, even when the *content* came from the draft. Mark draft-sourced
+    // files so they're recognizable in Smartcat.
+    const isDraft = rawDoc._id.startsWith('drafts.')
+    const doc = isDraft ? {...rawDoc, _id: publishedId(rawDoc._id)} : rawDoc
+    const name = resolveDocumentTitle(schema, doc)
+    log({level: 'info', message: `${name || doc._id}  ·  ${doc._type}${isDraft ? ' (draft)' : ''}`})
+    try {
+      const fields = fieldsFor(doc._type)
+      // Fields skipped because they hold a block type that can't be serialized
+      // (e.g. a custom `table`): left untranslated on purpose, reported as errors
+      // below so the editor knows to act rather than lose content silently.
+      const skippedBlockTypes = new Map<string, string[]>()
+      const locjson = serializeToLocjson(doc as never, fields, {
+        sourceLanguage: source,
+        fieldLanguageKey,
+        onSkippedField: ({fieldPath, types}) => skippedBlockTypes.set(fieldPath, types),
+      })
+      // A field produced a unit ⇒ serialized; otherwise its source was empty.
+      const unitByKey = new Map(locjson.units.map((u) => [u.key, u]))
+      for (const field of fields) {
+        const unit = unitByKey.get(field.path)
+        const skippedTypes = skippedBlockTypes.get(field.path)
+        if (unit) {
+          log({level: 'success', indent: true, message: `${field.title || field.path}: serialized (${field.kind})`, value: unit.source.join('')})
+        } else if (skippedTypes) {
+          log({
+            level: 'error',
+            indent: true,
+            message: `${field.title || field.path}: not translated — contains block type(s) that can't be translated: ${skippedTypes.join(', ')}. The whole field was left untranslated to avoid losing this content.`,
+          })
+        } else {
+          // Field-level with members in other locales but not the source is a
+          // source-language mismatch, not an empty field — name the locales seen.
+          const otherLocales =
+            field.localization === 'field'
+              ? memberLocalesWithContent(getAtPath(doc, field.path), fieldLanguageKey).filter((l) => l !== source)
+              : []
+          const reason = otherLocales.length
+            ? `no '${source}' content (I see only: ${otherLocales.join(', ')})`
+            : 'no source content'
+          log({level: 'skip', indent: true, message: `${field.title || field.path}: skipped — ${reason}`})
+        }
+      }
+      // Surface the rest of the type's fields too, so a missing translation is
+      // explained ("not translatable") rather than silently absent.
+      const selected = new Set(fields.map((f) => f.path))
+      const excluded = new Set(exclude ?? [])
+      for (const fieldName of schemaFieldNames(schema, doc._type)) {
+        if (selected.has(fieldName) || excluded.has(fieldName)) continue
+        log({level: 'skip', indent: true, message: `${fieldName}: skipped — not translatable`})
+      }
+      if (locjson.units.length === 0) {
+        // Distinguish "nothing to translate" from "everything translatable was
+        // held back": the latter means the whole document goes untranslated, so
+        // flag it as an error rather than a benign skip.
+        if (skippedBlockTypes.size > 0) {
+          log({
+            level: 'error',
+            indent: true,
+            message: 'not sent — its only translatable content is in field(s) with block type(s) that can’t be translated (see above)',
+          })
+        } else {
+          log({level: 'skip', indent: true, message: 'no translatable content — not sent'})
+        }
+        continue
+      }
+      outbox.push({
+        _key: uuid(),
+        sourceDocId: doc._id,
+        title: name,
+        filename: buildLocjsonFilename(doc._type, doc._id, name, {draft: isDraft}),
+        locjson: JSON.stringify(locjson),
+      })
+    } catch (err) {
+      log({level: 'error', indent: true, message: `failed to serialize: ${errorMessage(err)}`})
+    }
+  }
+  log({level: 'success', message: `Queued ${outbox.length} file(s)${deletions.length ? ` · ${deletions.length} for deletion` : ''}`})
+
+  await client
+    .patch(projectId)
+    .set({
+      outbox,
+      pendingDeletions: deletions,
+      targetLanguages,
+      sourceLanguage: source,
+      smartcatLanguages,
+      status: 'queued',
+      lastError: null,
+    })
+    .commit()
+
+  return {prepared: outbox.length, deleting: deletions.length}
+}
+
+// ---------------------------------------------------------------------------
+// Import: inbox (translated LocJSON) → locale variants + metadata, status = completed
+// ---------------------------------------------------------------------------
+
+export interface ApplyImportArgs {
+  client: ProcessingClient
+  schema: ProcessingSchema
+  projectId: string
+  /** Document-level locale field name (document-internationalization `languageField`). */
+  documentLanguageField: string
+  /** Field-level locale key (internationalized-array): field name or `'_key'`. */
+  fieldLanguageKey: string
+  /** Streams per-document/per-field progress to the UI; no-op if omitted. */
+  onLog?: LogFn
+}
+
+const INBOX_QUERY = `*[_id == $id][0]{
+  sourceLanguage,
+  inbox[]{ sourceDocId, targetLanguage, smartcatDocumentId, locjson },
+  progress[]{_key, sourceDocId, title, targets[]{_key, language, smartcatDocumentId, stages, complete, imported, syncedAt}}
+}`
+
+export async function applyImportedTranslations({
+  client,
+  schema,
+  projectId,
+  documentLanguageField,
+  fieldLanguageKey,
+  onLog,
+}: ApplyImportArgs): Promise<{imported: number; status: 'completed' | 'translating'}> {
+  const log: LogFn = onLog ?? (() => {})
+  const project = await client.fetch<{
+    sourceLanguage?: string
+    inbox?: {sourceDocId?: string; targetLanguage: string; smartcatDocumentId?: string; locjson: string}[]
+    progress?: DocProgress[]
+  } | null>(INBOX_QUERY, {id: projectId})
+
+  const sourceLanguage = requireSourceLanguage(project?.sourceLanguage)
+  const inbox = project?.inbox ?? []
+  // Resolved titles per source doc, from the stored progress (the same source the
+  // import Function log uses) — so the log shows names, not raw document ids.
+  const titleByDoc = new Map<string, string>()
+  for (const p of project?.progress ?? []) {
+    if (p.sourceDocId && p.title) titleByDoc.set(p.sourceDocId, p.title)
+  }
+  let imported = 0
+  // (sourceDocId, targetLanguage) pairs we successfully imported.
+  const importedKeys = new Set<string>()
+
+  // Localization mode is per-type; derive once per type from the schema.
+  const modeByType = new Map<string, LocalizationMode>()
+  const modeFor = (type: string): LocalizationMode => {
+    let mode = modeByType.get(type)
+    if (!mode) {
+      mode = localizationMode(schema.get(type))
+      modeByType.set(type, mode)
+    }
+    return mode
+  }
+
+  // Translatable-field descriptors per type (shapes + nesting), for reconstructing
+  // nested/array member values on write-back. Same exclude as export.
+  const descriptorsByType = new Map<string, ReturnType<typeof getTranslatableFields>>()
+  const descriptorsFor = (type: string) => {
+    let d = descriptorsByType.get(type)
+    if (!d) {
+      d = getTranslatableFields(schema.get(type), {exclude: [documentLanguageField]})
+      descriptorsByType.set(type, d)
+    }
+    return d
+  }
+
+  log({level: 'info', message: `Import — ${inbox.length} translated file(s)`})
+
+  for (const item of inbox) {
+    let parsed: LocJSON
+    try {
+      parsed = JSON.parse(item.locjson) as LocJSON
+    } catch {
+      log({level: 'error', message: `${item.sourceDocId || 'unknown'} → ${item.targetLanguage}: invalid LocJSON, skipped`})
+      continue
+    }
+    const type = parsed.properties?.['x-sanity']?.documentType
+    const result = deserializeFromLocjson(parsed, {
+      parseHtml,
+      getBlockContentType: (fieldPath) => (type ? blockContentTypeFor(schema, type, fieldPath) : undefined),
+    })
+    if (!result.documentId || !result.documentType) {
+      log({level: 'error', message: `${item.sourceDocId || 'unknown'} → ${item.targetLanguage}: missing document id/type, skipped`})
+      continue
+    }
+
+    const mode = modeFor(result.documentType)
+    const title = titleByDoc.get(result.documentId)
+    const label = title ? `${title} (Sanity ID: ${result.documentId})` : result.documentId
+    log({level: 'info', message: `${label} → ${item.targetLanguage}  ·  ${result.documentType} (${mode} mode)`})
+
+    let ok = false
+    // Each item is isolated: a failure is logged and skipped, so one bad
+    // document never aborts the rest of the batch.
+    try {
+      ok =
+        mode === 'field'
+          ? await applyFieldLevelTranslations(client, {
+              schema,
+              type: result.documentType,
+              docId: result.documentId,
+              locale: item.targetLanguage,
+              sourceLanguage: result.sourceLanguage || sourceLanguage,
+              descriptors: descriptorsFor(result.documentType),
+              translations: result.fields,
+              sources: result.sources,
+              languageKey: fieldLanguageKey,
+            }, log)
+          : await upsertVariant(client, {
+              sourceId: result.documentId,
+              type: result.documentType,
+              sourceLanguage,
+              locale: item.targetLanguage,
+              fields: result.fields,
+              sources: result.sources,
+              languageField: documentLanguageField,
+            }, log)
+    } catch (err) {
+      log({level: 'error', indent: true, message: `failed: ${errorMessage(err)}`})
+    }
+    if (ok) {
+      imported++
+      importedKeys.add(`${result.documentId}__${item.targetLanguage}`)
+    }
+  }
+
+  // Mark the imported targets, then decide completion: the project is "completed"
+  // only when every target is complete AND imported. Otherwise it stays
+  // "translating" so the remaining targets can be imported once they finish.
+  const progress = (project?.progress ?? []).map((doc) => ({
+    ...doc,
+    targets: doc.targets.map((target) =>
+      importedKeys.has(`${doc.sourceDocId}__${target.language}`)
+        ? {...target, imported: true}
+        : target,
+    ),
+  }))
+  const status = summarizeCompletion(progress).allDone ? 'completed' : 'translating'
+
+  await client
+    .patch(projectId)
+    .set({progress, status, lastImportAt: new Date().toISOString()})
+    .unset(['inbox'])
+    .commit()
+
+  return {imported, status}
+}
+
+interface ApplyFieldLevelArgs {
+  schema: ProcessingSchema
+  type: string
+  docId: string
+  locale: string
+  /** Source language — its array member is the structural template for reconstruction. */
+  sourceLanguage: string
+  /** Translatable-field descriptors for `type` (shapes + nesting). */
+  descriptors: TranslatableField[]
+  /** Translated leaf values keyed by full unit path. */
+  translations: Record<string, unknown>
+  /** Source (pre-translation) text per unit path, for the JSON well-formedness check. */
+  sources: Record<string, string>
+  /** How members identify their locale: a field name (`'language'`) or `'_key'`. */
+  languageKey: string
+}
+
+/** A value is "potential JSON" if it's a string whose first non-blank char is `{`. */
+function isPotentialJson(value: unknown): value is string {
+  return typeof value === 'string' && value.trimStart().startsWith('{')
+}
+
+/**
+ * Guards a field whose **source** is JSON: the translated value must also parse.
+ * Returns the parse error message when the translation is malformed (caller logs
+ * it and skips the field); `null` when there's nothing to enforce — the source
+ * isn't confirmed JSON — or the translation is valid JSON.
+ */
+function malformedJsonError(source: unknown, translated: unknown): string | null {
+  // Only enforce when the source is confirmed JSON (starts with `{` and parses).
+  if (!isPotentialJson(source)) return null
+  try {
+    JSON.parse(source)
+  } catch {
+    return null // source isn't really JSON, so don't hold the translation to it
+  }
+  if (typeof translated !== 'string') return 'translated value is not a string'
+  try {
+    JSON.parse(translated)
+    return null
+  } catch (err) {
+    return err instanceof Error ? err.message : String(err)
+  }
+}
+
+const DRAFTS_PREFIX = 'drafts.'
+
+/** The published (bare) form of a document id. */
+function publishedId(id: string): string {
+  return id.startsWith(DRAFTS_PREFIX) ? id.slice(DRAFTS_PREFIX.length) : id
+}
+
+/** The draft form of a document id. */
+function draftId(id: string): string {
+  return id.startsWith(DRAFTS_PREFIX) ? id : DRAFTS_PREFIX + id
+}
+
+interface EditableDraft {
+  draftId: string
+  /** Content edits are computed against: the draft if one exists, else published. */
+  base: Record<string, unknown>
+  /** Whether a draft already exists (so we don't clone published over it). */
+  exists: boolean
+}
+
+/**
+ * Resolves the **draft** to write imported translations into, so they accumulate
+ * for editorial review instead of landing on the live document (where they'd be
+ * invisible behind an existing draft and overwritten on the next publish).
+ *
+ * Read-only: returns the existing draft if there is one (so a concurrent draft
+ * isn't clobbered), otherwise the published document as the base to seed from.
+ * `null` if neither exists. Use {@link commitToDraft} to actually write.
+ */
+async function loadEditableDraft(client: ProcessingClient, id: string): Promise<EditableDraft | null> {
+  const dId = draftId(id)
+  const draft = await client.fetch<Record<string, unknown> | null>(`*[_id == $id][0]`, {id: dId})
+  if (draft) return {draftId: dId, base: draft, exists: true}
+
+  const published = await client.fetch<Record<string, unknown> | null>(`*[_id == $id][0]`, {id: publishedId(id)})
+  if (!published) return null
+  return {draftId: dId, base: published, exists: false}
+}
+
+/**
+ * Writes `attrs` onto the draft, first cloning the published document into a new
+ * draft if none exists yet. Only call when there is something to write, so an
+ * unchanged import never leaves a spurious empty draft behind.
+ */
+async function commitToDraft(client: ProcessingClient, editable: EditableDraft, attrs: Record<string, unknown>): Promise<void> {
+  if (!editable.exists) {
+    await client.createIfNotExists({...stripSystemFields(editable.base), _id: editable.draftId, _type: editable.base._type})
+  }
+  await client.patch(editable.draftId).set(attrs).commit()
+}
+
+/**
+ * Field-level (internationalized-array) import: writes each translated field's
+ * value into the **same** document's **draft**, as the array member for `locale`
+ * — updating the existing member (preserving its `_key`) or appending a new one.
+ * No locale variant document and no translation.metadata.
+ */
+async function applyFieldLevelTranslations(
+  client: ProcessingClient,
+  {docId, locale, sourceLanguage, descriptors, translations, sources, languageKey}: ApplyFieldLevelArgs,
+  log: LogFn,
+): Promise<boolean> {
+  const editable = await loadEditableDraft(client, docId)
+  if (!editable) {
+    log({level: 'error', indent: true, message: `source document not found: ${docId}`})
+    return false
+  }
+  const doc = editable.base
+  const byKey = languageKey === '_key'
+  const patchSet: Record<string, unknown> = {}
+
+  // One patch entry per (nested) i18n field. The target member value is rebuilt
+  // from the SOURCE member as a template — preserving `_key`s and non-text fields
+  // — with each translated leaf overlaid by its valuePath.
+  for (const field of descriptors) {
+    if (field.localization !== 'field') continue
+    const existing = (Array.isArray(getAtPath(doc, field.path)) ? getAtPath(doc, field.path) : []) as Record<string, unknown>[]
+    const template = (existing.find((m) => m?.[languageKey] === sourceLanguage) ?? existing.find((m) => m?.value !== undefined))?.value
+
+    let target: unknown = structuredClone(template)
+    let changed = false
+    for (const leaf of enumerateLeaves(field, template)) {
+      let value = translations[leaf.fullKey]
+      if (value === undefined) continue
+      if (leaf.kind === 'portableText' && Array.isArray(value)) value = value.map((b) => keyBlock(b as Record<string, unknown>))
+      // A JSON source ⇒ its translation must parse too, or we'd write broken JSON.
+      const jsonError = malformedJsonError(sources[leaf.fullKey], value)
+      if (jsonError) {
+        log({level: 'error', indent: true, message: `${leaf.fullKey}: '${locale}' translation is not valid JSON — skipped`, value: valuePreview(value), error: jsonError})
+        continue
+      }
+      target = leaf.valuePath ? setAtPath(target, leaf.valuePath, value) : value
+      changed = true
+    }
+    if (!changed) continue
+
+    const idx = existing.findIndex((m) => m?.[languageKey] === locale)
+    if (idx >= 0 && sameValue(existing[idx]?.value, target)) {
+      log({level: 'skip', indent: true, message: `${field.path}: '${locale}' unchanged — skipped`})
+      continue
+    }
+    if (idx >= 0) {
+      patchSet[field.path] = existing.map((m, i) => (i === idx ? {...m, value: target} : m))
+      log({level: 'update', indent: true, message: `${field.path}: updating '${locale}' field variant`, before: valuePreview(existing[idx]?.value), value: valuePreview(target)})
+    } else {
+      // v4.x keys members by `_key`; v5+ uses a uuid `_key` plus a language field.
+      const _type = existing.find((m) => m?._type)?._type
+      patchSet[field.path] = [
+        ...existing,
+        byKey ? {_key: locale, _type, value: target} : {_key: uuid(), _type, [languageKey]: locale, value: target},
+      ]
+      log({level: 'info', indent: true, message: `${field.path}: creating '${locale}' field variant`, value: valuePreview(target)})
+    }
+  }
+
+  if (Object.keys(patchSet).length === 0) {
+    log({level: 'success', indent: true, message: `${docId}: no field changes`})
+    return true
+  }
+  await commitToDraft(client, editable, patchSet)
+  log({level: 'success', indent: true, message: `saved ${Object.keys(patchSet).length} field(s) on draft of ${docId}`})
+  return true
+}
+
+interface UpsertVariantArgs {
+  sourceId: string
+  type: string
+  sourceLanguage: string
+  locale: string
+  fields: Record<string, unknown>
+  /** Source (pre-translation) text per field, for the JSON well-formedness check. */
+  sources: Record<string, string>
+  /** Document locale field name (document-internationalization `languageField`). */
+  languageField: string
+}
+
+interface MetaTranslation {
+  language?: string
+  value?: {_ref?: string}
+}
+
+async function upsertVariant(
+  client: ProcessingClient,
+  {sourceId, type, sourceLanguage, locale, fields, sources, languageField}: UpsertVariantArgs,
+  log: LogFn,
+): Promise<boolean> {
+  const source = await client.fetch<Record<string, unknown> | null>(`*[_id == $id][0]`, {id: sourceId})
+  if (!source) {
+    log({level: 'error', indent: true, message: `source document not found: ${sourceId}`})
+    return false
+  }
+
+  const translatedFields = keyPortableText(fields)
+
+  const metadata = await client.fetch<{_id: string; translations?: MetaTranslation[]} | null>(
+    `*[_type == $metaType && references($sourceId)][0]{_id, translations}`,
+    {metaType: METADATA_TYPE, sourceId},
+  )
+  const existingVariantId = metadata?.translations?.find((t) => t.language === locale)?.value?._ref
+
+  // Log the intent before each write so a failure mid-op is still traceable.
+  // All writes target the variant's draft, so translations accumulate for review.
+  let variantId: string
+  if (existingVariantId) {
+    // Edit the variant's draft (seeded from its published version if needed), so
+    // imported fields are reviewable and don't get clobbered by an open draft.
+    const editable = await loadEditableDraft(client, existingVariantId)
+    if (!editable) {
+      log({level: 'error', indent: true, message: `'${locale}' document variant not found: ${existingVariantId}`})
+      return false
+    }
+    const variant = editable.base
+    // Only write fields whose translated value actually differs from the variant.
+    const changed: Record<string, unknown> = {}
+    for (const [path, value] of Object.entries(translatedFields)) {
+      if (sameValue(variant[path], value)) {
+        log({level: 'skip', indent: true, message: `${path}: unchanged — skipped`})
+        continue
+      }
+      const jsonError = malformedJsonError(sources[path], value)
+      if (jsonError) {
+        log({
+          level: 'error',
+          indent: true,
+          message: `${path}: translation is not valid JSON — skipped`,
+          before: valuePreview(variant[path]),
+          value: valuePreview(value),
+          error: jsonError,
+        })
+        continue
+      }
+      changed[path] = value
+      log({
+        level: 'update',
+        indent: true,
+        message: `${path}: updating`,
+        before: valuePreview(variant[path]),
+        value: valuePreview(value),
+      })
+    }
+    if (Object.keys(changed).length > 0) {
+      await commitToDraft(client, editable, changed)
+      log({level: 'success', indent: true, message: `updated ${Object.keys(changed).length} field(s) on '${locale}' document variant draft`})
+    } else {
+      log({level: 'success', indent: true, message: `'${locale}' document variant already up to date`})
+    }
+    variantId = publishedId(existingVariantId)
+  } else {
+    // Drop any field whose source is JSON but whose translation doesn't parse,
+    // so a malformed value never lands on the new variant.
+    const writableFields: Record<string, unknown> = {}
+    for (const [path, value] of Object.entries(translatedFields)) {
+      const jsonError = malformedJsonError(sources[path], value)
+      if (jsonError) {
+        log({
+          level: 'error',
+          indent: true,
+          message: `${path}: translation is not valid JSON — skipped`,
+          value: valuePreview(value),
+          error: jsonError,
+        })
+        continue
+      }
+      writableFields[path] = value
+      log({level: 'info', indent: true, message: `${path}`, value: valuePreview(value)})
+    }
+    log({level: 'info', indent: true, message: `creating new '${locale}' document variant draft`})
+    // Create the variant as a draft; metadata references its published (bare) id.
+    variantId = uuid()
+    await client.create({...stripSystemFields(source), _id: draftId(variantId), [languageField]: locale, ...writableFields})
+  }
+
+  if (!metadata?._id) {
+    log({level: 'info', indent: true, message: 'creating translation metadata'})
+    await client.create({
+      _type: METADATA_TYPE,
+      schemaTypes: [type],
+      translations: [translationEntry(sourceLanguage, sourceId), translationEntry(locale, variantId)],
+    })
+  } else if (!existingVariantId) {
+    log({level: 'info', indent: true, message: 'linking variant into translation metadata'})
+    await client
+      .patch(metadata._id)
+      .setIfMissing({translations: []})
+      .insert('after', 'translations[-1]', [translationEntry(locale, variantId)])
+      .commit()
+  }
+
+  log({level: 'success', indent: true, message: `'${locale}' document variant ready: ${variantId}`})
+  return true
+}
+
+function translationEntry(language: string, ref: string) {
+  return {
+    _key: uuid(),
+    _type: REFERENCE_VALUE_TYPE,
+    language,
+    value: {_type: 'reference', _ref: ref, _weak: true},
+  }
+}
+
+function stripSystemFields(doc: Record<string, unknown>): Record<string, unknown> {
+  const {_id, _rev, _createdAt, _updatedAt, ...rest} = doc
+  void _id
+  void _rev
+  void _createdAt
+  void _updatedAt
+  return rest
+}
+
+function keyPortableText(fields: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(fields)) {
+    if (Array.isArray(value) && value.some((v) => v && typeof v === 'object' && '_type' in v)) {
+      out[key] = value.map((b) => keyBlock(b as Record<string, unknown>))
+    } else {
+      out[key] = value
+    }
+  }
+  return out
+}
+
+function keyBlock(block: Record<string, unknown>): Record<string, unknown> {
+  const keyed: Record<string, unknown> = {_key: (block._key as string) || uuid(), ...block}
+  if (Array.isArray(keyed.children)) {
+    keyed.children = (keyed.children as Record<string, unknown>[]).map((child) => ({
+      _key: (child._key as string) || uuid(),
+      ...child,
+    }))
+  }
+  return keyed
+}
+
+/**
+ * Deep value equality that ignores volatile `_key`s and object-key order, so an
+ * unchanged translation — whose Portable Text gets freshly re-keyed on each
+ * deserialize — isn't mistaken for a change.
+ */
+function sameValue(a: unknown, b: unknown): boolean {
+  return stableString(a) === stableString(b)
+}
+
+function stableString(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableString).join(',')}]`
+  if (value && typeof value === 'object') {
+    const entries = Object.entries(value as Record<string, unknown>)
+      .filter(([k]) => k !== '_key')
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stableString(v)}`).join(',')}}`
+  }
+  return JSON.stringify(value) ?? 'undefined'
+}