Setting Up Your Sanity (Documents) Connector

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

Prerequisites and notes on the translation process 

Before setting up the Sanity (Documents) Connector, it’s important to understand how translated documents are created and managed.

Data model

Below is an example of how three English documents will be translated into French. The same set of translated documents will be created for each target language. For example, if you have 100 source documents and translate them into three target languages, you will end up with a total of 400 documents. 

Required schema configuration 

Your development team must add a new string field called language to your Sanity document schemas. This field is used by the connector to establish relationships between source documents and their translated counterparts. 

How translated documents are created

The connector creates translated documents using a specific ID pattern based on the source document ID and the language code. 

Translated document ID pattern:
<source document ID>-<language code>

For example, if your configuration includes French (France) [fr-FR] and German (Germany) [de-DE], and your source document ID is abc, the translated document IDs will be:

• abc-fr-FR for French
• abc-de-DE for German

Additional details:

• The connector does not save any additional metadata in your Sanity documents/storage. 
• Translated documents are created by:
  1. Cloning the source document 
  2. Assigning a new ID using the pattern described above
  3. Populating the language field with the appropriate locale code (e.g., fr-FR, de-DE)
  4. Copying over all field values, both localizable and non-localizable from the source document into the translated version

As a result, each translated document contains a snapshot of the original document's content at the time of translation. 

Step 1: Create a dedicated Smartling project for the connector

You must create one dedicated Smartling project per Sanity.io project. If you have multiple Sanity projects with documents for translation, you will need to create a separate Smartling project for each one.

1. Create a new project in Smartling. 
2. Select the project type "Connector".
3. Select "Sanity (Documents)" as your connecting platform. 
4. Choose your desired source and target locales. 

Once the project has been created, ensure that all workflows, linguistic assets, and team members are set up correctly. In particular, we recommend checking that the default workflows for all of your target languages are set up according to your preferences. If auto-authorization is enabled in your Smartling settings, these workflows will be used automatically for all translation requests through the connector. 

Step 2: Install the Smartling plugin to export the document schema 

Install the Smartling plugin by following the steps in Sanity's documentation. Use the CLI command:

sanity install smartling

Export Sanity document configuration

To replicate your Sanity document structure in Smartling, you will need to export your configuration from Sanity. 

1. Select the document type
2. Select the source language
3. Click Download Smartling config. This will export a JSON file that you will later import into Smartling. No special formatting is required. 

Note: If you update your document structure in Sanity, you must export and re-import the configuration file. However, this step is not required each time you add new content within the existing structure.

Step 3: Connect Sanity to Smartling

To connect your Sanity environment to Smartling, you'll need a Sanity API token. 

To create a Sanity API token: 

1. Go to the Sanity Management Console and select your project.
2. Navigate to the API tab. 
3. Under Tokens, click Add new token. 
4. Name your token and ensure it has read and write permissions. 

For more information, please refer to the Sanity documentation. 

Next, use the API token to connect your Sanity project to Smartling: 

1. In your Sanity Connector project, click on the Settings tab > Sanity Settings
2. Click Connect to Sanity Documents
   
   
3. Enter the API Token for your Sanity project and click Save Connection. 
4. Choose the Sanity Project name from the dropdown.  
5. Choose the Sanity dataset from the dropdown.
   • This will typically be your production dataset.
6. Select an upload option: draft or published.
   • This controls which version (Draft or Published) will be ingested into Smartling as the source for translation.
7. Click Save Connection.
8. Next, a window will appear prompting you to import your Sanity documents configuration file. Drag and drop the file, or click Select File to upload the JSON file.
9. Once the file is imported, the connection will be saved automatically, and you’ll be redirected back to the connector settings page.

Troubleshooting import

If you receive an import error, verify that you selected the correct document type and source language when exporting the config file from Sanity. 

Note: Please remember, if you update your document structure in Sanity, you must export and re-import the configuration file. However, this step is not required each time you add new content within the existing structure.

Step 4: Configure the Sanity (Documents) Connector

Once you have successfully connected your Sanity environment to Smartling, complete the following configurations within the Sanity Settings page by navigating to the project > Settings tab > Sanity Documents Settings. 

• General
• Language Configuration
• Content Parsing 
• Smartling Settings

General 

Automation of Prior Requests for Translation 

This setting controls how you want the connector to monitor changes to content that has already been requested for translation in Smartling. 

Options include: 

• Auto: The connector will detect changes to previously submitted source content every three hours. Any detected updates are batched into a Job and sit in awaiting authorization. However, if auto-authorize is enabled under Smartling Settings, the updated content is automatically authorized for translation. This feature does not detect content in new assets—only updates to content from assets previously submitted for translation. In other words, if an asset is brand new and has never been requested for translation, its content will not be picked up by this automation. See additional details here. 
• Manual: The connector checks for changes to source content every 3 hours but does not automatically submit updates for translation.
• Disabled: The connector does not check for changes to source content.

Three hours is the shortest recommended duration between checks. Consult your Solution Architect to adjust the frequency to a longer interval using cron. 

Delivery Options

• Never publish: When the completed translations are delivered, they are delivered in draft state and are not published automatically. 
• Always publish: Smartling will publish an asset after successful delivery, even if the asset was in a draft state as a source.
• Smart publish: This option ensures the connector will match the asset's current status upon translation delivery. It will respect the original publishing state. Drafts remain drafts, and published assets are republished. 

Upload Options 

This setting controls which version of the asset (Draft or Published) is ingested and used as the source for translation.

Be sure to click the Save button after updating any settings. 

Language Configuration 

In the Language Configuration section, you will see the target languages for the project. The first time you open this page, you will find a blank field to the left of each of the Smartling target languages. For each Smartling target language, select the appropriate Sanity language from the dropdown menu.

Click the checkmark to save each mapping. 

Any language left blank will not appear in the list of target languages when requesting content for translation in Smartling. 

You cannot map a Smartling language to more than one Sanity language. 

Each time you add a new language to the project, you must map that language in the connector settings.

1. From within your Sanity project, click on the Settings tab > Sanity Documents Settings. 
2. Select the appropriate language from the dropdown menu. 
3. Click the checkmark to save each mapping. 
   
   

Content Parsing

When Smartling ingests content from Sanity, it processes the content based on your configuration settings and may break down the individual fields into even smaller strings for translation. This process is called content parsing. You can configure this parsing behavior: 

1. From within your Sanity project, click on the Settings tab > Sanity Documents Settings.
2. Under Content Parsing, Documents is the default content selection. Click each field to expand and choose your preferred parsing option.
3. Click Save.

Parsing Option	Description
Copy source	Source content is copied directly into the translation.
Do not translate	Use this option if the field should not be translated.
Plain text	All text and characters are treated as plain text. Use this for fields that you expect to only have plain text with no markup or formatting.
HTML	Parses the field’s HTML tags to improve translation memory leverage and the translator experience in the CAT Tool. Use this option for fields that are likely to contain HTML markup.

 

Smartling settings

Talk to your Customer Success Manager or Solution Architect about options regarding auto-authorization, translation retrieval type, file versioning, and capturing custom placeholders. For more details, see the information linked here. 

 

Now, you're ready to start Translating with the Sanity (Documents) Connector.