Get help on Discord

Understanding the impact of field level translation in Sanity

5 replies
Last updated: Feb 8, 2024
Hi, I'm researching ways to Localize content in Sanity and in the Sanity docs I read that Portable text shouldn't be used with field level translation. Can someone help explaining me why thats the case and what happens if I do use it?
AI Update

The recommendation against using Portable Text with field-level translation comes down to a technical limitation around attribute counts in Sanity's content structure.

Why It's Problematic

Portable Text generates a massive number of attributes because of its complex, nested structure. Each block, mark, annotation, and inline object creates its own set of paths in the document. When you combine this with field-level localization, where each language creates its own complete set of nested paths, the attribute count multiplies rapidly and can exceed Sanity's attribute limits.

Here's the key difference:

  • Document-level translation (separate documents per language): Each document has its own Portable Text structure, so attributes don't multiply
  • Field-level translation with Portable Text: Every language within the same field generates its own complete set of paths, causing the attribute count to explode

What Happens If You Use It Anyway

If you implement field-level translation with Portable Text, you risk:

  1. Hitting attribute limits: Your content can become stuck and uneditable
  2. Performance issues: The excessive attribute count can slow down queries and editing
  3. Migration headaches: Fixing the issue often requires heavy-duty migrations to restructure your content

According to Sanity's documentation on this specific issue, this can create situations where content becomes stuck and difficult to resolve.

What You Should Do Instead

For content that includes Portable Text or any rich text content, use document-level localization instead. This approach creates separate documents for each language version, completely avoiding the attribute multiplication problem while still giving you full flexibility with complex content structures.

Field-level localization works fine for simple fields like strings, numbers, or basic objects—just not for Portable Text or block content.

If you're looking at plugins like the sanity-plugin-intl-input, be aware it only works with the deprecated Studio v2 and still carries the same Portable Text limitations.

You eat through your attribute limit and end up getting to a point where your content is stuck unless you run a heavy duty migration.
hey, thanks. it's not very clear to me: does creating seperate documents uses less attributes than adding two portable text fields in one document?
Document level translation means that all translations use the same structure and therefore generate fewer paths. Here’s a super simple example:
Document level (multiple documents but they all use this structure):

{
  name,
  content: {
    //all of the paths the a block array can create
  }
}
Field level:

{
 name: {
  en
  de
  etc.
 }
  content: {
    en: {
       //lots of paths
    },
    de: {
       //lots of paths
   }
}
That’s much clearer now. Thank you
user M
You’re welcome!

Sanity – Build the way you think, not the way your CMS thinks

Sanity is the developer-first content operating system that gives you complete control. Schema-as-code, GROQ queries, and real-time APIs mean no more workarounds or waiting for deployments. Free to start, scale as you grow.

Get started for freeExplore the demo

Was this answer helpful?