Sanity (Documents) Connector Overview

Sanity CMS is a cloud-based, headless CMS that helps you manage and organize content for reuse across platforms. It features a user-friendly editor, Sanity Studio, and provides APIs, libraries, and tools for integrating with various technologies. Smartling supports both a field-level and document-level connector for Sanity. The connector you use depends on how you prefer to structure and manage your content within Sanity. 

This documentation is for the Sanity (Documents) Connector. If you are using field-level localization, please refer to the documentation on the Sanity (Fields) Connector. 

Please note that this connector is a paid product. For pricing information, please reach out to your Smartling Customer Success Manager.

Sanity (Fields) vs. Sanity (Documents) 

In a headless CMS like Sanity, you can store and localize content in two different ways: field-level or document-level. 

Field-level localization

• Stores all languages within a single document
• Limited publishing flexibility; requires you to publish content in all languages simultaneously
• Ideal for documents that include a mix of language-specific and common fields

With field-level localization, each translatable field (e.g., title, description, CTA) is localized individually within the same document. For example, a document might contain fields like title.en, title.fr, and title.de. This approach allows for granular control over what content gets translated, and keeps all language versions in a single entry.

Document-level localization

• Creates a separate document with a unique ID for each language version
• Greater flexibility in managing and publishing each language independently 
• References link language versions together 

With document-level localization, a separate document is created for each language version. For example, you would have one document for English, another for French, and another for German, each containing a full set of content. 

The best approach depends on your preferred content strategy and how much flexibility you need when managing and publishing localized content. Please refer to the Sanity documentation for more details. 

How it works

Smartling’s Sanity Connector offers a seamless way to localize your Sanity content. Content from your Sanity.io datastore can be requested for translation within the Smartling dashboard and is automatically delivered back to Sanity Studio once complete. 

Supported content types

The connector currently ingests all assets and related assets up to five levels deep within the following Sanity content types:

• Documents

Images and video files are not supported content types for translation.

Limitations 

• The connector cannot import or reuse any existing translations in Sanity.
• The connector follows Sanity's document-level localization approach, but is not compatible with Sanity-developed plugins. Specifically, the connector is not compatible with the Document Internalization or Sanity Studio Smartling plugins. You can use either Smartling's Sanity connector or Sanity's plugins, but not both at the same time. 

Sanity asset list 

Once you have connected your Sanity account, your Sanity content will appear in the Sanity tab of your Smartling project.

The asset list includes the following columns: 

• Title: The title of the asset in Sanity.
• Status (Smartling): The asset's translation status in Smartling.
• Content Type: The Sanity content type.
• Modified (Sanity): The date the asset was last modified in Sanity. 
• Created: The date the asset was created in Sanity.

When your Sanity content is pulled into Smartling for translation, it is imported as a JSON file. Each asset listed in your asset list corresponds to a JSON file in Smartling that contains the content for that item. Once translations for an asset are completed for a locale, the connector delivers the translations back to Sanity. 

The file name in Smartling follows this format:
Asset Name-DOCUMENT~Content Type~Document ID.json

Asset details

Click the information icon beside the asset name to access the Asset Details page. Here, you can view additional information about the asset, including the translation status for each language. From this page, you can also Request Translation and Export Translations for the selected asset. 



If you click on the name of a target locale from the Asset Details page, you can view the asset's content in the Strings View. 

Search & filters

When you navigate to the Sanity asset list via the project's Sanity tab, you can view all assets pulled in from Sanity. On the left side of the page, you will find several filters including: 

Sanity filters

• Content Type: Filter by Sanity content type. 
• Date Modified: The date the asset was last modified in Sanity. 
• Date Created: The date the asset was created in Sanity. 
• Asset IDs: Unique identifier for an asset, which can be found under the title. You can search for multiple IDs at a time, simply enter a comma separated list of IDs in the search field. 
  
• Search: Allows you to search by asset title. You can only search for one asset at a time; comma-separated search is not supported. 

Smartling filters 

• Smartling Status: 
  Completed - Translations were successfully delivered from Smartling to Sanity.
  Failed - The asset submission failed, or the translation delivery failed. 
  In Progress - The asset has been successfully sent to Smartling from Sanity, and the translation process has commenced but is not yet completed. 
  Not Translated - The asset has never been submitted for translation.
  Translated - The asset was translated, but translations have not been delivered. 
• Language:
  Filter by target language. 

Sort

At the top right of the page, you can filter by last modified date.