---
url: /en/docs/i18n/options.md
description: >-
  Configure the i18n option in Sveltia CMS at the top, collection, file and
  field levels, and control which locales are enabled by default.
---

# 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](/en/docs/collections/files), 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](/en/docs/i18n#configuration).

## 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:

::: code-group

```yaml [YAML]
i18n:
  structure: multiple_folders
  locales: [en, de, fr]
```

```toml [TOML]
[i18n]
structure = "multiple_folders"
locales = ["en", "de", "fr"]
```

```json [JSON]
{
  "i18n": {
    "structure": "multiple_folders",
    "locales": ["en", "de", "fr"]
  }
}
```

```js [JavaScript]
{
  i18n: {
    structure: "multiple_folders",
    locales: ["en", "de", "fr"],
  },
}
```

:::

* `structure`: Defines how localized content is stored. See [Content Structures](/en/docs/i18n/structures) for the available options.
* `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 filename for the default locale. This is useful for frameworks like [Zola](https://www.getzola.org/documentation/content/multilingual/) 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.

::: warning 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, which works with all multiple files/folders structures, not just the `multiple_files` structure.

:::

## 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.

::: code-group

```yaml [YAML]{3}
collections:
  - name: posts
    i18n: true
```

```toml [TOML]{3}
[[collections]]
name = "posts"
i18n = true
```

```json [JSON]{5}
{
  "collections": [
    {
      "name": "posts",
      "i18n": true
    }
  ]
}
```

```js [JavaScript]{5}
{
  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.

::: code-group

```yaml [YAML]{3-5}
collections:
  - name: posts
    i18n:
      structure: multiple_files
      locales: [en, de, fr, ja]
```

```toml [TOML]{4-6}
[[collections]]
name = "posts"

[collections.i18n]
structure = "multiple_files"
locales = ["en", "de", "fr", "ja"]
```

```json [JSON]{5-8}
{
  "collections": [
    {
      "name": "posts",
      "i18n": {
        "structure": "multiple_files",
        "locales": ["en", "de", "fr", "ja"]
      }
    }
  ]
}
```

```js [JavaScript]{5-8}
{
  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](/en/docs/collections/entries). For [file collections](/en/docs/collections/files), see [File Collections](/en/docs/i18n/structures#file-collections) on the Content Structures page.

## File-Level Configuration

Each file in a [file collection](/en/docs/collections/files) 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.

::: code-group

```yaml [YAML]{4,9}
collections:
  - name: pages
    label: Pages
    i18n: true
    files:
      - name: about
        label: About Page
        file: content/about.md
        i18n: true
```

```toml [TOML]{4,10}
[[collections]]
name = "pages"
label = "Pages"
i18n = true

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

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

```js [JavaScript]{6,12}
{
  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:

::: code-group

```yaml [YAML]{4,9-10}
collections:
  - name: pages
    label: Pages
    i18n: true
    files:
      - name: about
        label: About Page
        file: content/about.md
        i18n:
          locales: [en, fr]
```

```toml [TOML]{4,11-12}
[[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 [JSON]{6,12-14}
{
  "collections": [
    {
      "name": "pages",
      "label": "Pages",
      "i18n": true,
      "files": [
        {
          "name": "about",
          "label": "About Page",
          "file": "content/about.md",
          "i18n": {
            "locales": ["en", "fr"]
          }
        }
      ]
    }
  ]
}
```

```js [JavaScript]{6,12-14}
{
  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](/en/docs/collections/files). See [File Collections](/en/docs/i18n/structures#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.

::: info 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](/en/docs/fields/hidden) 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](/en/docs/fields/list):
  * `true` makes all subfields editable separately for each 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. Subfields can be configured with their own `i18n` options.
* The [Object field type](/en/docs/fields/object):
  * `true` makes all subfields editable separately for each locale.
  * `duplicate` makes all subfields duplicate. Subfields can be configured with their own `i18n` options.
* The [KeyValue field type](/en/docs/fields/keyvalue) additionally accepts `duplicate_keys`, which makes the keys duplicate — they are copied from the default locale 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:

::: code-group

```yaml [YAML]{5,9}
fields:
  - name: title
    label: Title
    widget: string
    i18n: true
  - name: date
    label: Date
    widget: datetime
    i18n: duplicate
```

```toml [TOML]{5,11}
[[fields]]
label = "Title"
name = "title"
widget = "string"
i18n = true

[[fields]]
label = "Date"
name = "date"
widget = "datetime"
i18n = "duplicate"
```

```json [JSON]{7,13}
{
  "fields": [
    {
      "label": "Title",
      "name": "title",
      "widget": "string",
      "i18n": true
    },
    {
      "label": "Date",
      "name": "date",
      "widget": "datetime",
      "i18n": "duplicate"
    }
  ]
}
```

```js [JavaScript]{7,13}
{
  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:

::: code-group

```yaml [YAML]{5-6}
fields:
  - name: summary
    label: Summary
    widget: string
    i18n: true
    required: [en, de]
```

```toml [TOML]{5-6}
[[fields]]
label = "Summary"
name = "summary"
widget = "string"
i18n = true
required = ["en", "de"]
```

```json [JSON]{7-8}
{
  "fields": [
    {
      "label": "Summary",
      "name": "summary",
      "widget": "string",
      "i18n": true,
      "required": ["en", "de"]
    }
  ]
}
```

```js [JavaScript]{7-8}
{
  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.

::: code-group

```yaml{5} [YAML]
i18n:
  structure: multiple_files
  locales: [en, fr, de]
  default_locale: en
  initial_locales: [en, fr]
```

```toml{5} [TOML]
[i18n]
structure = "multiple_files"
locales = ["en", "fr", "de"]
default_locale = "en"
initial_locales = ["en", "fr"]
```

```json{6} [JSON]
{
  "i18n": {
    "structure": "multiple_files",
    "locales": ["en", "fr", "de"],
    "default_locale": "en",
    "initial_locales": ["en", "fr"]
  }
}
```

```js{6} [JavaScript]
{
  i18n: {
    structure: "multiple_files",
    locales: ["en", "fr", "de"],
    default_locale: "en",
    initial_locales: ["en", "fr"],
  },
}
```

:::

::: warning 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).

:::