feat: i18n support (#387)
This commit is contained in:
Daniel Lautzenheiser
committed by
GitHub
GitHub
parent
7372c3735b
commit
a01f30ef69
@ -10,276 +10,6 @@ Static CMS runs new functionality in an open beta format from time to time. That
|
||||
|
||||
**Use these features at your own risk.**
|
||||
|
||||
## i18n Support
|
||||
|
||||
The CMS can provide a side by side interface for authoring content in multiple languages.
|
||||
Configuring the 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>
|
||||
|
||||
## Folder Collections Path
|
||||
|
||||
See [Folder Collections Path](/docs/collection-types#folder-collections-path).
|
||||
|
||||
274
packages/docs/content/docs/i18n-support.mdx
Normal file
274
packages/docs/content/docs/i18n-support.mdx
Normal file
@ -0,0 +1,274 @@
|
||||
---
|
||||
group: Collections
|
||||
title: i18n Support
|
||||
beta: true
|
||||
weight: 30
|
||||
---
|
||||
|
||||
The CMS can provide a side by side interface for authoring content in multiple languages.
|
||||
Configuring the 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>
|
||||
Reference in New Issue
Block a user