gt-sanity 0.0.5 → 1.0.0

package/src/configuration/baseDocumentLevelConfig/helpers/createI18nDocAndPatchMetadata.ts

@@ -1,12 +1,18 @@
+// adapted from https://github.com/sanity-io/sanity-translations-tab. See LICENSE.md for more details.
+
 import { SanityClient, SanityDocumentLike } from 'sanity';
+import { pluginConfig } from '../../../adapter/core';
+import { applyDocuments } from '../../../utils/applyDocuments';
 
-export const createI18nDocAndPatchMetadata = (
+export async function createI18nDocAndPatchMetadata(
+  sourceDocument: SanityDocumentLike,
   translatedDoc: SanityDocumentLike,
   localeId: string,
   client: SanityClient,
   translationMetadata: SanityDocumentLike,
+  sourceDocumentId: string,
   languageField: string = 'language'
-): void => {
+): Promise<void> {
   translatedDoc[languageField] = localeId;
   const translations = translationMetadata.translations as Record<
     string,
@@ -22,26 +28,54 @@ export const createI18nDocAndPatchMetadata = (
 
   //remove system fields
   const { _updatedAt, _createdAt, ...rest } = translatedDoc;
-  client.create({ ...rest, _id: 'drafts.' }).then((doc) => {
-    const _ref = doc._id.replace('drafts.', '');
-    client
-      .transaction()
-      .patch(translationMetadata._id, (p) =>
-        p.insert(operation, location, [
-          {
-            _key: localeId,
-            _type: 'internationalizedArrayReferenceValue',
-            value: {
-              _type: 'reference',
-              _ref,
-              _weak: true,
-              _strengthenOnPublish: {
-                type: doc._type,
-              },
+
+  const appliedDocument = applyDocuments(
+    sourceDocumentId,
+    sourceDocument,
+    rest,
+    pluginConfig.getIgnoreFields()
+  );
+
+  // Check if this is a singleton document and apply singleton mapping
+  const singletons = pluginConfig.getSingletons();
+  const isSingleton = singletons.includes(sourceDocumentId);
+
+  let createDocumentPromise;
+  if (isSingleton) {
+    const singletonMapping = pluginConfig.getSingletonMapping();
+    const translatedDocId = singletonMapping(sourceDocumentId, localeId);
+    createDocumentPromise = client.create({
+      ...appliedDocument,
+      _type: rest._type,
+      _id: `drafts.${translatedDocId}`,
+    });
+  } else {
+    createDocumentPromise = client.create({
+      ...appliedDocument,
+      _type: rest._type,
+      _id: 'drafts.',
+    });
+  }
+
+  const doc = await createDocumentPromise;
+  const _ref = doc._id.replace('drafts.', '');
+  const result = await client
+    .transaction()
+    .patch(translationMetadata._id, (p) =>
+      p.insert(operation, location, [
+        {
+          _key: localeId,
+          _type: 'internationalizedArrayReferenceValue',
+          value: {
+            _type: 'reference',
+            _ref,
+            _weak: true,
+            _strengthenOnPublish: {
+              type: doc._type,
             },
           },
-        ])
-      )
-      .commit();
-  });
-};
+        },
+      ])
+    )
+    .commit();
+}

package/src/configuration/baseDocumentLevelConfig/helpers/createTranslationMetadata.ts

@@ -1,3 +1,5 @@
+// adapted from https://github.com/sanity-io/sanity-translations-tab. See LICENSE.md for more details.
+
 import {
   KeyedObject,
   Reference,

package/src/configuration/baseDocumentLevelConfig/helpers/getOrCreateTranslationMetadata.ts

@@ -1,3 +1,5 @@
+// adapted from https://github.com/sanity-io/sanity-translations-tab. See LICENSE.md for more details.
+
 import {
   KeyedObject,
   Reference,

package/src/configuration/baseDocumentLevelConfig/helpers/getTranslationMetadata.ts

@@ -1,3 +1,5 @@
+// adapted from https://github.com/sanity-io/sanity-translations-tab. See LICENSE.md for more details.
+
 import { SanityClient, SanityDocumentLike } from 'sanity';
 
 export const getTranslationMetadata = (

package/src/configuration/baseDocumentLevelConfig/helpers/patchI18nDoc.ts

@@ -1,25 +1,48 @@
+// adapted from https://github.com/sanity-io/sanity-translations-tab. See LICENSE.md for more details.
+
 import { SanityClient, SanityDocumentLike } from 'sanity';
+import { applyDocuments } from '../../../utils/applyDocuments';
+import { pluginConfig } from '../../../adapter/core';
+
+const SYSTEM_FIELDS = ['_id', '_rev', '_updatedAt', 'language'];
 
-export const patchI18nDoc = (
+const isSystemField = (field: string) => SYSTEM_FIELDS.includes(field);
+
+export async function patchI18nDoc(
+  sourceDocumentId: string,
   i18nDocId: string,
+  sourceDocument: SanityDocumentLike,
   mergedDocument: SanityDocumentLike,
   translatedFields: Record<string, any>,
   client: SanityClient
-): void => {
+): Promise<void> {
   const cleanedMerge: Record<string, any> = {};
   Object.entries(mergedDocument).forEach(([key, value]) => {
     if (
       //only patch those fields that had translated strings
       key in translatedFields &&
       //don't overwrite any existing system values on the i18n doc
-      !['_id', '_rev', '_updatedAt', 'language'].includes(key)
+      !isSystemField(key)
     ) {
       cleanedMerge[key] = value;
     }
   });
-
-  client
-    .transaction()
-    .patch(i18nDocId, (p) => p.set(cleanedMerge))
+  const cleanedSourceDocument: Record<string, any> = {};
+  Object.entries(sourceDocument).forEach(([key, value]) => {
+    if (
+      // extract only the fields that are not system fields
+      !isSystemField(key)
+    ) {
+      cleanedSourceDocument[key] = value;
+    }
+  });
+  const appliedDocument = applyDocuments(
+    sourceDocumentId,
+    cleanedSourceDocument,
+    cleanedMerge,
+    pluginConfig.getIgnoreFields()
+  );
+  const newDocument = await client
+    .patch(i18nDocId, { set: appliedDocument })
     .commit();
-};
+}

package/src/configuration/baseDocumentLevelConfig/index.ts

@@ -1,53 +1,26 @@
+// adapted from https://github.com/sanity-io/sanity-translations-tab. See LICENSE.md for more details.
+
 import {
   ExportForTranslation,
   GTSerializedDocument,
   ImportTranslation,
 } from '../../types';
-import { SanityDocument } from 'sanity';
-import { findLatestDraft } from '../utils';
-import { documentLevelPatch } from './documentLevelPatch';
-import { legacyDocumentLevelPatch } from './legacyDocumentLevelPatch';
-import {
-  BaseDocumentDeserializer,
-  BaseDocumentSerializer,
-  defaultStopTypes,
-  customSerializers,
-  customBlockDeserializers,
-} from 'sanity-naive-html-serializer';
-import { gtConfig } from '../../adapter/core';
+import { findLatestDraft } from '../utils/findLatestDraft';
+import { pluginConfig } from '../../adapter/core';
+import { importDocument } from '../../translation/importDocument';
+import { serializeDocument } from '../../utils/serialize';
 
 export const baseDocumentLevelConfig = {
   exportForTranslation: async (
-    ...params: Parameters<ExportForTranslation>
+    docInfo: Parameters<ExportForTranslation>[0],
+    context: Parameters<ExportForTranslation>[1]
   ): Promise<GTSerializedDocument> => {
-    const [
-      docInfo,
-      context,
-      serializationOptions = {},
-      languageField = 'language',
-    ] = params;
     const { client, schema } = context;
-    const stopTypes = [
-      ...(serializationOptions.additionalStopTypes ?? []),
-      ...defaultStopTypes,
-    ];
-    const serializers = {
-      ...customSerializers,
-      types: {
-        ...customSerializers.types,
-        ...(serializationOptions.additionalSerializers ?? {}),
-      },
-    };
+    const languageField = pluginConfig.getLanguageField();
     const doc = await findLatestDraft(docInfo.documentId, client);
     delete doc[languageField];
-    const baseLanguage = gtConfig.getSourceLocale();
-    const serialized = BaseDocumentSerializer(schema).serializeDocument(
-      doc,
-      'document',
-      baseLanguage,
-      stopTypes,
-      serializers
-    );
+    const baseLanguage = pluginConfig.getSourceLocale();
+    const serialized = serializeDocument(doc, schema, baseLanguage);
     return {
       content: serialized.content,
       documentId: docInfo.documentId,
@@ -55,75 +28,19 @@ export const baseDocumentLevelConfig = {
     };
   },
   importTranslation: (
-    ...params: Parameters<ImportTranslation>
+    docInfo: Parameters<ImportTranslation>[0],
+    localeId: Parameters<ImportTranslation>[1],
+    document: Parameters<ImportTranslation>[2],
+    context: Parameters<ImportTranslation>[3],
+    mergeWithTargetLocale: boolean = false
   ): Promise<void> => {
-    const [
+    return importDocument(
       docInfo,
       localeId,
       document,
       context,
-      serializationOptions = {},
-      languageField = 'language',
-      mergeWithTargetLocale = false,
-    ] = params;
-    const { client } = context;
-    const deserializers = {
-      types: {
-        ...(serializationOptions.additionalDeserializers ?? {}),
-      },
-    };
-    const blockDeserializers = [
-      ...(serializationOptions.additionalBlockDeserializers ?? []),
-      ...customBlockDeserializers,
-    ];
-
-    const deserialized = BaseDocumentDeserializer.deserializeDocument(
-      document,
-      deserializers,
-      blockDeserializers
-    ) as SanityDocument;
-    return documentLevelPatch(
-      docInfo, // versionId is not used here, since we just use the _rev id in the deserialized HTML itself
-      deserialized,
-      localeId,
-      client,
-      languageField,
       mergeWithTargetLocale
     );
   },
-  secretsNamespace: 'translationService',
+  secretsNamespace: 'generaltranslation',
 };
-
-export const legacyDocumentLevelConfig = {
-  ...baseDocumentLevelConfig,
-  importTranslation: (
-    ...params: Parameters<ImportTranslation>
-  ): Promise<void> => {
-    const [docInfo, localeId, document, context, serializationOptions = {}] =
-      params;
-    const { client } = context;
-    const deserializers = {
-      types: {
-        ...(serializationOptions.additionalDeserializers ?? {}),
-      },
-    };
-    const blockDeserializers = [
-      ...(serializationOptions.additionalBlockDeserializers ?? []),
-      ...customBlockDeserializers,
-    ];
-
-    const deserialized = BaseDocumentDeserializer.deserializeDocument(
-      document,
-      deserializers,
-      blockDeserializers
-    ) as SanityDocument;
-    return legacyDocumentLevelPatch(
-      docInfo, // versionId is not used here, since we just use the _rev id in the deserialized HTML itself
-      deserialized,
-      localeId,
-      client
-    );
-  },
-};
-
-export { documentLevelPatch, legacyDocumentLevelPatch };

package/src/configuration/baseFieldLevelConfig.ts

@@ -1,3 +1,5 @@
+// adapted from https://github.com/sanity-io/sanity-translations-tab. See LICENSE.md for more details.
+
 import { SanityClient, SanityDocument } from 'sanity';
 import {
   BaseDocumentSerializer,
@@ -6,7 +8,7 @@ import {
   defaultStopTypes,
   customSerializers,
   customBlockDeserializers,
-} from 'sanity-naive-html-serializer';
+} from '../serialization/';
 
 import type {
   ExportForTranslation,
@@ -14,8 +16,10 @@ import type {
   GTSerializedDocument,
   ImportTranslation,
 } from '../types';
-import { findLatestDraft, findDocumentAtRevision } from './utils';
-import { gtConfig } from '../adapter/core';
+import { findLatestDraft } from './utils/findLatestDraft';
+import { findDocumentAtRevision } from './utils/findDocumentAtRevision';
+import { pluginConfig } from '../adapter/core';
+import { deserializeDocument, serializeDocument } from '../utils/serialize';
 
 export const fieldLevelPatch = async (
   docInfo: GTFile,
@@ -25,7 +29,7 @@ export const fieldLevelPatch = async (
   mergeWithTargetLocale: boolean = false
 ): Promise<void> => {
   let baseDoc: SanityDocument;
-  const baseLanguage = gtConfig.getSourceLocale();
+  const baseLanguage = pluginConfig.getSourceLocale();
   if (docInfo.documentId && docInfo.versionId) {
     baseDoc = await findDocumentAtRevision(
       docInfo.documentId,
@@ -48,30 +52,13 @@ export const fieldLevelPatch = async (
 
 export const baseFieldLevelConfig = {
   exportForTranslation: async (
-    ...params: Parameters<ExportForTranslation>
+    docInfo: Parameters<ExportForTranslation>[0],
+    context: Parameters<ExportForTranslation>[1]
   ): Promise<GTSerializedDocument> => {
-    const [docInfo, context, serializationOptions = {}] = params;
-    const baseLanguage = gtConfig.getSourceLocale();
+    const baseLanguage = pluginConfig.getSourceLocale();
     const { client, schema } = context;
-    const stopTypes = [
-      ...(serializationOptions.additionalStopTypes ?? []),
-      ...defaultStopTypes,
-    ];
-    const serializers = {
-      ...customSerializers,
-      types: {
-        ...customSerializers.types,
-        ...(serializationOptions.additionalSerializers ?? {}),
-      },
-    };
     const doc = await findLatestDraft(docInfo.documentId, client);
-    const serialized = BaseDocumentSerializer(schema).serializeDocument(
-      doc,
-      'field',
-      baseLanguage,
-      stopTypes,
-      serializers
-    );
+    const serialized = serializeDocument(doc, schema, baseLanguage);
     return {
       content: serialized.content,
       documentId: docInfo.documentId,
@@ -79,33 +66,14 @@ export const baseFieldLevelConfig = {
     };
   },
   importTranslation: (
-    ...params: Parameters<ImportTranslation>
+    docInfo: Parameters<ImportTranslation>[0],
+    localeId: Parameters<ImportTranslation>[1],
+    document: Parameters<ImportTranslation>[2],
+    context: Parameters<ImportTranslation>[3],
+    mergeWithTargetLocale: boolean = false
   ): Promise<void> => {
-    const [
-      docInfo,
-      localeId,
-      document,
-      context,
-      serializationOptions = {},
-      ,
-      mergeWithTargetLocale,
-    ] = params;
     const { client } = context;
-    const deserializers = {
-      types: {
-        ...(serializationOptions.additionalDeserializers ?? {}),
-      },
-    };
-    const blockDeserializers = [
-      ...(serializationOptions.additionalBlockDeserializers ?? []),
-      ...customBlockDeserializers,
-    ];
-
-    const deserialized = BaseDocumentDeserializer.deserializeDocument(
-      document,
-      deserializers,
-      blockDeserializers
-    ) as SanityDocument;
+    const deserialized = deserializeDocument(document);
     return fieldLevelPatch(
       docInfo,
       deserialized,
@@ -114,5 +82,5 @@ export const baseFieldLevelConfig = {
       mergeWithTargetLocale
     );
   },
-  secretsNamespace: 'translationService',
+  secretsNamespace: 'generaltranslation',
 };

package/src/configuration/utils/checkSerializationVersion.ts

@@ -1,3 +1,5 @@
+// adapted from https://github.com/sanity-io/sanity-translations-tab. See LICENSE.md for more details.
+
 export const checkSerializationVersion = (HTMLdoc: string): string | null => {
   const parser = new DOMParser();
   const node = parser.parseFromString(HTMLdoc, 'text/html');

package/src/configuration/utils/findDocumentAtRevision.ts

@@ -1,3 +1,5 @@
+// adapted from https://github.com/sanity-io/sanity-translations-tab. See LICENSE.md for more details.
+
 import { SanityClient, SanityDocument } from 'sanity';
 
 //revision fetch

package/src/configuration/utils/findLatestDraft.ts

@@ -1,3 +1,5 @@
+// adapted from https://github.com/sanity-io/sanity-translations-tab. See LICENSE.md for more details.
+
 import { SanityClient, SanityDocument } from 'sanity';
 
 //use perspectives in the future

package/src/hooks/useClient.ts

@@ -1,5 +1,7 @@
+// adapted from https://github.com/sanity-io/sanity-translations-tab. See LICENSE.md for more details.
+
 import { SanityClient, useClient as useSanityClient } from 'sanity';
 
 export const useClient = (): SanityClient => {
-  return useSanityClient({ apiVersion: '2022-12-07' });
+  return useSanityClient({ apiVersion: '2025-09-15' });
 };

package/src/hooks/useSecrets.ts

@@ -1,3 +1,5 @@
+// adapted from https://github.com/sanity-io/sanity-translations-tab. See LICENSE.md for more details.
+
 import { useState, useEffect } from 'react';
 import { SanityDocumentLike } from 'sanity';
 import { useClient } from './useClient';

package/src/index.ts

@@ -1,4 +1,4 @@
-import TranslationsTab from './components/TranslationsTab';
+import TranslationsTab from './components/tab/TranslationsTab';
 import {
   Secrets,
   Adapter,
@@ -6,17 +6,8 @@ import {
   ImportTranslation,
   TranslationFunctionContext,
   TranslationsTabConfigOptions,
-  GTFile,
 } from './types';
-import {
-  baseDocumentLevelConfig,
-  legacyDocumentLevelConfig as baseLegacyDocumentLevelConfig,
-  legacyDocumentLevelPatch,
-  baseFieldLevelConfig,
-  findLatestDraft,
-  documentLevelPatch,
-  fieldLevelPatch,
-} from './configuration';
+import { findLatestDraft } from './configuration/utils/findLatestDraft';
 import {
   BaseDocumentSerializer,
   BaseDocumentDeserializer,
@@ -24,7 +15,7 @@ import {
   defaultStopTypes,
   customSerializers,
   SerializedDocument,
-} from 'sanity-naive-html-serializer';
+} from './serialization';
 
 export type {
   Secrets,
@@ -39,63 +30,50 @@ export {
   TranslationsTab,
   //helpers for end developers who may need to customize serialization
   findLatestDraft,
-  legacyDocumentLevelPatch,
-  documentLevelPatch,
-  fieldLevelPatch,
   BaseDocumentSerializer,
   BaseDocumentDeserializer,
   BaseDocumentMerger,
   defaultStopTypes,
   customSerializers,
+  attachGTData,
+  detachGTData,
 };
 
-import { GTAdapter } from './adapter';
 import { definePlugin } from 'sanity';
-import { gt, gtConfig } from './adapter/core';
-import { GTSerializedDocument } from './types';
+import { route } from 'sanity/router';
+import { gt, pluginConfig } from './adapter/core';
 import { libraryDefaultLocale } from 'generaltranslation/internal';
+import type { IgnoreFields, TranslateDocumentFilter } from './adapter/types';
+import TranslationsTool from './components/page/TranslationsTool';
+import { SECRETS_NAMESPACE } from './utils/shared';
+import type { PortableTextHtmlComponents } from '@portabletext/to-html';
+import { attachGTData, detachGTData } from './serialization/data';
 
-interface ConfigOptions {
-  adapter: Adapter;
-  secretsNamespace: string | null;
-  exportForTranslation: (
-    docInfo: GTFile,
-    context: TranslationFunctionContext
-  ) => Promise<GTSerializedDocument>;
-  importTranslation: (
-    docInfo: GTFile,
-    localeId: string,
-    doc: string,
-    context: TranslationFunctionContext
-  ) => Promise<void>;
-}
-
-export const defaultDocumentLevelConfig: ConfigOptions = {
-  ...baseDocumentLevelConfig,
-  adapter: GTAdapter,
-  secretsNamespace: 'generaltranslation',
-};
-
-export const legacyDocumentLevelConfig: ConfigOptions = {
-  ...baseLegacyDocumentLevelConfig,
-  adapter: GTAdapter,
-  secretsNamespace: 'generaltranslation',
+export type GTPluginConfig = Omit<
+  Parameters<typeof gt.setConfig>[0],
+  'locales'
+> & {
+  locales: string[];
+  singletons?: string[];
+  // Optional mapping function to map source document ids to translated singleton document ids
+  // By default, the translated singleton document is is `${sourceDocumentId}-${locale}`
+  singletonMapping?: (sourceDocumentId: string, locale: string) => string;
+  ignoreFields?: IgnoreFields[];
+  languageField?: string;
+  translateDocuments?: TranslateDocumentFilter[];
+  secretsNamespace?: string;
+  additionalStopTypes?: string[];
+  additionalSerializers?: Partial<PortableTextHtmlComponents>;
+  additionalDeserializers?: Record<string, any>;
+  additionalBlockDeserializers?: any[];
 };
 
-export const defaultFieldLevelConfig: ConfigOptions = {
-  ...baseFieldLevelConfig,
-  adapter: GTAdapter,
-  secretsNamespace: 'generaltranslation',
-};
-
-export { GTAdapter };
-
 /**
  * Usage in `sanity.config.ts` (or .js)
  *
  * ```ts
  * import {defineConfig} from 'sanity'
- * import {gtPlugin} from '@generaltranslation/sanity'
+ * import {gtPlugin} from 'gt-sanity'
  *
  * export default defineConfig({
  *   // ...
@@ -103,18 +81,64 @@ export { GTAdapter };
  * })
  * ```
  */
-export const gtPlugin = definePlugin<
-  Omit<Parameters<typeof gt.setConfig>[0], 'locales'> & { locales: string[] }
->(({ sourceLocale, locales, customMapping, apiKey, projectId }) => {
-  gtConfig.setLocales(locales);
-  gtConfig.setSourceLocale(sourceLocale || libraryDefaultLocale);
-  gt.setConfig({
-    sourceLocale: sourceLocale,
-    customMapping: customMapping,
-    apiKey: apiKey,
-    projectId: projectId,
-  });
-  return {
-    name: '@generaltranslation/sanity',
-  };
-});
+export const gtPlugin = definePlugin<GTPluginConfig>(
+  ({
+    languageField = 'language',
+    sourceLocale = libraryDefaultLocale,
+    locales,
+    customMapping,
+    apiKey,
+    projectId,
+    singletons,
+    singletonMapping,
+    ignoreFields,
+    translateDocuments,
+    secretsNamespace = SECRETS_NAMESPACE,
+    additionalStopTypes = [],
+    additionalSerializers = {},
+    additionalDeserializers = {},
+    additionalBlockDeserializers = [],
+  }) => {
+    // Validate the translateDocuments
+    translateDocuments = translateDocuments?.filter((filter) => {
+      if (filter.documentId || filter.type) {
+        return true;
+      }
+      return false;
+    });
+
+    pluginConfig.init(
+      secretsNamespace,
+      languageField,
+      sourceLocale,
+      locales,
+      singletons || [],
+      // singletons is a string array of singleton document ids
+      singletonMapping ||
+        ((sourceDocumentId, locale) => `${sourceDocumentId}-${locale}`),
+      ignoreFields || [],
+      translateDocuments || [],
+      additionalStopTypes,
+      additionalSerializers,
+      additionalDeserializers,
+      additionalBlockDeserializers
+    );
+    gt.setConfig({
+      sourceLocale: sourceLocale,
+      customMapping: customMapping,
+      apiKey: apiKey,
+      projectId: projectId,
+    });
+    return {
+      name: 'gt-sanity',
+      tools: [
+        {
+          name: 'translations',
+          title: 'Translations',
+          component: TranslationsTool,
+          router: route.create('/*'),
+        },
+      ],
+    };
+  }
+);