Get help on Discord

Issue with using the document-internationalization plugin in Sanity and troubleshooting steps.

58 replies
Last updated: Mar 8, 2022
Hello Sanity team, I am trying to use the document-internationalization plugin which works well with GROQ but I am struggling to follow the GraphQL doc (https://github.com/sanity-io/document-internationalization/blob/main/docs/graphql-intl-doc.md ). I can edit the document but once deployed, I can’t find any i18_* field. Would you have any example please? Many thanks!
AI Update

I can see you're having trouble finding the i18n_* fields in your GraphQL API after deploying. The issue is that the GraphQL documentation file you're referencing no longer exists in the plugin repository – it returns a 404 error, which explains why you're struggling to follow it.

Here's what's actually happening with the document-internationalization plugin and GraphQL:

How the Plugin Actually Works

The plugin uses a metadata document approach. When you create translations:

  1. Your content documents (like a lesson document) remain as separate documents for each language
  2. A special translation.metadata document is created that links all the language versions together
  3. Each content document gets a language field (or whatever you configure via languageField)

The __i18n_lang, __i18n_base, and __i18n_refs fields are internal metadata fields that exist on the translation.metadata document type, not directly on your content documents.

The GraphQL Challenge

The plugin was primarily designed for GROQ queries, and GraphQL support has significant limitations. The metadata document structure doesn't expose these internal fields in a straightforward way through GraphQL.

Option 1: Use GROQ (Recommended)

Since you mentioned GROQ works well, stick with it. You can query by the language field on your documents:

*[_type == "lesson" && language == "en"]

Option 2: Query via the language field in GraphQL

Your content documents should have a language field that you can query in GraphQL:

query {
  allLesson(where: { language: { eq: "en" } }) {
    _id
    title
    language
  }
}

Make sure you've run sanity graphql deploy after adding the plugin.

Option 3: Check the Sanity Community

The original community thread you may have seen discusses these exact limitations. The missing documentation suggests GraphQL isn't a fully supported path for this plugin.

The key takeaway: the plugin's GraphQL support is limited by design. The internal i18n_* fields aren't meant to be directly queried through GraphQL – instead, use the language field on your content documents to filter by language.

Hi (Removed Name), many thanks, I’ve checked it indeed by searching, just in case, are you using GraphQL or Groq please?
Groq
sorry i haven't see you searching for GraphQL 😞
no problem and many thanks! Ton blog est en ligne?
Mon blog n'est pas en ligne encore , je lutte sur la pagination 😞 ( i'm on nextJs BTW )
same here, nextjs
i have manage to translate all my blog post , if you need help , but only with GROQ
Many thanks!
and i'm working a way to do pagination , i want to display only five article per page , but my lack of knowledge regarding NextJS is a big issue for this task 😁
Hi (Removed Name). Would you be able to share an example GraphQL query that attempts to fetch the internationalised content?
It would also be handy if you're able to share the URL for your GraphQL Playground. Feel free to DM that to avoid sharing it publicly
🙂.
Hi (Removed Name)!
Now I don’t think my config is right, I’ve tried to follow the guidelines and ended up with the following, which I don’t think is right:
export default createSchema({
  name: 'default',
  i18n: {
    fieldNames: {
      lang: 'i18n_lang',
      baseReference: 'i18n_base',
      references: 'i18n_refs'
    }
  },
  fields: [
    {
      name: 'i18n_lang',
      type: 'string',
      hidden: true,
    },
    {
      name: 'i18n_base',
      type: 'reference',
      hidden: true,
    },
    {
      name: 'i18n_refs',
      type: 'array',
      hidden: true,
      of: [
        {
          type: 'reference',
          to: [{type: 'schema'}],
        },
      ],
    },
  ],
  types: schemaTypes.concat([
    // =======================
    // ELEMENTS
    // =======================
    title,
    navigationItem,

    // =======================
    // DOCUMENTS
    // =======================
    page,
    headerPage,
  ]),
})
Page document being:
export default {
  type: 'document',
  name: 'page',
  title: 'Page',
  i18n: true,
  fields: [
    {
      name: 'title',
      type: 'title',
    },
  ],
}
Aha! I think I see the issue here. The fields need to be added to your individual schemas. Like this:

export default {
  type: 'document',
  name: 'page',
  title: 'Page',
  i18n: true,
  fields: [
    {
      name: 'title',
      type: 'title',
    },
    // Add the i18n fields to the schema here:
    {
      name: 'i18n_lang',
      type: 'string',
      hidden: true,
    },
    {
      name: 'i18n_base',
      type: 'reference',
      hidden: true,
    },
    {
      name: 'i18n_refs',
      type: 'array',
      hidden: true,
      of: [
        {
          type: 'reference',
          to: [{type: 'schema'}],
        },
      ],
    },
  ],
}
Let me know whether this helps
🙂.
I try directly but has issue doing so, I proceed right now
Ok, so when doing so here is what I see:
and was not sure whether
to: [{type: 'schema'}],
was the issue
This main schema is still correct please? (specifying i18 on it)
export default createSchema({
  // We name our schema
  name: 'default',
  // Then proceed to concatenate our document type
  // to the ones provided by any plugins that are installed
  i18n: {
    fieldNames: {
      lang: 'i18n_lang',
      baseReference: 'i18n_base',
      references: 'i18n_refs'
    }
  },
  types: schemaTypes.concat([
    // =======================
    // ELEMENTS
    // =======================
    title,
    navigationItem,

    // =======================
    // DOCUMENTS
    // =======================
    page,
    headerPage,
  ]),
})
Yes, I think you've added the 
i18n
options in exactly the right spot! Let me look into that other issue.
Many thanks (Removed Name), that’s fantastic
Okay, I think I see the issue. The reference should be to the translated document type. In your case:

{
  name: 'i18n_refs',
  type: 'array',
  hidden: true,
  of: [
    {
      type: 'reference',
      to: [{type: 'page'}],
    },
  ],
},
This is because the reference is to another (translated) document of the 
Page
type.
I adjust
ok makes total sense sorry about this one, and just one left as in:
The reference type is missing or having an invalid value for the required "to" property. It should be an array of accepted types.
Have you added the 
i18n_lang
, 
i18n_base
, and 
i18n_refs
fields to all of your schemas that support i18n?
I double check immediately
all the document using i18 have it, now the elements do not have any specifications do they need it too please?
(namely title / item-navigation)
Thank you for checking. I believe it's only necessary for documents that support i18n.
which makes sense indeed
Should this field be also set to the current document type as in:
{
      name: 'i18n_base',
      type: 'reference',
      hidden: true,
    }
vs

{
  name: 'i18n_base',
  type: 'reference',
  hidden: true,
  of: [
    {type: 'page'},
  ],
},
?
I think you're right that the 
of
option needs to be set there! The docs don't mention what this should be, so I'll need to do a little investigating here.
i’ve tried but didn’t resolve the issue, I keep trying
(Removed Name), ok the fields now appear but with null values
(Removed Name), I got it here:
so document looks like:
export default {
  type: 'document',
  name: 'page',
  title: 'Page',
  i18n: true,
  fields: [
    {
      name: 'title',
      type: 'title',
    },
    //======================= I18 requirements
    // Add the i18n fields to the schema here:
    {
      name: 'i18n_lang',
      type: 'string',
      hidden: true,
    },
    {
      name: 'i18n_base',
      type: 'array',
      hidden: true,
      of: [
            {
              type: 'reference',
              to: [{type: 'page'}],
            },
          ],
    },
    {
      name: 'i18n_refs',
      type: 'array',
      hidden: true,
      of: [
        {
          type: 'reference',
          to: [{type: 'page'}],
        },
      ],
    },
  ],
};
as you pointed reference was required in the same way in i18n_base as in i18n_refs
Many many many thanks (Removed Name)! Fantastic!
current document being:
export default {
  type: 'document',
  name: 'page',
  title: 'Page',
  i18n: true,
  fields: [
    {
      name: 'title',
      type: 'title',
    },
    //======================= I18 requirements
    // Add the i18n fields to the schema here:
    {
      name: 'i18n_lang',
      type: 'string',
      hidden: true,
    },
    {
      name: 'i18n_base',
      type: 'array',
      hidden: true,
      of: [
            {
              type: 'reference',
              to: [{type: 'page'}],
            },
          ],
    },
    {
      name: 'i18n_refs',
      type: 'array',
      hidden: true,
      of: [
        {
          type: 'reference',
          to: [{type: 'page'}],
        },
      ],
    },
  ],
};
current document being:
export default {
  type: 'document',
  name: 'page',
  title: 'Page',
  i18n: true,
  fields: [
    {
      name: 'title',
      type: 'title',
    },
    //======================= I18 requirements
    // Add the i18n fields to the schema here:
    {
      name: 'i18n_lang',
      type: 'string',
      hidden: true,
    },
    {
      name: 'i18n_base',
      type: 'array',
      hidden: true,
      of: [
            {
              type: 'reference',
              to: [{type: 'page'}],
            },
          ],
    },
    {
      name: 'i18n_refs',
      type: 'array',
      hidden: true,
      of: [
        {
          type: 'reference',
          to: [{type: 'page'}],
        },
      ],
    },
  ],
};
Good morning (Removed Name), I hope you’re well, I am coming back to you as I’d like to ensure the following is correct, it seems to work so also want to share:

1/ Main schema: 
export default createSchema({
  name: 'default',
  types: schemaTypes.concat([
    // -- ELEMENTS
    title,
    // -- DOCUMENTS
    page,
  ]),
})
=> i18 has been removed from here, and fieldnames added in the config (config/@sanity/document-internationalization.json)


2/ document-internationalization.json:
{
    "idStructure": "delimiter",
    "referenceBehavior": "strong",
    "languages": [
        {"id": "en", "title": "English"},
        {"id": "fr", "title": "French"},
        {"id": "es", "title": "Spanish"}
    ],
    "withTranslationsMaintenance": false,
    "fieldNames": {
        "lang": "i18n_lang",
        "references": "i18n_refs",
        "baseReference": "i18n_base"
    }
}

3/ In the document page:
export default {
  type: 'document',
  name: 'page',
  title: 'Page',
  i18n: true,
  fields: [
    {
      name: 'title',
      type: 'title',
    },
    //==========================
    //======== I18 requirements
    //==========================
    {
      name: 'i18n_lang',
      type: 'string',
      hidden: true,
    },
    {
      name: 'i18n_base',
      type: 'reference',
      hidden: true,
      to: [
        { type: 'page' },
      ],
    },
    {
      name: 'i18n_refs',
      type: 'array',
      hidden: true,
      of: [
        {
          type: 'reference',
          to: [{ type: 'page' }],
        },
      ],
    },
  ],
=> i18n_base is not an array of reference: the base being the default, I suppose it only should receive one hence the direct ref. without an array:

4/ Once deployed I can query all and by country with expected results:

query AllPages {
  allCountries: allPage {
    _type
    _id
    i18n_lang
    title {
      title
    }
  }
  spanishOnly: allPage(where: { i18n_lang: { eq: "es" } }) {
    _type
    _id
    i18n_lang
    title {
      title
    }
  }
}
=>

{
  "data": {
    "allCountries": [
      {
        "_type": "page",
        "_id": "10fad58e-6eab-46f3-b704-341cf9f0dc9a",
        "i18n_lang": "en",
        "title": {
          "title": "Homepage"
        }
      },
      {
        "_type": "page",
        "_id": "10fad58e-6eab-46f3-b704-341cf9f0dc9a__i18n_es",
        "i18n_lang": "es",
        "title": {
          "title": "Casa"
        }
      },
      {
        "_type": "page",
        "_id": "10fad58e-6eab-46f3-b704-341cf9f0dc9a__i18n_fr",
        "i18n_lang": "fr",
        "title": {
          "title": "Accueil"
        }
      }
    ],
    "spanishOnly": [
      {
        "_type": "page",
        "_id": "10fad58e-6eab-46f3-b704-341cf9f0dc9a__i18n_es",
        "i18n_lang": "es",
        "title": {
          "title": "Casa"
        }
      }
    ]
  }
}
Morning
user E
, just in case, does the deployed gql API looks good to you please?
https://hxxbibp8.api.sanity.io/v1/graphql/production/default
Morning
user E
, just in case, does the deployed gql API looks good to you please?
https://hxxbibp8.api.sanity.io/v1/graphql/production/default
(I’d rather be sure before expanding it, many thanks in advance)
query AllPages {
  allCountries: allPage {
    _type
    _id
    i18n_lang
    title
    slug {
      current
    }
  }
  frenchOnly: allPage(where: { i18n_lang: { eq: "en" } }) {
    _type
    _id
    i18n_lang
    title
  }
}
Hi (Removed Name). I'm really glad to hear you got this working, and thanks for sharing with the community! 🙂
I'll take a look now.
Hi (Removed Name). I'm really glad to hear you got this working, and thanks for sharing with the community! 🙂
I'll take a look now.
Great, many thanks!
This looks awesome. I think you're spot on with the config here 🙌.
Thank you for highlighting some of the missing details in our docs. I'll pass this along so we can get it fixed!
This looks awesome. I think you're spot on with the config here 🙌.
Thank you for highlighting some of the missing details in our docs. I'll pass this along so we can get it fixed!
Perfect, glad it’s aligned and glad it’s correct! Many thanks (Removed Name)!
Have a nice one!
You too! Let us know if there is anything else we can help with 🙂.
Many thanks, Sanity is a very great tool, and the team is spot on!

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?