@braze/sanity-plugin-ai-translation 0.3.0 → 0.3.2

package/README.md

@@ -64,7 +64,7 @@ Your Studio must already support internationalized documents.
 
 Required:
 
-- **Sanity Studio v4** (plugin is built for Sanity Studio v4)
+- **Sanity Studio v6.12 or newer** with `@sanity/ui` v4, React 19.2+, and Node.js 22.12+ (the plugin invokes Sanity Functions through Studio's client, which needs `@sanity/client` 8.3+; Studio 6.12 is the first release that bundles it)
 - `@sanity/document-internationalization` configured
 - `sanity-plugin-internationalized-array` installed and configured (used for glossary term translations)
 - `@sanity/client` **7.1.0+** (required for Agent Actions)
@@ -159,6 +159,7 @@ export default defineConfig({
 
 - `schemaId` is usually `'_.schemas.default'` for most projects.
 - `languageFieldName` must match the field your documents use (often `language`).
+- `glossaryDataset` (optional) reads glossary terms from another dataset in the same project. See [`translationGlossaryTerm`](#translationglossaryterm).
 
 ### 3) Add translation history metadata
 
@@ -247,9 +248,16 @@ aiTranslationPlugin({
 The plugin exposes a server-only entry at `@braze/sanity-plugin-ai-translation/server` for running the OpenAI call outside the browser (for example in a Sanity function). It does not load React or Studio, it is not part of the Studio bundle, and it does not read the API key from the environment, so the caller passes it in.
 
 ```typescript
-import { requestOpenAICompletion } from "@braze/sanity-plugin-ai-translation/server";
+import {
+  isOpenAIModel,
+  OPENAI_MODELS,
+  requestOpenAICompletion,
+} from "@braze/sanity-plugin-ai-translation/server";
 
 // payload: { model, messages, reasoningEffort?, temperature? } assembled in Studio
+if (!isOpenAIModel(payload.model)) {
+  throw new Error(`model must be one of ${OPENAI_MODELS.join(", ")}`);
+}
 const { content, tokensUsed } = await requestOpenAICompletion(payload, {
   apiKey: process.env.OPENAI_API_KEY!,
 });
@@ -261,7 +269,7 @@ The first argument is the client-supplied request and is validated at runtime. T
 - Only `role` and `content` are sent for each message. Any other fields in the payload are dropped.
 - Logs never include prompt or document text, even with plugin logging turned on. They include only the model, message roles, and content lengths.
 
-Serialization, prompt assembly, structure validation, and the Content Release write stay in Studio. The entry does not allowlist models. Do that in the caller before invoking it.
+Serialization, prompt assembly, structure validation, and the Content Release write stay in Studio. The entry does not allowlist models on its own. Do that in the caller before invoking it, with `isOpenAIModel` (or `OPENAI_MODELS`): it is the same list the `openai.model` plugin option accepts, so Studio and the function never disagree about which models are allowed.
 
 ---
 
@@ -382,6 +390,19 @@ Conceptual example:
 
 Glossary terms are used to build locale-specific translation instructions.
 
+By default, glossary terms are read from the dataset of the document being translated. To share one glossary across datasets, set `glossaryDataset` to another dataset in the same project:
+
+```typescript
+aiTranslationPlugin({
+  // ...
+  glossaryDataset: "production",
+});
+```
+
+- Terms are read with the editor's existing Studio session, so editors need read access to that dataset.
+- Only glossary terms come from `glossaryDataset`. `translationSettings` (global prompt, locale prompts, protected phrases) is still read from the document's dataset.
+- Nothing is written to either dataset's glossary.
+
 ---
 
 ## Advanced configuration

package/dist/index.d.ts

@@ -1,9 +1,5 @@
-import { ArrayDefinition } from "sanity";
-import { FieldDefinitionBase } from "sanity";
 import { Plugin as Plugin_2 } from "sanity";
 import type { SanityDocument } from "sanity";
-import { WidenInitialValue } from "sanity";
-import { WidenValidation } from "sanity";
 
 /**
  * AI translation plugin for Sanity Studio
@@ -269,6 +265,26 @@ export declare type InferOriginalType<T> =
 export declare type InferTranslatableType<T> =
   T extends FieldTransform<unknown, infer R> ? R : never;
 
+/**
+ * OpenAI models the plugin supports.
+ *
+ * This is the single source of truth: Studio's `PluginConfig['openai']['model']` is derived from
+ * it, and the translation function allowlists against it before calling `requestOpenAICompletion`,
+ * so the two can never drift apart.
+ *
+ * @public
+ */
+declare const OPENAI_MODELS: readonly [
+  "gpt-5.1",
+  "gpt-5",
+  "gpt-5-mini",
+  "gpt-5-nano",
+  "gpt-5-pro",
+  "gpt-4o",
+  "gpt-4-turbo",
+  "gpt-4",
+];
+
 /**
  * Event emitted when an OpenAI API call is made
  * @public
@@ -288,6 +304,13 @@ declare interface OpenAIApiCallEvent extends TelemetryEventBase {
   };
 }
 
+/**
+ * An OpenAI model id from {@link OPENAI_MODELS}
+ *
+ * @public
+ */
+export declare type OpenAIModel = (typeof OPENAI_MODELS)[number];
+
 /**
  *
  * Configuration for the Sanity AI Translation plugin.
@@ -310,22 +333,18 @@ export declare interface PluginConfig {
    * Requires `@sanity/client` 8.1 or newer as Studio's client.
    */
   openai?: {
-    /** Blueprint stack that contains the translation function, e.g. `ST-bfgaj9tnk7`. Required for OpenAI mode. */
+    /** Blueprint stack that contains the translation function, e.g. `ST-xxxxxxxxxx`. Required for OpenAI mode. */
     stackId: string;
     /**
      * Name of the translation function, as declared in the blueprint.
      * @defaultValue 'ai-translation'
      */
     functionName?: string;
-    model?:
-      | "gpt-5.1"
-      | "gpt-5"
-      | "gpt-5-mini"
-      | "gpt-5-nano"
-      | "gpt-5-pro"
-      | "gpt-4o"
-      | "gpt-4-turbo"
-      | "gpt-4";
+    /**
+     * OpenAI model id. Must be one of `OPENAI_MODELS` from the server entry.
+     * @defaultValue 'gpt-5'
+     */
+    model?: OpenAIModel;
     reasoningEffort?: "low" | "medium" | "high";
     enabled?: boolean;
     defaultMode?: TranslationMode;
@@ -362,6 +381,17 @@ export declare interface PluginConfig {
    * ```
    */
   unsetFields?: UnsetFieldEntry[];
+  /**
+   * Dataset (in the same project) to read `translationGlossaryTerm` documents from.
+   * Defaults to the dataset of the document being translated.
+   * Translation settings and locale prompts are always read from the document's dataset.
+   *
+   * @example
+   * ```typescript
+   * glossaryDataset: 'production'
+   * ```
+   */
+  glossaryDataset?: string;
   /**
    * Optional telemetry configuration for monitoring translation operations.
    * Provides callbacks for lightweight events and detailed error bundles.
@@ -684,12 +714,51 @@ declare type TranslationErrorType =
  * @public
  */
 export declare const translationHistorySchema: {
-  type: "array";
   name: "translationHistory";
-} & Omit<ArrayDefinition, "preview"> &
-  FieldDefinitionBase &
-  WidenValidation &
-  WidenInitialValue;
+  type: "array";
+  of: {
+    name: string;
+    type: "object";
+    fields: (
+      | {
+          name: "language";
+          title: string;
+          description: string;
+          type: "string";
+        }
+      | {
+          name: "sourceId";
+          title: string;
+          description: string;
+          type: "string";
+        }
+      | {
+          name: "sourceRev";
+          title: string;
+          description: string;
+          type: "string";
+        }
+      | {
+          name: "sourceLanguage";
+          title: string;
+          description: string;
+          type: "string";
+        }
+      | {
+          name: "sourceSnapshot";
+          title: string;
+          description: string;
+          type: "text";
+        }
+      | {
+          name: "targetId";
+          title: string;
+          description: string;
+          type: "string";
+        }
+    )[];
+  }[];
+};
 
 /**
  * Event emitted when an individual translation job completes successfully