@smartcat/sanity-plugin 1.0.0 → 1.1.0

package/dist/locjson.d.cts

@@ -0,0 +1,291 @@
+/**
+ * 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. When the exported content came from the document's draft, a `-draft`
+ * marker is appended so it's visible in Smartcat (`…-3f14f092-draft.locjson`).
+ */
+export declare function buildLocjsonFilename(
+  documentType: string,
+  documentId: string,
+  title?: string,
+  options?: {
+    draft?: boolean;
+  },
+): string;
+
+export declare 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 declare function deserializeFromLocjson(
+  locjson: LocJSON,
+  options: DeserializeOptions,
+): DeserializedDocument;
+
+export declare 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;
+}
+
+/**
+ * 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 declare function getTranslatableFields(
+  compiledType: unknown,
+  options?: GetTranslatableFieldsOptions,
+): TranslatableField[];
+
+declare 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[];
+}
+
+/**
+ * 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 declare function htmlToPortableText(
+  html: string,
+  blockContentType: unknown,
+  parseHtml: ParseHtml,
+): PortableTextBlock[];
+
+/**
+ * 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 declare function inferTranslatableFields(
+  doc: Record<string, unknown>,
+  options?: GetTranslatableFieldsOptions,
+): TranslatableField[];
+
+/**
+ * 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 declare type LocalizationMode = "document" | "field";
+
+export declare interface LocJSON {
+  properties: LocJSONProperties;
+  units: LocUnit[];
+}
+
+export declare interface LocJSONProperties {
+  version: number;
+  "x-sanity"?: SanityFileMeta;
+}
+
+export declare interface LocUnit {
+  /** Unique, stable id within the file. We use the Sanity field path. */
+  key: string;
+  properties?: LocUnitProperties;
+  source: string[];
+  target: string[];
+}
+
+export declare interface LocUnitProperties {
+  comments?: string[];
+  "x-smartcat-format"?: SmartcatFormat;
+  "x-smartcat-split"?: "full";
+  "x-sanity"?: SanityUnitMeta;
+}
+
+/**
+ * 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 declare function orderFieldsBy(
+  fields: TranslatableField[],
+  orderedPaths: string[] | undefined,
+): TranslatableField[];
+
+/** Parses an HTML string into a DOM Document. Provided by the environment. */
+export declare type ParseHtml = (html: string) => Document;
+
+/** A Portable Text block (loosely typed — shape varies by schema). */
+export declare type PortableTextBlock = Record<string, unknown>;
+
+/**
+ * Renders Portable Text to an HTML string for translation.
+ * Whole-field: the entire block array becomes one HTML document fragment.
+ */
+export declare function portableTextToHtml(
+  blocks: PortableTextBlock[] | undefined | null,
+): string;
+
+/** Our per-document metadata, stored at file level. */
+export declare 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 declare interface SanityUnitMeta {
+  /** Path of the Sanity field this unit represents (also used as the unit key). */
+  fieldPath: string;
+}
+
+/** A minimal view of a Sanity document needed for serialization. */
+export declare interface SerializableDocument {
+  _id: string;
+  _type: string;
+  _rev?: string;
+  [key: string]: unknown;
+}
+
+export declare 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;
+}
+
+/**
+ * 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 declare function serializeToLocjson(
+  doc: SerializableDocument,
+  fields: TranslatableField[],
+  options: SerializeOptions,
+): LocJSON;
+
+/**
+ * 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 declare type SmartcatFormat = "markdown" | "html";
+
+/** A translatable field selected from a document/schema. */
+export declare 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;
+}
+
+/** Kind of translatable field, deciding how it is serialized. */
+export declare type TranslatableFieldKind = "plain" | "portableText";
+
+/**
+ * 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 declare 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 declare type ValueShape =
+  | {
+      container: "scalar";
+      kind: TranslatableFieldKind;
+    }
+  | {
+      container: "arrayOfScalar";
+      kind: TranslatableFieldKind;
+    }
+  | {
+      container: "arrayOfObject";
+      leaves: TranslatableLeaf[];
+    }
+  | {
+      container: "object";
+      leaves: TranslatableLeaf[];
+    };
+
+export {};

package/dist/locjson.d.ts

@@ -0,0 +1,291 @@
+/**
+ * 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. When the exported content came from the document's draft, a `-draft`
+ * marker is appended so it's visible in Smartcat (`…-3f14f092-draft.locjson`).
+ */
+export declare function buildLocjsonFilename(
+  documentType: string,
+  documentId: string,
+  title?: string,
+  options?: {
+    draft?: boolean;
+  },
+): string;
+
+export declare 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 declare function deserializeFromLocjson(
+  locjson: LocJSON,
+  options: DeserializeOptions,
+): DeserializedDocument;
+
+export declare 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;
+}
+
+/**
+ * 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 declare function getTranslatableFields(
+  compiledType: unknown,
+  options?: GetTranslatableFieldsOptions,
+): TranslatableField[];
+
+declare 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[];
+}
+
+/**
+ * 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 declare function htmlToPortableText(
+  html: string,
+  blockContentType: unknown,
+  parseHtml: ParseHtml,
+): PortableTextBlock[];
+
+/**
+ * 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 declare function inferTranslatableFields(
+  doc: Record<string, unknown>,
+  options?: GetTranslatableFieldsOptions,
+): TranslatableField[];
+
+/**
+ * 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 declare type LocalizationMode = "document" | "field";
+
+export declare interface LocJSON {
+  properties: LocJSONProperties;
+  units: LocUnit[];
+}
+
+export declare interface LocJSONProperties {
+  version: number;
+  "x-sanity"?: SanityFileMeta;
+}
+
+export declare interface LocUnit {
+  /** Unique, stable id within the file. We use the Sanity field path. */
+  key: string;
+  properties?: LocUnitProperties;
+  source: string[];
+  target: string[];
+}
+
+export declare interface LocUnitProperties {
+  comments?: string[];
+  "x-smartcat-format"?: SmartcatFormat;
+  "x-smartcat-split"?: "full";
+  "x-sanity"?: SanityUnitMeta;
+}
+
+/**
+ * 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 declare function orderFieldsBy(
+  fields: TranslatableField[],
+  orderedPaths: string[] | undefined,
+): TranslatableField[];
+
+/** Parses an HTML string into a DOM Document. Provided by the environment. */
+export declare type ParseHtml = (html: string) => Document;
+
+/** A Portable Text block (loosely typed — shape varies by schema). */
+export declare type PortableTextBlock = Record<string, unknown>;
+
+/**
+ * Renders Portable Text to an HTML string for translation.
+ * Whole-field: the entire block array becomes one HTML document fragment.
+ */
+export declare function portableTextToHtml(
+  blocks: PortableTextBlock[] | undefined | null,
+): string;
+
+/** Our per-document metadata, stored at file level. */
+export declare 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 declare interface SanityUnitMeta {
+  /** Path of the Sanity field this unit represents (also used as the unit key). */
+  fieldPath: string;
+}
+
+/** A minimal view of a Sanity document needed for serialization. */
+export declare interface SerializableDocument {
+  _id: string;
+  _type: string;
+  _rev?: string;
+  [key: string]: unknown;
+}
+
+export declare 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;
+}
+
+/**
+ * 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 declare function serializeToLocjson(
+  doc: SerializableDocument,
+  fields: TranslatableField[],
+  options: SerializeOptions,
+): LocJSON;
+
+/**
+ * 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 declare type SmartcatFormat = "markdown" | "html";
+
+/** A translatable field selected from a document/schema. */
+export declare 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;
+}
+
+/** Kind of translatable field, deciding how it is serialized. */
+export declare type TranslatableFieldKind = "plain" | "portableText";
+
+/**
+ * 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 declare 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 declare type ValueShape =
+  | {
+      container: "scalar";
+      kind: TranslatableFieldKind;
+    }
+  | {
+      container: "arrayOfScalar";
+      kind: TranslatableFieldKind;
+    }
+  | {
+      container: "arrayOfObject";
+      leaves: TranslatableLeaf[];
+    }
+  | {
+      container: "object";
+      leaves: TranslatableLeaf[];
+    };
+
+export {};

package/dist/locjson.js

@@ -0,0 +1,12 @@
+import { buildLocjsonFilename, deserializeFromLocjson, getTranslatableFields, htmlToPortableText, inferTranslatableFields, orderFieldsBy, portableTextToHtml, serializeToLocjson } from "./_chunks-es/index2.js";
+export {
+  buildLocjsonFilename,
+  deserializeFromLocjson,
+  getTranslatableFields,
+  htmlToPortableText,
+  inferTranslatableFields,
+  orderFieldsBy,
+  portableTextToHtml,
+  serializeToLocjson
+};
+//# sourceMappingURL=locjson.js.map

package/dist/locjson.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"locjson.js","sources":[],"sourcesContent":[],"names":[],"mappings":";"}

package/dist/progress.cjs

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: !0 });
+var progress = require("./_chunks-cjs/index.cjs");
+exports.buildProgress = progress.buildProgress;
+exports.buildStageNameMap = progress.buildStageNameMap;
+exports.hasConfirmedContent = progress.hasConfirmedContent;
+exports.isTargetComplete = progress.isTargetComplete;
+exports.itemsFromProject = progress.itemsFromProject;
+exports.keyify = progress.keyify;
+exports.runProgressSync = progress.runProgressSync;
+exports.sourceIdPrefix = progress.sourceIdPrefix;
+exports.stagesFromDocument = progress.stagesFromDocument;
+exports.summarizeCompletion = progress.summarizeCompletion;
+exports.targetKey = progress.targetKey;
+exports.targetPercent = progress.targetPercent;
+//# sourceMappingURL=progress.cjs.map

package/dist/progress.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;"}