Import an existing glossary

Klaviyo's Smart Translations feature uses a glossary to control how specific terms are translated — brand names, product names, slogans, or technical terms that need a consistent translation across every campaign.

If you already maintain a glossary in another translation system (DeepL, Lokalise, Phrase, an internal spreadsheet), you can import it directly into Klaviyo as a CSV instead of recreating each entry by hand.

When to use CSV import

CSV import is useful when you want to:

• Bring an existing glossary into Klaviyo from a TMS (Translation Management System) like DeepL, Lokalise, Phrase, or memoQ.
• Add a large batch of terms at once (dozens or hundreds), rather than typing each one in the UI.
• Migrate a glossary maintained in a shared spreadsheet to a single source of truth in Klaviyo.

For just a handful of terms, adding them manually one-by-one in the glossary panel is usually faster.

Prepare your CSV file

File format

• Encoding: UTF-8
• File type: .csv
• Delimiter: comma (,)
• Header row: required (see below)

Wrap terms that contain commas in double quotes, such as "hello, world", so the comma stays within the term.

Each term can contain up to 200 characters. Your saved glossary can contain up to 3,000 entries, including existing entries when you use Add.

Sample file

Required columns

Every row must include 4 columns:

• source term — the term in the source language
• target term — how the term should be translated
• source locale — the BCP-47 locale tag of the source language
• target locale — the BCP-47 locale tag of the target language

All 4 headers must be present in the first row of the file. Column order does not matter.

Locale codes (BCP-47)

Locale codes follow the BCP-47 standard. The most common form is a two-letter language code, optionally followed by a region:

• en — English
• en-US — English (United States)
• en-GB — English (United Kingdom)
• fr — French
• fr-CA — French (Canada)
• de — German
• ja — Japanese
• pt-BR — Portuguese (Brazil)

Use a locale supported by Smart Translations. If a regional variant is not supported, the importer uses a supported variant of the same language when it can resolve one. Otherwise, the row is skipped. For example, en-US is imported as en, and pt-BR as pt. Supported variants such as en-GB and fr-CA are kept. Use the resolved locale when checking for conflicting translations.

Multiple language pairs in one file

A single CSV can include entries for many language pairs. Rows that share the same term and locale are grouped into one glossary entry. For example:

These 4 rows describe 1 glossary entry with English, French, Spanish, and German terms. The last row repeats a pair already linked through hello, so it does not create another entry. This is useful if you maintain one master glossary that powers translation in several locales.

Glossary terms are symmetric

Each glossary entry defines a bidirectional equivalence between terms. If you import:

Klaviyo will:

• Translate hello as bonjour when translating English → French.
• Translate bonjour as hello when translating French → English.

This means you cannot define asymmetric mappings such as:

Both rows map bonjour to a different English term, which is a conflict within the CSV. The importer keeps the first mapping and skips the conflicting row with a warning (see Troubleshoot import errors).

If you need different English translations for bonjour depending on context, glossary terms aren't the right tool — they're meant for terms that translate the same way every time.

Import modes

When you import, choose one of 2 modes:

• Add keeps existing glossary entries and appends entries from the CSV. It does not check incoming entries for conflicts with the saved glossary. Compare your file with the saved glossary before importing: conflicting entries can change which translation is used.
• Replace all replaces your entire saved glossary with the valid entries from the CSV. Rows skipped during validation are not included.

Import the file

1. Go to Settings > Translations > Glossary.
2. Click Import CSV.

3. In the dialog, choose Add or Replace all.

4. Click the file area and select your .csv file (or drag the file into the area).
5. Click Next. Klaviyo validates the file but does not save anything yet. You'll see a preview screen.
6. Review the preview:
   • Total rows is the number of nonblank data rows, excluding the header.
   • Valid entries is the number of glossary entries created from the file. Multiple rows can be grouped into 1 entry, so this can be lower than the total row count.
   • Rows skipped — how many were dropped due to validation issues.
7. If warnings appear, review which rows were skipped or changed before proceeding. To fix the file, click Select a different file, upload the corrected file, and choose the import mode again.
8. Click Import to save the changes.

After a successful import, the dialog closes and the glossary panel shows your saved terms. Use Source Language and Target Language to review each imported language pair.

If a file-level error blocks validation, you'll see an Import failed screen instead of the preview. Fix the error and select a different file to try again.

Troubleshoot import errors

Klaviyo shows validation messages explaining what needs attention. File-level errors block the import; row-level warnings identify rows that are skipped or changed.

File-level errors

These stop the import entirely. Fix them and try again.

Row-level warnings

These identify rows that are skipped or changed. You can import the remaining valid entries if no file-level error blocks the import.

Generic validation error

If you see “A validation error occurred. Please check your file and try again.” check that the file matches the expected format. The saved glossary is limited to 3,000 entries; Add counts existing entries too. If the combined total exceeds this limit, remove entries or use a reviewed replacement file that stays within the limit. Contact support if the error persists.

Additional resources