Title

BigCommerce Translations App

User Guide

This guide will help you get started with the BigCommerce Translations App, which enables you to manage translations for your Catalyst storefront’s catalog across multiple languages.

Under the hood this app is using the same GraphQL Admin APIs you can use with your preferred translation provider. If you aren’t ready for that, the import / export format is built to work well with AI.

The following catalog fields are translatable:

  • Basic Information:
    • Product Name (name)
    • Description (description)
  • SEO Information:
    • Page Title (pageTitle)
    • Meta Description (metaDescription)
  • Storefront Details:
    • Warranty (warranty)
    • Availability Description (availabilityDescription)
    • Search Keywords (searchKeywords)
  • Pre-order Settings:
    • Pre-order Message (preOrderMessage)
  • Options:
    • Option Display Name (displayName)
    • Option Values:
      • Value Label (label)
  • Modifiers (for various types including Checkbox, TextField, MultilineTextField, NumbersOnlyTextField, Dropdown, RadioButtons, RectangleList, Swatch, and PickList):
    • Modifier Display Name (displayName)
    • Field Value (for Checkbox type)
    • Default Value (for TextField types)
    • Value Labels (for selection-based types)
  • Custom Fields:
    • Field Name (name)
    • Field Value (value)

The app itself is also translated into multiple locales. This means if you change your store profile to use one of these locales as your preferred language, you’ll get a localized management experience:

  • da-DK – Danish (Denmark)
  • de-DE – German (Germany)
  • en-US – English (United States)
  • es-419 – Spanish (Latin America)
  • es-ES – Spanish (Spain)
  • fr-FR – French (France)
  • it-IT – Italian (Italy)
  • ja-JP – Japanese (Japan)
  • ko-KR – Korean (South Korea)
  • nl-NL – Dutch (Netherlands)
  • no-NO – Norwegian (Norway)
  • pl-PL – Polish (Poland)
  • pt-BR – Portuguese (Brazil)
  • sv-SE – Swedish (Sweden)
  • uk-UA – Ukrainian (Ukraine)
  • zh-CN – Chinese (Simplified, China)

Prerequisites

Before installing the app, ensure you have:

  1. A BigCommerce store with Catalyst enabled
  2. Multi-language functionality turned on in your store settings
  3. At least one additional language configured for your storefront channel

To activate a Catalyst storefront, go to the Channels section in your control panel and select “+ Create channel”. You will see the option to create a Catalyst storefront if you are on a paid plan.

The app will check if you have multi-language functionality turned on when you load it. It will look like this:

If you don’t have the functionality turned on for your store yet, contact support to find out how.

Installation

  1. Visit this link to view the installation screen: https://login.bigcommerce.com/deep-links/app/54742
  2. Click “Install”
  3. Once installed, you’ll find the app:
    • In your BigCommerce admin panel under “Apps”
    • As a new “Translate” action within your Products list

Features

The app provides two main ways to manage your catalog’s translations:

1. Individual Product Translation

Navigate to your Products list in your BigCommerce control panel and click on the “Actions” dropdown for the product you want to translate. You will see a menu option for “Translate” like this:

The translate extension will show, surfacing all channels with more than one locale. By default it will show the first locale that is not the default locale for the channel. Once you select a channel and locale, it will be remembered in your browser and auto selected the next time you open this.

In this screen you will be able to edit translations for:

  • Product name and description
  • SEO title and meta description
  • Variant option labels
  • Custom fields
  • Pre-order settings
  • Modifier options and values

If you would like more area to edit these translations, press the expand icon [<] in the top left of the extension to utilize all the real estate of the control panel.

It will then show the default local and selected language you want to translate into side-by-side.

After you’ve made your edits, press “Save” and you’ll see a success message when it succeeds.

If you don’t see an update, the most common reason is your control panel session for the app has expired. Refresh your browser to fix this issue, logging in again to your account if necessary.

2. Bulk Translation Management

To manage translations in bulk, open up the apps main screen and press “Start Translation Workflow”.

This will open up a Translation Jobs section where you can import and export translation CSVs.

Exporting Translation CSVs

Exporting is normally where you start translating, as it gives you the CSV file structured in a way that makes translating the values easier. To start that click “Action” at the top and select “Export”. It will open up a modal for you to select the channel and locale you would like to translate.

After starting the export, you will see it show in the Job Results section of the page. Once it’s complete you can download the CSV file through the […] in the Actions column of the table.

The export columns will have a format of fieldName_defaultLocale and fieldName_targetLocale. Like this:

Importing Translation CSVs

After you add or update your translations within the CSV file, you can start the import job by going to the Translation Jobs section (by pressing “Start translation workflow on the main app screen). You will be asked to select the channel and locale, then the CSV you’d like to import.

You will get a preview of the header row and first row of data before uploading. After uploading the file, the import process will start.

ℹ️ Supported Columns for Import CSVs

The following fields are supported in the fieldName_targetLocale format:

  • name
  • description
  • pageTitle
  • metaDescription
  • warranty
  • availabilityDescription
  • searchKeywords
  • preOrderMessage
  • options
  • modifiers
  • customFields

As an example, if you wanted to import French page titles and meta descriptions, you would use:

  • pageTitle_fr
  • metaDescription_fr

Starting with an export of the locale makes this easier as the CSV columns will already be named in the correct format. You can then remove columns you don’t want to edit from there.

Best Practices for Imports

  1. Export the most recent version of translations for the locale you want to edit in bulk, before starting edits
  2. Keep the column headers unchanged
    • e.g. Don’t modify name_es to name_spanish
  3. Only edit the translated column cells
    • Editing the default locale columns won’t change anything, as they are not utilized during import. Those columns are for your reference when translating.
  4. Save your work frequently when editing the CSV
  5. Save your import CSV in the same format as the export CSV
    • e.g. Don’t change the CSV delimiter from comma (,) to semicolon (;)
  6. Test translations on your storefront after import

Troubleshooting

If you encounter issues:

  1. Verify that multi-language functionality is enabled
  2. Verify that your session is still value (refreshing the page is the easiest fix)
  3. Ensure you’re using the correct locale code for your target language
  4. Check that your import CSV maintains the original format export CSV format
    • Delimiter: , (comma)
    • Quote Character: ” (double quote)
    • Escape Character: ” (double quote)