@smartcat/sanity-plugin 1.0.0 → 1.1.0

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'

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

@@ -0,0 +1,615 @@
+import {describe, expect, it, vi} from 'vitest'
+import {Schema} from '@sanity/schema'
+import {JSDOM} from 'jsdom'
+import {
+  getTranslatableFields,
+  inferTranslatableFields,
+  innerValueType,
+  localizationMode,
+  orderFieldsBy,
+} from './fields'
+import {findUnserializableBlockTypes, portableTextToHtml} from './portableText'
+import {serializeToLocjson} from './serialize'
+import {deserializeFromLocjson} from './deserialize'
+import {buildLocjsonFilename} from './filename'
+import type {LocJSON} from './types'
+
+// A schema resembling the studio's page/blogPost, with non-translatable fields
+// mixed in to exercise selection. (Object-based built-ins like slug/image/
+// reference aren't registered in a bare @sanity/schema compile, so non-text
+// fields are represented here with primitives, a plain array, and an object —
+// all of which must be excluded just the same.)
+const schema = Schema.compile({
+  name: 'test',
+  types: [
+    // @sanity/table shape: rows of plain-string cells, embedded in Portable Text.
+    {name: 'tableRow', type: 'object', fields: [{name: 'cells', type: 'array', of: [{type: 'string'}]}]},
+    {name: 'table', type: 'object', fields: [{name: 'rows', type: 'array', of: [{type: 'tableRow'}]}]},
+    {
+      name: 'page',
+      type: 'document',
+      fields: [
+        {name: 'language', type: 'string', options: {documentInternationalization: {exclude: true}}},
+        {name: 'title', type: 'string'},
+        {name: 'excerpt', type: 'text'},
+        {name: 'views', type: 'number'},
+        {name: 'featured', type: 'boolean'},
+        {name: 'tags', type: 'array', of: [{type: 'string'}]},
+        {name: 'seo', type: 'object', fields: [{name: 'metaTitle', type: 'string'}]},
+        {name: 'body', type: 'array', of: [{type: 'block'}, {type: 'table'}]},
+      ],
+    },
+  ],
+})
+
+const pageType = schema.get('page')
+const bodyType = pageType.fields.find((f: {name: string}) => f.name === 'body').type
+
+const parseHtml = (html: string) => new JSDOM(html).window.document
+const getBlockContentType = () => bodyType
+
+function makeBlock(text: string, marks: string[] = []) {
+  return {
+    _type: 'block',
+    _key: 'b1',
+    style: 'normal',
+    markDefs: [],
+    children: [{_type: 'span', _key: 's1', text, marks}],
+  }
+}
+
+function makeTable(rows: string[][]) {
+  return {
+    _type: 'table',
+    _key: 't1',
+    rows: rows.map((cells, i) => ({_type: 'tableRow', _key: `row${i}`, cells})),
+  }
+}
+
+describe('getTranslatableFields', () => {
+  it('selects string/text/portable-text and excludes the rest', () => {
+    const fields = getTranslatableFields(pageType)
+    const byPath = Object.fromEntries(fields.map((f) => [f.path, f.kind]))
+
+    expect(byPath).toEqual({title: 'plain', excerpt: 'plain', body: 'portableText'})
+    // excluded: the language field (marked via document-internationalization's
+    // field option), primitives, plain array, object
+    expect(byPath.language).toBeUndefined()
+    expect(byPath.views).toBeUndefined()
+    expect(byPath.featured).toBeUndefined()
+    expect(byPath.tags).toBeUndefined()
+    expect(byPath.seo).toBeUndefined()
+  })
+
+  it('excludes fields marked non-translatable by document-internationalization', () => {
+    const s = Schema.compile({
+      name: 'opt',
+      types: [
+        {
+          name: 'thing',
+          type: 'document',
+          fields: [
+            {name: 'title', type: 'string'},
+            {name: 'sku', type: 'string', options: {documentInternationalization: {exclude: true}}},
+          ],
+        },
+      ],
+    })
+    const fields = getTranslatableFields(s.get('thing'))
+    expect(fields.map((f) => f.path)).toEqual(['title']) // sku skipped via the i18n option
+  })
+
+  it('never selects fields on Sanity system types (e.g. sanity.imageAsset)', () => {
+    // Built-in asset docs are referenced by image/file fields and carry plain
+    // string fields (originalFilename, path, url) that must never be translated.
+    const imageAsset = {
+      jsonType: 'object',
+      name: 'sanity.imageAsset',
+      fields: [
+        {name: 'originalFilename', type: {jsonType: 'string', name: 'string'}},
+        {name: 'path', type: {jsonType: 'string', name: 'string'}},
+        {name: 'title', type: {jsonType: 'string', name: 'string'}},
+      ],
+    }
+    expect(getTranslatableFields(imageAsset)).toEqual([])
+  })
+
+  it('honors a custom exclude list (e.g. the configured language field)', () => {
+    const fields = getTranslatableFields(pageType, {exclude: ['title']})
+    expect(fields.map((f) => f.path)).toEqual(['excerpt', 'body'])
+  })
+
+  it('opts custom-named types into translation via smartcatTranslation.include', () => {
+    const s = Schema.compile({
+      name: 'inc',
+      types: [
+        {name: 'headingString', type: 'string', options: {smartcatTranslation: {include: true}}},
+        {name: 'richText', type: 'array', of: [{type: 'block'}], options: {smartcatTranslation: {include: true}}},
+        {
+          name: 'thing',
+          type: 'document',
+          fields: [
+            {name: 'heading', type: 'headingString'}, // custom string alias → plain
+            {name: 'tagline', type: 'string', options: {smartcatTranslation: {include: true}}}, // per-field
+            {name: 'content', type: 'richText'}, // custom PT alias → portableText
+            {name: 'plain', type: 'string'}, // still works via the default allowlist
+          ],
+        },
+      ],
+    })
+    const fields = getTranslatableFields(s.get('thing'))
+    expect(Object.fromEntries(fields.map((f) => [f.path, f.kind]))).toEqual({
+      heading: 'plain',
+      tagline: 'plain',
+      content: 'portableText',
+      plain: 'plain',
+    })
+  })
+
+  it('lets include override a document-internationalization exclude', () => {
+    const s = Schema.compile({
+      name: 'override',
+      types: [
+        {
+          name: 'thing',
+          type: 'document',
+          fields: [
+            {
+              name: 'note',
+              type: 'string',
+              options: {documentInternationalization: {exclude: true}, smartcatTranslation: {include: true}},
+            },
+          ],
+        },
+      ],
+    })
+    expect(getTranslatableFields(s.get('thing')).map((f) => f.path)).toEqual(['note'])
+  })
+
+  it('warns and skips when an included field has no translatable representation', () => {
+    const s = Schema.compile({
+      name: 'badinc',
+      types: [
+        {
+          name: 'thing',
+          type: 'document',
+          fields: [{name: 'count', type: 'number', options: {smartcatTranslation: {include: true}}}],
+        },
+      ],
+    })
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const fields = getTranslatableFields(s.get('thing'))
+    expect(fields).toEqual([])
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('count'))
+    warn.mockRestore()
+  })
+})
+
+describe('portableTextToHtml', () => {
+  it('renders unknown/custom block types as nothing, not a placeholder', () => {
+    // A custom block with no to-html component. The default behavior emits a
+    // hidden `<div style="display:none">Unknown block type "…"</div>`, whose
+    // English text would be translated into every locale and which Smartcat
+    // rejects as unparseable HTML. It must be dropped entirely instead.
+    const blocks = [
+      makeBlock('Delivery info'),
+      {_type: 'heroBanner', _key: 'h1', heading: 'Save 20%'},
+    ]
+    const html = portableTextToHtml(blocks)
+    expect(html).not.toContain('Unknown block type')
+    expect(html).not.toContain('display:none')
+    expect(html).toContain('Delivery info')
+  })
+
+  it('renders a table block to an HTML <table>, escaping cell text', () => {
+    const html = portableTextToHtml([makeTable([['Region', 'Price'], ['EU', '<10 & up']])])
+    expect(html).toContain('<table><tbody>')
+    expect(html).toContain('<tr><td>Region</td><td>Price</td></tr>')
+    // cells are HTML-escaped so markup-looking text survives Smartcat's parser
+    expect(html).toContain('<td>&lt;10 &amp; up</td>')
+  })
+})
+
+describe('findUnserializableBlockTypes', () => {
+  const table = makeTable([['A', 'B']])
+
+  it('flags custom top-level block types', () => {
+    const embed = {_type: 'heroBanner', _key: 'h1', heading: 'x'}
+    expect(findUnserializableBlockTypes([makeBlock('text'), embed])).toEqual(['heroBanner'])
+  })
+
+  it('does NOT flag a table block (it round-trips through HTML)', () => {
+    expect(findUnserializableBlockTypes([makeBlock('text'), table])).toEqual([])
+  })
+
+  it('flags custom inline children (non-span)', () => {
+    const withInline = {
+      _type: 'block',
+      _key: 'b1',
+      children: [
+        {_type: 'span', _key: 's1', text: 'see '},
+        {_type: 'stockTicker', _key: 'i1', symbol: 'HUEL'},
+      ],
+    }
+    expect(findUnserializableBlockTypes([withInline])).toEqual(['stockTicker'])
+  })
+
+  it('returns empty for standard blocks/spans', () => {
+    expect(findUnserializableBlockTypes([makeBlock('a'), makeBlock('b')])).toEqual([])
+  })
+})
+
+describe('inferTranslatableFields', () => {
+  it('never selects fields on Sanity system types (e.g. sanity.imageAsset)', () => {
+    const asset = {
+      _type: 'sanity.imageAsset',
+      originalFilename: '01-Front Shot - es-ES.jpg',
+      path: 'images/xyz/production/abc-1468x1468.jpg',
+      url: 'https://cdn.sanity.io/images/xyz/production/abc-1468x1468.jpg',
+    }
+    expect(inferTranslatableFields(asset)).toEqual([])
+  })
+})
+
+describe('orderFieldsBy', () => {
+  it('reorders data-inferred fields to match schema order (title before body)', () => {
+    // Simulate Content Lake returning keys alphabetically (body before title).
+    const inferred = inferTranslatableFields({body: [makeBlock('x')], title: 'T'})
+    expect(inferred.map((f) => f.path)).toEqual(['body', 'title'])
+
+    const ordered = orderFieldsBy(inferred, ['title', 'body'])
+    expect(ordered.map((f) => f.path)).toEqual(['title', 'body'])
+  })
+
+  it('puts unlisted fields last, preserving their order', () => {
+    const fields = inferTranslatableFields({title: 'T', body: [makeBlock('x')], summary: 'S'})
+    const ordered = orderFieldsBy(fields, ['title'])
+    expect(ordered[0].path).toBe('title')
+    expect(ordered.slice(1).map((f) => f.path).sort()).toEqual(['body', 'summary'])
+  })
+
+  it('returns fields unchanged when no order is given', () => {
+    const fields = inferTranslatableFields({title: 'T'})
+    expect(orderFieldsBy(fields, undefined)).toBe(fields)
+  })
+})
+
+describe('serializeToLocjson', () => {
+  const doc = {
+    _id: '3f14f092-3475-42fc-a9f4-abf710d71ea8',
+    _type: 'page',
+    _rev: 'rev-1',
+    language: 'en',
+    title: 'About Us',
+    excerpt: 'Line one\nLine two',
+    body: [makeBlock('We build delightful things.')],
+  }
+  const fields = getTranslatableFields(pageType)
+  const locjson = serializeToLocjson(doc, fields, {sourceLanguage: 'en', fieldLanguageKey: 'language'})
+
+  it('writes file-level x-sanity metadata', () => {
+    expect(locjson.properties['x-sanity']).toEqual({
+      documentId: doc._id,
+      documentType: 'page',
+      rev: 'rev-1',
+      sourceLanguage: 'en',
+    })
+  })
+
+  it('emits one unit per non-empty translatable field, keyed by field path', () => {
+    expect(locjson.units.map((u) => u.key)).toEqual(['title', 'excerpt', 'body'])
+  })
+
+  it('splits plain text into line segments (keeping newlines) and marks html units', () => {
+    const excerpt = locjson.units.find((u) => u.key === 'excerpt')!
+    expect(excerpt.source).toEqual(['Line one\n', 'Line two'])
+    expect(excerpt.source.join('')).toBe('Line one\nLine two')
+    expect(excerpt.properties?.['x-smartcat-format']).toBeUndefined()
+
+    const body = locjson.units.find((u) => u.key === 'body')!
+    expect(body.properties?.['x-smartcat-format']).toBe('html')
+    expect(body.source[0]).toContain('We build delightful things.')
+    expect(body.properties?.['x-sanity']).toEqual({fieldPath: 'body'})
+  })
+
+  it('skips a Portable Text field containing an unserializable block, and reports it', () => {
+    const skipped: {fieldPath: string; types: string[]}[] = []
+    const result = serializeToLocjson(
+      {
+        _id: 'x',
+        _type: 'page',
+        title: 'Delivery',
+        body: [makeBlock('How much is delivery?'), {_type: 'heroBanner', _key: 'h1', heading: 'x'}],
+      },
+      fields,
+      {
+        sourceLanguage: 'en',
+        fieldLanguageKey: 'language',
+        onSkippedField: ({fieldPath, types}) => skipped.push({fieldPath, types}),
+      },
+    )
+    // title still serialized; body left out entirely (not partially)
+    expect(result.units.map((u) => u.key)).toEqual(['title'])
+    expect(skipped).toEqual([{fieldPath: 'body', types: ['heroBanner']}])
+  })
+
+  it('serializes a body containing a table (renders it into the HTML unit)', () => {
+    const result = serializeToLocjson(
+      {_id: 'x', _type: 'page', title: '', body: [makeTable([['Region', 'Price']])]},
+      fields,
+      {sourceLanguage: 'en', fieldLanguageKey: 'language'},
+    )
+    const body = result.units.find((u) => u.key === 'body')!
+    expect(body.properties?.['x-smartcat-format']).toBe('html')
+    expect(body.source[0]).toContain('<td>Region</td>')
+  })
+
+  it('skips empty fields', () => {
+    const empty = serializeToLocjson(
+      {_id: 'x', _type: 'page', title: '', body: []},
+      fields,
+      {sourceLanguage: 'en', fieldLanguageKey: 'language'},
+    )
+    expect(empty.units).toHaveLength(0)
+  })
+
+  it('skips whitespace-only plain fields', () => {
+    const blank = serializeToLocjson(
+      {_id: 'x', _type: 'page', title: '   ', excerpt: '\n\n', body: []},
+      fields,
+      {sourceLanguage: 'en', fieldLanguageKey: 'language'},
+    )
+    expect(blank.units).toHaveLength(0)
+  })
+
+  it('skips Portable Text that renders to markup but carries no visible text', () => {
+    // An "emptied" rich-text field: the paragraph/list structure survives but the
+    // spans hold no text, so toHTML yields <p></p> / <br/> — non-empty markup that
+    // must NOT become a unit.
+    for (const body of [
+      [makeBlock('')], // <p></p>
+      [makeBlock('   ')], // <p>&nbsp; </p>
+      [makeBlock('\n')], // <p><br/></p>
+      [{_type: 'block', _key: 'b1', style: 'normal', markDefs: [], children: []}], // <p></p>
+    ]) {
+      const result = serializeToLocjson(
+        {_id: 'x', _type: 'page', title: '', body},
+        fields,
+        {sourceLanguage: 'en', fieldLanguageKey: 'language'},
+      )
+      expect(result.units).toHaveLength(0)
+    }
+  })
+
+  it('keeps a field whose text is surrounded by whitespace (preserving it in source)', () => {
+    const result = serializeToLocjson(
+      {_id: 'x', _type: 'page', title: '  Hello  ', body: []},
+      fields,
+      {sourceLanguage: 'en', fieldLanguageKey: 'language'},
+    )
+    expect(result.units.map((u) => u.key)).toEqual(['title'])
+    expect(result.units[0].source.join('')).toBe('  Hello  ')
+  })
+})
+
+describe('round-trip', () => {
+  const doc = {
+    _id: 'abc12345-0000',
+    _type: 'page',
+    _rev: 'rev-1',
+    language: 'en',
+    title: 'About Us',
+    excerpt: 'Line one\nLine two',
+    body: [makeBlock('We build delightful things.', ['strong'])],
+  }
+  const fields = getTranslatableFields(pageType)
+
+  it('deserialize(serialize(doc)) preserves translatable field values', () => {
+    const locjson = serializeToLocjson(doc, fields, {sourceLanguage: 'en', fieldLanguageKey: 'language'})
+    // Simulate "no-op translation": copy source into target.
+    const translated: LocJSON = {
+      ...locjson,
+      units: locjson.units.map((u) => ({...u, target: [...u.source]})),
+    }
+
+    const result = deserializeFromLocjson(translated, {parseHtml, getBlockContentType})
+
+    expect(result.documentId).toBe(doc._id)
+    expect(result.documentType).toBe('page')
+    expect(result.fields.title).toBe('About Us')
+    expect(result.fields.excerpt).toBe('Line one\nLine two')
+
+    const body = result.fields.body as Array<Record<string, unknown>>
+    expect(Array.isArray(body)).toBe(true)
+    const spans = (body[0].children as Array<{text: string; marks: string[]}>)
+    expect(spans[0].text).toBe('We build delightful things.')
+    expect(spans[0].marks).toContain('strong')
+  })
+
+  it('uses target text when present (actual translation)', () => {
+    const locjson = serializeToLocjson(doc, fields, {sourceLanguage: 'en', fieldLanguageKey: 'language'})
+    const translated: LocJSON = {
+      ...locjson,
+      units: locjson.units.map((u) =>
+        u.key === 'title' ? {...u, target: ['À propos']} : {...u, target: [...u.source]},
+      ),
+    }
+    const result = deserializeFromLocjson(translated, {parseHtml, getBlockContentType})
+    expect(result.fields.title).toBe('À propos')
+  })
+
+  it('round-trips a table block, translating its cells', () => {
+    const tableDoc = {
+      _id: 'abc12345-0000',
+      _type: 'page',
+      title: 'Pricing',
+      body: [makeBlock('Our plans:'), makeTable([['Region', 'Price'], ['EU', '€10']])],
+    }
+    const locjson = serializeToLocjson(tableDoc, fields, {sourceLanguage: 'en', fieldLanguageKey: 'language'})
+    // Translate the header cells by rewriting the HTML unit's target.
+    const translated: LocJSON = {
+      ...locjson,
+      units: locjson.units.map((u) =>
+        u.key === 'body'
+          ? {...u, target: [u.source[0].replace('Region', 'Région').replace('Price', 'Prix')]}
+          : {...u, target: [...u.source]},
+      ),
+    }
+    const result = deserializeFromLocjson(translated, {parseHtml, getBlockContentType})
+    const body = result.fields.body as Array<Record<string, unknown>>
+    const table = body.find((b) => b._type === 'table')!
+    const rows = table.rows as Array<{_type: string; _key: string; cells: string[]}>
+    expect(rows.map((r) => r.cells)).toEqual([
+      ['Région', 'Prix'],
+      ['EU', '€10'],
+    ])
+    // rows keep the tableRow type and carry a _key (required for array members)
+    expect(rows.every((r) => r._type === 'tableRow' && typeof r._key === 'string')).toBe(true)
+  })
+})
+
+// --- Field-level localization (sanity-plugin-internationalized-array) ---------
+
+const faqSchema = Schema.compile({
+  name: 'faqTest',
+  types: [
+    {name: 'internationalizedArrayStringValue', type: 'object', fields: [{name: 'value', type: 'string'}]},
+    {name: 'internationalizedArrayString', type: 'array', of: [{type: 'internationalizedArrayStringValue'}]},
+    {
+      name: 'internationalizedArraySimpleBlockContentValue',
+      type: 'object',
+      fields: [{name: 'value', type: 'array', of: [{type: 'block'}]}],
+    },
+    {
+      name: 'internationalizedArraySimpleBlockContent',
+      type: 'array',
+      of: [{type: 'internationalizedArraySimpleBlockContentValue'}],
+    },
+    {
+      name: 'faq',
+      type: 'document',
+      fields: [
+        {name: 'question', type: 'internationalizedArrayString'},
+        {name: 'answer', type: 'internationalizedArraySimpleBlockContent'},
+        {name: 'note', type: 'string'}, // plain top-level field — skipped in field mode
+      ],
+    },
+  ],
+})
+const faqType = faqSchema.get('faq')
+const answerBlockType = innerValueType(faqType.fields.find((f: {name: string}) => f.name === 'answer').type)
+
+const member = (language: string, value: unknown, type = 'internationalizedArrayStringValue') => ({
+  _key: `${language}-key`,
+  _type: type,
+  language,
+  value,
+})
+
+describe('field-level localization', () => {
+  it('localizationMode is field for an internationalized-array type, document otherwise', () => {
+    expect(localizationMode(faqType)).toBe('field')
+    expect(localizationMode(pageType)).toBe('document')
+  })
+
+  it('selects only the i18n-array fields and skips plain top-level fields (homogeneity rule)', () => {
+    const fields = getTranslatableFields(faqType)
+    expect(fields.map((f) => [f.path, f.kind, f.localization])).toEqual([
+      ['question', 'plain', 'field'],
+      ['answer', 'portableText', 'field'],
+    ])
+    expect(fields.find((f) => f.path === 'note')).toBeUndefined()
+  })
+
+  it('serializes the source-language member value of each field', () => {
+    const doc = {
+      _id: 'faq-1',
+      _type: 'faq',
+      question: [member('en', 'How?'), member('fr', 'Comment ?')],
+      answer: [
+        member('en', [makeBlock('Like this.')], 'internationalizedArraySimpleBlockContentValue'),
+      ],
+    }
+    const locjson = serializeToLocjson(doc, getTranslatableFields(faqType), {sourceLanguage: 'en', fieldLanguageKey: 'language'})
+    const question = locjson.units.find((u) => u.key === 'question')!
+    expect(question.source.join('')).toBe('How?')
+    const answer = locjson.units.find((u) => u.key === 'answer')!
+    expect(answer.properties?.['x-smartcat-format']).toBe('html')
+    expect(answer.source[0]).toContain('Like this.')
+  })
+
+  it('reads the source member by _key when fieldLanguageKey is "_key" (v4)', () => {
+    const doc = {
+      _id: 'faq-1',
+      _type: 'faq',
+      question: [
+        {_key: 'en', _type: 'internationalizedArrayStringValue', value: 'How?'},
+        {_key: 'fr', _type: 'internationalizedArrayStringValue', value: 'Comment ?'},
+      ],
+    }
+    const locjson = serializeToLocjson(doc, getTranslatableFields(faqType), {
+      sourceLanguage: 'en',
+      fieldLanguageKey: '_key',
+    })
+    expect(locjson.units.find((u) => u.key === 'question')!.source.join('')).toBe('How?')
+  })
+
+  it('does not match a _key-keyed member under the "language" key (no fallback)', () => {
+    const doc = {
+      _id: 'faq-1',
+      _type: 'faq',
+      question: [{_key: 'en', _type: 'internationalizedArrayStringValue', value: 'How?'}],
+    }
+    const locjson = serializeToLocjson(doc, getTranslatableFields(faqType), {sourceLanguage: 'en', fieldLanguageKey: 'language'})
+    expect(locjson.units.find((u) => u.key === 'question')).toBeUndefined()
+  })
+
+  it('round-trips field-level values (LocJSON carries no localization marker)', () => {
+    const doc = {
+      _id: 'faq-1',
+      _type: 'faq',
+      question: [member('en', 'How?')],
+      answer: [member('en', [makeBlock('Like this.')], 'internationalizedArraySimpleBlockContentValue')],
+    }
+    const locjson = serializeToLocjson(doc, getTranslatableFields(faqType), {sourceLanguage: 'en', fieldLanguageKey: 'language'})
+    expect(locjson.properties['x-sanity']).not.toHaveProperty('localization')
+
+    const translated: LocJSON = {
+      ...locjson,
+      units: locjson.units.map((u) =>
+        u.key === 'question' ? {...u, target: ['Comment ?']} : {...u, target: [...u.source]},
+      ),
+    }
+    const result = deserializeFromLocjson(translated, {
+      parseHtml,
+      getBlockContentType: (path) => (path === 'answer' ? answerBlockType : undefined),
+    })
+    expect(result.fields.question).toBe('Comment ?')
+    const body = result.fields.answer as Array<Record<string, unknown>>
+    expect((body[0].children as Array<{text: string}>)[0].text).toBe('Like this.')
+  })
+})
+
+describe('buildLocjsonFilename', () => {
+  it('builds "<type>/<title>-<idPrefix>.locjson"', () => {
+    expect(buildLocjsonFilename('page', '3f14f092-3475-42fc-a9f4-abf710d71ea8', 'About Us')).toBe(
+      'page/About Us-3f14f092.locjson',
+    )
+  })
+
+  it('strips drafts. prefix and sanitizes the title', () => {
+    expect(buildLocjsonFilename('blogPost', 'drafts.7c7b0950-aaaa', 'Why We Love / Content')).toBe(
+      'blogPost/Why We Love Content-7c7b0950.locjson',
+    )
+  })
+
+  it('falls back when title is missing', () => {
+    expect(buildLocjsonFilename('page', 'abc12345-0000')).toBe('page/Untitled-abc12345.locjson')
+  })
+
+  it('appends a -draft marker when the source was a draft', () => {
+    expect(buildLocjsonFilename('page', '3f14f092-3475', 'About Us', {draft: true})).toBe(
+      'page/About Us-3f14f092-draft.locjson',
+    )
+  })
+})

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

@@ -0,0 +1,41 @@
+import {describe, expect, it} from 'vitest'
+import {getAtPath, parsePath, setAtPath} from './paths'
+
+describe('parsePath', () => {
+  it('parses fields, array-by-key, and array-by-index', () => {
+    expect(parsePath('benefits.items[b1].value')).toEqual([{field: 'benefits'}, {field: 'items'}, {key: 'b1'}, {field: 'value'}])
+    expect(parsePath('tabs[2]')).toEqual([{field: 'tabs'}, {index: 2}])
+    expect(parsePath('')).toEqual([])
+  })
+})
+
+const value = [
+  {_key: 'b1', key: 'protein', value: 'High in protein'},
+  {_key: 'b2', key: 'fibre', value: 'Rich in fibre'},
+]
+
+describe('getAtPath', () => {
+  it('reads by _key and index', () => {
+    expect(getAtPath(value, '[b1].value')).toBe('High in protein')
+    expect(getAtPath(value, '[1].key')).toBe('fibre')
+    expect(getAtPath(value, '[missing].value')).toBeUndefined()
+  })
+})
+
+describe('setAtPath', () => {
+  it('replaces a leaf immutably, preserving siblings and _keys', () => {
+    const next = setAtPath(value, '[b1].value', 'PROTEINE')
+    expect(next[0]).toEqual({_key: 'b1', key: 'protein', value: 'PROTEINE'})
+    expect(next[1]).toEqual(value[1])
+    expect(value[0].value).toBe('High in protein') // original untouched
+  })
+
+  it('empty path replaces the whole value', () => {
+    expect(setAtPath('old', '', 'new')).toBe('new')
+  })
+
+  it('is a no-op when an intermediate segment is missing', () => {
+    const next = setAtPath(value, '[nope].value', 'x')
+    expect(next).toEqual(value)
+  })
+})