- Enabling Localization
- Updating all API Calls
- Localization of Pages
- Localization of Collections
- Localization Permission (Enterprise plan feature)
Localization is the act of customizing your content to the specific locale (geographic location) of the person interacting with your content.
ButterCMS has full support for the localization of your content. Locale names and keys are completely customizable.
Enabling Localization
To set up Localization in your ButterCMS account, just go to Settings > Localization and enter the name and slug for all the Locales you are setting up:
By default, the first Locale you enter will be your Default Locale. You can change this anytime, by clicking on the radio button for the Locale you want to set as the default:
NOTE: Once a locale name and API slug have been saved, they can no longer be edited or changed.
Updating all API Calls
After enabling Localization, you will need to update all API calls to include the locale params. Below is a guide you can refer to.
Single Page:
https://api.buttercms.com/v2/pages/<page_type_slug>/<page_slug>/?locale=en&preview=1&auth_token=your_api_token
Multiple Single Pages:
https://api.buttercms.com/v2/pages/*/?preview=1&page=1&page_size=10&locale=en&levels=2&auth_token=your_api_token
Page Types:
https://api.buttercms.com/v2/pages/<page_type>/?preview=1&fields.tag=example&fields.genre=api&order=title&page=1&page_size=10&locale=en&levels=2&auth_token=your_api_token'
Collections:
https://api.buttercms.com/v2/content/artists/?preview=1&fields.genre=Rock&order=name&page=1&page_size=10&locale=en&levels=2&auth_token=your_api_token'
Localization of Pages
Once you have Localization enabled with your default language set (i.e. English shown in the image above), creating localized versions of each page can be done as follows
Important: After entering content in your default language, the pages created in other languages will remain empty until you enter that translated content or copy content from another locale.
Localization of Collections
Localization for Collections works similarly. All the fields in your Default Locale will be defined and the same fields are created for other Locales automatically. However, similar to Pages, the content you create for your default locale in a Collection will not automatically translate to your other localized Collections.
The fields on your other locales will stay empty until you have updated them with the appropriate translated content or you have copied the content from your other locale by clicking on the 'Copy from' drop-down and choosing the locale you want to copy content from:
To complete translating all of your content to fill the other localized versions of each Page or Collection, you can approach this one of two ways. You can utilize Butter's Write API to translate and automatically write in this translated content into your localized pages: Write API for Translating Content.
Alternatively, you can use a third-party tool or writer proficient in the additional languages to translate this content update the localized Pages and Collections with the translated content.
Localization Permission (Enterprise plan feature)
Allows you to control which locales can be accessed by each user on the account. This feature is enabled in the Pages, Collections, and Workspaces dashboard.
IMPORTANT: Please reach out to the ButterCMS Support Team via the in-app chat or email if you wish to delete a locale from your account or completely disable localization.