Understanding Content Parsing in Sanity: Do Not Translate vs. Copy Source

This article explains how different content parsing options affect your translated documents in Sanity, particularly when source documents are updated after initial translation.

This article only applies to document-level translation, including the Sanity (Documents) Connector, and other document-level connectors such as the Contentful (Entries) Connector.

Overview

When configuring field parsing in the Sanity Documents Connector, two options can cause confusion: "Do not translate" and "Copy source". While both options prevent fields from being sent to the Smartling TMS for translation, they behave differently when source documents are updated.

Key concepts

How the connector works

1. Initial translation: The connector creates a complete copy of the source document with a new ID, then overlays the translated content
2. Field handling:
   • "Plain text" and "HTML" fields are sent to the Smartling TMS for translation
   • "Do not translate" and "Copy source" fields are never sent to the TMS but are handled by the connector
3. Update timing: "Copy source" fields update during each translation delivery (when all strings are translated for a locale or when a manual export is triggered)

The critical difference

• "Do not translate": Field values are frozen in translated documents after initial creation
• "Copy source": Field values stay synchronized with the source document on every delivery

Example

The following example uses an e-commerce product document:

Initial source document (English)

{
  "_id": "product-123",
  "title": "Winter Sale",            // Configured as "Plain text"
  "price": "$14.99",                 // Configured as "Do not translate"
  "sku": "PROD-123",                 // Configured as "Copy source"
  "support_phone": "+1 123-456-0100" // Configured as "Copy source"
}

After initial translation to French

After the strings for French are fully translated, the French document is created:

{
  "_id": "product-123-fr-FR",
  "title": "Soldes d'hiver",         // ✅ Translated
  "price": "$14.99",                 // Copied (not translated)
  "sku": "PROD-123",                 // Copied (not translated)
  "support_phone": "+1 123-456-0100" // Copied (not translated)
}

At this stage, all non-translatable fields contain source values.

Source document updated

Now you or a member of your team updates the source document:

{
  "_id": "product-123",
  "title": "Spring Sale",            // Changed
  "price": "$16.99",                 // Changed
  "sku": "PROD-456",                 // Changed
  "support_phone": "+1 280-555-0200" // Changed
}

After translating the update

When the updated content is translated and delivered:

{
  "_id": "product-123-fr-FR",
  "title": "Soldes de printemps",     // ✅ New translation
  "price": "$14.99",                  // ❌ Unchanged (Do not translate)
  "sku": "PROD-456",                  // ✅ Updated (Copy source)
  "support_phone": "+1 280-555-0200"  // ✅ Updated (Copy source)
}

When to use each option

Use "Do not translate" for:

• Regional pricing: Different prices for different markets that you'll update manually
• Local contact information: Country-specific phone numbers or addresses (when you have regional offices)
• Market-specific content: Legal text, compliance numbers, local store hours
• Regional product codes: When SKUs differ by region

Example: A product that costs $14.99 in the US but €12.99 in France, where each price is manually managed

Use "Copy source" for:

• Global identifiers: Universal product codes, SKUs that never change by region
• Company information: Main headquarters phone, corporate email (when you have only one global office)
• Technical specifications: Model numbers, dimensions, weights
• Universal URLs: Links to global resources

Example: A global support phone number that should be the same across all language versions

Any manual changes to "Copy source" fields in translated documents will be overwritten during the next translation delivery.

Here is a decision tree to help select the appropriate option:

1. Does this field need translation?
   • Yes → Use "Plain text" or "HTML"
   • No → Continue to question 2
2. Should this field have the same value across all language versions?
   • Yes → Use "Copy source" (e.g., global phone, universal SKU)
   • No → Continue to question 3
3. Will you manually manage different values per market/region?
   • Yes → Use "Do not translate" (e.g., regional prices, local contacts)
   • No → Reconsider if "Copy source" might be appropriate

Practical scenarios

Scenario 1: Multi-market pricing

Setup: Configure price field as "Do not translate"
Result: Each market can maintain different prices:

• English: $14.99
• French: €12.99
• German: €13.49

When you update the US price to $16.99, European prices remain unchanged.

Scenario 2: Global product update

Setup: Configure product_code field as "Copy source"
Result: When you update the product code from "WIDGET-001" to "WIDGET-002" in the source, all translated documents automatically receive the new code.

Scenario 3: Regional vs. global contact

Setup:

• local_support_phone: "Do not translate" (different number for each regional office)
• global_hotline: "Copy source" (same worldwide number)

Result:

• Each region maintains its local support number through manual updates
• Global hotline updates simultaneously across all languages during translation delivery

Best practices

• Plan your field parsing configuration before initial translation
• Document your parsing choices for team reference
• Test with a sample document to verify behavior
• Review field purposes to ensure you are using the correct content parsing option

Troubleshooting

Issue: Updated values not appearing in translations

For "Copy source" fields:

• Verify the field is configured as "Copy source" in connector content parsing settings
• Ensure a translation delivery occurred after the source update (either all strings for the locale were translated or a manual export was triggered)
• Remember: Updates only happen during translation delivery, not immediately after changes are made to the source content

For "Do not translate" fields:

• This is expected behavior - these fields never update automatically, you must manually update values in each translated document in Sanity. 

Issue: Manual changes being overwritten

Cause: A "Copy source" field was manually edited in a translated document. 
Solution: Change the field configuration from "Copy source" to "Do not translate" if you need region-specific values, as the "Copy source" fields will always sync from the source document. 

Issue: Can't find field in TMS/CAT tool

This is expected: "Do not translate" and "Copy source" fields are never sent to the Smartling TMS. They are handled entirely by the connector. Only "Plain text" and "HTML" fields appear in Smartling for linguists to translate.