static-cms/packages/docs/content/docs/i18n-support.mdx

---
group: Collections
title: i18n Support
beta: true
weight: 30
---

Static CMS can provide a side by side interface for authoring content in multiple languages.
Configuring Static CMS for i18n support requires top level configuration, collection level configuration and field level configuration.

### Top level configuration

<CodeTabs>

```yaml
i18n:
  # Required and can be one of multiple_folders, multiple_files or single_file
  # multiple_folders - persists files in `<folder>/<locale>/<slug>.<extension>`
  # multiple_files - persists files in `<folder>/<slug>.<locale>.<extension>`
  # single_file - persists a single file in `<folder>/<slug>.<extension>`
  structure: multiple_folders

  # Required - a list of locales to show in the editor UI
  locales: [en, de, fr]

  # Optional, defaults to the first item in locales.
  # The locale to be used for fields validation and as a baseline for the entry.
  defaultLocale: en
```

```js
i18n: {
  /**
   * Required and can be one of multiple_folders, multiple_files or single_file
   * multiple_folders - persists files in `<folder>/<locale>/<slug>.<extension>`
   * multiple_files - persists files in `<folder>/<slug>.<locale>.<extension>`
   * single_file - persists a single file in `<folder>/<slug>.<extension>`
   */
  structure: 'multiple_folders',

  // Required - a list of locales to show in the editor UI
  locales: ['en', 'de', 'fr'],

  /**
   * Optional, defaults to the first item in locales.
   * The locale to be used for fields validation and as a baseline for the entry.
   */
  defaultLocale: 'en'
},
```

</CodeTabs>

### Collection level configuration

<CodeTabs>
```yaml
collections:
  - name: i18n_content
    # same as the top level, but all fields are optional and defaults to the top level
    # can also be a boolean to accept the top level defaults
    i18n: true
```

```js
collections: [
  {
    name: 'i18n_content',
    /**
     * same as the top level, but all fields are optional and defaults to the top level
     * can also be a boolean to accept the top level defaults
     */
    i18n: true
  },
],
```

</CodeTabs>

When using a file collection, you must also enable i18n for each individual file:

<CodeTabs>
```yaml
collections:
  - name: pages
    label: Pages
    # Configure i18n for this collection.
    i18n:
      structure: single_file
      locales: [en, de, fr]
    files:
      - name: about
        label: About Page
        file: site/content/about.yml
        # Enable i18n for this file.
        i18n: true
        fields:
          - { label: Title, name: title, widget: string, i18n: true }
```

```js
collections: [
  {
    name: 'pages',
    label: 'Pages',
    // Configure i18n for this collection.
    i18n: {
      structure: 'single_file',
      locales: ['en', 'de', 'fr']
    },
    files: [
      {
        name: 'about',
        label: 'About Page',
        file: 'site/content/about.yml',
        // Enable i18n for this file.
        i18n: true,
        fields: [
          { label: 'Title', name: 'title', widget: 'string', i18n: true }
        ],
      },
    ],
  },
],
```

</CodeTabs>

### Field level configuration

<CodeTabs>
```yaml
fields:
  - label: Title
    name: title
    widget: string
    # same as 'i18n: translate'. Allows translation of the title field
    i18n: true
  - label: Date
    name: date
    widget: datetime
    # The date field will be duplicated from the default locale.
    i18n: duplicate
  - label: Body
    name: body
    # The markdown field will be omitted from the translation.
    widget: markdown
```

```js
fields: [
  {
    label: 'Title',
    name: 'title',
    widget: 'string',
    // same as 'i18n: translate'. Allows translation of the title field
    i18n: true
  },
  {
    label: 'Date',
    name: 'date',
    widget: 'datetime',
    // The date field will be duplicated from the default locale.
    i18n: 'duplicate'
  },
  {
    label: 'Body',
    name: 'body',
    // The markdown field will be omitted from the translation.
    widget: 'markdown'
  },
],
```

</CodeTabs>

Example configuration:

<CodeTabs>
```yaml
i18n:
  structure: multiple_folders
  locales: [en, de, fr]

collections:
  - name: posts
    label: Posts
    folder: content/posts
    create: true
    i18n: true
    fields:
      - label: Title
        name: title
        widget: string
        i18n: true
      - label: Date
        name: date
        widget: datetime
        i18n: duplicate
      - label: Body
        name: body
        widget: markdown
```

```js
i18n: {
  structure: 'multiple_folders',
  locales: ['en', 'de', 'fr']
},
collections: [
  {
    name: 'posts',
    label: 'Posts',
    folder: 'content/posts',
    create: true,
    i18n: true,
    fields: [
      { label: 'Title', name: 'title', widget: 'string', i18n: true },
      { label: 'Date', name: 'date', widget: 'datetime', i18n: 'duplicate' },
      { label: 'Body', name: 'body', widget: 'markdown' },
    ],
  },
],
```

</CodeTabs>

### Limitations

1. File collections support only `structure: single_file`.
2. List widgets only support `i18n: true`. `i18n` configuration on sub fields is ignored.
3. Object widgets only support `i18n: true` and `i18n` configuration should be done per field:

<CodeTabs>
```yaml
- label: 'Object'
  name: 'object'
  widget: 'object'
  i18n: true
  fields:
    - { label: 'String', name: 'string', widget: 'string', i18n: true }
    - { label: 'Date', name: 'date', widget: 'datetime', i18n: duplicate }
    - { label: 'Boolean', name: 'boolean', widget: 'boolean', i18n: duplicate }
    - {
        label: 'Object',
        name: 'object',
        widget: 'object',
        i18n: true,
        field: { label: 'String', name: 'string', widget: 'string', i18n: duplicate },
      }
```

```js
{
  label: 'Object',
  name: 'object',
  widget: 'object',
  i18n: true,
  fields: [
    { label: 'String', name: 'string', widget: 'string', i18n: true },
    { label: 'Date', name: 'date', widget: 'datetime', i18n: 'duplicate' },
    { label: 'Boolean', name: 'boolean', widget: 'boolean', i18n: 'duplicate' },
    {
      label: 'Object',
      name: 'object',
      widget: 'object',
      i18n: true,
      field: { label: 'String', name: 'string', widget: 'string', i18n: 'duplicate' },
    },
  ],
},
```

</CodeTabs>