Internationalization (i18n) Setup

To enable automatic internationalization for list items, you must configure custom translation resource bundles on the structureToolPlugin initialization.

Configuration

Pass your translation resource files into the i18n option dictionary, mapping each supported locale code (e.g., 'en-US' or 'es-ES') to its corresponding resources:

src/structure/index.ts

import { structureToolPlugin } from 'sanity-plugin-structure-tool';
import en from './locales/en.json';
import es from './locales/es.json';

export const { structure, templates, defineListItems } = structureToolPlugin({
  title: 'Project Name',
  // Register translation locale resource bundles
  i18n: {
    'en-US': {
      resources: en,
    },
    'es-ES': {
      resources: es,
    },
  },
});

Registering Custom Languages

English (en-US) translation support is enabled by default in Sanity Studio. If you want to support other languages (like Spanish 'es-ES'), you need to install and register the corresponding official locale plugin.

You can find all available locale plugins in the Sanity Locales repository.

Example: Spanish Setup

Install @sanity/locale-es-es, then register it in your sanity.config.ts:

sanity.config.ts

import { defineConfig } from 'sanity';
import { esESLocale } from '@sanity/locale-es-es'; // Import the locale plugin
import { structure } from './src/structure';

export default defineConfig({
  // ... other configurations
  plugins: [
    structure({
      listItems,
    }),
    esESLocale(), // Register the locale plugin
  ],
});

Nested JSON Keys

Translation keys inside list items support standard dot-notation (e.g. drawer.folder) to access nested translation values within the registered JSON structure.

This enables you to organize translation keys hierarchically:

JSON

{
  title: 'drawer.folder',
  i18n: true,
  children: [
    {
      title: 'drawer.level_1',
      i18n: true,
      schemaType: 'author',
    }
  ]
}

Helpers

helpers.children({
  title: 'drawer.folder',
  i18n: true,
  children: [
    helpers.listing('author', {
      title: 'drawer.level_1',
      i18n: true,
    }),
  ],
});

en.json

{
  "drawer": {
    "folder": "Drawer",
    "level_1": "Level 1 Depth"
  }
}

es.json

{
  "drawer": {
    "folder": "Cajón",
    "level_1": "Nivel de Profundidad 1"
  }
}

Usage Examples

Once setup is complete, you can enable localization on individual list items by setting i18n: true. See the i18n Examples page for complete usage configurations.

Overwrites & Fallbacks

When i18n: true is set on a list item, the string configured as its title will be treated as the translation key rather than a static display title. The active locale's translation value will overwrite the original title.

• Locale Fallback: If the translation key is missing in the active locale, Sanity Studio will attempt to fall back to the English (en-US) translation bundle.
• Missing Key Fallback: If the key is not defined in any registered translation resource bundle, the title will fall back to displaying the raw key string itself (e.g., 'authors').