How to manage translations in bulk with CSV

Manage translations outside Klaviyo by exporting and editing a CSV file, then importing it back to update translations in bulk or collaborate with others.

Export a CSV of your translations

Follow these steps to export the current translations for a single message:

1. Open the message you want to update (campaign email, flow email, SMS, WhatsApp message, etc.).
2. Click the message’s Translate icon or button, or the button showing the number of translations, to open the translation editor. If the message has not been translated yet, complete the language setup first.
3. In the translation editor, open the 3-dot actions menu and click Export.

4. Under Select export format, choose CSV. Keep Smartling compatible selected if you will send the file to Smartling, or clear it to edit a standard CSV in a spreadsheet.

5. Under Languages to export, choose Select all to include all existing translation languages, or Custom selection to choose specific languages. To export only the source text for a translator, choose the source-language-only option. The source language is included in every export.
6. Click Export to download the CSV.

Smartling CSV

A Smartling-compatible CSV includes:

Smartling directives at the top of the file, including:

# smartling.first_row_header=TRUE
# smartling.paths=2
# smartling.source_key_paths=1
# smartling.translations_in_columns=TRUE

• block_id – the unique identifier for each translatable string in this message.
• Source language code (e.g., en) – the original source text for that string.
• Language columns for the translation languages you selected, if any.

You can use this file as-is to import your strings to Smartling. Smartling automatically parses the CSV, extracts the strings, and lets you trigger translation jobs.

After the job finishes, download the translated CSV. Before importing it into Klaviyo, remove any leading # smartling. directive rows so the first row contains the column headers. Keep the block_id column, the source-language column, and at least 1 supported translation-language column. Then follow Import the CSV below.

Standard CSV

A standard CSV includes:

• block_id – the unique identifier for each translatable string in this message.
• source – the original source text for that string.
• Language columns: 1 column per translation language you selected, named with its language code (for example, en, fr, es-MX). A source-only export has no translation-language columns.

You can now open this file in Excel, Google Sheets, or another spreadsheet editor.

Update the CSV

When you edit the CSV, you only need to work in the language columns.

Do not edit, add, or delete any values in the block_id column. If a row has an invalid or missing block_id, that row is ignored during import and its translations are not updated.

What you can safely change

In the CSV:

• Update existing translations by editing the appropriate language column.
• Add missing translations by filling in empty cells for a language column.
• Leave a language’s values unchanged if you do not want to update that language.
• Add one or more new language columns:
  • Use a valid BCP‐47 language code (for example, fr-CA, de, ca).
  • On import, supported languages with new translation values are added to the translation editor for this message.

What you should not change

Avoid the following:

• Do not edit or delete block_id values.
• Do not add rows. Each row must continue to map to an existing translatable string in the message.
• Do not change the source values in the CSV:
  • To change the source content, edit the message directly in the Klaviyo editor, then export a new CSV.
• Keep the block_id and source column headers unchanged. In a Smartling CSV, keep the source-language column header instead of source. Keep each translation-language column labeled with its supported language code.
• Do not change the file format:
  • Keep the file as a .csv file.
  • Save in UTF‐8 encoding.

Keep personalization variables and template tags, such as {{ first_name }} and {% if ... %}, unchanged in each translation. If these placeholders differ from the source message, validation blocks the import.

Handling empty cells

If you clear out a translation cell in the CSV and leave it empty:

• The import treats that empty string as a value.
• The existing translation for that cell is overwritten with an empty value. This can effectively remove a translation.

If clearing a cell also removes placeholders that are present in the source, validation blocks the import. Restore the placeholders or remove that language column before importing.

If you want to avoid changing a translation, leave its existing value in the CSV or remove that language column entirely before importing.

When you are done editing, save the file as a UTF‐8 encoded .csv.

Import the CSV

After you have updated and saved your CSV:

1. Return to the translation editor for the same message.
2. Open the 3-dot actions menu and click Import CSV.
3. In the import modal, either:

• Click Select file and choose your CSV, or
• Drag and drop your CSV into the upload area.

4. Click Next to validate the file and preview the changes.

Klaviyo runs a validation “dry run” and shows:

• A summary of how many rows will be updated, unchanged, or ignored
• Any warnings or errors it detected

1. Review the summary and warnings carefully.
2. If everything looks correct, click Import to apply the changes.

When the import succeeds, the modal closes and your translations are updated in the translation editor. Review the imported translations.

During validation, Klaviyo also checks for:

• File type and encoding: use a UTF-8 encoded CSV.
• CSV columns: keep block_id, the source column (or the source-language column for Smartling), and at least 1 supported translation-language column.
• Language codes that are not recognized or not supported by the channel.
• Empty translation values and other potential issues.
• Personalization variables and template tags that differ from the source message.

If validation fails, you see an error message. Click Select new file after correcting the CSV to try again; validation does not change your translations.

Understand import results

After validation, the import summary shows what will happen if you proceed.

Summary counts

The summary can include counts like:

• Updated: the number of rows where at least 1 translation value will change.
• Skipped (unchanged): rows in the CSV where all included translation values match what is already stored.
• Ignored: rows that will not be imported, such as duplicate rows after the first occurrence or rows whose block_id does not exist in this message.

Best practices

To keep your translation data accurate and easy to manage:

1. Start from the latest export. Avoid reusing older CSVs, especially after you change content or languages in the message.
2. Keep a backup of each export. Save a copy of the CSV before making changes so you can roll back if needed.
3. Coordinate with translators. Explain which columns they can edit (language columns only) and which columns they must not change (block_id, source).
4. Work in smaller batches if needed. If your file is very large, consider splitting work across multiple messages or running several smaller imports.
5. Use supported language codes. When adding new language columns, use supported BCP-47 codes from the Smart Translations article to avoid “unprocessable” languages.

Resolve validation warnings and import errors

If you see warnings or errors during import validation, review the sections below to understand what they mean and how to fix them.

Additional resources