@smartcat/sanity-plugin 1.0.1 → 1.1.0

package/src/progress/core.ts

@@ -1,6 +1,6 @@
 import type {SmartcatProject, SmartcatDocument, RequestLogger} from '../smartcat/types'
 import {toSanityLanguage, type SmartcatLanguageMapping} from '../lib/languageMap'
-import {itemDocDeref} from '../lib/projectItems'
+import {ITEM_ID, itemDocDerefRespectingDraft} from '../lib/projectItems'
 import type {LogLine} from '../lib/log'
 
 /**
@@ -121,11 +121,14 @@ export interface ProjectItem {
 
 /**
  * Extracts the 8-char source-id prefix Smartcat preserves in a document's
- * filename (built as `<title>-<idPrefix>.locjson`). Used to correlate a Smartcat
+ * filename (built as `<title>-<idPrefix>.locjson`, or `<title>-<idPrefix>-draft.locjson`
+ * when the content came from the document's draft). Used to correlate a Smartcat
  * document back to a Sanity source document.
  *
- * The prefix is always the final 8 characters before the extension, so take the
- * tail rather than splitting on a dash — the title or the id prefix itself can
+ * A trailing `-draft` marker is stripped first, so a draft-sourced file resolves
+ * to the same id as its published counterpart. The prefix is then always the
+ * final 8 characters before the (marker and) extension, so take the tail rather
+ * than splitting on a dash — the title or the id prefix itself can
  * contain dashes (e.g. a custom id like `demo-pdpA` → prefix `demo-pdp`), which
  * would make a last-dash split return the wrong fragment.
  *
@@ -139,7 +142,12 @@ export function sourceIdPrefix(doc: SmartcatDocument): string {
   const base = doc.name || doc.filename || doc.fullPath || ''
   const leaf = base.split('/').pop() ?? ''
   const noExt = leaf.replace(/\.locjson$/i, '')
-  return noExt.slice(-8)
+  // Draft-sourced files carry a trailing `-draft` marker (informational only, so
+  // a project never holds both a document's draft and its published version).
+  // Strip it before taking the tail so a draft file correlates to the same source
+  // id as its published counterpart — the id prefix is what identifies the item.
+  const noDraft = noExt.replace(/-draft$/, '')
+  return noDraft.slice(-8)
 }
 
 /**
@@ -292,7 +300,7 @@ const PROGRESS_QUERY = `*[_id == $id][0]{
   status,
   smartcatProjectId,
   smartcatLanguages[]{sanityId, smartcatLanguage},
-  "items": items[]{ "doc": ${itemDocDeref('{_id}')} },
+  "items": items[]{ "_id": ${ITEM_ID}, "title": ${itemDocDerefRespectingDraft('.title')} },
   progress[]{_key, sourceDocId, title, targets[]{_key, language, smartcatDocumentId, stages, complete, imported, syncedAt}}
 }`
 
@@ -301,18 +309,32 @@ interface ProgressProjectData {
   status?: string
   smartcatProjectId?: string
   smartcatLanguages?: SmartcatLanguageMapping[]
-  items?: {doc: {_id: string} | null}[]
+  items?: ProjectItemRef[]
   progress?: DocProgress[]
 }
 
-/** Resolves a project's referenced items into the lightweight shape we correlate on. */
-export function itemsFromProject(project: {
-  items?: {doc: {_id: string} | null}[]
-}): ProjectItem[] {
-  return (project.items ?? [])
-    .map((i) => i?.doc)
-    .filter((d): d is {_id: string} => Boolean(d))
-    .map((d) => ({_id: d._id}))
+/** A project item as read for correlation: its stored id (always present) plus a
+ * best-effort title. `doc` is the legacy shape — some callers still project it. */
+interface ProjectItemRef {
+  _id?: string
+  title?: string
+  doc?: {_id?: string; title?: string} | null
+}
+
+/**
+ * Resolves a project's items into the lightweight shape we correlate on. The id
+ * is the item's stored `docId` — NOT a dereferenced document — so an item whose
+ * document exists only as a draft (never published) still correlates instead of
+ * being silently dropped. Tolerates the legacy `{doc}` projection.
+ */
+export function itemsFromProject(project: {items?: ProjectItemRef[]}): ProjectItem[] {
+  const result: ProjectItem[] = []
+  for (const item of project.items ?? []) {
+    const _id = item?._id ?? item?.doc?._id
+    if (!_id) continue
+    result.push({_id, title: item?.title ?? item?.doc?.title ?? undefined})
+  }
+  return result
 }
 
 /**

package/src/progress/progress.test.ts

@@ -58,6 +58,18 @@ describe('stage helpers', () => {
     expect(sourceIdPrefix({id: 'g_1', filename: 'aiAssistantModal.resetChat-11AKrV8G.locjson'})).toBe('11AKrV8G')
     expect(sourceIdPrefix({id: 'g_1', name: 'v2.5 Landing Page-ab12cd34'})).toBe('ab12cd34')
   })
+
+  it('correlates a draft-sourced file to the same id as its published counterpart', () => {
+    // Draft files carry a trailing `-draft` marker; it must be stripped so both
+    // resolve to the same source id (a project holds one version, never both).
+    const published = {id: 'g_1', filename: 'page/About Us-f18f0d41.locjson'}
+    const draft = {id: 'g_2', filename: 'page/About Us-f18f0d41-draft.locjson'}
+    expect(sourceIdPrefix(published)).toBe('f18f0d41')
+    expect(sourceIdPrefix(draft)).toBe('f18f0d41')
+    expect(sourceIdPrefix(draft)).toBe(sourceIdPrefix(published))
+    // Marker stripped from the name form (no extension) too.
+    expect(sourceIdPrefix({id: 'g_3', name: 'About Us-f18f0d41-draft'})).toBe('f18f0d41')
+  })
 })
 
 const scProject: SmartcatProject = {
@@ -131,6 +143,16 @@ describe('buildProgress', () => {
   it('resolves items from a project shape', () => {
     expect(itemsFromProject({items: [{doc: {_id: 'a'}}, {doc: null}]})).toEqual([{_id: 'a'}])
   })
+
+  it('resolves items by stored id, so a draft-only item still correlates', () => {
+    // Current query projects the item's stored `docId` as `_id` (no deref), so an
+    // item whose document exists only as a draft is not dropped.
+    expect(itemsFromProject({items: [{_id: 'draftOnlyId', title: 'Draft Page'}]})).toEqual([
+      {_id: 'draftOnlyId', title: 'Draft Page'},
+    ])
+    // Items with no id at all (deleted/unresolvable) are still dropped.
+    expect(itemsFromProject({items: [{doc: null}, {}]})).toEqual([])
+  })
 })
 
 describe('summarizeCompletion', () => {

package/src/schema/translationProject.ts

@@ -97,6 +97,10 @@ export function createTranslationProjectType(): SchemaTypeDefinition {
             fields: [
               defineField({name: 'docId', title: 'Document ID', type: 'string'}),
               defineField({name: 'docType', title: 'Document type', type: 'string'}),
+              // Set when the item was added from the published perspective, so the
+              // export translates the published document. Absent/false (incl. all
+              // legacy items) prefers the draft — see itemDocDerefRespectingDraft.
+              defineField({name: 'sourceIsPublished', title: 'Source is published', type: 'boolean'}),
             ],
             preview: {select: {title: 'docId', subtitle: 'docType'}},
           }),

package/src/tool/Dashboard.tsx

@@ -11,7 +11,8 @@ import type {ResolvedSmartcatConfig} from '../lib/resolveConfig'
  * view, so the selected project is reflected in the URL (deep-linkable).
  */
 export function createDashboardComponent(config: ResolvedSmartcatConfig) {
-  const {sourceLanguage, languages, documentI18nLanguageField, fieldI18nLanguageField} = config
+  const {sourceLanguage, languages, translatableTypes, documentI18nLanguageField, fieldI18nLanguageField} =
+    config
 
   return function Dashboard() {
     const router = useRouter()
@@ -31,6 +32,7 @@ export function createDashboardComponent(config: ResolvedSmartcatConfig) {
               onBack={goBack}
               languages={languages}
               sourceLanguage={sourceLanguage}
+              translatableTypes={translatableTypes}
               documentI18nLanguageField={documentI18nLanguageField}
               fieldI18nLanguageField={fieldI18nLanguageField}
             />

package/src/tool/ProjectView.tsx

@@ -50,6 +50,8 @@ interface ProjectViewProps {
   onBack: () => void
   languages: SmartcatLanguage[]
   sourceLanguage: string
+  /** Configured translatable types (undefined = all), shown in the export log. */
+  translatableTypes?: string[]
   /** document-internationalization `languageField` (document locale field name). */
   documentI18nLanguageField: string
   /** internationalized-array locale key: field name (`'language'`) or `'_key'`. */
@@ -164,13 +166,15 @@ const CodeArea = styled.textarea`
 function ViewLocjsonButton(props: {
   docId: string
   type: string
+  /** Whether the export will translate the published doc (else prefer the draft). */
+  sourceIsPublished: boolean | null
   client: {fetch: (query: string, params?: Record<string, unknown>) => Promise<unknown>}
   schema: {get: (typeName: string) => unknown}
   sourceLanguage: string
   documentI18nLanguageField: string
   fieldI18nLanguageField: string
 }) {
-  const {docId, type, client, schema, sourceLanguage, documentI18nLanguageField, fieldI18nLanguageField} = props
+  const {docId, type, sourceIsPublished, client, schema, sourceLanguage, documentI18nLanguageField, fieldI18nLanguageField} = props
   const [open, setOpen] = useState(false)
   const [content, setContent] = useState<string | null>(null)
   const [filename, setFilename] = useState<string | null>(null)
@@ -182,8 +186,18 @@ function ViewLocjsonButton(props: {
     setFilename(null)
     setError(null)
     try {
-      const doc = await client.fetch('*[_id == $id][0]', {id: docId})
-      if (!doc) throw new Error(`Document not found: ${docId}`)
+      // Resolve the same version the export will send: the draft (fallback to
+      // published) unless the item was added from the published perspective.
+      const raw = (await client.fetch(
+        sourceIsPublished
+          ? '*[_id == $id][0]'
+          : 'coalesce(*[_id == "drafts." + $id][0], *[_id == $id][0])',
+        {id: docId},
+      )) as (Record<string, unknown> & {_id: string}) | null
+      if (!raw) throw new Error(`Document not found: ${docId}`)
+      const isDraft = typeof raw._id === 'string' && raw._id.startsWith('drafts.')
+      // Serialize under the canonical (bare) id, matching the export.
+      const doc = isDraft ? {...raw, _id: docId} : raw
       const fields = getTranslatableFields(schema.get(type), {exclude: [documentI18nLanguageField]})
       const locjson = serializeToLocjson(doc as never, fields, {
         sourceLanguage,
@@ -191,13 +205,13 @@ function ViewLocjsonButton(props: {
       })
       // Same name the export sends to Smartcat; the last path segment is the
       // file's basename (the Smartcat "folder/" prefix can't be a local filename).
-      const smartcatName = buildLocjsonFilename(type, docId, resolveDocumentTitle(schema, doc as never))
+      const smartcatName = buildLocjsonFilename(type, docId, resolveDocumentTitle(schema, doc as never), {draft: isDraft})
       setFilename(smartcatName.split('/').pop() || smartcatName)
       setContent(JSON.stringify(locjson, null, 2))
     } catch (err) {
       setError(err instanceof Error ? err.message : String(err))
     }
-  }, [client, schema, docId, type, sourceLanguage, documentI18nLanguageField, fieldI18nLanguageField])
+  }, [client, schema, docId, type, sourceIsPublished, sourceLanguage, documentI18nLanguageField, fieldI18nLanguageField])
 
   const download = useCallback(() => {
     if (content == null || !filename) return
@@ -268,6 +282,7 @@ export function ProjectView({
   onBack,
   languages,
   sourceLanguage,
+  translatableTypes,
   documentI18nLanguageField,
   fieldI18nLanguageField,
 }: ProjectViewProps) {
@@ -588,6 +603,7 @@ export function ProjectView({
         targetLanguages: targets,
         sourceLanguage,
         languages,
+        translatableTypes,
         exclude: [documentI18nLanguageField],
         fieldLanguageKey: fieldI18nLanguageField,
         deletions,
@@ -865,16 +881,28 @@ export function ProjectView({
                   <Stack space={3}>
                     <Flex align="center" gap={3}>
                       <Flex align="center" gap={2}>
+                        <Badge
+                          tone={item.sourceIsPublished ? 'positive' : 'caution'}
+                          paddingX={2}
+                          title={
+                            item.sourceIsPublished
+                              ? 'The published version is the translation source'
+                              : 'The draft version is the translation source'
+                          }
+                        >
+                          {item.sourceIsPublished ? 'Published' : 'Draft'}
+                        </Badge>
                         <Text weight="medium">
                           <span style={isMarked ? {textDecoration: 'line-through'} : undefined}>
                             <DocTitle doc={item.doc} />
                           </span>
                         </Text>
-                        {item.doc?._type && <Badge tone="primary">{item.doc._type}</Badge>}
+                        {item.doc?._type && <Badge tone="primary" paddingX={2}>{item.doc._type}</Badge>}
                         {item.doc?._type && modeByType.has(item.doc._type) && (
                           <Badge
                             tone="default"
                             fontSize={0}
+                            paddingX={2}
                             title={
                               modeByType.get(item.doc._type) === 'field'
                                 ? 'This item is translated in field mode; translations will be stored as language variants of each field'
@@ -889,6 +917,7 @@ export function ProjectView({
                           <ViewLocjsonButton
                             docId={item.doc._id}
                             type={item.doc._type}
+                            sourceIsPublished={item.sourceIsPublished}
                             client={client}
                             schema={schema}
                             sourceLanguage={sourceLanguage}

package/src/tool/data.ts

@@ -18,6 +18,12 @@ export interface ProjectItemRef {
   _key: string
   /** Published id of the added document, normalized across old (`_ref`) and new (`docId`) items. */
   docId: string
+  /**
+   * Whether the published version is the translation source (vs the draft),
+   * decided and stored when the item was added. Drives the Draft/Published pill
+   * and which version the export serializes. Null on legacy items (pre-flag).
+   */
+  sourceIsPublished: boolean | null
   doc: {_id: string; _type: string} | null
   /** Locale variants linked via translation.metadata: language -> variant doc id. */
   translations: {language: string; id: string}[] | null
@@ -66,6 +72,7 @@ export const PROJECT_DETAIL_QUERY = `*[_id == $id][0]{
   items[]{
     _key,
     "docId": ${ITEM_ID},
+    sourceIsPublished,
     "doc": ${itemDocDeref('{_id, _type}')},
     "translations": *[_type == "translation.metadata" && references(${ITEM_ID_FROM_SUBQUERY})][0]
       .translations[]{language, "id": value._ref}

package/src/tool/processing.test.ts

@@ -141,10 +141,85 @@ describe('prepareExport', () => {
     expect(locjson.properties['x-sanity'].documentId).toBe('page-1')
   })
 
-  const table = {_type: 'table', _key: 't1', rows: [{_key: 'r1', _type: 'tableRow', cells: ['A', 'B']}]}
+  it('logs a config header with source language, languages, and translatable types', async () => {
+    const {client} = makeClient({project: {sourceLanguage: 'en', items: [{doc: sourceDoc}]}})
+    const logs: {level: string; message: string}[] = []
+    await prepareExport({
+      client, schema, projectId: 'p1', targetLanguages: ['fr'], sourceLanguage: 'en',
+      languages: LANGUAGES, translatableTypes: ['page', 'faq'], fieldLanguageKey: 'language',
+      onLog: (l) => logs.push(l),
+    })
+    const messages = logs.map((l) => l.message)
+    expect(messages).toContain('Config — source language: en')
+    expect(messages).toContain('translatable types: page, faq')
+    expect(messages.some((m) => /Project — source: en → targets: fr/.test(m))).toBe(true)
+  })
+
+  it('reports "all types" in the config header when translatableTypes is omitted', async () => {
+    const {client} = makeClient({project: {sourceLanguage: 'en', items: [{doc: sourceDoc}]}})
+    const logs: {message: string}[] = []
+    await prepareExport({
+      client, schema, projectId: 'p1', targetLanguages: ['fr'], sourceLanguage: 'en',
+      languages: LANGUAGES, fieldLanguageKey: 'language', onLog: (l) => logs.push(l),
+    })
+    expect(logs.map((l) => l.message)).toContain('translatable types: all types')
+  })
+
+  it('explains a source-language mismatch on a field-level field by naming the locales present', async () => {
+    // Field members exist only for en-GB, but the project source is 'en'.
+    const faqDoc = {
+      _id: 'faq-mismatch',
+      _type: 'faq',
+      question: [{_key: 'q', _type: 'internationalizedArrayStringValue', language: 'en-GB', value: 'How?'}],
+    }
+    const {client} = makeClient({project: {sourceLanguage: 'en', items: [{doc: faqDoc}]}})
+    const logs: {level: string; message: string}[] = []
+    await prepareExport({
+      client, schema: faqSchema, projectId: 'p1', targetLanguages: ['fr'], sourceLanguage: 'en',
+      languages: LANGUAGES, fieldLanguageKey: 'language', onLog: (l) => logs.push(l),
+    })
+    expect(logs.some((l) => /Question:.*no 'en' content \(I see only: en-GB\)/.test(l.message))).toBe(true)
+  })
+
+  it('translates draft content under the canonical (bare) id and marks the file -draft', async () => {
+    // The item resolves to the draft (drafts.page-9); the export must keep the
+    // bare id as identity but serialize the draft's content and flag the file.
+    const draftDoc = {_id: 'drafts.page-9', _type: 'page', language: 'en', title: 'Draft Title', body: [block('Draft body.')]}
+    const {client, patches} = makeClient({
+      project: {sourceLanguage: 'en', items: [{docId: 'page-9', docType: 'page', doc: draftDoc}]},
+    })
+    const logs: {message: string}[] = []
+    const {prepared} = await prepareExport({
+      client, schema, projectId: 'p1', targetLanguages: ['fr'], sourceLanguage: 'en',
+      languages: LANGUAGES, fieldLanguageKey: 'language', onLog: (l) => logs.push(l),
+    })
+    expect(prepared).toBe(1)
+    const outbox = patches.at(-1)!.outbox as {sourceDocId: string; filename: string; locjson: string}[]
+    expect(outbox[0].sourceDocId).toBe('page-9') // bare, not drafts.page-9
+    expect(JSON.parse(outbox[0].locjson).properties['x-sanity'].documentId).toBe('page-9')
+    expect(outbox[0].filename).toMatch(/-draft\.locjson$/)
+    expect(logs.some((l) => /Draft Title.*\(draft\)/.test(l.message))).toBe(true)
+  })
+
+  it('reports a project item that resolves to no document instead of dropping it silently', async () => {
+    const {client, patches} = makeClient({
+      project: {sourceLanguage: 'en', items: [{docId: 'missing-1', docType: 'page', doc: null}]},
+    })
+    const logs: {level: string; message: string}[] = []
+    const {prepared} = await prepareExport({
+      client, schema, projectId: 'p1', targetLanguages: ['fr'], sourceLanguage: 'en',
+      languages: LANGUAGES, fieldLanguageKey: 'language', onLog: (l) => logs.push(l),
+    })
+    expect(prepared).toBe(0)
+    expect(patches.at(-1)!.outbox).toEqual([])
+    expect(logs.some((l) => l.level === 'error' && /missing-1.*no document found/.test(l.message))).toBe(true)
+  })
+
+  // A custom block with no HTML representation (unlike `table`, which round-trips).
+  const heroBanner = {_type: 'heroBanner', _key: 'h1', heading: 'Save 20%'}
 
   it('leaves out a field with an unserializable block but still sends the rest of the document', async () => {
-    const doc = {_id: 'page-2', _type: 'page', language: 'en', title: 'About Us', body: [block('Intro.'), table]}
+    const doc = {_id: 'page-2', _type: 'page', language: 'en', title: 'About Us', body: [block('Intro.'), heroBanner]}
     const {client, patches} = makeClient({project: {sourceLanguage: 'en', items: [{doc}]}})
     const logs: {level: string; message: string}[] = []
 
@@ -157,13 +232,13 @@ describe('prepareExport', () => {
     const outbox = patches.at(-1)!.outbox as {locjson: string}[]
     const locjson = JSON.parse(outbox[0].locjson)
     expect(locjson.units.map((u: {key: string}) => u.key)).toEqual(['title']) // body left out
-    expect(logs.some((l) => l.level === 'error' && /Body: not translated.*table/.test(l.message))).toBe(true)
+    expect(logs.some((l) => l.level === 'error' && /Body: not translated.*heroBanner/.test(l.message))).toBe(true)
   })
 
   it('does not emit a zero-unit LocJSON when the only content is in an unserializable field', async () => {
     // A single-field document whose one field can't be serialized: it must not be
     // sent at all (no empty LocJSON), and the whole document is flagged.
-    const doc = {_id: 'page-3', _type: 'page', language: 'en', title: '', body: [table]}
+    const doc = {_id: 'page-3', _type: 'page', language: 'en', title: '', body: [heroBanner]}
     const {client, patches} = makeClient({project: {sourceLanguage: 'en', items: [{doc}]}})
     const logs: {level: string; message: string}[] = []
 

package/src/tool/processing.ts

@@ -1,6 +1,6 @@
 import {uuid} from '@sanity/uuid'
 import {resolveDocumentTitle} from '../lib/documentTitle'
-import {itemDocDeref} from '../lib/projectItems'
+import {ITEM_ID, itemDocDerefRespectingDraft} from '../lib/projectItems'
 import {
   enumerateLeaves,
   getTranslatableFields,
@@ -68,6 +68,26 @@ 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
@@ -106,6 +126,8 @@ export interface PrepareExportArgs {
   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
@@ -115,7 +137,14 @@ export interface PrepareExportArgs {
   onLog?: LogFn
 }
 
-const ITEMS_QUERY = `*[_id == $id][0]{ sourceLanguage, items[]{ "doc": ${itemDocDeref()} } }`
+const ITEMS_QUERY = `*[_id == $id][0]{
+  sourceLanguage,
+  items[]{
+    "docId": ${ITEM_ID},
+    "docType": docType,
+    "doc": ${itemDocDerefRespectingDraft()}
+  }
+}`
 
 export async function prepareExport({
   client,
@@ -124,6 +153,7 @@ export async function prepareExport({
   targetLanguages,
   sourceLanguage,
   languages,
+  translatableTypes,
   exclude,
   fieldLanguageKey,
   deletions = [],
@@ -132,7 +162,11 @@ export async function prepareExport({
   const log: LogFn = onLog ?? (() => {})
   const project = await client.fetch<{
     sourceLanguage?: string
-    items?: {doc: (Record<string, unknown> & {_id: string; _type: string}) | null}[]
+    items?: {
+      docId?: string
+      docType?: string
+      doc: (Record<string, unknown> & {_id: string; _type: string}) | null
+    }[]
   } | null>(ITEMS_QUERY, {id: projectId})
 
   const source = project?.sourceLanguage || sourceLanguage
@@ -150,10 +184,16 @@ export async function prepareExport({
   }
   // Don't re-upload documents that are being deleted this round.
   const deletedDocIds = new Set(deletions.map((d) => d.sourceDocId))
-  const docs = (project?.items ?? [])
-    .map((i) => i?.doc)
+  // 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))
-    .filter((d) => !deletedDocIds.has(d._id))
 
   // The translatable field list is per-type, so compute it once per type even
   // when a project holds many documents of the same type.
@@ -167,12 +207,36 @@ export async function prepareExport({
     return fields
   }
 
-  log({level: 'info', message: `Export — ${docs.length} document(s) → ${targetLanguages.join(', ') || '(no targets)'}`})
+  // 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 doc of docs) {
+  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}`})
+    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
@@ -198,7 +262,16 @@ export async function prepareExport({
             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 {
-          log({level: 'skip', indent: true, message: `${field.title || field.path}: skipped — no source content`})
+          // 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
@@ -228,7 +301,7 @@ export async function prepareExport({
         _key: uuid(),
         sourceDocId: doc._id,
         title: name,
-        filename: buildLocjsonFilename(doc._type, doc._id, name),
+        filename: buildLocjsonFilename(doc._type, doc._id, name, {draft: isDraft}),
         locjson: JSON.stringify(locjson),
       })
     } catch (err) {