Setting up your Sanity Connector

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

Step One: Create a Connector Project in Smartling

Step one in setting up a Connector in Smartling is always to set up a Connector Project in Smartling. Read about how to create a Project here.

Only one project in Sanity.io can be connected to Smartling. If you have multiple Sanity.io projects with documents for translation, you will need to create the same amount of Smartling projects and connect each individually.

Prerequisites for Integrating

• Install the Smartling plugin by following the steps in Sanity's documentation. Use the CLI command sanity install smartling
• Ensure Sanity users have read, create, and update permissions enabled (Administer or Read + Write user roles)

Export Sanity Document Configuration

To ensure your Sanity Document configuration and structure is replicated in Smartling, you need to export the configuration from Sanity.

1. Select the Document type
2. Select the source language
3. Click Download Smartling config. No formatting is required for import.

Each time you change the Document structure in Sanity, you will need to follow the steps to export and import the configuration. Note, you do not have to do this each time you create new content within the Document structure.

Connect Sanity to Smartling

1. From your Sanity Connector project, click on the Settings tab > Sanity Settings
2. Click Connect to Sanity
3. Enter the API Token for  (found in Sanity.io)
   • This is the Sanity Project you want to connect to Smartling.
4. Click Connect
5. Choose the Sanity Project name from the dropdown (found in Sanity.io). 
   • The Sanity Project contains datasets and the language configuration schema.
6. Choose the Sanity dataset from the dropdown (found in Sanity.io).
   • This will typically be your production dataset.
7. Click Save

Your Sanity instance will now be connected to your Smartling project.

Import Document Configuration

Once you have authenticated Smarting to connect to your Sanity instance, you need to import your exported Sanity Document configuration. In your Sanity project in Smartling;

1. Click the Settings tab > Sanity Settings

2. Under Import Sanity Configuration, drag and drop or click Select File to top your local drive and select and import the most recent configuration file (.json) to Smartling

Troubleshooting Import

If you receive an error from importing the configuration file, it is likely related to the options you chose when exporting the file. Ensure the correct Document type is selected, along with the correct source language.

Each time you change the Document structure in Sanity, you will need to follow the steps to export and import the configuration. Note, you do not have to do this each time you create new content within the Document structure.

Configure Sanity Connector

The Document structure as seen in your Sanity instance will be present in Smartling once you complete the steps to import and export the Document configuration file. The following are the Connector settings in how you want content ingested and delivered.

General

You can configure your Sanity Studio URL and the behavior of the connector when updates are made to your previously translated content.

1. From within your Smartling Sanity Project, click on Project Settings > Sanity Settings
2. Enter the Sanity Studio URL.
   • Smartling will use this URL as a route to link to any asset in your Sanity Studio via the App Link column in the Sanity Asset List.
3. Click the Automation of Prior Request for Translation dropdown to select your desired behavior.
4. Click Save

Automation of Prior Request for Translation

• Auto: The Sanity Connector will detect changes to source content every 3 hours. Any changes detected to the source content will be submitted to Smartling for translation, batched into a Job and sit in awaiting authorization. However, if auto-authorize is enabled under Smartling Settings, the updated content will be batched into a Job and automatically authorized for translation. Smartling will not detect net new content, only updates to content that have been submitted for translation in the past.
• Manual: The Sanity Connector will detect changes to source content every 3 hours, but will not submit new content for translation. Changed content will be indicated by a checkmark in the Outdated column in the Sanity Progress.
• Disabled: The Sanity Connector will not detect changes to source content or automatically submit new changes.

3 hours is the recommended shortest time duration between checks. Talk to your Solutions Architect about changing the frequency to longer wave periods using cron.

Language Configuration 

1. From within your Smartling Sanity Project, click on Project Settings > Sanity Settings
2. In the Language Configuration section, you will see the number of target languages in your Smartling project, along with the source language in your Smartling project. These details should match dropdown menus with your Sanity target languages.
3. Choose the correct target language from the dropdown menu to map the language in your Sanity language configuration to your Smartling project target language
4. Click Save after mapping each of the target languages.

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

Configure Content Parsing

When Smartling captures content from Sanity, it may process the fields of an entry based on your configuration settings and may break down the individual fields into even smaller strings for translation. This process makes it easier to produce higher quality translations faster.

Parsing Option	Description
Do not translate	Use this if the field shouldn't be translated using Smartling.
Markdown	Parses Markdown tags similar to HTML tags for the best experience by translators and maximum Translation Memory leverage. Use this when your field is likely to have Markdown.
Plain text	All text and characters 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 for the best experience by translators and maximum Translation Memory leverage.  Use this when your field is likely to have HTML markup in it

1. From your Sanity project, click the gear icon and select Project Settings. Then, on the left side, click Sanity Settings.  
2. Under Content Parsing, Entries is the default content selection. Click each fields to expand and choose your preferred parsing option.
3. Click Save.

Smartling Settings

Talk to your Customer Success Manager or Solutions Architect about options on auto-authorization and translation retrieval.

If you choose to integrate a JS library or other visual context tools, consult your Customer Success Manager or Solutions Architect to ensure the default context functionality is disabled. It is enabled by default for the standard visual context.