@smartcat/sanity-plugin 1.0.0 → 1.0.1

package/src/lib/languageMap.ts

@@ -0,0 +1,71 @@
+/**
+ * Sanity ↔ Smartcat language-code mapping.
+ *
+ * Sanity locale tags (`id`) don't always match the codes Smartcat understands
+ * (e.g. Sanity "PL-PL" vs Smartcat "pl"). The browser resolves the mapping from
+ * plugin config and stamps the relevant pairs onto the project; the thin
+ * Functions read them back. This module is dependency-free so it bundles into
+ * both the Studio and the Functions.
+ *
+ * The invariant: everything stored in Sanity uses the Sanity `id`; only the
+ * Smartcat HTTP calls use `smartcatLanguage`. So callers map forward (id → code)
+ * when talking to Smartcat and invert (code → id) when storing what comes back.
+ */
+
+export interface SmartcatLanguageMapping {
+  sanityId: string
+  smartcatLanguage: string
+}
+
+/** Minimal language shape needed to build mappings (a subset of SmartcatLanguage). */
+interface MappableLanguage {
+  id: string
+  smartcatLanguage?: string
+}
+
+/**
+ * Builds the mapping pairs for the given Sanity ids, resolving each to its
+ * configured `smartcatLanguage` (falling back to the id when not configured).
+ */
+export function buildLanguageMappings(
+  languages: MappableLanguage[],
+  ids: string[],
+): SmartcatLanguageMapping[] {
+  const byId = new Map(languages.map((l) => [l.id, l.smartcatLanguage || l.id]))
+  return ids.map((id) => ({sanityId: id, smartcatLanguage: byId.get(id) || id}))
+}
+
+/** Sanity id → Smartcat code. Identity when no mapping is found. */
+export function toSmartcatLanguage(
+  mappings: SmartcatLanguageMapping[] | undefined,
+  sanityId: string,
+): string {
+  return mappings?.find((m) => m.sanityId === sanityId)?.smartcatLanguage ?? sanityId
+}
+
+/** Smartcat code → Sanity id. Identity when no mapping is found. */
+export function toSanityLanguage(
+  mappings: SmartcatLanguageMapping[] | undefined,
+  smartcatLanguage: string,
+): string {
+  return mappings?.find((m) => m.smartcatLanguage === smartcatLanguage)?.sanityId ?? smartcatLanguage
+}
+
+/**
+ * Finds Smartcat codes that more than one Sanity id maps to. A non-empty result
+ * means the inverse (code → id) is ambiguous, so translations can't be routed
+ * back — callers should reject such a configuration.
+ */
+export function findDuplicateSmartcatLanguages(
+  mappings: SmartcatLanguageMapping[],
+): {smartcatLanguage: string; sanityIds: string[]}[] {
+  const byCode = new Map<string, string[]>()
+  for (const m of mappings) {
+    const ids = byCode.get(m.smartcatLanguage) ?? []
+    ids.push(m.sanityId)
+    byCode.set(m.smartcatLanguage, ids)
+  }
+  return [...byCode.entries()]
+    .filter(([, ids]) => ids.length > 1)
+    .map(([smartcatLanguage, sanityIds]) => ({smartcatLanguage, sanityIds}))
+}

package/src/lib/linkedDocuments.test.ts

@@ -0,0 +1,56 @@
+import {describe, expect, it} from 'vitest'
+import {collectRefs, gatherLinkedDocuments, type GatherClient} from './linkedDocuments'
+
+const ref = (id: string) => ({_type: 'reference', _ref: id})
+
+describe('collectRefs', () => {
+  it('finds refs nested in objects, arrays, and portable text; strips drafts prefix', () => {
+    const doc = {
+      _id: 'x',
+      hero: ref('a'),
+      content: [{blocks: [ref('b'), {asset: ref('drafts.c')}]}],
+      plain: 'no ref',
+    }
+    expect([...collectRefs(doc)].sort()).toEqual(['a', 'b', 'c'])
+  })
+})
+
+describe('gatherLinkedDocuments', () => {
+  // page1 → card1 (fragment), page2 (peer root), img1 (asset)
+  // card1 → page1 (cycle), button1 (fragment)
+  // page2 → card2  (behind a root — must NOT be reached)
+  const dataset: Record<string, Record<string, unknown>> = {
+    page1: {_id: 'page1', _type: 'page', a: ref('card1'), b: ref('page2'), c: ref('img1')},
+    card1: {_id: 'card1', _type: 'card', a: ref('page1'), b: ref('button1')},
+    button1: {_id: 'button1', _type: 'button'},
+    page2: {_id: 'page2', _type: 'page', a: ref('card2')},
+    card2: {_id: 'card2', _type: 'card'},
+    img1: {_id: 'img1', _type: 'sanity.imageAsset'},
+  }
+
+  const client: GatherClient = {
+    async fetch<T>(query: string, params: Record<string, unknown>): Promise<T> {
+      const ids = params.ids as string[]
+      const docs = ids.map((id) => dataset[id]).filter(Boolean)
+      const typeOnly = query.includes('_type}')
+      return (typeOnly ? docs.map((d) => ({_id: d._id, _type: d._type})) : docs) as T
+    },
+  }
+
+  const isRoot = (t: string) => t === 'page'
+  const isTranslatable = (t: string) => ['page', 'card', 'button'].includes(t)
+
+  it('gathers translatable fragments, stops at peer roots and assets, is cycle-safe', async () => {
+    const linked = await gatherLinkedDocuments({client, rootId: 'page1', isRoot, isTranslatable})
+    expect(linked.map((l) => l.docId).sort()).toEqual(['button1', 'card1'])
+    // page2 (peer root) skipped → card2 unreachable; img1 (asset) excluded.
+    expect(linked.find((l) => l.docId === 'card2')).toBeUndefined()
+    expect(linked.find((l) => l.docId === 'page2')).toBeUndefined()
+  })
+
+  it('carries the resolved docType for each linked document', async () => {
+    const linked = await gatherLinkedDocuments({client, rootId: 'page1', isRoot, isTranslatable})
+    expect(linked.find((l) => l.docId === 'card1')?.docType).toBe('card')
+    expect(linked.find((l) => l.docId === 'button1')?.docType).toBe('button')
+  })
+})

package/src/lib/linkedDocuments.ts

@@ -0,0 +1,100 @@
+/** Minimal client surface the gather needs. */
+export interface GatherClient {
+  fetch<T>(query: string, params: Record<string, unknown>): Promise<T>
+}
+
+export interface LinkedDocument {
+  docId: string
+  docType: string
+}
+
+export interface GatherOptions {
+  client: GatherClient
+  /** Published id of the document to start from. */
+  rootId: string
+  /** Root/standalone types — traversal stops here (peer content, not pulled in). */
+  isRoot: (type: string) => boolean
+  /** Types with localizable content — added to the project and recursed into. */
+  isTranslatable: (type: string) => boolean
+  /** Documents fetched per round. */
+  batchSize?: number
+}
+
+const bareId = (id: string) => id.replace(/^drafts\./, '')
+
+/** Every `_ref` string anywhere in a document's JSON, as bare (published) ids. */
+export function collectRefs(node: unknown, out: Set<string> = new Set()): Set<string> {
+  if (!node || typeof node !== 'object') return out
+  if (Array.isArray(node)) {
+    for (const item of node) collectRefs(item, out)
+    return out
+  }
+  const obj = node as Record<string, unknown>
+  if (typeof obj._ref === 'string') out.add(bareId(obj._ref))
+  for (const [key, value] of Object.entries(obj)) {
+    if (key === '_ref') continue
+    collectRefs(value, out)
+  }
+  return out
+}
+
+// Prefer the draft copy (freshest refs) when both draft and published exist.
+function pickPreferDraft<T extends {_id: string}>(docs: T[] | null): Map<string, T> {
+  const chosen = new Map<string, T>()
+  for (const doc of docs ?? []) {
+    const bare = bareId(doc._id)
+    if (!chosen.has(bare) || doc._id.startsWith('drafts.')) chosen.set(bare, doc)
+  }
+  return chosen
+}
+
+/**
+ * Breadth-first gather of documents linked (transitively) from `rootId`.
+ *
+ * Follows references only through translatable, non-root documents; stops at
+ * root types (peer pages, translated on their own) and at non-localizable leaves
+ * (assets, config). Cycle-safe. Returns the linked documents to add — excluding
+ * the root itself.
+ */
+export async function gatherLinkedDocuments({
+  client,
+  rootId,
+  isRoot,
+  isTranslatable,
+  batchSize = 50,
+}: GatherOptions): Promise<LinkedDocument[]> {
+  const start = bareId(rootId)
+  const seen = new Set<string>([start])
+  const result: LinkedDocument[] = []
+  let frontier: string[] = [start]
+
+  while (frontier.length) {
+    const batch = frontier.splice(0, batchSize)
+    // Full bodies of the docs we're expanding — needed to read their outgoing refs.
+    const bodies = await client.fetch<Array<Record<string, unknown> & {_id: string}>>(
+      `*[_id in $ids]`,
+      {ids: batch.flatMap((id) => [id, `drafts.${id}`])},
+    )
+    const candidates = new Set<string>()
+    for (const doc of pickPreferDraft(bodies).values()) {
+      for (const ref of collectRefs(doc)) candidates.add(ref)
+    }
+    const fresh = [...candidates].filter((id) => !seen.has(id))
+    if (!fresh.length) continue
+    fresh.forEach((id) => seen.add(id))
+
+    // Classify fresh candidates by type (light query — avoids pulling full
+    // bodies of peer pages and assets we won't recurse into).
+    const typed = await client.fetch<Array<{_id: string; _type: string}>>(
+      `*[_id in $ids]{_id, _type}`,
+      {ids: fresh.flatMap((id) => [id, `drafts.${id}`])},
+    )
+    for (const [id, doc] of pickPreferDraft(typed)) {
+      const type = doc._type
+      if (!type || isRoot(type) || !isTranslatable(type)) continue
+      result.push({docId: id, docType: type})
+      frontier.push(id)
+    }
+  }
+  return result
+}

package/src/lib/locjson/deserialize.ts

@@ -0,0 +1,60 @@
+import {htmlToPortableText, type ParseHtml} from './portableText'
+import type {LocJSON} from './types'
+
+export interface DeserializeOptions {
+  /** DOM parser for HTML units (DOMParser in Studio, jsdom in Functions). */
+  parseHtml: ParseHtml
+  /** Returns the compiled block content type for a Portable Text field path. */
+  getBlockContentType: (fieldPath: string) => unknown
+}
+
+export interface DeserializedDocument {
+  documentId?: string
+  documentType?: string
+  sourceLanguage?: string
+  /** Translated field values, keyed by field path. */
+  fields: Record<string, unknown>
+  /**
+   * Source (pre-translation) text per field path, as the raw joined string. Used
+   * to decide whether a field is JSON (so its translation can be validated before
+   * import). Always the string form, even for HTML units.
+   */
+  sources: Record<string, string>
+}
+
+/**
+ * Parses a (translated) LocJSON file back into Sanity field values.
+ *
+ * Uses each unit's `target` (falling back to `source` when a unit hasn't been
+ * translated yet, so the result is always coherent). HTML units are converted
+ * back to Portable Text via the field's compiled block content type.
+ */
+export function deserializeFromLocjson(locjson: LocJSON, options: DeserializeOptions): DeserializedDocument {
+  const fileMeta = locjson.properties?.['x-sanity']
+  const fields: Record<string, unknown> = {}
+  const sources: Record<string, string> = {}
+
+  for (const unit of locjson.units ?? []) {
+    const fieldPath = unit.properties?.['x-sanity']?.fieldPath ?? unit.key
+    const text = (unit.target?.length ? unit.target : unit.source) ?? []
+
+    // LocJSON splits a string into arbitrary chunks with no implied delimiter,
+    // so the original is always reconstructed by concatenating the segments.
+    const value = text.join('')
+    sources[fieldPath] = (unit.source ?? []).join('')
+
+    if (unit.properties?.['x-smartcat-format'] === 'html') {
+      fields[fieldPath] = htmlToPortableText(value, options.getBlockContentType(fieldPath), options.parseHtml)
+    } else {
+      fields[fieldPath] = value
+    }
+  }
+
+  return {
+    documentId: fileMeta?.documentId,
+    documentType: fileMeta?.documentType,
+    sourceLanguage: fileMeta?.sourceLanguage,
+    fields,
+    sources,
+  }
+}

package/src/lib/locjson/fields.ts

@@ -0,0 +1,355 @@
+import type {LocalizationMode, TranslatableField, TranslatableLeaf, ValueShape} from './types'
+
+export interface GetTranslatableFieldsOptions {
+  /**
+   * Field names to exclude (e.g. the i18n language field, passed by the caller
+   * as the configured `documentI18nPluginLanguageField`). Defaults to none.
+   */
+  exclude?: string[]
+}
+
+interface CompiledType {
+  jsonType?: string
+  name?: string
+  title?: string
+  of?: CompiledType[]
+  fields?: CompiledField[]
+  options?: {
+    documentInternationalization?: {exclude?: boolean}
+    smartcatTranslation?: {include?: boolean}
+  }
+}
+
+/**
+ * True when a field is marked non-translatable via document-internationalization's
+ * own field option (`options.documentInternationalization.exclude`). Honoring it
+ * means consumers exclude fields per type using the i18n plugin's native marker —
+ * no separate config here.
+ */
+function isExcludedByDocumentI18n(field: CompiledField): boolean {
+  return field.type?.options?.documentInternationalization?.exclude === true
+}
+
+interface CompiledField {
+  name: string
+  type?: CompiledType
+}
+
+/**
+ * True for a Sanity **system** type — the reserved `sanity.` namespace, notably
+ * the `sanity.imageAsset` / `sanity.fileAsset` documents that image/file fields
+ * reference. Their string fields (`originalFilename`, `path`, `url`, …) look
+ * translatable but must never be sent: assets are shared across locales, and
+ * translating a filename or CDN path corrupts the reference. Excluding them here
+ * keeps them out of both the linked-document crawl and export serialization,
+ * since both decide translatability via {@link getTranslatableFields}.
+ */
+export function isSystemType(typeName: unknown): boolean {
+  return typeof typeName === 'string' && typeName.startsWith('sanity.')
+}
+
+/**
+ * True for a `sanity-plugin-internationalized-array` array type (e.g.
+ * `internationalizedArrayString`). Detected structurally by naming convention so
+ * we never need a dependency on that plugin.
+ */
+export function isInternationalizedArrayType(type?: CompiledType): boolean {
+  return (
+    type?.jsonType === 'array' &&
+    typeof type.name === 'string' &&
+    type.name.startsWith('internationalizedArray')
+  )
+}
+
+/** True for an array member `_type` like `internationalizedArrayStringValue`. */
+export function isInternationalizedArrayMemberType(typeName: unknown): boolean {
+  return typeof typeName === 'string' && /^internationalizedArray.+Value$/.test(typeName)
+}
+
+/** The inner value type of an internationalized-array field (its member's `value` field). */
+export function innerValueType(arrayType?: CompiledType): CompiledType | undefined {
+  return arrayType?.of?.[0]?.fields?.find((f) => f.name === 'value')?.type
+}
+
+/**
+ * Localization mode of a **compiled** schema type: `field` if it declares any
+ * internationalized-array field (in which case only those fields are
+ * translatable), otherwise `document`. A pure function of the type, so callers
+ * should compute it once per type.
+ */
+export function localizationMode(compiledType: unknown): LocalizationMode {
+  const fields = (compiledType as CompiledType)?.fields
+  if (!Array.isArray(fields)) return 'document'
+  return fields.some((f) => isInternationalizedArrayType(f.type)) ? 'field' : 'document'
+}
+
+/**
+ * Selects translatable fields from a **compiled** Sanity schema type.
+ *
+ * Document-mode types (default policy, installation-agnostic):
+ * - `string` and `text` fields  -> plain units
+ * - Portable Text (arrays containing `block` members) -> HTML units
+ * - everything else (slug, url, datetime, number, boolean, reference, image,
+ *   non-block arrays, objects, system `_` fields, excluded names) is excluded.
+ *
+ * Field-mode types (any internationalized-array field present): only the
+ * internationalized-array fields are translatable; each is classified by its
+ * inner `value` type (string/text -> plain, Portable Text -> HTML).
+ *
+ * The compiled schema shape isn't strongly typed publicly, so this reads it
+ * defensively. Callers that need overrides can post-filter the result.
+ */
+export function getTranslatableFields(
+  compiledType: unknown,
+  options: GetTranslatableFieldsOptions = {},
+): TranslatableField[] {
+  const rootType = compiledType as CompiledType
+  if (isSystemType(rootType?.name)) return []
+  if (!Array.isArray(rootType?.fields)) return []
+  const result: TranslatableField[] = []
+  walkFields(rootType, '', localizationMode(rootType), new Set(options.exclude ?? []), result)
+  return result
+}
+
+/**
+ * Recursively selects translatable fields. In field-mode it descends through
+ * plain object fields (so nested internationalized-array fields, e.g.
+ * `benefits.items`, are reached) and classifies each i18n field's member value
+ * shape. Document-mode keeps the flat top-level behavior.
+ */
+function walkFields(
+  compiledType: CompiledType | undefined,
+  prefix: string,
+  mode: LocalizationMode,
+  exclude: Set<string>,
+  out: TranslatableField[],
+): void {
+  for (const field of compiledType?.fields ?? []) {
+    // `exclude` (the i18n language field) only ever appears at the top level.
+    if (!field?.name || field.name.startsWith('_') || (prefix === '' && exclude.has(field.name))) continue
+    const forceInclude = field.type?.options?.smartcatTranslation?.include === true
+    if (isExcludedByDocumentI18n(field) && !forceInclude) continue
+    const path = prefix ? `${prefix}.${field.name}` : field.name
+    const title = field.type?.title || titleCase(field.name)
+
+    if (mode === 'field') {
+      if (isInternationalizedArrayType(field.type)) {
+        const inner = innerValueType(field.type)
+        const shape = classifyValueShape(inner) ?? (forceInclude ? classifyValueShapeByJsonType(inner) : null)
+        if (shape) out.push({path, localization: 'field', kind: shape.container === 'scalar' ? shape.kind : 'plain', title, value: shape})
+        else if (forceInclude) warnUntranslatableInclude(field.name, inner)
+      } else if (isPlainObject(field.type)) {
+        walkFields(field.type, path, mode, exclude, out)
+      }
+    } else {
+      const kind = classifyField(field.type) ?? (forceInclude ? classifyByJsonType(field.type) : null)
+      if (kind) out.push({path, localization: 'document', kind, title, value: {container: 'scalar', kind}})
+      else if (forceInclude) warnUntranslatableInclude(field.name, field.type)
+    }
+  }
+}
+
+/** One translatable leaf of a field, expanded against a concrete source value. */
+export interface FieldLeaf {
+  /** Unique unit key / x-sanity fieldPath. */
+  fullKey: string
+  /** Path within the member value to the leaf (empty = the value itself). */
+  valuePath: string
+  kind: TranslatableField['kind']
+  title?: string
+}
+
+/**
+ * Expand a field into its translatable leaves against a concrete source value
+ * (the source-language member value for field-mode). Serialize and import both
+ * call this with the SAME source value, so the unit keys they compute match.
+ */
+export function enumerateLeaves(field: TranslatableField, sourceValue: unknown): FieldLeaf[] {
+  const base = field.path
+  const shape: ValueShape = field.value ?? {container: 'scalar', kind: field.kind}
+  if (shape.container === 'scalar') {
+    return [{fullKey: base, valuePath: '', kind: shape.kind, title: field.title}]
+  }
+  if (shape.container === 'arrayOfScalar') {
+    const arr = Array.isArray(sourceValue) ? sourceValue : []
+    return arr.map((_, i) => ({fullKey: `${base}[${i}]`, valuePath: `[${i}]`, kind: shape.kind, title: field.title}))
+  }
+  if (shape.container === 'object') {
+    return shape.leaves.map((l) => ({fullKey: `${base}.${l.subPath}`, valuePath: l.subPath, kind: l.kind, title: l.title ?? field.title}))
+  }
+  const arr = Array.isArray(sourceValue) ? sourceValue : []
+  const out: FieldLeaf[] = []
+  for (const item of arr) {
+    const key = (item as Record<string, unknown>)?._key
+    if (typeof key !== 'string') continue
+    for (const l of shape.leaves) {
+      const valuePath = l.subPath ? `[${key}].${l.subPath}` : `[${key}]`
+      out.push({fullKey: `${base}${valuePath}`, valuePath, kind: l.kind, title: l.title ?? field.title})
+    }
+  }
+  return out
+}
+
+/** A recursable plain object (not a reference/image/file/slug/geopoint). */
+function isPlainObject(type?: CompiledType): boolean {
+  if (type?.jsonType !== 'object' || !Array.isArray(type.fields)) return false
+  if (type.fields.some((f) => f.name === '_ref')) return false
+  return !['reference', 'image', 'file', 'slug', 'geopoint'].includes(type.name ?? '')
+}
+
+/** Classify an internationalized-array member's `value` type into a ValueShape. */
+function classifyValueShape(inner?: CompiledType): ValueShape | null {
+  if (!inner) return null
+  const scalar = classifyField(inner)
+  if (scalar) return {container: 'scalar', kind: scalar}
+  if (inner.jsonType === 'array' && Array.isArray(inner.of)) {
+    const member = inner.of[0]
+    if (member?.jsonType === 'string' && (member.name === 'string' || member.name === 'text')) {
+      return {container: 'arrayOfScalar', kind: 'plain'}
+    }
+    if (isPlainObject(member)) {
+      const leaves = collectLeaves(member, '')
+      if (leaves.length) return {container: 'arrayOfObject', leaves}
+    }
+    return null
+  }
+  if (isPlainObject(inner)) {
+    const leaves = collectLeaves(inner, '')
+    if (leaves.length) return {container: 'object', leaves}
+  }
+  return null
+}
+
+/** ValueShape by jsonType only (for `smartcatTranslation.include` overrides). */
+function classifyValueShapeByJsonType(inner?: CompiledType): ValueShape | null {
+  const kind = classifyByJsonType(inner)
+  return kind ? {container: 'scalar', kind} : null
+}
+
+/** Translatable string/text/Portable-Text leaves within an object (recursing plain objects). */
+function collectLeaves(objType: CompiledType | undefined, prefix: string): TranslatableLeaf[] {
+  const leaves: TranslatableLeaf[] = []
+  for (const f of objType?.fields ?? []) {
+    if (!f?.name || f.name.startsWith('_')) continue
+    if (isExcludedByDocumentI18n(f) && f.type?.options?.smartcatTranslation?.include !== true) continue
+    const subPath = prefix ? `${prefix}.${f.name}` : f.name
+    const kind = classifyField(f.type)
+    if (kind) leaves.push({subPath, kind, title: f.type?.title || titleCase(f.name)})
+    else if (isPlainObject(f.type)) leaves.push(...collectLeaves(f.type, subPath))
+  }
+  return leaves
+}
+
+/** True for an array whose members include a Portable Text `block` type. */
+function isPortableTextArray(type: CompiledType): boolean {
+  return (
+    type.jsonType === 'array' &&
+    Array.isArray(type.of) &&
+    type.of.some((member) => member?.name === 'block' || member?.jsonType === 'block')
+  )
+}
+
+function classifyField(type?: CompiledType): TranslatableField['kind'] | null {
+  if (!type) return null
+
+  // Plain text: only the `string` and `text` base types (not url, slug, datetime…).
+  if (type.jsonType === 'string' && (type.name === 'string' || type.name === 'text')) {
+    return 'plain'
+  }
+
+  if (isPortableTextArray(type)) return 'portableText'
+
+  return null
+}
+
+/**
+ * Classify by base `jsonType` only, ignoring the type name. Used for fields
+ * explicitly opted in with `smartcatTranslation.include`, where the name isn't in
+ * the default allowlist (e.g. a custom string alias) but the underlying shape is
+ * still translatable.
+ */
+function classifyByJsonType(type?: CompiledType): TranslatableField['kind'] | null {
+  if (!type) return null
+  if (type.jsonType === 'string') return 'plain'
+  if (isPortableTextArray(type)) return 'portableText'
+  return null
+}
+
+function warnUntranslatableInclude(fieldName: string, type?: CompiledType): void {
+  // eslint-disable-next-line no-console
+  console.warn(
+    `[smartcat-translation] Field "${fieldName}" is marked smartcatTranslation.include ` +
+      `but its type (name: ${JSON.stringify(type?.name)}, jsonType: ${JSON.stringify(type?.jsonType)}) ` +
+      `has no translatable representation; skipping.`,
+  )
+}
+
+function titleCase(name: string): string {
+  return name.replace(/([A-Z])/g, ' $1').replace(/^./, (c) => c.toUpperCase())
+}
+
+/**
+ * Selects translatable fields from a document's **data** (no schema needed) —
+ * for use in Sanity Functions, which run server-side without the Studio schema.
+ *
+ * Applies the same homogeneity rule as {@link getTranslatableFields}: if any
+ * field holds internationalized-array members, the document is field-mode and
+ * only those fields are selected (classified by a sample member's `value`);
+ * otherwise top-level `string`/Portable Text fields are selected (document-mode).
+ */
+export function inferTranslatableFields(
+  doc: Record<string, unknown>,
+  options: GetTranslatableFieldsOptions = {},
+): TranslatableField[] {
+  if (isSystemType(doc._type)) return []
+  const exclude = new Set(options.exclude ?? [])
+
+  const isI18nArray = (value: unknown): value is Array<{value?: unknown}> =>
+    Array.isArray(value) &&
+    value.some((m) => m && typeof m === 'object' && isInternationalizedArrayMemberType((m as {_type?: unknown})._type))
+
+  const entries = Object.entries(doc).filter(([key]) => !key.startsWith('_') && !exclude.has(key))
+  const fieldMode = entries.some(([, value]) => isI18nArray(value))
+
+  const result: TranslatableField[] = []
+  for (const [key, value] of entries) {
+    if (fieldMode) {
+      if (!isI18nArray(value)) continue
+      const sample = value.find((m) => m && typeof m === 'object')?.value
+      const kind = sampleKind(sample)
+      if (kind) result.push({path: key, kind, localization: 'field', title: titleCase(key)})
+    } else if (typeof value === 'string') {
+      if (value.length > 0) result.push({path: key, kind: 'plain', localization: 'document', title: titleCase(key)})
+    } else if (Array.isArray(value) && value.some(isPortableTextBlock)) {
+      result.push({path: key, kind: 'portableText', localization: 'document', title: titleCase(key)})
+    }
+  }
+  return result
+}
+
+function sampleKind(value: unknown): TranslatableField['kind'] | null {
+  if (typeof value === 'string') return 'plain'
+  if (Array.isArray(value) && value.some(isPortableTextBlock)) return 'portableText'
+  return null
+}
+
+function isPortableTextBlock(value: unknown): boolean {
+  return Boolean(value && typeof value === 'object' && (value as {_type?: string})._type === 'block')
+}
+
+/**
+ * Reorders fields to match `orderedPaths` (e.g. a schema's field order). Fields
+ * not listed keep their original relative order and go last. Stable.
+ */
+export function orderFieldsBy(
+  fields: TranslatableField[],
+  orderedPaths: string[] | undefined,
+): TranslatableField[] {
+  if (!orderedPaths || orderedPaths.length === 0) return fields
+  const rank = new Map(orderedPaths.map((path, i) => [path, i]))
+  const at = (path: string) => (rank.has(path) ? (rank.get(path) as number) : Number.MAX_SAFE_INTEGER)
+  return fields
+    .map((field, i) => ({field, i}))
+    .sort((a, b) => at(a.field.path) - at(b.field.path) || a.i - b.i)
+    .map((x) => x.field)
+}

package/src/lib/locjson/filename.ts

@@ -0,0 +1,27 @@
+/**
+ * Builds the Smartcat document filename for a Sanity document:
+ *   "<type>/<sanitized title>-<id prefix>.locjson"
+ * e.g. "page/About Us-3f14f092.locjson".
+ *
+ * The type acts as a folder; the id prefix guarantees uniqueness. Identity on
+ * import comes from the file's `x-sanity` metadata, not this name, so renames
+ * are safe.
+ */
+export function buildLocjsonFilename(documentType: string, documentId: string, title?: string): string {
+  const idPrefix = stripDraft(documentId).slice(0, 8) || 'unknown'
+  const safeTitle = sanitizeSegment(title || 'Untitled')
+  const safeType = sanitizeSegment(documentType) || 'document'
+  return `${safeType}/${safeTitle}-${idPrefix}.locjson`
+}
+
+function stripDraft(id: string): string {
+  return id.replace(/^drafts\./, '')
+}
+
+/** Removes characters unsafe for file paths while keeping it human-readable. */
+function sanitizeSegment(value: string): string {
+  return value
+    .replace(/[/\\?%*:|"<>]/g, ' ') // path-unsafe characters
+    .replace(/\s+/g, ' ')
+    .trim()
+}

package/src/lib/locjson/index.ts

@@ -0,0 +1,10 @@
+export * from './types'
+export {getTranslatableFields, inferTranslatableFields, orderFieldsBy} from './fields'
+export {buildLocjsonFilename} from './filename'
+export {serializeToLocjson, type SerializeOptions, type SerializableDocument} from './serialize'
+export {
+  deserializeFromLocjson,
+  type DeserializeOptions,
+  type DeserializedDocument,
+} from './deserialize'
+export {portableTextToHtml, htmlToPortableText, type PortableTextBlock, type ParseHtml} from './portableText'