Set up and use the ButterCMS integration

Overview

Integrating ButterCMS with Smartcat lets you translate your website content while keeping it synchronized across both platforms. This guide helps you set up the integration, map languages, and start translating your CMS pages directly in Smartcat.

In this guide, you learn how to:

• Connect ButterCMS to your Smartcat Workspace

• Configure your API keys and localization settings

• Map your ButterCMS locales to Smartcat languages

• Create and verify your integration

• Troubleshoot common issues

Setting up the integration

Step 1 — Open Smartcat integrations

1. Log in to your Smartcat Workspace

2. From your homepage, click Set up an integration

3. From the available options, select ButterCMS

Step 2 — Add your ButterCMS API keys

1. In a separate browser tab, open your ButterCMS account settings

2. Locate your API Keys (both Read and Write keys)

3. Copy these keys and paste them into the Create Integration form in Smartcat

4. Double-check that no spaces or special characters are accidentally copied

Step 3 — Add page types

1. In ButterCMS, go to Content Types → Page Types

2. Identify the page types that you want to translate

3. Click each page type to open it, then copy the Page Type ID

   

4. Paste the ID into the corresponding field in Smartcat's Create Integration form

Step 4 — Map ButterCMS locales to Smartcat languages

1. In ButterCMS, return to your account settings and open the Localization tab

2. Review your active locales (for example, en, de, es, fr)

3. In Smartcat, map these locales to their corresponding Smartcat languages

4. Once all locales are mapped, click Create Integration to finalize the setup

The ButterCMS integration is now connected and ready to use.

Using the integration

To start the translation process, select your content (for example, an article) and click Create translation.

1. Select whether you want to create a new project in Smartcat or upload a file to an existing project

2. Enter the project data, such as name, deadline, and source and target language. You can select multiple target languages

3. Select the appropriate workflow for your translation. The Automatic Translation → Post-Editing workflow allows Smartcat to select the most suitable AI engine for the initial translation. After that, you can review the translation yourself or invite a collaborator to your project in Smartcat

4. Proceed to the integration-specific settings by clicking the respective button. Select the import mode for your translation: import existing translations or skip this step

5. After synchronization is complete, you see a list of target languages under the title of the original file. Click the underlined title on the left to open your project in Smartcat

Your ButterCMS content is now available for translation inside your Smartcat project.

Troubleshooting and common issues

API key errors

Problem: Smartcat displays an "Invalid API key" or "Authentication failed" message.

Solution:

1. Ensure you copied both Read and Write keys correctly

2. Verify your ButterCMS account permissions include API access

3. Try regenerating new keys and re-entering them in Smartcat

Missing or unlisted page types

Problem: Your expected page types don't appear in Smartcat.

Solution:

1. Confirm that the page type exists and is published in ButterCMS

2. Check that the Page Type ID was entered correctly

3. Reconnect the integration if new pages were added after setup

Locale mapping issues

Problem: Some target languages aren't displaying properly.

Solution:

1. Review your ButterCMS Localization tab to confirm all locales are active

2. Make sure each locale is mapped to a valid Smartcat language code

3. Re-save the integration to refresh language mapping

FAQs

Does the integration support all content types?

Currently, it supports Page Types and Collections. Some dynamic modules may require manual syncing.

What happens if I update a page in ButterCMS after integration?

If autosync rules are set up, Smartcat automatically detects and imports updates during the next sync cycle.

Summary

By following this guide, you have:

1. Linked your ButterCMS account with Smartcat

2. Configured locales and page types

3. Learned how to troubleshoot common connection issues

You are now ready to streamline your multilingual content process directly between ButterCMS and Smartcat.