@smartcat/sanity-plugin 1.2.1 → 1.4.0

package/src/export/export.test.ts

@@ -33,7 +33,7 @@ function fakeSanity(project: unknown) {
 // Stateful Smartcat fake. `getProject` reflects documents created so far; names
 // encode the source-id prefix exactly as buildLocjsonFilename does.
 function fakeSmartcat(initialDocs: SmartcatDocument[] = []) {
-  const uploads: {filename: string; body: string}[] = []
+  const uploads: {filename: string; body: string; targetLanguage?: string}[] = []
   const updates: {documentId: string; filename: string; body: string}[] = []
   const deletes: string[] = []
   const docs = [...initialDocs]
@@ -46,12 +46,14 @@ function fakeSmartcat(initialDocs: SmartcatDocument[] = []) {
   }
   const client: SmartcatExportClient = {
     createProject: vi.fn(async () => ({id: 'guid-1'})),
-    uploadDocument: vi.fn(async (_p: string, filename: string, body: string) => {
-      uploads.push({filename, body})
+    uploadDocument: vi.fn(async (_p: string, filename: string, body: string, targetLanguage?: string) => {
+      uploads.push({filename, body, targetLanguage})
       const leaf = filename.split('/').pop()!.replace(/\.[^.]+$/, '')
       const id = `gNew${++guid}_12`
-      docs.push({id, name: leaf, targetLanguage: 'fr', workflowStages: [{id: 'st-tr', progress: 0}]})
-      return [{id, targetLanguage: 'fr'}]
+      // A per-language upload reports that one language; else default to fr.
+      const lang = targetLanguage || 'fr'
+      docs.push({id, name: leaf, targetLanguage: lang, workflowStages: [{id: 'st-tr', progress: 0}]})
+      return [{id, name: leaf, targetLanguage: lang}]
     }),
     uploadDocuments: vi.fn(async (_p: string, files: {filename: string; content: string}[]) => {
       const out: SmartcatDocument[] = []
@@ -116,6 +118,41 @@ describe('runExportUpload — first sync', () => {
     expect(progress[0].targets[0]).toMatchObject({language: 'fr', smartcatDocumentId: 'gNew1_12'})
   })
 
+  it('uploads per-language bilingual files with a pinned target language, and records their ids', async () => {
+    // Two languages of one source: each outbox entry names `_<lang>` and carries a
+    // targetLanguage → uploaded via uploadDocument with that language pinned.
+    const project = {
+      _id: 'p1',
+      name: 'Spring',
+      sourceLanguage: 'en',
+      targetLanguages: ['fr', 'de'],
+      smartcatLanguages: [
+        {sanityId: 'fr', smartcatLanguage: 'fr'},
+        {sanityId: 'de', smartcatLanguage: 'de'},
+      ],
+      outbox: [
+        {sourceDocId: 'about123-aaaa', title: 'About', filename: 'page/About-about123_fr.locjson', locjson: '{"units":[]}', targetLanguage: 'fr'},
+        {sourceDocId: 'about123-aaaa', title: 'About', filename: 'page/About-about123_de.locjson', locjson: '{"units":[]}', targetLanguage: 'de'},
+      ],
+    }
+    const {client: sanity, sets} = fakeSanity(project)
+    const {client: smartcat, uploads} = fakeSmartcat()
+
+    const result = await runExportUpload({sanity, smartcat, projectId: 'p1', now: () => 'T'})
+
+    expect(uploads).toEqual([
+      {filename: 'page/About-about123_fr.locjson', body: '{"units":[]}', targetLanguage: 'fr'},
+      {filename: 'page/About-about123_de.locjson', body: '{"units":[]}', targetLanguage: 'de'},
+    ])
+    expect(result).toMatchObject({created: 2, updated: 0, failed: 0})
+    // Both languages correlate back to the one source, each with its own doc id.
+    const progress = sets.at(-1)!.progress as {sourceDocId: string; targets: {language: string; smartcatDocumentId?: string}[]}[]
+    expect(progress).toHaveLength(1)
+    expect(progress[0].sourceDocId).toBe('about123-aaaa')
+    expect(progress[0].targets.map((t) => t.language).sort()).toEqual(['de', 'fr'])
+    expect(progress[0].targets.every((t) => t.smartcatDocumentId)).toBe(true)
+  })
+
   it('maps Sanity ids to Smartcat codes for createProject', async () => {
     const project = {
       _id: 'p1',

package/src/export/index.ts

@@ -1,7 +1,7 @@
 import type {CreateProjectInput, RequestLogger, SmartcatDocument, SmartcatProject} from '../smartcat/types'
 import {SmartcatError} from '../smartcat/client'
 import {buildProgress, sourceIdPrefix, type DocProgress, type ProjectItem} from '../progress/core'
-import {toSmartcatLanguage, type SmartcatLanguageMapping} from '../lib/languageMap'
+import {toSmartcatLanguage, toSanityLanguage, type SmartcatLanguageMapping} from '../lib/languageMap'
 import {resolveWorkflowCreateParams} from '../lib/workflow'
 import type {LogLine} from '../lib/log'
 
@@ -49,7 +49,8 @@ export interface SanityLikeClient {
 /** Structural subset of SmartcatClient the export needs. */
 export interface SmartcatExportClient {
   createProject(input: CreateProjectInput): Promise<{id: string}>
-  uploadDocument(projectId: string, filename: string, content: string): Promise<SmartcatDocument[]>
+  /** `targetLanguage` (Smartcat code) restricts a bilingual file to one language. */
+  uploadDocument(projectId: string, filename: string, content: string, targetLanguage?: string): Promise<SmartcatDocument[]>
   uploadDocuments(projectId: string, files: {filename: string; content: string}[]): Promise<SmartcatDocument[]>
   updateDocument(documentId: string, filename: string, content: string): Promise<SmartcatDocument[]>
   deleteDocument(documentId: string): Promise<void>
@@ -95,7 +96,7 @@ const PROJECT_QUERY = `*[_id == $id][0]{
   smartcatProjectId,
   smartcatProjectUrl,
   smartcatLanguages[]{sanityId, smartcatLanguage},
-  outbox[]{sourceDocId, title, filename, locjson},
+  outbox[]{sourceDocId, title, filename, locjson, targetLanguage},
   pendingDeletions[]{itemKey, sourceDocId, smartcatDocumentId},
   progress[]{_key, sourceDocId, title, targets[]{_key, language, smartcatDocumentId, stages, complete, imported, syncedAt}}
 }`
@@ -105,6 +106,9 @@ interface OutboxItem {
   title?: string
   filename: string
   locjson: string
+  /** Present for per-language bilingual files (send-existing flow): the single
+   * Smartcat target-language code this file carries. Absent ⇒ target all langs. */
+  targetLanguage?: string
 }
 
 interface ProjectData {
@@ -255,12 +259,20 @@ export async function runExportUpload(options: RunExportUploadOptions): Promise<
       }
     }
 
+    // Per-language bilingual files (send-existing flow) upload one document per
+    // (source × language); the rest target all languages with one file. They take
+    // different upload/update paths, so split them here.
+    const perLangBox = outbox.filter((item) => item.targetLanguage)
+    const stdBox = outbox.filter((item) => !item.targetLanguage)
+
     // For an existing project, find which source files are already in Smartcat so
-    // we update them in place rather than creating duplicates.
+    // we update them in place rather than creating duplicates. Only the all-language
+    // files use this source-prefix map; per-language files resolve their existing
+    // document id per (source × language) from stored progress below.
     const existing =
-      isNew || outbox.length === 0
+      isNew || stdBox.length === 0
         ? new Map<string, string>()
-        : existingDocIdsBySource(await smartcat.getProject(scProjectId as string), outbox)
+        : existingDocIdsBySource(await smartcat.getProject(scProjectId as string), stdBox)
 
     let created = 0
     let updated = 0
@@ -272,8 +284,23 @@ export async function runExportUpload(options: RunExportUploadOptions): Promise<
     // a re-export (see the field-level "Untitled" progress bug).
     const writtenDocs: SmartcatDocument[] = []
 
-    const toUpdate = outbox.filter((item) => item.sourceDocId && existing.get(item.sourceDocId))
-    const toCreate = outbox.filter((item) => !(item.sourceDocId && existing.get(item.sourceDocId)))
+    const toUpdate = stdBox.filter((item) => item.sourceDocId && existing.get(item.sourceDocId))
+    const toCreate = stdBox.filter((item) => !(item.sourceDocId && existing.get(item.sourceDocId)))
+
+    // Existing per-language document ids, keyed `${sourceDocId}__${sanityLocale}`
+    // from stored progress — the target that re-sync updates in place. Progress
+    // stores the Sanity locale, so map the outbox's Smartcat code back to it.
+    const perLangDocId = new Map<string, string>()
+    for (const doc of project.progress ?? []) {
+      for (const t of doc.targets) {
+        if (t.smartcatDocumentId) perLangDocId.set(`${doc.sourceDocId}__${t.language}`, t.smartcatDocumentId)
+      }
+    }
+    const existingPerLangId = (item: OutboxItem): string | undefined => {
+      if (!item.sourceDocId || !item.targetLanguage) return undefined
+      const locale = toSanityLanguage(project.smartcatLanguages, item.targetLanguage)
+      return perLangDocId.get(`${item.sourceDocId}__${locale}`)
+    }
 
     // Updates stay per-item (no multi-file equivalent) — today's behavior.
     for (const item of toUpdate) {
@@ -348,6 +375,34 @@ export async function runExportUpload(options: RunExportUploadOptions): Promise<
     // under JS's single-threaded async interleaving.
     await runWithConcurrency(chunk(toCreate, UPLOAD_CHUNK_SIZE), UPLOAD_CHUNK_CONCURRENCY, processChunk)
 
+    // Per-language bilingual files: one document per (source × language). Update in
+    // place when a stored document id exists for that pair (rename-proof: keyed by
+    // the stable Smartcat id, not the filename), otherwise create with the target
+    // language pinned via the upload's `documentModel`. Tag written docs with the
+    // filename so buildProgress correlates them, and capture the id for next time.
+    await runWithConcurrency(perLangBox, UPLOAD_CHUNK_CONCURRENCY, async (item) => {
+      const existingId = existingPerLangId(item)
+      try {
+        const returned = existingId
+          ? await smartcat.updateDocument(existingId, item.filename, item.locjson)
+          : await smartcat.uploadDocument(scProjectId as string, item.filename, item.locjson, item.targetLanguage)
+        for (const d of returned) writtenDocs.push({...d, name: d.name || item.filename})
+        if (existingId) updated++
+        else created++
+        log.push({level: 'success', message: `${existingId ? 'Updated' : 'Uploaded'} ${item.filename}`})
+      } catch (e) {
+        // A 409 means a prior attempt already created this file (HTTP error masking
+        // a successful create) — it's synced, not failed.
+        if (e instanceof SmartcatError && e.status === 409) {
+          created++
+          log.push({level: 'success', message: `Already synced ${item.filename}`})
+        } else {
+          failed++
+          log.push({level: 'error', message: `Skipped ${item.filename} — upload failed (see error above)`})
+        }
+      }
+    })
+
     // Re-fetch for authoritative ids/stages, and mirror the name back on first
     // creation (Smartcat may have de-duplicated it, e.g. "My test (1)"). Then add
     // any just-written docs it hasn't indexed yet so none are dropped this run.

package/src/lib/locjson/filename.ts

@@ -12,13 +12,18 @@ export function buildLocjsonFilename(
   documentType: string,
   documentId: string,
   title?: string,
-  options: {draft?: boolean} = {},
+  options: {draft?: boolean; language?: string} = {},
 ): string {
   const idPrefix = stripDraft(documentId).slice(0, 8) || 'unknown'
   const safeTitle = sanitizeSegment(title || 'Untitled')
   const safeType = sanitizeSegment(documentType) || 'document'
   const draftMarker = options.draft ? '-draft' : ''
-  return `${safeType}/${safeTitle}-${idPrefix}${draftMarker}.locjson`
+  // Per-language bilingual files (send-existing flow) append `_<lang>` so Smartcat
+  // groups the languages of one source as a single multilingual document, and so
+  // `sourceIdPrefix` can strip the marker back off. The language sits after the
+  // draft marker; correlation strips them in reverse.
+  const langMarker = options.language ? `_${sanitizeSegment(options.language)}` : ''
+  return `${safeType}/${safeTitle}-${idPrefix}${draftMarker}${langMarker}.locjson`
 }
 
 function stripDraft(id: string): string {

package/src/lib/locjson/locjson.test.ts

@@ -344,6 +344,39 @@ describe('serializeToLocjson', () => {
     expect(body.source[0]).toContain('<td>Region</td>')
   })
 
+  it('bilingual (document-level): fills each unit target from the target-locale sibling doc', () => {
+    const result = serializeToLocjson(
+      {_id: 'x', _type: 'page', title: 'About Us', excerpt: 'Line one\nLine two', body: [makeBlock('We build things.')]},
+      fields,
+      {
+        sourceLanguage: 'en',
+        fieldLanguageKey: 'language',
+        target: {
+          language: 'fr',
+          doc: {_id: 'x-fr', _type: 'page', title: 'À propos', excerpt: 'Ligne un\nLigne deux', body: [makeBlock('Nous créons des choses.')]},
+        },
+      },
+    )
+    const title = result.units.find((u) => u.key === 'title')!
+    expect(title.source.join('')).toBe('About Us')
+    expect(title.target.join('')).toBe('À propos')
+    const excerpt = result.units.find((u) => u.key === 'excerpt')!
+    expect(excerpt.target).toEqual(['Ligne un\n', 'Ligne deux'])
+    const body = result.units.find((u) => u.key === 'body')!
+    expect(body.target[0]).toContain('Nous créons des choses.')
+  })
+
+  it('bilingual: leaves target empty when the target-locale field has no content', () => {
+    const result = serializeToLocjson(
+      {_id: 'x', _type: 'page', title: 'About Us', body: []},
+      fields,
+      {sourceLanguage: 'en', fieldLanguageKey: 'language', target: {language: 'fr', doc: {_id: 'x-fr', _type: 'page'}}},
+    )
+    const title = result.units.find((u) => u.key === 'title')!
+    expect(title.source.join('')).toBe('About Us')
+    expect(title.target).toEqual([]) // no French title → Smartcat translates it
+  })
+
   it('skips empty fields', () => {
     const empty = serializeToLocjson(
       {_id: 'x', _type: 'page', title: '', body: []},
@@ -538,6 +571,28 @@ describe('field-level localization', () => {
     expect(answer.source[0]).toContain('Like this.')
   })
 
+  it('bilingual (field-level): fills target from the target-language member on the same doc', () => {
+    const doc = {
+      _id: 'faq-1',
+      _type: 'faq',
+      question: [member('en', 'How?'), member('fr', 'Comment ?')],
+      answer: [
+        member('en', [makeBlock('Like this.')], 'internationalizedArraySimpleBlockContentValue'),
+        member('fr', [makeBlock('Comme ceci.')], 'internationalizedArraySimpleBlockContentValue'),
+      ],
+    }
+    const locjson = serializeToLocjson(doc, getTranslatableFields(faqType), {
+      sourceLanguage: 'en',
+      fieldLanguageKey: 'language',
+      target: {language: 'fr'},
+    })
+    const question = locjson.units.find((u) => u.key === 'question')!
+    expect(question.source.join('')).toBe('How?')
+    expect(question.target.join('')).toBe('Comment ?')
+    const answer = locjson.units.find((u) => u.key === 'answer')!
+    expect(answer.target[0]).toContain('Comme ceci.')
+  })
+
   it('reads the source member by _key when fieldLanguageKey is "_key" (v4)', () => {
     const doc = {
       _id: 'faq-1',
@@ -612,4 +667,13 @@ describe('buildLocjsonFilename', () => {
       'page/About Us-3f14f092-draft.locjson',
     )
   })
+
+  it('appends a _<lang> marker for per-language bilingual files (after the draft marker)', () => {
+    expect(buildLocjsonFilename('page', '3f14f092-3475', 'About Us', {language: 'fr'})).toBe(
+      'page/About Us-3f14f092_fr.locjson',
+    )
+    expect(buildLocjsonFilename('page', 'drafts.3f14f092-3475', 'About Us', {draft: true, language: 'de'})).toBe(
+      'page/About Us-3f14f092-draft_de.locjson',
+    )
+  })
 })

package/src/lib/locjson/serialize.ts

@@ -23,6 +23,20 @@ export interface SerializeOptions {
    * round-trip; the caller surfaces this to the user's log.
    */
   onSkippedField?: (info: {fieldPath: string; title?: string; types: string[]}) => void
+  /**
+   * When set, produces a **bilingual** file for a single target language: each
+   * unit's `target` is populated from the existing translation, in parallel with
+   * its `source`. Used by the "send existing translations" flow. The target value
+   * of a field is read the same way as the source, but for the target language:
+   * - field-level: the target-language member's `value` on the same document;
+   * - document-level: the same field path on `doc` (the target-locale sibling).
+   * `language` is the Sanity locale (matches internationalized-array members).
+   */
+  target?: {
+    language: string
+    /** The target-locale sibling document (document-level only). */
+    doc?: SerializableDocument
+  }
 }
 
 /** A minimal view of a Sanity document needed for serialization. */
@@ -55,10 +69,22 @@ export function serializeToLocjson(
         ? memberValue(getAtPath(doc, field.path), options.sourceLanguage, options.fieldLanguageKey)
         : getAtPath(doc, field.path)
 
+    // The existing translation for this field (bilingual mode only): read the same
+    // way as the source, but for the target language / target-locale document.
+    const targetOpt = options.target
+    const targetSource =
+      !targetOpt
+        ? undefined
+        : field.localization === 'field'
+          ? memberValue(getAtPath(doc, field.path), targetOpt.language, options.fieldLanguageKey)
+          : getAtPath(targetOpt.doc, field.path)
+
     // A scalar field yields one leaf; array/object member values yield one leaf
     // per translatable string inside (addressed by valuePath).
     for (const leaf of enumerateLeaves(field, source)) {
       const value = leaf.valuePath ? getAtPath(source, leaf.valuePath) : source
+      const targetValue =
+        targetSource === undefined ? undefined : leaf.valuePath ? getAtPath(targetSource, leaf.valuePath) : targetSource
       const comments = leaf.title ? [leaf.title] : undefined
 
       if (leaf.kind === 'plain') {
@@ -71,7 +97,8 @@ export function serializeToLocjson(
           // Split into line segments but keep the trailing newline on each, so
           // concatenating the segments (LocJSON's '' join) reconstructs the original.
           source: value.split(/(?<=\n)/),
-          target: [],
+          // Existing translation (parallel to source), or empty for Smartcat to fill.
+          target: typeof targetValue === 'string' && targetValue.length > 0 ? targetValue.split(/(?<=\n)/) : [],
         })
       } else {
         const blocks = value as PortableTextBlock[] | undefined
@@ -86,11 +113,20 @@ export function serializeToLocjson(
         // `<br/>`), so also require actual visible text before emitting a unit.
         const html = portableTextToHtml(blocks)
         if (!html || portableTextToPlainText(blocks).trim().length === 0) continue
+        // Existing translation as HTML — only when the target-locale value is itself
+        // serializable and carries visible text; otherwise leave it for Smartcat.
+        const targetBlocks = targetValue as PortableTextBlock[] | undefined
+        const targetHtml =
+          targetSource === undefined ||
+          findUnserializableBlockTypes(targetBlocks).length > 0 ||
+          portableTextToPlainText(targetBlocks).trim().length === 0
+            ? ''
+            : portableTextToHtml(targetBlocks)
         units.push({
           key: leaf.fullKey,
           properties: {comments, 'x-smartcat-format': 'html', 'x-smartcat-split': 'full', 'x-sanity': {fieldPath: leaf.fullKey}},
           source: [html],
-          target: [],
+          target: targetHtml ? [targetHtml] : [],
         })
       }
     }

package/src/progress/core.ts

@@ -138,10 +138,26 @@ export interface ProjectItem {
  * — leaving the wrong 8 chars, so those documents silently never correlate,
  * never import, and re-syncs duplicate them instead of updating.
  */
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
 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, '')
+  let noExt = leaf.replace(/\.locjson$/i, '')
+  // Per-language bilingual files (send-existing flow) are named
+  // `<title>-<idPrefix>_<lang>.locjson`, and Smartcat's export echoes a trailing
+  // `(<lang>)`. Strip both — keyed to *this* document's known target language, so
+  // the language marker doesn't occupy the id-prefix tail. Legacy source-only
+  // names (`<title>-<idPrefix>.locjson`) have neither, so are left untouched; the
+  // key guard also stops a title that legitimately ends in `_xx`/`(xx)` from being
+  // mangled unless `xx` is exactly this doc's target language.
+  const lang = doc.targetLanguage
+  if (lang) {
+    noExt = noExt.replace(new RegExp(`\\(${escapeRegExp(lang)}\\)$`), '')
+    noExt = noExt.replace(new RegExp(`_${escapeRegExp(lang)}$`), '')
+  }
   // 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
@@ -186,12 +202,31 @@ export function buildProgress(
   }
 
   const itemByPrefix = new Map<string, ProjectItem>()
-  for (const item of items) itemByPrefix.set(stripDraft(item._id).slice(0, 8), item)
+  const itemById = new Map<string, ProjectItem>()
+  for (const item of items) {
+    itemByPrefix.set(stripDraft(item._id).slice(0, 8), item)
+    itemById.set(stripDraft(item._id), item)
+  }
+
+  // Rename-proof correlation: recover a document's item from a previously stored
+  // `smartcatDocumentId`. The Smartcat document id (`<fileGuid>_<langNum>`) is
+  // stable across file renames in Smartcat, whereas its filename (which
+  // `sourceIdPrefix` parses) is not. Prefer the stored id; fall back to the
+  // filename prefix for documents not yet stored (first sync) or legacy projects.
+  const sourceDocIdByScId = new Map<string, string>()
+  for (const doc of previous ?? []) {
+    for (const target of doc.targets) {
+      if (target.smartcatDocumentId) sourceDocIdByScId.set(target.smartcatDocumentId, doc.sourceDocId)
+    }
+  }
 
   const byDoc = new Map<string, DocProgress>()
   for (const scDoc of scProject.documents ?? []) {
     if (!scDoc.targetLanguage) continue
-    const item = itemByPrefix.get(sourceIdPrefix(scDoc))
+    const storedSourceDocId = scDoc.id ? sourceDocIdByScId.get(scDoc.id) : undefined
+    const item =
+      (storedSourceDocId ? itemById.get(stripDraft(storedSourceDocId)) : undefined) ??
+      itemByPrefix.get(sourceIdPrefix(scDoc))
     if (!item) continue
 
     // Store the Sanity locale tag, not Smartcat's code.
@@ -216,8 +251,14 @@ export function buildProgress(
   }
 
   // Preserve item order; sort each doc's targets by language for stable display.
+  // Dedupe by id: the send-existing flow yields one item per (source × language),
+  // so `items` can list a source more than once — its single grouped docProgress
+  // must still appear only once.
   const result: DocProgress[] = []
+  const seen = new Set<string>()
   for (const item of items) {
+    if (seen.has(item._id)) continue
+    seen.add(item._id)
     const docProgress = byDoc.get(item._id)
     if (!docProgress) continue
     docProgress.targets.sort((a, b) => a.language.localeCompare(b.language))

package/src/progress/progress.test.ts

@@ -59,6 +59,19 @@ describe('stage helpers', () => {
     expect(sourceIdPrefix({id: 'g_1', name: 'v2.5 Landing Page-ab12cd34'})).toBe('ab12cd34')
   })
 
+  it('strips a per-language `_<lang>` suffix (and Smartcat `(<lang>)` echo) keyed to the target language', () => {
+    // Send-existing flow names files `<title>-<idPrefix>_<lang>.locjson`; the id
+    // prefix must survive the language suffix.
+    expect(sourceIdPrefix({id: 'g_1', name: 'About Us-f18f0d41_fr', targetLanguage: 'fr'})).toBe('f18f0d41')
+    expect(sourceIdPrefix({id: 'g_1', filename: 'About Us-f18f0d41_de.locjson', targetLanguage: 'de'})).toBe('f18f0d41')
+    // Smartcat's export echoes a trailing `(<lang>)` — strip that too.
+    expect(sourceIdPrefix({id: 'g_1', name: 'About Us-f18f0d41_fr(fr)', targetLanguage: 'fr'})).toBe('f18f0d41')
+    // Draft marker sits before the language suffix.
+    expect(sourceIdPrefix({id: 'g_1', name: 'About Us-f18f0d41-draft_fr', targetLanguage: 'fr'})).toBe('f18f0d41')
+    // Key guard: a title ending in `_xx` is untouched unless xx is the target language.
+    expect(sourceIdPrefix({id: 'g_1', name: 'Report_v2-f18f0d41', targetLanguage: 'fr'})).toBe('f18f0d41')
+  })
+
   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).
@@ -155,6 +168,33 @@ describe('buildProgress', () => {
   })
 })
 
+describe('buildProgress rename-proof correlation', () => {
+  it('recovers a renamed document via the stored smartcatDocumentId (not its filename)', () => {
+    // A user renamed the file in Smartcat, so its name no longer carries the id
+    // prefix — filename correlation would drop it. The stored id from the previous
+    // sync recovers the item.
+    const renamed: SmartcatProject = {
+      id: 'p1',
+      workflowStages: STAGE_NAMES,
+      documents: [
+        {id: '817_12', name: 'Totally Renamed', targetLanguage: 'fr', workflowStages: [{id: 'st-tr', progress: 100}, {id: 'st-ed', progress: 100}]},
+      ],
+    }
+    const previous = [
+      {
+        _key: 'k',
+        sourceDocId: 'f18f0d41-aaaa-bbbb',
+        title: 'About Us',
+        targets: [{_key: 't', language: 'fr', smartcatDocumentId: '817_12', stages: [], complete: true, imported: false}],
+      },
+    ]
+    const progress = buildProgress(items, renamed, previous, 'now')
+    expect(progress).toHaveLength(1)
+    expect(progress[0].sourceDocId).toBe('f18f0d41-aaaa-bbbb')
+    expect(progress[0].targets[0]).toMatchObject({language: 'fr', smartcatDocumentId: '817_12'})
+  })
+})
+
 describe('summarizeCompletion', () => {
   it('flags allDone only when every target is complete AND imported', () => {
     const progress: DocProgress[] = [

package/src/schema/translationProject.ts

@@ -101,6 +101,18 @@ export function createTranslationProjectType(): SchemaTypeDefinition {
               // 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'}),
+              // When true, the export sends the item's *existing* translations to
+              // Smartcat: one bilingual LocJSON per target language (populated from
+              // field/linked-doc translations), grouped via `{name}_{lang}.locjson`.
+              // Absent/false (incl. all legacy items) ⇒ today's behaviour: a single
+              // source-only file targeting all languages. Note: imported bilingual
+              // targets land confirmed at every workflow stage (Smartcat ignores
+              // per-segment status on LocJSON import), i.e. they skip human review.
+              defineField({
+                name: 'sendExistingTranslations',
+                title: 'Send existing translations',
+                type: 'boolean',
+              }),
             ],
             preview: {select: {title: 'docId', subtitle: 'docType'}},
           }),
@@ -210,8 +222,15 @@ export function createTranslationProjectType(): SchemaTypeDefinition {
             type: 'object',
             name: 'smartcatOutboxItem',
             fields: [
+              defineField({name: 'sourceDocId', type: 'string'}),
+              defineField({name: 'title', type: 'string'}),
               defineField({name: 'filename', type: 'string'}),
               defineField({name: 'locjson', type: 'text'}),
+              // Present only for per-language bilingual files (send-existing flow):
+              // the single target language this file carries, so the export Function
+              // uploads it with `documentModel targetLanguages:[lang]`. Absent ⇒
+              // upload targeting all project languages (the source-only default).
+              defineField({name: 'targetLanguage', type: 'string'}),
             ],
           }),
         ],

package/src/smartcat/client.ts

@@ -115,13 +115,27 @@ export class SmartcatClient {
     return this.request('GET', `${API_BASE}/template`)
   }
 
-  /** Uploads one source file into a project. `filename` may include a folder path. */
+  /**
+   * Uploads one source file into a project. `filename` may include a folder path.
+   *
+   * When `targetLanguage` is given (a Smartcat language code), the file is
+   * restricted to that single target language via the `documentModel` settings
+   * part — used by the "send existing translations" flow, which uploads one
+   * bilingual LocJSON per language. Omitted ⇒ the document targets every project
+   * language (today's source-only default).
+   */
   async uploadDocument(
     projectId: string,
     filename: string,
     content: string,
+    targetLanguage?: string,
   ): Promise<SmartcatDocument[]> {
     const form = new FormData()
+    if (targetLanguage) {
+      // `documentModel` is a JSON array (one entry per file); a bare object 400s.
+      const model = [{targetLanguages: [targetLanguage]}]
+      form.append('documentModel', new Blob([JSON.stringify(model)], {type: 'application/json'}), 'documentModel')
+    }
     // Use a generic content type: declaring application/json makes Smartcat try
     // to map the file to an API model instead of importing it as a document.
     form.append('file', new Blob([content], {type: 'application/octet-stream'}), filename)