How to Prepare a CSV File for Translation

Learn how to prepare a CSV file for translation, with best practices for file structure, keys, placeholders, plural forms, special characters, and UTF-8 encoding.

What is a CSV File for Translation?

CSV (Comma-Separated Values) is a plain text format that organizes data into rows and columns, with each value separated by a comma. It’s one of the most widely used formats for software localization because it’s lightweight, easy to edit, and supported by most development frameworks, e-commerce platforms, and translation tools.

How to Structure a CSV File for Translation

To prepare a CSV file for translation, you need a clear header row, unique identifier keys, and a source text column. Getting this right before you upload your file to a translation tool prevents import errors, missing strings, and broken output.

The Header Row

Make the first row of your file column names, not content. Use plain, descriptive labels like key, source_text, and context. These tell your translation tool and any human reviewers exactly what each column contains.

Required Columns

Every translation-ready CSV needs at minimum a key column and a source text column.

The key column holds a unique identifier for each string. Your application uses it to match the right translation at runtime. Use a consistent naming convention, stick to lowercase letters, underscores, and dots. This column does not get translated. Common formats include button.submit, error.invalid_login, and onboarding.welcome_message.

The source_text column contains the original text in your base language, ready for translation.

Never change a key after translation has started. Doing so creates a new string and orphans the existing translation.

Optional Columns

Include a context or description column wherever possible. Short strings like “Save” or “Back” can mean different things depending on where they appear in your interface. A brief note lets you track where each string appears.

For large files, a namespace or group column helps you organize strings by feature or section, making the file significantly easier to manage and review.

Language Columns

If your workflow requires keeping source and target languages in the same file, add a column for each target language using BCP-47 language codes as the header. For example, use es_ES for Spanish (Spain)  or fr_FR for French.

How to Handle Placeholders and Variables in CSV Translation

Different frameworks use different placeholder syntax. Make sure you know which format your application expects and use it consistently across your entire file:

If your source text includes HTML tags like <strong>, <br>, or <a href="">, treat them the same way as placeholders. 

Never translate placeholders or HTML tags. PTC automatically detects and preserves placeholders and HTML tags across all supported formats. It never translates or modifies them, and it keeps them in the correct position in each target language.

How to Handle Plural Forms in CSV Localization

To handle plurals correctly across languages, you need to store singular and plural forms in separate rows with distinct keys. If you combine plural forms into a single string, translations won’t adapt to the grammatical rules of other languages.

For example:

• English has two plural forms: singular and plural
• Many other languages have more: Arabic has six plural forms, Russian has three, and Polish has four

 A translation tool that only accounts for singular and plural will produce incorrect output for these languages.

Don’t combine plural forms into a single string using slashes or parentheses, like “You have {count} item(s) in your cart.” This approach is not translatable and breaks the grammar of most languages.

How to Escape Special Characters in CSV Files

To keep your CSV file valid, you need to handle special characters correctly before sending it for translation.

• Commas: Enclose any string that contains a comma in double quotes, otherwise the parser treats it as a column separator and splits your string across cells.
• Quotes: If a string contains double quotes, escape them by doubling them. For example, Click ""Save"" to continue. 
• Curly quotes: Always use straight quotes (") rather than curly quotes (" "). CSV parsers do not recognize curly quotes and will throw formatting errors.
• Trailing spaces: Remove trailing spaces from all cells before sending your file. They are invisible in most spreadsheet editors but can cause string matching failures in your application.
• Line breaks: If a string needs a line break, enclose it in double quotes and include the break inside.

Example of a Translation-Ready CSV File

How to Save Your CSV File With UTF-8 Encoding

Save your CSV file in UTF-8 encoding before uploading it for translation. UTF-8 supports every character set you are likely to need, including accented characters like é and ü, non-Latin scripts like Arabic, Japanese, and Chinese, and special symbols.

Without UTF-8, characters outside the basic Latin alphabet may display as ???, empty boxes, or garbled text in your application.

To save as UTF-8:

• In Excel, choose File → Save As and select “CSV UTF-8 (Comma delimited) (*.csv)” from the format dropdown. 
• In Google Sheets, go to File → Download → Comma-separated values (.csv). Google Sheets exports as UTF-8 by default.

CSV Translation Best Practices

Following these practices before you translate your CSV file will save you time, prevent errors, and improve the quality of your translations.

✔ Use a dedicated translation tool

Avoid translating CSV files manually in a text editor or spreadsheet software. Dedicated translation tools like PTC preserve your file structure, handle placeholders correctly, and keep your keys intact throughout the process.

✔ Use standard commas as your delimiter

Some tools default to semicolons, but commas are the most widely supported and least likely to cause import errors.

✔ Keep one string per rows

Combining multiple strings into a single row makes translations impossible to manage and breaks most translation tools.

✔ Isolate translatable columns

When working with large CSV files, keep columns that need translation separate from those that should remain unchanged, such as numeric IDs, SKUs, or technical parameters. This reduces the risk of a translator or tool accidentally modifying data that should stay untouched.

✔ Avoid merged cells and spreadsheet formatting

CSV is plain text. Any formatting applied through spreadsheet software gets stripped when the file is processed.

✔ Remove unnecessary columns and metadata

Only include columns your translation tool needs. Extra columns add noise and increase the risk of import errors.

✔ Test with a small sample first

Before running a large file through translation, test with a small sample to catch structural or encoding issues early.

✔ Validate your file before uploading

Check that every row has a unique key with no duplicates, that no keys contain spaces or special characters, and that there are no broken rows or missing translations. Most translation management tools include built-in validation, or you can use a dedicated CSV validator before uploading.

✔ Keep a backup

Always keep a copy of your original CSV file before sending it for translation.