sanity-plugin-media 4.1.0 → 4.2.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Sanity.io
+Copyright (c) 2026 Sanity.io
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -95,7 +95,6 @@ export default defineConfig({
 })
 ```
 
-
 ### Plugin Config
 
 ```ts
@@ -111,7 +110,7 @@ export default defineConfig({
         enabled: true,
         // boolean - enables an optional "Credit Line" field in the plugin.
         // Used to store credits e.g. photographer, licence information
-        excludeSources: ['unsplash'],
+        excludeSources: ['unsplash']
         // string | string[] - when used with 3rd party asset sources, you may
         // wish to prevent users overwriting the creditLine based on the `source.name`
       },
@@ -122,13 +121,66 @@ export default defineConfig({
       components: {
         details: CustomDetails
         // Custom component for asset details (see below)
-      }
+      },
       // Custom components to override default UI (see below)
+      locales: [
+        // { id: string, title: string, ...extra }[] - enable localization for asset fields. Each object must have a unique id and a human-readable title.
+        // When set, all localizable fields (title, altText, description, creditLine) will be shown in tabs by language.
+        {id: 'en', title: 'English'},
+        {id: 'it', title: 'Italian'},
+        {id: 'es', title: 'Spanish'},
+        {id: 'fr', title: 'French'},
+        {id: 'de', title: 'German'},
+        {id: 'pt', title: 'Portuguese'},
+        {id: 'ja', title: 'Japanese'},
+        {id: 'zh', title: 'Chinese'},
+        {id: 'ru', title: 'Russian'},
+        {id: 'ar', title: 'Arabic'}
+      ]
     })
-  ],
+  ]
 })
 ```
 
+### Localization (Optional)
+
+You can enable localization support by passing a `locales` array to the plugin config, following the [Sanity recommended scheme](https://www.sanity.io/docs/studio/localization#k4da239411955):
+
+If omitted, localization features will be disabled and the plugin will work as usual.
+
+**Fallback for missing translations:**
+The plugin does not apply any automatic fallback for missing translations. You can decide how to handle this in your queries or frontend logic. For example, to show the default language if a translation is missing, you can use GROQ's `coalesce()`:
+
+```
+coalesce(altText.it, altText.en)
+```
+
+**UI note:**
+When `locales` are provided, all localized fields (title, altText, description, creditLine) are grouped by language in tabs. Each tab shows all fields for a single language, making it easy to edit translations for many languages in a compact interface.
+
+This will return the Italian value if present, otherwise English, otherwise French, etc. Adjust the order as needed for your project.
+
+#### Migrating existing assets to localized format
+
+If you enable `locales` on a project that already has assets with plain string fields (e.g. `title: "My photo"`), you should run the provided migration script to convert those fields to the localized object format (e.g. `title: {en: "My photo"}`).
+
+**1. Edit the script** — open `scripts/migrate-to-localized-fields.ts` and set `DEFAULT_LOCALE_ID` to the locale id that your existing values should be mapped to.
+
+**2. Run the migration:**
+
+```sh
+npx sanity@latest migration run scripts/migrate-to-localized-fields.ts \
+  --project <projectId> --dataset <dataset>
+```
+
+The script targets `sanity.imageAsset` and `sanity.fileAsset` documents and converts any plain string value in `title`, `altText`, `description`, and `creditLine` to `{[DEFAULT_LOCALE_ID]: value}`. Fields that are already in object format are left untouched.
+
+> **Without migration:** Legacy string fields can also be migrated when an asset is edited and saved in the plugin. Running the script is still recommended to migrate all existing assets consistently before users start editing.
+
+#### Removing locales
+
+If you remove the `locales` option after assets have been saved in localized format, the plugin will show a warning in the asset edit dialog offering a **"Cleanup localized fields"** action. Clicking it removes locale keys that are no longer configured and, if no locales remain, flattens the fields back to plain strings.
+
 #### Custom Asset Details Component
 
 Custom React component for the asset details form via the plugin config. This allows you to override or extend the default asset details UI.

package/dist/index.d.mts

@@ -14,13 +14,73 @@ import * as z from 'zod'
 
 declare type Asset = FileAsset | ImageAsset
 
-declare type AssetFormData = z.infer<typeof assetFormSchema>
+declare type AssetFormData = z.infer<ReturnType<typeof getAssetFormSchema>>
 
-declare const assetFormSchema: z.ZodObject<
+declare type CustomFields = {
+  altText?: LocalizedString
+  description?: LocalizedString
+  opt?: {
+    media?: {
+      tags?: SanityReference[]
+    }
+  }
+  title?: LocalizedString
+}
+
+declare type DetailsProps = {
+  formUpdating: boolean
+  handleCreateTag: (title: string) => void
+  control: Control<AssetFormData>
+  errors: FieldErrors<AssetFormData>
+  register: UseFormRegister<AssetFormData>
+  allTagOptions: TagSelectOption[]
+  assetTagOptions: TagSelectOption[] | null
+  currentAsset: Asset
+  creditLine?: {
+    enabled: boolean
+    excludeSources?: string | string[] | undefined
+  }
+  locales?: Locale_2[]
+}
+
+declare type FileAsset = SanityAssetDocument &
+  CustomFields & {
+    _type: 'sanity.fileAsset'
+  }
+
+declare function getAssetFormSchema(
+  locales?: {
+    id: string
+  }[]
+): z.ZodObject<
   {
-    altText: z.ZodOptional<z.ZodString>
-    creditLine: z.ZodOptional<z.ZodString>
-    description: z.ZodOptional<z.ZodString>
+    altText:
+      | z.ZodOptional<z.ZodString>
+      | z.ZodObject<
+          Record<string, z.ZodTypeAny>,
+          'passthrough',
+          z.ZodTypeAny,
+          z.objectOutputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>,
+          z.objectInputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>
+        >
+    creditLine:
+      | z.ZodOptional<z.ZodString>
+      | z.ZodObject<
+          Record<string, z.ZodTypeAny>,
+          'passthrough',
+          z.ZodTypeAny,
+          z.objectOutputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>,
+          z.objectInputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>
+        >
+    description:
+      | z.ZodOptional<z.ZodString>
+      | z.ZodObject<
+          Record<string, z.ZodTypeAny>,
+          'passthrough',
+          z.ZodTypeAny,
+          z.objectOutputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>,
+          z.objectInputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>
+        >
     opt: z.ZodObject<
       {
         media: z.ZodObject<
@@ -35,12 +95,12 @@ declare const assetFormSchema: z.ZodObject<
                   'strip',
                   z.ZodTypeAny,
                   {
-                    label: string
                     value: string
+                    label: string
                   },
                   {
-                    label: string
                     value: string
+                    label: string
                   }
                 >,
                 'many'
@@ -52,16 +112,16 @@ declare const assetFormSchema: z.ZodObject<
           {
             tags:
               | {
-                  label: string
                   value: string
+                  label: string
                 }[]
               | null
           },
           {
             tags:
               | {
-                  label: string
                   value: string
+                  label: string
                 }[]
               | null
           }
@@ -73,8 +133,8 @@ declare const assetFormSchema: z.ZodObject<
         media: {
           tags:
             | {
-                label: string
                 value: string
+                label: string
               }[]
             | null
         }
@@ -83,15 +143,23 @@ declare const assetFormSchema: z.ZodObject<
         media: {
           tags:
             | {
-                label: string
                 value: string
+                label: string
               }[]
             | null
         }
       }
     >
     originalFilename: z.ZodString
-    title: z.ZodOptional<z.ZodString>
+    title:
+      | z.ZodOptional<z.ZodString>
+      | z.ZodObject<
+          Record<string, z.ZodTypeAny>,
+          'passthrough',
+          z.ZodTypeAny,
+          z.objectOutputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>,
+          z.objectInputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>
+        >
   },
   'strip',
   z.ZodTypeAny,
@@ -100,74 +168,75 @@ declare const assetFormSchema: z.ZodObject<
       media: {
         tags:
           | {
-              label: string
               value: string
+              label: string
             }[]
           | null
       }
     }
     originalFilename: string
-    altText?: string | undefined
-    creditLine?: string | undefined
-    description?: string | undefined
-    title?: string | undefined
+    altText?:
+      | string
+      | z.objectOutputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>
+      | undefined
+    creditLine?:
+      | string
+      | z.objectOutputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>
+      | undefined
+    description?:
+      | string
+      | z.objectOutputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>
+      | undefined
+    title?:
+      | string
+      | z.objectOutputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>
+      | undefined
   },
   {
     opt: {
       media: {
         tags:
           | {
-              label: string
               value: string
+              label: string
             }[]
           | null
       }
     }
     originalFilename: string
-    altText?: string | undefined
-    creditLine?: string | undefined
-    description?: string | undefined
-    title?: string | undefined
+    altText?:
+      | string
+      | z.objectInputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>
+      | undefined
+    creditLine?:
+      | string
+      | z.objectInputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>
+      | undefined
+    description?:
+      | string
+      | z.objectInputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>
+      | undefined
+    title?:
+      | string
+      | z.objectInputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>
+      | undefined
   }
 >
 
-declare type CustomFields = {
-  altText?: string
-  description?: string
-  opt?: {
-    media?: {
-      tags?: SanityReference[]
-    }
-  }
-  title?: string
-}
-
-declare type DetailsProps = {
-  formUpdating: boolean
-  handleCreateTag: (title: string) => void
-  control: Control<AssetFormData>
-  errors: FieldErrors<AssetFormData>
-  register: UseFormRegister<AssetFormData>
-  allTagOptions: TagSelectOption[]
-  assetTagOptions: TagSelectOption[] | null
-  currentAsset: Asset
-  creditLine?: {
-    enabled: boolean
-    excludeSources?: string | string[] | undefined
-  }
-}
-
-declare type FileAsset = SanityAssetDocument &
-  CustomFields & {
-    _type: 'sanity.fileAsset'
-  }
-
 declare type ImageAsset = SanityImageAssetDocument &
   CustomFields & {
     _type: 'sanity.imageAsset'
-    creditLine?: string
+    creditLine?: LocalizedString
   }
 
+declare type Locale_2 = {
+  title: string
+  id: string
+  [key: string]: unknown
+}
+
+declare type LocalizedString = string | Record<string, string>
+
 export declare const media: Plugin_2<void | MediaToolOptions>
 
 export declare const mediaAssetSource: {
@@ -188,11 +257,16 @@ export declare type MediaToolOptions = {
       }
     >
   }
-  creditLine: {
+  creditLine?: {
     enabled: boolean
     excludeSources?: string | string[]
   }
   directUploads?: boolean
+  /**
+   * Optional locales following Sanity recommended scheme: [{ id, title }]
+   * https://www.sanity.io/docs/studio/localization#k4da239411955
+   */
+  locales?: Locale_2[]
 }
 
 declare type SanityReference = {
@@ -209,12 +283,12 @@ declare const tagOptionSchema: z.ZodObject<
   'strip',
   z.ZodTypeAny,
   {
-    label: string
     value: string
+    label: string
   },
   {
-    label: string
     value: string
+    label: string
   }
 >
 

package/dist/index.d.ts

@@ -14,13 +14,73 @@ import * as z from 'zod'
 
 declare type Asset = FileAsset | ImageAsset
 
-declare type AssetFormData = z.infer<typeof assetFormSchema>
+declare type AssetFormData = z.infer<ReturnType<typeof getAssetFormSchema>>
 
-declare const assetFormSchema: z.ZodObject<
+declare type CustomFields = {
+  altText?: LocalizedString
+  description?: LocalizedString
+  opt?: {
+    media?: {
+      tags?: SanityReference[]
+    }
+  }
+  title?: LocalizedString
+}
+
+declare type DetailsProps = {
+  formUpdating: boolean
+  handleCreateTag: (title: string) => void
+  control: Control<AssetFormData>
+  errors: FieldErrors<AssetFormData>
+  register: UseFormRegister<AssetFormData>
+  allTagOptions: TagSelectOption[]
+  assetTagOptions: TagSelectOption[] | null
+  currentAsset: Asset
+  creditLine?: {
+    enabled: boolean
+    excludeSources?: string | string[] | undefined
+  }
+  locales?: Locale_2[]
+}
+
+declare type FileAsset = SanityAssetDocument &
+  CustomFields & {
+    _type: 'sanity.fileAsset'
+  }
+
+declare function getAssetFormSchema(
+  locales?: {
+    id: string
+  }[]
+): z.ZodObject<
   {
-    altText: z.ZodOptional<z.ZodString>
-    creditLine: z.ZodOptional<z.ZodString>
-    description: z.ZodOptional<z.ZodString>
+    altText:
+      | z.ZodOptional<z.ZodString>
+      | z.ZodObject<
+          Record<string, z.ZodTypeAny>,
+          'passthrough',
+          z.ZodTypeAny,
+          z.objectOutputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>,
+          z.objectInputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>
+        >
+    creditLine:
+      | z.ZodOptional<z.ZodString>
+      | z.ZodObject<
+          Record<string, z.ZodTypeAny>,
+          'passthrough',
+          z.ZodTypeAny,
+          z.objectOutputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>,
+          z.objectInputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>
+        >
+    description:
+      | z.ZodOptional<z.ZodString>
+      | z.ZodObject<
+          Record<string, z.ZodTypeAny>,
+          'passthrough',
+          z.ZodTypeAny,
+          z.objectOutputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>,
+          z.objectInputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>
+        >
     opt: z.ZodObject<
       {
         media: z.ZodObject<
@@ -35,12 +95,12 @@ declare const assetFormSchema: z.ZodObject<
                   'strip',
                   z.ZodTypeAny,
                   {
-                    label: string
                     value: string
+                    label: string
                   },
                   {
-                    label: string
                     value: string
+                    label: string
                   }
                 >,
                 'many'
@@ -52,16 +112,16 @@ declare const assetFormSchema: z.ZodObject<
           {
             tags:
               | {
-                  label: string
                   value: string
+                  label: string
                 }[]
               | null
           },
           {
             tags:
               | {
-                  label: string
                   value: string
+                  label: string
                 }[]
               | null
           }
@@ -73,8 +133,8 @@ declare const assetFormSchema: z.ZodObject<
         media: {
           tags:
             | {
-                label: string
                 value: string
+                label: string
               }[]
             | null
         }
@@ -83,15 +143,23 @@ declare const assetFormSchema: z.ZodObject<
         media: {
           tags:
             | {
-                label: string
                 value: string
+                label: string
               }[]
             | null
         }
       }
     >
     originalFilename: z.ZodString
-    title: z.ZodOptional<z.ZodString>
+    title:
+      | z.ZodOptional<z.ZodString>
+      | z.ZodObject<
+          Record<string, z.ZodTypeAny>,
+          'passthrough',
+          z.ZodTypeAny,
+          z.objectOutputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>,
+          z.objectInputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>
+        >
   },
   'strip',
   z.ZodTypeAny,
@@ -100,74 +168,75 @@ declare const assetFormSchema: z.ZodObject<
       media: {
         tags:
           | {
-              label: string
               value: string
+              label: string
             }[]
           | null
       }
     }
     originalFilename: string
-    altText?: string | undefined
-    creditLine?: string | undefined
-    description?: string | undefined
-    title?: string | undefined
+    altText?:
+      | string
+      | z.objectOutputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>
+      | undefined
+    creditLine?:
+      | string
+      | z.objectOutputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>
+      | undefined
+    description?:
+      | string
+      | z.objectOutputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>
+      | undefined
+    title?:
+      | string
+      | z.objectOutputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>
+      | undefined
   },
   {
     opt: {
       media: {
         tags:
           | {
-              label: string
               value: string
+              label: string
             }[]
           | null
       }
     }
     originalFilename: string
-    altText?: string | undefined
-    creditLine?: string | undefined
-    description?: string | undefined
-    title?: string | undefined
+    altText?:
+      | string
+      | z.objectInputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>
+      | undefined
+    creditLine?:
+      | string
+      | z.objectInputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>
+      | undefined
+    description?:
+      | string
+      | z.objectInputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>
+      | undefined
+    title?:
+      | string
+      | z.objectInputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>
+      | undefined
   }
 >
 
-declare type CustomFields = {
-  altText?: string
-  description?: string
-  opt?: {
-    media?: {
-      tags?: SanityReference[]
-    }
-  }
-  title?: string
-}
-
-declare type DetailsProps = {
-  formUpdating: boolean
-  handleCreateTag: (title: string) => void
-  control: Control<AssetFormData>
-  errors: FieldErrors<AssetFormData>
-  register: UseFormRegister<AssetFormData>
-  allTagOptions: TagSelectOption[]
-  assetTagOptions: TagSelectOption[] | null
-  currentAsset: Asset
-  creditLine?: {
-    enabled: boolean
-    excludeSources?: string | string[] | undefined
-  }
-}
-
-declare type FileAsset = SanityAssetDocument &
-  CustomFields & {
-    _type: 'sanity.fileAsset'
-  }
-
 declare type ImageAsset = SanityImageAssetDocument &
   CustomFields & {
     _type: 'sanity.imageAsset'
-    creditLine?: string
+    creditLine?: LocalizedString
   }
 
+declare type Locale_2 = {
+  title: string
+  id: string
+  [key: string]: unknown
+}
+
+declare type LocalizedString = string | Record<string, string>
+
 export declare const media: Plugin_2<void | MediaToolOptions>
 
 export declare const mediaAssetSource: {
@@ -188,11 +257,16 @@ export declare type MediaToolOptions = {
       }
     >
   }
-  creditLine: {
+  creditLine?: {
     enabled: boolean
     excludeSources?: string | string[]
   }
   directUploads?: boolean
+  /**
+   * Optional locales following Sanity recommended scheme: [{ id, title }]
+   * https://www.sanity.io/docs/studio/localization#k4da239411955
+   */
+  locales?: Locale_2[]
 }
 
 declare type SanityReference = {
@@ -209,12 +283,12 @@ declare const tagOptionSchema: z.ZodObject<
   'strip',
   z.ZodTypeAny,
   {
-    label: string
     value: string
+    label: string
   },
   {
-    label: string
     value: string
+    label: string
   }
 >