Sveltia CMS

I18n Configuration Options ​

The i18n option can be defined at the top level of your configuration, on a collection, on a file in a file collection, and on individual fields. This page explains what each level accepts. For a complete example that sets up all levels at once, see the Internationalization overview.

Top-Level Configuration ​

Let’s start by defining the i18n option at the top-level of your configuration. The i18n option accepts the following properties:

yaml
i18n:
  structure: multiple_folders
  locales: [en, de, fr]
toml
[i18n]
structure = "multiple_folders"
locales = ["en", "de", "fr"]
json
{
  "i18n": {
    "structure": "multiple_folders",
    "locales": ["en", "de", "fr"]
  }
}
js
{
  i18n: {
    structure: "multiple_folders",
    locales: ["en", "de", "fr"],
  },
}
  • structure: (optional) Defines how localized content is stored. Default: single_file. See Content Structures for the available options. An entry collection can instead put the {{locale}} placeholder in its folder option to say where the locale folder goes, as in content/{{locale}}/posts. See Custom Locale Folder Placement.
  • locales: An array of locale codes representing the supported languages.
  • default_locale: (optional) Explicitly sets the default locale. If not provided, the first locale in the locales array is used.
  • omit_default_locale_from_file_path: (optional) When using a structure that creates separate files for each locale (e.g., multiple_files), setting this option to true will omit the locale code from the file path for the default locale. It also applies to file collections whose file path includes a {{locale}}. or {{locale}}/ placeholder. This is useful for frameworks like Zola that expect the default locale to have a specific filename.
  • omit_default_locale_from_preview_path: (optional) When set to true, the preview URL for the default locale will not include the locale code. This is useful for frameworks that expect the default locale to be served at the root path.

Deprecation Notice

The omit_default_locale_from_filename option is deprecated and will be removed in Sveltia CMS v1.0.0. Use omit_default_locale_from_file_path instead. The old option is simply an alias of the new one, which takes precedence if both are defined.

Collection-Level Configuration ​

You can opt into i18n for a specific collection by setting the i18n option to true. This will use the top-level i18n configuration for that collection.

yaml
collections:
  - name: posts
    i18n: true
toml
[[collections]]
name = "posts"
i18n = true
json
{
  "collections": [
    {
      "name": "posts",
      "i18n": true
    }
  ]
}
js
{
  collections: [
    {
      name: "posts",
      i18n: true,
    },
  ],
}

To override the global i18n settings for a specific collection, set the i18n option to an object with the desired configuration.

yaml
collections:
  - name: posts
    i18n:
      structure: multiple_files
      locales: [en, de, fr, ja]
toml
[[collections]]
name = "posts"

[collections.i18n]
structure = "multiple_files"
locales = ["en", "de", "fr", "ja"]
json
{
  "collections": [
    {
      "name": "posts",
      "i18n": {
        "structure": "multiple_files",
        "locales": ["en", "de", "fr", "ja"]
      }
    }
  ]
}
js
{
  collections: [
    {
      name: "posts",
      i18n: {
        structure: "multiple_files",
        locales: ["en", "de", "fr", "ja"],
      },
    },
  ],
}

Note that the structure option at the collection level only applies to entry collections. For file collections, see File Collections on the Content Structures page.

File-Level Configuration ​

Each file in a file collection can also have the i18n option set to true to enable localization for that specific file. As with collections, the file will use the top-level i18n configuration. The file-level option has no effect unless i18n is also enabled at the top level and on the collection.

yaml
collections:
  - name: pages
    label: Pages
    i18n: true
    files:
      - name: about
        label: About Page
        file: content/about.md
        i18n: true
toml
[[collections]]
name = "pages"
label = "Pages"
i18n = true

[[collections.files]]
name = "about"
label = "About Page"
file = "content/about.md"
i18n = true
json
{
  "collections": [
    {
      "name": "pages",
      "label": "Pages",
      "i18n": true,
      "files": [
        {
          "name": "about",
          "label": "About Page",
          "file": "content/about.md",
          "i18n": true
        }
      ]
    }
  ]
}
js
{
  collections: [
    {
      name: "pages",
      label: "Pages",
      i18n: true,
      files: [
        {
          name: "about",
          label: "About Page",
          file: "content/about.md",
          i18n: true,
        },
      ],
    },
  ],
}

If you want to override the global i18n settings for a specific file, set the i18n option to an object with the desired configuration. The following example enables localization only for English and French for the about file:

yaml
collections:
  - name: pages
    label: Pages
    i18n: true
    files:
      - name: about
        label: About Page
        file: content/about.md
        i18n:
          locales: [en, fr]
toml
[[collections]]
name = "pages"
label = "Pages"
i18n = true

[[collections.files]]
name = "about"
label = "About Page"
file = "content/about.md"

[collections.files.i18n]
locales = ["en", "fr"]
json
{
  "collections": [
    {
      "name": "pages",
      "label": "Pages",
      "i18n": true,
      "files": [
        {
          "name": "about",
          "label": "About Page",
          "file": "content/about.md",
          "i18n": {
            "locales": ["en", "fr"]
          }
        }
      ]
    }
  ]
}
js
{
  collections: [
    {
      name: "pages",
      label: "Pages",
      i18n: true,
      files: [
        {
          name: "about",
          label: "About Page",
          file: "content/about.md",
          i18n: {
            locales: ["en", "fr"],
          },
        },
      ],
    },
  ],
}

Note that the structure option does not apply to file collections. See File Collections on the Content Structures page for more details.

Field-Level Configuration ​

Each field can be localized individually by setting the i18n option. The i18n option for fields accepts the following values:

  • true
    • The field can be edited separately for each locale.
    • The values are stored separately for each locale.
  • false (default)
    • The field can only be edited in the default locale.
    • The field is hidden in non-default locales.
    • Only the default locale’s value is stored.
  • duplicate
    • The field can only be edited in the default locale.
    • The field is read-only in non-default locales, displaying the default locale’s value.
    • The same value is stored for all locales.

Legacy option values

For backward compatibility with Netlify/Decap CMS, Sveltia CMS also supports translate and none values for the field-level i18n option, which are equivalent to true and false, respectively.

Here’s how the i18n option behaves for different field types:

  • The Hidden field type does not have a visible UI representation, but you’ll still need to set the i18n option to true or duplicate to store values in non-default locales.
  • The complex List field type:
    • true lets each locale have its own items, which can be added, removed and reordered separately. A subfield only becomes editable in the other locales with its own i18n: true option; a subfield without the option is hidden there. If no subfield has the option, items can only be added in the default locale.
    • duplicate makes all subfields duplicate. When the user adds, reorders, or removes list items in the default locale, the same changes are reflected in other locales, where the items are shown read-only and can’t be added, removed or reordered. Subfields can be configured with their own i18n options.
  • The Object field type:
    • true lets the object appear in the other locales. A subfield only becomes editable there with its own i18n: true option; a subfield without the option is hidden in the other locales.
    • duplicate makes all subfields duplicate, and they are shown read-only in other locales. Subfields can be configured with their own i18n options.
  • The KeyValue field type additionally accepts duplicate_keys, which makes the keys duplicate — they are copied from the default locale, in the same order, and read-only in non-default locales — while the values can be edited separately for each locale.

Here’s an example of how to configure fields with different i18n options:

yaml
fields:
  - name: title
    label: Title
    widget: string
    i18n: true
  - name: date
    label: Date
    widget: datetime
    i18n: duplicate
toml
[[fields]]
label = "Title"
name = "title"
widget = "string"
i18n = true

[[fields]]
label = "Date"
name = "date"
widget = "datetime"
i18n = "duplicate"
json
{
  "fields": [
    {
      "label": "Title",
      "name": "title",
      "widget": "string",
      "i18n": true
    },
    {
      "label": "Date",
      "name": "date",
      "widget": "datetime",
      "i18n": "duplicate"
    }
  ]
}
js
{
  fields: [
    {
      label: "Title",
      name: "title",
      widget: "string",
      i18n: true,
    },
    {
      label: "Date",
      name: "date",
      widget: "datetime",
      i18n: "duplicate",
    },
  ],
}

When the i18n options is true, all locale are required to have a value for the field. if you want to make the field required only for specific locales, you can use an array value for the required option, which defaults to true.

In the following example, the summary field is required for English and German locales only:

yaml
fields:
  - name: summary
    label: Summary
    widget: string
    i18n: true
    required: [en, de]
toml
[[fields]]
label = "Summary"
name = "summary"
widget = "string"
i18n = true
required = ["en", "de"]
json
{
  "fields": [
    {
      "label": "Summary",
      "name": "summary",
      "widget": "string",
      "i18n": true,
      "required": ["en", "de"]
    }
  ]
}
js
{
  fields: [
    {
      label: "Summary",
      name: "summary",
      widget: "string",
      i18n: true,
      required: ["en", "de"],
    },
  ],
}

Disabling Non-Default Locale Content ​

Developers can specify locales to be enabled by default when users create a new entry draft, using the initial_locales i18n option, which accepts a locale list, default (default locale only) or all (all locales).

The default locale is always enabled, even if it’s excluded from initial_locales, while other locales can be enabled or disabled by users in the Content Editor through the three-dot menu in the top right corner, if this i18n option is defined.

The following example disables German by default, but users can manually enable it if needed. Users can also disable French, which is enabled by default.

yaml
i18n:
  structure: multiple_files
  locales: [en, fr, de]
  default_locale: en
  initial_locales: [en, fr]
toml
[i18n]
structure = "multiple_files"
locales = ["en", "fr", "de"]
default_locale = "en"
initial_locales = ["en", "fr"]
json
{
  "i18n": {
    "structure": "multiple_files",
    "locales": ["en", "fr", "de"],
    "default_locale": "en",
    "initial_locales": ["en", "fr"]
  }
}
js
{
  i18n: {
    structure: "multiple_files",
    locales: ["en", "fr", "de"],
    default_locale: "en",
    initial_locales: ["en", "fr"],
  },
}

Deprecation Notice

The save_all_locales option has been deprecated in favor of the more flexible initial_locales option and will be removed in Sveltia CMS v1.0.0. If you are upgrading from an older version, update your configuration accordingly: save_all_locales: false is equivalent to initial_locales: all, while save_all_locales: true is equivalent to initial_locales being omitted (all locales enabled by default).

Copyright © 2026 Kohei Yoshino