@smartcat/sanity-plugin 1.0.0 → 1.1.0

package/src/lib/locjson/paths.ts

@@ -0,0 +1,73 @@
+/**
+ * Tiny path grammar for addressing translatable leaves nested inside a field's
+ * value: `.field` for object properties, `[key]` for array members by `_key`,
+ * `[n]` for array members by index. Used to expand array/object member values
+ * into per-leaf LocJSON units and to overlay translations back onto a cloned
+ * source value.
+ *
+ * e.g. `items[b1].value`, `tabs[2]`, `` (empty = the value itself).
+ */
+export type PathSeg = {field: string} | {key: string} | {index: number}
+
+export function parsePath(path: string): PathSeg[] {
+  const segs: PathSeg[] = []
+  const re = /\.?([^.[\]]+)|\[([^\]]+)\]/g
+  let m: RegExpExecArray | null
+  while ((m = re.exec(path)) !== null) {
+    if (m[1] !== undefined) segs.push({field: m[1]})
+    else if (/^\d+$/.test(m[2])) segs.push({index: Number(m[2])})
+    else segs.push({key: m[2]})
+  }
+  return segs
+}
+
+/** Append a segment to a base path string, producing a valid path. */
+export function joinPath(base: string, seg: PathSeg): string {
+  if ('field' in seg) return base ? `${base}.${seg.field}` : seg.field
+  if ('index' in seg) return `${base}[${seg.index}]`
+  return `${base}[${seg.key}]`
+}
+
+function child(container: unknown, seg: PathSeg): unknown {
+  if (container == null || typeof container !== 'object') return undefined
+  if ('field' in seg) return (container as Record<string, unknown>)[seg.field]
+  if ('index' in seg) return Array.isArray(container) ? container[seg.index] : undefined
+  return Array.isArray(container)
+    ? container.find((m) => m && typeof m === 'object' && (m as Record<string, unknown>)._key === seg.key)
+    : undefined
+}
+
+/** Read the value at a path from a root value (undefined if any segment misses). */
+export function getAtPath(root: unknown, path: string): unknown {
+  let cur = root
+  for (const seg of parsePath(path)) {
+    cur = child(cur, seg)
+    if (cur === undefined) return undefined
+  }
+  return cur
+}
+
+/**
+ * Return a deep clone of `root` with the leaf at `path` replaced by `value`.
+ * An empty path replaces the whole value. Missing intermediate segments are a
+ * no-op (the clone is returned unchanged), so a template that lacks a leaf can't
+ * be corrupted.
+ */
+export function setAtPath<T>(root: T, path: string, value: unknown): T {
+  const segs = parsePath(path)
+  if (segs.length === 0) return value as T
+  const clone = structuredClone(root)
+  let cur: unknown = clone
+  for (let i = 0; i < segs.length - 1; i++) {
+    cur = child(cur, segs[i])
+    if (cur == null || typeof cur !== 'object') return clone
+  }
+  const last = segs[segs.length - 1]
+  if ('field' in last) (cur as Record<string, unknown>)[last.field] = value
+  else if ('index' in last && Array.isArray(cur)) cur[last.index] = value
+  else if ('key' in last && Array.isArray(cur)) {
+    const idx = cur.findIndex((m) => m && typeof m === 'object' && (m as Record<string, unknown>)._key === last.key)
+    if (idx >= 0) cur[idx] = value
+  }
+  return clone
+}

package/src/lib/locjson/portableText.ts

@@ -0,0 +1,157 @@
+import {escapeHTML, toHTML} from '@portabletext/to-html'
+import {htmlToBlocks, type DeserializerRule} from '@sanity/block-tools'
+
+/** A Portable Text block (loosely typed — shape varies by schema). */
+export type PortableTextBlock = Record<string, unknown>
+
+/**
+ * Custom (non-`block`) top-level Portable Text types that we *can* round-trip
+ * through HTML, and so must NOT treat as unserializable. Each needs both a
+ * `toHTML` component (below) and an `htmlToBlocks` rule (see {@link tableRule})
+ * so the block survives export → translation → import intact.
+ *
+ * Currently just `@sanity/table`: `{_type:'table', rows:[{_type:'tableRow',
+ * cells: string[]}]}` — plain-string cells, no header row, no col/row spans.
+ */
+const SERIALIZABLE_CUSTOM_TYPES = new Set(['table'])
+
+/** Renders a `@sanity/table` block to an HTML `<table>` for translation. */
+function tableToHtml(value: unknown): string {
+  const rows = Array.isArray((value as {rows?: unknown})?.rows) ? (value as {rows: unknown[]}).rows : []
+  const trs = rows
+    .map((row) => {
+      const cells = Array.isArray((row as {cells?: unknown})?.cells) ? (row as {cells: unknown[]}).cells : []
+      const tds = cells.map((cell) => `<td>${escapeHTML(typeof cell === 'string' ? cell : '')}</td>`).join('')
+      return `<tr>${tds}</tr>`
+    })
+    .join('')
+  return `<table><tbody>${trs}</tbody></table>`
+}
+
+/**
+ * An `htmlToBlocks` rule that turns a translated `<table>` back into a
+ * `@sanity/table` block. Rows get deterministic index-based `_key`s (the whole
+ * field value is replaced on import, so keys need only be unique within the
+ * table); cells are plain strings, matching the schema.
+ */
+const tableRule: DeserializerRule = {
+  deserialize(el, _next, createBlock) {
+    if ((el as Element).tagName?.toLowerCase() !== 'table') return undefined
+    const rows = Array.from((el as Element).querySelectorAll('tr')).map((tr, i) => ({
+      _type: 'tableRow',
+      _key: `row${i}`,
+      cells: Array.from(tr.querySelectorAll('td, th')).map((cell) => cell.textContent ?? ''),
+    }))
+    return createBlock({_type: 'table', rows}) as never
+  },
+}
+
+/** Parses an HTML string into a DOM Document. Provided by the environment. */
+export type ParseHtml = (html: string) => Document
+
+/**
+ * Renders Portable Text to an HTML string for translation.
+ * Whole-field: the entire block array becomes one HTML document fragment.
+ */
+export function portableTextToHtml(blocks: PortableTextBlock[] | undefined | null): string {
+  if (!blocks || blocks.length === 0) return ''
+  return toHTML(blocks as never, {
+    // Fallback only. Serialization skips any field containing an unserializable
+    // block up front (see findUnserializableBlockTypes), so to-html should never
+    // meet an unknown type here. If one slips through, render it as empty rather
+    // than let @portabletext/to-html emit its default placeholder — a hidden
+    // `<div style="display:none">Unknown block type "…"</div>` whose English text
+    // would otherwise be sent to Smartcat and translated into every locale.
+    // (`onMissingComponent: false` only silences the warning; it does NOT stop the
+    // placeholder — the `unknownType` override is what suppresses it.)
+    onMissingComponent: false,
+    components: {
+      unknownType: () => '',
+      // Serializable custom block types get real markup so their text is
+      // translatable and can be parsed back (see SERIALIZABLE_CUSTOM_TYPES).
+      types: {table: ({value}) => tableToHtml(value)},
+    },
+  })
+}
+
+/**
+ * Distinct `_type`s in a Portable Text value that `@portabletext/to-html` cannot
+ * serialize: any top-level member that isn't a standard `block` (and isn't in
+ * {@link SERIALIZABLE_CUSTOM_TYPES}, e.g. `table`, which we render explicitly),
+ * or any inline child that isn't a `span` (e.g. an inline object). Such nodes
+ * render to nothing, so a field containing them can't survive the HTML
+ * round-trip — the caller skips the whole field and warns rather than silently
+ * drop or corrupt it. Marks/annotations are intentionally not included: their
+ * text survives (only the annotation would be lost).
+ */
+export function findUnserializableBlockTypes(
+  blocks: PortableTextBlock[] | undefined | null,
+): string[] {
+  if (!Array.isArray(blocks)) return []
+  const types = new Set<string>()
+  for (const block of blocks) {
+    if (!block || typeof block !== 'object') continue
+    const type = (block as {_type?: unknown})._type
+    if (type !== 'block') {
+      if (typeof type === 'string' && !SERIALIZABLE_CUSTOM_TYPES.has(type)) types.add(type)
+      continue
+    }
+    const children = (block as {children?: unknown}).children
+    if (!Array.isArray(children)) continue
+    for (const child of children) {
+      const childType = (child as {_type?: unknown} | null)?._type
+      if (typeof childType === 'string' && childType !== 'span') types.add(childType)
+    }
+  }
+  return [...types].sort()
+}
+
+/**
+ * Extracts the visible text of Portable Text — the concatenation of every span's
+ * `text` across all blocks (recursing into `children`). Used to decide whether a
+ * field carries anything translatable: structural-but-textless blocks render to
+ * non-empty HTML (`<p></p>`, `<br/>`, `<ul><li></li></ul>`), so emptiness must be
+ * judged from the source blocks, not from stripping tags/entities out of the HTML
+ * (which would mishandle `&nbsp;` and void elements).
+ */
+export function portableTextToPlainText(blocks: PortableTextBlock[] | undefined | null): string {
+  if (!Array.isArray(blocks)) return ''
+  let text = ''
+  const visit = (node: unknown): void => {
+    if (Array.isArray(node)) {
+      node.forEach(visit)
+    } else if (node && typeof node === 'object') {
+      const value = node as {text?: unknown; children?: unknown; rows?: unknown}
+      if (typeof value.text === 'string') text += value.text
+      if (Array.isArray(value.children)) visit(value.children)
+      // `table` blocks carry text in `rows[].cells[]` (plain strings), not spans;
+      // count it so a table-only field isn't judged empty and skipped on export.
+      if (Array.isArray(value.rows)) {
+        for (const row of value.rows) {
+          const cells = (row as {cells?: unknown})?.cells
+          if (Array.isArray(cells)) for (const cell of cells) if (typeof cell === 'string') text += cell
+        }
+      }
+    }
+  }
+  visit(blocks)
+  return text
+}
+
+/**
+ * Parses translated HTML back into Portable Text using the field's compiled
+ * block content type. `parseHtml` supplies a DOM parser:
+ *   - Studio:    (html) => new DOMParser().parseFromString(html, 'text/html')
+ *   - Functions: (html) => new JSDOM(html).window.document
+ */
+export function htmlToPortableText(
+  html: string,
+  blockContentType: unknown,
+  parseHtml: ParseHtml,
+): PortableTextBlock[] {
+  if (!html.trim()) return []
+  return htmlToBlocks(html, blockContentType as never, {
+    parseHtml,
+    rules: [tableRule],
+  }) as unknown as PortableTextBlock[]
+}

package/src/lib/locjson/serialize.ts

@@ -0,0 +1,124 @@
+import {
+  findUnserializableBlockTypes,
+  portableTextToHtml,
+  portableTextToPlainText,
+  type PortableTextBlock,
+} from './portableText'
+import {enumerateLeaves} from './fields'
+import {getAtPath} from './paths'
+import type {LocJSON, LocUnit, TranslatableField} from './types'
+
+export interface SerializeOptions {
+  sourceLanguage: string
+  /**
+   * How internationalized-array members identify their locale: a field name
+   * (e.g. `'language'`) or `'_key'` (v4.x and lower). Resolved by the caller (see
+   * `resolveConfig`); no default is assumed here.
+   */
+  fieldLanguageKey: string
+  /**
+   * Called when a Portable Text field is skipped because it contains block types
+   * that can't be serialized (see {@link findUnserializableBlockTypes}). The
+   * whole field is left out so its content isn't dropped or corrupted on the
+   * round-trip; the caller surfaces this to the user's log.
+   */
+  onSkippedField?: (info: {fieldPath: string; title?: string; types: string[]}) => void
+}
+
+/** A minimal view of a Sanity document needed for serialization. */
+export interface SerializableDocument {
+  _id: string
+  _type: string
+  _rev?: string
+  [key: string]: unknown
+}
+
+/**
+ * Serializes a Sanity document into a LocJSON file: one unit per translatable
+ * field. Plain fields become plain units (segments split on newlines); Portable
+ * Text fields become whole-field HTML units (Smartcat segments them internally).
+ *
+ * Fields with no value are skipped, so the file only contains real source text.
+ */
+export function serializeToLocjson(
+  doc: SerializableDocument,
+  fields: TranslatableField[],
+  options: SerializeOptions,
+): LocJSON {
+  const units: LocUnit[] = []
+
+  for (const field of fields) {
+    // For field-level (internationalized-array) fields the source content is the
+    // source-language member's `value` (the field may be nested through objects).
+    const source =
+      field.localization === 'field'
+        ? memberValue(getAtPath(doc, field.path), options.sourceLanguage, options.fieldLanguageKey)
+        : getAtPath(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 comments = leaf.title ? [leaf.title] : undefined
+
+      if (leaf.kind === 'plain') {
+        // Skip when there's no translatable text. Trim only for the check — the
+        // stored source keeps its original whitespace so the round-trip is exact.
+        if (typeof value !== 'string' || value.trim().length === 0) continue
+        units.push({
+          key: leaf.fullKey,
+          properties: {comments, 'x-smartcat-split': 'full', 'x-sanity': {fieldPath: leaf.fullKey}},
+          // 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: [],
+        })
+      } else {
+        const blocks = value as PortableTextBlock[] | undefined
+        // A field with a block to-html can't serialize (e.g. a custom `table`)
+        // is skipped whole: partial HTML would drop that block on the round-trip.
+        const unserializable = findUnserializableBlockTypes(blocks)
+        if (unserializable.length > 0) {
+          options.onSkippedField?.({fieldPath: field.path, title: field.title, types: unserializable})
+          continue
+        }
+        // `html` is non-empty for structural-but-textless blocks (e.g. `<p></p>`,
+        // `<br/>`), so also require actual visible text before emitting a unit.
+        const html = portableTextToHtml(blocks)
+        if (!html || portableTextToPlainText(blocks).trim().length === 0) continue
+        units.push({
+          key: leaf.fullKey,
+          properties: {comments, 'x-smartcat-format': 'html', 'x-smartcat-split': 'full', 'x-sanity': {fieldPath: leaf.fullKey}},
+          source: [html],
+          target: [],
+        })
+      }
+    }
+  }
+
+  return {
+    properties: {
+      version: 1,
+      'x-sanity': {
+        documentId: doc._id,
+        documentType: doc._type,
+        rev: doc._rev,
+        sourceLanguage: options.sourceLanguage,
+      },
+    },
+    units,
+  }
+}
+
+/**
+ * Reads the `value` of an internationalized-array field's member for a given
+ * language. Members are identified strictly by `languageKey` — a field name
+ * (`'language'`, v5+) or `'_key'` (v4.x and lower).
+ */
+function memberValue(field: unknown, language: string, languageKey: string): unknown {
+  if (!Array.isArray(field)) return undefined
+  const member = field.find(
+    (m) => m && typeof m === 'object' && (m as Record<string, unknown>)[languageKey] === language,
+  )
+  return (member as {value?: unknown} | undefined)?.value
+}

package/src/lib/locjson/types.ts

@@ -0,0 +1,106 @@
+/**
+ * Minimal LocJSON type definitions.
+ *
+ * LocJSON is Smartcat's JSON localization format: a set of `units`, each with a
+ * stable `key`, a `source` (array of string segments) and a `target` that
+ * Smartcat fills in. File- and unit-level `properties` may carry arbitrary
+ * `x-*` metadata that round-trips through translation.
+ */
+
+/** How a unit's content should be treated by Smartcat. "plain" is the default and is omitted. */
+export type SmartcatFormat = 'markdown' | 'html'
+
+/** Our per-document metadata, stored at file level. */
+export interface SanityFileMeta {
+  documentId: string
+  documentType: string
+  /** `_rev` at export time, to detect source drift when translations return. */
+  rev?: string
+  sourceLanguage: string
+}
+
+/** Our per-unit metadata, stored at unit level. */
+export interface SanityUnitMeta {
+  /** Path of the Sanity field this unit represents (also used as the unit key). */
+  fieldPath: string
+}
+
+export interface LocUnitProperties {
+  comments?: string[]
+  'x-smartcat-format'?: SmartcatFormat
+  'x-smartcat-split'?: 'full'
+  'x-sanity'?: SanityUnitMeta
+}
+
+export interface LocUnit {
+  /** Unique, stable id within the file. We use the Sanity field path. */
+  key: string
+  properties?: LocUnitProperties
+  source: string[]
+  target: string[]
+}
+
+export interface LocJSONProperties {
+  version: number
+  'x-sanity'?: SanityFileMeta
+}
+
+export interface LocJSON {
+  properties: LocJSONProperties
+  units: LocUnit[]
+}
+
+/** Kind of translatable field, deciding how it is serialized. */
+export type TranslatableFieldKind = 'plain' | 'portableText'
+
+/**
+ * Where a document's translations live:
+ * - `document`: separate locale documents linked via translation.metadata
+ *   (@sanity/document-internationalization).
+ * - `field`: inline per-language array members on the same document
+ *   (sanity-plugin-internationalized-array).
+ *
+ * This is a per-type property derived from the schema; it never travels in
+ * LocJSON. On a `field` field the source value is the source-language array
+ * member's `value` rather than the field itself.
+ */
+export type LocalizationMode = 'document' | 'field'
+
+/**
+ * A translatable leaf inside an array/object member value, addressed relative to
+ * that value (see `paths.ts`). `subPath` is empty for a scalar member value.
+ */
+export interface TranslatableLeaf {
+  subPath: string
+  kind: TranslatableFieldKind
+  title?: string
+}
+
+/**
+ * How a field-mode member value is shaped:
+ * - `scalar` — the value is itself the translatable leaf (string/text/Portable Text).
+ * - `arrayOfScalar` — an array of strings; one leaf per index.
+ * - `arrayOfObject` — an array of objects; the listed `leaves` per item (by `_key`).
+ * - `object` — a single object; the listed `leaves`.
+ */
+export type ValueShape =
+  | {container: 'scalar'; kind: TranslatableFieldKind}
+  | {container: 'arrayOfScalar'; kind: TranslatableFieldKind}
+  | {container: 'arrayOfObject'; leaves: TranslatableLeaf[]}
+  | {container: 'object'; leaves: TranslatableLeaf[]}
+
+/** A translatable field selected from a document/schema. */
+export interface TranslatableField {
+  /** Path to the field (dotted; nested through plain objects). Also the base unit key. */
+  path: string
+  kind: TranslatableFieldKind
+  /** How serialize extracts the source value (direct field vs. source-language array member). */
+  localization: LocalizationMode
+  /** Optional human title, surfaced to translators as a unit comment. */
+  title?: string
+  /**
+   * Shape of the (source-language member's) value. Absent means `scalar` — the
+   * historical behavior. Present when the value nests translatable leaves.
+   */
+  value?: ValueShape
+}

package/src/lib/log.ts

@@ -0,0 +1,33 @@
+/**
+ * Live, in-memory log lines for the export/import flows, streamed to the
+ * ProjectView Log panel as each document and field is processed. Never persisted
+ * — purely a session-scoped trace for troubleshooting (e.g. on client calls).
+ */
+export type LogLevel = 'info' | 'success' | 'skip' | 'error' | 'update'
+
+export interface LogLine {
+  level: LogLevel
+  message: string
+  /** Field-level lines are indented under their document header. */
+  indent?: boolean
+  /** Optional value (source or translated text); revealed on click in the panel. */
+  value?: string
+  /** Prior value; when set, the panel shows `before` and `value` side by side. */
+  before?: string
+  /** Extra detail (e.g. a JSON parse error); shown in its own box on expand. */
+  error?: string
+}
+
+/** Sink for log lines; processing accepts one to stream progress to the UI. */
+export type LogFn = (line: LogLine) => void
+
+/** Parse a Function's JSON-encoded `functionLog` field into log lines (lenient). */
+export function parseFunctionLog(raw: string | null | undefined): LogLine[] {
+  if (!raw) return []
+  try {
+    const parsed = JSON.parse(raw)
+    return Array.isArray(parsed) ? (parsed as LogLine[]) : []
+  } catch {
+    return []
+  }
+}

package/src/lib/projectItems.ts

@@ -0,0 +1,31 @@
+/**
+ * GROQ fragments for reading a translation project's `items`.
+ *
+ * An item is either the current `smartcat.projectItem` shape (`{docId, docType}`)
+ * or a legacy weak reference (`{_ref}`) from before the migration. These
+ * fragments normalize across both so the old/new tolerance lives in one place —
+ * interpolate them into item queries rather than re-writing `coalesce(...)`.
+ */
+
+/** Normalized item id, evaluated in the item's own scope (inside `items[...]`). */
+export const ITEM_ID = 'coalesce(docId, _ref)'
+
+/** Normalized item id, evaluated from a subquery nested under an item (via `^`). */
+export const ITEM_ID_FROM_SUBQUERY = 'coalesce(^.docId, ^._ref)'
+
+/** Dereference an item's document, with an optional projection e.g. `{_id, _type}`. */
+export const itemDocDeref = (projection = ''): string => `*[_id == ${ITEM_ID_FROM_SUBQUERY}][0]${projection}`
+
+/**
+ * Dereference an item's document, honoring where it was added from: items added
+ * in the **published** perspective (`sourceIsPublished == true`) resolve the
+ * published document only; every other item (including legacy items with no
+ * flag) prefers the **draft**, falling back to published. This makes the export
+ * translate the content the editor was actually viewing, and gives pre-existing
+ * projects the draft-preferring default for free.
+ */
+export const itemDocDerefRespectingDraft = (projection = ''): string =>
+  `select(` +
+  `sourceIsPublished == true => *[_id == ${ITEM_ID_FROM_SUBQUERY}][0]${projection}, ` +
+  `coalesce(*[_id == "drafts." + ${ITEM_ID_FROM_SUBQUERY}][0]${projection}, *[_id == ${ITEM_ID_FROM_SUBQUERY}][0]${projection})` +
+  `)`

package/src/lib/resolveConfig.test.ts

@@ -0,0 +1,62 @@
+import {describe, expect, it} from 'vitest'
+import {resolveConfig} from './resolveConfig'
+import {SETTINGS_TYPE, TRANSLATION_PROJECT_TYPE} from './constants'
+
+describe('resolveConfig', () => {
+  it('applies defaults for omitted optional fields', () => {
+    const resolved = resolveConfig({sourceLanguage: 'en'})
+    expect(resolved).toMatchObject({
+      rootTypes: [],
+      sourceLanguage: 'en',
+      languages: [],
+      documentI18nLanguageField: 'language',
+      fieldI18nLanguageField: 'language',
+    })
+  })
+
+  it('treats every non-plugin type as translatable when translatableTypes is omitted', () => {
+    const {isTranslatableType} = resolveConfig({sourceLanguage: 'en'})
+    expect(isTranslatableType('page')).toBe(true)
+    expect(isTranslatableType('anythingElse')).toBe(true)
+    expect(isTranslatableType(TRANSLATION_PROJECT_TYPE)).toBe(false)
+    expect(isTranslatableType(SETTINGS_TYPE)).toBe(false)
+  })
+
+  it('restricts translatable types to the configured list', () => {
+    const {isTranslatableType} = resolveConfig({sourceLanguage: 'en', translatableTypes: ['page']})
+    expect(isTranslatableType('page')).toBe(true)
+    expect(isTranslatableType('article')).toBe(false)
+  })
+
+  it('inherits explicitly-configured translatableTypes as rootTypes', () => {
+    const resolved = resolveConfig({sourceLanguage: 'en', translatableTypes: ['page', 'article']})
+    expect(resolved.rootTypes).toEqual(['page', 'article'])
+  })
+
+  it('leaves rootTypes empty when translatableTypes is also omitted (no crawl boundary)', () => {
+    expect(resolveConfig({sourceLanguage: 'en'}).rootTypes).toEqual([])
+  })
+
+  it('honors an explicit rootTypes override independent of translatableTypes', () => {
+    const resolved = resolveConfig({
+      sourceLanguage: 'en',
+      translatableTypes: ['page', 'article'],
+      rootTypes: ['page'],
+    })
+    expect(resolved.rootTypes).toEqual(['page'])
+  })
+
+  it('honors explicit overrides (e.g. internationalized-array v4 `_key`)', () => {
+    const resolved = resolveConfig({
+      sourceLanguage: 'en',
+      documentI18nPluginLanguageField: 'lang',
+      fieldI18nPluginLanguageField: '_key',
+    })
+    expect(resolved.documentI18nLanguageField).toBe('lang')
+    expect(resolved.fieldI18nLanguageField).toBe('_key')
+  })
+
+  it('throws when sourceLanguage is missing', () => {
+    expect(() => resolveConfig({sourceLanguage: ''})).toThrow(/sourceLanguage/)
+  })
+})

package/src/lib/resolveConfig.ts

@@ -0,0 +1,54 @@
+import {requireSourceLanguage, SETTINGS_TYPE, TRANSLATION_PROJECT_TYPE} from './constants'
+import type {SmartcatLanguage, SmartcatPluginConfig} from '../types'
+
+/** The plugin's own document types, never translatable regardless of config. */
+const PLUGIN_TYPES = new Set([TRANSLATION_PROJECT_TYPE, SETTINGS_TYPE])
+
+/**
+ * Plugin config with every optional field resolved to its default. This is the
+ * single place plugin defaults are applied — notably the internationalized-array
+ * locale key, whose default (`'language'`, plugin v5+) is the one version
+ * assumption; downstream code receives a concrete value and never re-guesses.
+ */
+export interface ResolvedSmartcatConfig {
+  /**
+   * Whether a document type shows the "Add to translation project" UI. When
+   * `translatableTypes` is omitted this is true for every type except the
+   * plugin's own `smartcat.*` types; otherwise it's list membership.
+   */
+  isTranslatableType: (type: string) => boolean
+  /**
+   * The explicitly-configured translatable types, verbatim, for display/logging.
+   * `undefined` means none was configured — every non-plugin type is translatable
+   * (see {@link isTranslatableType}). Logic should use the predicate, not this.
+   */
+  translatableTypes?: string[]
+  /** Root/standalone types where the linked-documents crawl stops. */
+  rootTypes: string[]
+  sourceLanguage: string
+  languages: SmartcatLanguage[]
+  /** document-internationalization locale field (its `languageField`). */
+  documentI18nLanguageField: string
+  /** internationalized-array member locale key (`'language'` v5+, `'_key'` v4.x). */
+  fieldI18nLanguageField: string
+}
+
+export function resolveConfig(config: SmartcatPluginConfig): ResolvedSmartcatConfig {
+  const translatableTypes = config.translatableTypes
+  const isTranslatableType = translatableTypes
+    ? (type: string) => translatableTypes.includes(type)
+    : (type: string) => !PLUGIN_TYPES.has(type)
+
+  return {
+    isTranslatableType,
+    translatableTypes,
+    // `rootTypes` inherits the *explicitly-configured* translatableTypes (not the
+    // resolved "everything") so an unconfigured Studio gets no crawl boundary
+    // rather than every type being a root (which would stop the crawl at once).
+    rootTypes: config.rootTypes ?? translatableTypes ?? [],
+    sourceLanguage: requireSourceLanguage(config.sourceLanguage),
+    languages: config.languages ?? [],
+    documentI18nLanguageField: config.documentI18nPluginLanguageField ?? 'language',
+    fieldI18nLanguageField: config.fieldI18nPluginLanguageField ?? 'language',
+  }
+}

package/src/lib/workflow.test.ts

@@ -0,0 +1,37 @@
+import {describe, it, expect} from 'vitest'
+import {
+  isWorkflowValid,
+  resolveWorkflowCreateParams,
+  STANDARD_AI,
+  STANDARD_AI_HUMAN,
+} from './workflow'
+
+describe('isWorkflowValid', () => {
+  it('accepts the standard presets regardless of templates', () => {
+    expect(isWorkflowValid(STANDARD_AI_HUMAN, [])).toBe(true)
+    expect(isWorkflowValid(STANDARD_AI, [])).toBe(true)
+  })
+
+  it('accepts a template only while its id is still cached', () => {
+    expect(isWorkflowValid('template:abc', ['abc', 'def'])).toBe(true)
+    expect(isWorkflowValid('template:gone', ['abc', 'def'])).toBe(false)
+  })
+
+  it('rejects empty / unknown values (no selection)', () => {
+    expect(isWorkflowValid('', ['abc'])).toBe(false)
+    expect(isWorkflowValid('whatever', ['abc'])).toBe(false)
+  })
+})
+
+describe('resolveWorkflowCreateParams', () => {
+  it('maps the standard presets to workflow stages', () => {
+    expect(resolveWorkflowCreateParams(STANDARD_AI_HUMAN)).toEqual({
+      workflowStages: ['translation', 'postediting'],
+    })
+    expect(resolveWorkflowCreateParams(STANDARD_AI)).toEqual({workflowStages: ['translation']})
+  })
+
+  it('maps a template selection to a template id', () => {
+    expect(resolveWorkflowCreateParams('template:abc')).toEqual({templateId: 'abc'})
+  })
+})