CSV Files: Complete Guide to CSV Based Localization

What Are CSV Files for Localization?

CSV (Comma-Separated Values) files are a simple, universal text format for storing tabular data. They’re widely used in localization because they can be opened by virtually any spreadsheet application, text editor, or programming language, making them an excellent choice for exchanging translation data between different systems and teams.

CSV files store data in plain text with values separated by commas (or other delimiters), making them lightweight, easy to parse, and compatible with almost any tool or platform.

Why AZbox Supports CSV Format

At AZbox, we understand that CSV is often the common denominator when exchanging data between different localization tools and workflows. That’s why AZbox fully supports CSV file import and export, allowing you to:

• Import existing CSV files directly into your AZbox project
• Export translations to CSV for use in any system
• Exchange data with external tools and translators
• Migrate from legacy systems that export to CSV
• Integrate with custom workflows and scripts
• Process translations programmatically with ease

CSV File Structure for Localization

Basic Structure

A simple CSV file for localization:

key,en,es,fr
welcome_title,Welcome,Bienvenido,Bienvenue
button_save,Save,Guardar,Enregistrer
button_cancel,Cancel,Cancelar,Annuler
error_network,Network error,Error de red,Erreur réseau

With Comments and Context

Enhanced structure with additional metadata:

key,en,es,comment,context
welcome_title,Welcome,Bienvenido,Home screen title,Displayed at top of home page
button_save,Save,Guardar,Action button,Used in forms
button_cancel,Cancel,Cancelar,Action button,Used in dialogs
error_network,Network error,Error de red,Error message,Shown when offline

Multi-Language File

All languages in a single file:

key,en,es,fr,de,it,pt
app_name,My App,Mi App,Mon App,Meine App,La Mia App,Meu App
welcome,Welcome,Bienvenido,Bienvenue,Willkommen,Benvenuto,Bem-vindo
goodbye,Goodbye,Adiós,Au revoir,Auf Wiedersehen,Arrivederci,Adeus

CSV Delimiters and Formats

Common Delimiters

Delimiter	Name	Example	Common Use
,	Comma	key,en,es	Standard CSV
;	Semicolon	key;en;es	European locales
\t	Tab	key en es	TSV files
`	`	Pipe	`key

Semicolon-Separated (European Format)

Many European systems use semicolons because commas are used as decimal separators:

key;en;es;fr
price;"$9.99";"9,99 €";"9,99 €"
welcome;Welcome;Bienvenido;Bienvenue

Tab-Separated Values (TSV)

TSV files avoid delimiter conflicts within text:

key	en	es	fr
welcome	Welcome	Bienvenido	Bienvenue
message	Hello, world!	¡Hola, mundo!	Bonjour le monde!

Handling Special Characters

Quoting Rules

Values containing special characters must be quoted:

key,en,es
greeting,"Hello, friend!","¡Hola, amigo!"
quote,"He said ""Hello""","Él dijo ""Hola"""
multiline,"Line 1
Line 2","Línea 1
Línea 2"

Escaping Rules

Character	How to Handle	Example
Comma	Wrap in quotes	"Hello, world"
Quote	Double the quote	"Say ""Hi"""
Newline	Wrap in quotes	"Line1\nLine2"
Leading/trailing space	Wrap in quotes	" space "

Example with Special Characters

key,en,es,notes
terms,"Terms & Conditions","Términos y Condiciones","Legal page"
quote,"She said ""Yes!""","Ella dijo ""¡Sí!""","Quote example"
list,"Red, Green, Blue","Rojo, Verde, Azul","Color list"
multiline,"First line
Second line","Primera línea
Segunda línea","Multi-line text"

Recommended CSV Structure

Column Configuration

For optimal import into AZbox:

Column	Header	Description	Required
1	key	Unique string identifier	✅ Yes
2	en or source	Source language	✅ Yes
3+	es, fr, etc.	Target languages	✅ At least one
N	comment	Notes for translators	Optional
N+1	context	Where string appears	Optional
N+2	max_length	Character limit	Optional

Complete Example

key,en,es,fr,comment,max_length
app_name,My Application,Mi Aplicación,Mon Application,App display name,30
welcome_message,"Welcome back, {name}!","¡Bienvenido, {name}!","Bienvenue, {name}!",Home greeting,50
items_count,{count} items,{count} artículos,{count} articles,Cart count,20
btn_checkout,Checkout,Pagar,Commander,Cart button,15
error_login,Invalid credentials,Credenciales inválidas,Identifiants invalides,Login error,40

Handling Placeholders

Variable Placeholders

Document placeholders in your CSV:

key,en,es,placeholder_info
greeting,"Hello, {username}!","¡Hola, {username}!","{username} = user's display name"
order,"Order #{id} - {status}","Pedido #{id} - {status}","{id} = order number, {status} = order status"
price,"Price: {currency}{amount}","Precio: {amount} {currency}","{currency} = $, €; {amount} = number"

Plural Forms

For plural handling, use separate rows or keys:

key,plural_form,en,es
items_count,one,{count} item,{count} artículo
items_count,other,{count} items,{count} artículos
days_left,zero,Expires today,Expira hoy
days_left,one,{count} day left,{count} día restante
days_left,other,{count} days left,{count} días restantes

ICU Message Format

For complex messages:

key,en,es,format
cart_items,"{count, plural, one {# item} other {# items}}","{count, plural, one {# artículo} other {# artículos}}",ICU
gender_greeting,"{gender, select, male {Mr.} female {Ms.} other {}}","{gender, select, male {Sr.} female {Sra.} other {}}",ICU

Character Encoding

UTF-8 Encoding

Always use UTF-8 encoding for CSV files to support all languages:

key,en,ja,zh,ar
hello,Hello,こんにちは,你好,مرحبا
goodbye,Goodbye,さようなら,再见,وداعا
thanks,Thank you,ありがとう,谢谢,شكرا

BOM (Byte Order Mark)

Some applications require UTF-8 BOM for proper encoding detection:

• With BOM: Better compatibility with Excel
• Without BOM: Standard UTF-8, better for programming

Encoding Issues and Solutions

Problem	Cause	Solution
é instead of é	Wrong encoding	Save as UTF-8
??? characters	Missing encoding	Add BOM or specify UTF-8
Mojibake (garbled text)	Encoding mismatch	Re-export with correct encoding

Importing CSV to AZbox

Step 1: Prepare Your CSV File

Ensure your file follows best practices:

1. First row: Column headers
2. Consistent delimiter: Use comma or semicolon throughout
3. Proper quoting: Quote values with special characters
4. UTF-8 encoding: Save with UTF-8 encoding
5. No empty rows: Remove blank lines

Step 2: Import via AZbox Dashboard

1. Log in to your AZbox dashboard
2. Navigate to your project
3. Go to Import/Export section
4. Select Import and choose CSV
5. Upload your CSV file
6. Configure import settings:
   • Select delimiter (comma, semicolon, tab)
   • Specify encoding (UTF-8, UTF-8 BOM)
   • Map columns to fields
7. Preview and confirm import

Step 3: Column Mapping

Map your CSV columns to AZbox fields:

CSV Column → AZbox Field
─────────────────────────
key        → Key
en         → English (source)
es         → Spanish
fr         → French
comment    → Comment
context    → Context

Exporting CSV from AZbox

Export Options

Customize your CSV export:

Option	Description
Languages	Select which languages to include
Delimiter	Choose comma, semicolon, or tab
Encoding	UTF-8 or UTF-8 with BOM
Include metadata	Add comments, context columns
Empty translations	Include or skip untranslated

Export Steps

1. Go to Import/Export in your project
2. Select Export and choose CSV
3. Configure export options
4. Download the generated CSV file

Export Formats

Single file with all languages:

key,en,es,fr,de
welcome,Welcome,Bienvenido,Bienvenue,Willkommen

One file per language:

• translations_en.csv
• translations_es.csv
• translations_fr.csv

Working with CSV in Different Tools

Microsoft Excel

Opening CSV:

1. File → Open → Select CSV file
2. Text Import Wizard appears
3. Select “Delimited” and UTF-8 encoding
4. Choose delimiter (comma)
5. Finish import

Saving CSV:

1. File → Save As
2. Choose “CSV UTF-8 (Comma delimited)”
3. Click Save

Google Sheets

Opening CSV:

1. File → Import → Upload
2. Select CSV file
3. Choose “Replace spreadsheet” or “Insert new sheet”
4. Separator: Detect automatically or Comma

Exporting CSV:

1. File → Download → Comma Separated Values (.csv)

LibreOffice Calc

Opening CSV:

1. File → Open → Select CSV
2. Choose Character set: UTF-8
3. Select separator: Comma
4. Click OK

Saving CSV:

1. File → Save As
2. Choose “Text CSV (.csv)”
3. Check “Edit filter settings”
4. Character set: UTF-8
5. Field delimiter: ,
6. Text delimiter: “

Command Line (Unix/Linux/macOS)

View CSV:

# View with column alignment
column -s, -t file.csv | less -S

# View specific columns
cut -d, -f1,3 file.csv

# Count lines
wc -l file.csv

Convert encoding:

# Convert to UTF-8
iconv -f ISO-8859-1 -t UTF-8 input.csv > output.csv

# Add BOM for Excel
printf '\xEF\xBB\xBF' > output.csv && cat input.csv >> output.csv

Python

Reading CSV:

import csv

with open('translations.csv', 'r', encoding='utf-8') as file:
    reader = csv.DictReader(file)
    for row in reader:
        print(f"Key: {row['key']}, EN: {row['en']}, ES: {row['es']}")

Writing CSV:

import csv

data = [
    {'key': 'welcome', 'en': 'Welcome', 'es': 'Bienvenido'},
    {'key': 'goodbye', 'en': 'Goodbye', 'es': 'Adiós'},
]

with open('output.csv', 'w', encoding='utf-8', newline='') as file:
    writer = csv.DictWriter(file, fieldnames=['key', 'en', 'es'])
    writer.writeheader()
    writer.writerows(data)

JavaScript/Node.js

Reading CSV:

const fs = require('fs');
const csv = require('csv-parse/sync');

const content = fs.readFileSync('translations.csv', 'utf-8');
const records = csv.parse(content, { columns: true });

records.forEach(row => {
    console.log(`Key: ${row.key}, EN: ${row.en}, ES: ${row.es}`);
});

Writing CSV:

const fs = require('fs');
const { stringify } = require('csv-stringify/sync');

const data = [
    { key: 'welcome', en: 'Welcome', es: 'Bienvenido' },
    { key: 'goodbye', en: 'Goodbye', es: 'Adiós' },
];

const output = stringify(data, { header: true });
fs.writeFileSync('output.csv', output);

Best Practices for CSV Localization

1. Always Use UTF-8

# Check file encoding
file -I translations.csv

# Expected output
translations.csv: text/plain; charset=utf-8

2. Consistent Key Naming

Bad:

key,en
Str1,Welcome
btn-save,Save
ERROR_MSG,Error

Good:

key,en
welcome_title,Welcome
button_save,Save
error_generic,Error

3. Quote All Text Values

Safer approach - quote everything:

key,en,es
"welcome","Welcome","Bienvenido"
"greeting","Hello, friend!","¡Hola, amigo!"
"price","$9.99","9,99 €"

4. Include Header Row

Always include descriptive headers:

key,en,es,fr,comment
welcome,Welcome,Bienvenido,Bienvenue,Home screen greeting

5. Validate Before Import

Check your CSV:

• No duplicate keys
• Consistent number of columns
• Proper quoting
• Valid encoding

6. Document Placeholders

key,en,es,placeholders
greeting,"Hello, {name}!","¡Hola, {name}!","{name}: user's name"
count,"{n} items","{n} artículos","{n}: number of items"

7. Handle Empty Values

key,en,es,fr
welcome,Welcome,Bienvenido,
goodbye,Goodbye,,Au revoir

Empty cells indicate untranslated strings.

Common Issues and Solutions

Issue: Encoding Problems

Problem: Special characters appear corrupted (é → é).

Solution:

1. Open in text editor
2. Save As with UTF-8 encoding
3. Or convert: iconv -f ISO-8859-1 -t UTF-8 input.csv > output.csv

Issue: Delimiter Conflicts

Problem: Commas in text break the structure.

Solution:

• Quote all text values: "Hello, world"
• Or use a different delimiter (semicolon, tab)

Issue: Excel Changes Data

Problem: Excel converts values (dates, numbers) incorrectly.

Solution:

• Import via Text Import Wizard
• Format columns as “Text” before importing
• Use a different application (Google Sheets, VS Code)

Issue: Line Breaks in Values

Problem: Multi-line text breaks CSV structure.

Solution: Quote the entire value:

key,en
message,"First line
Second line
Third line"

Issue: Duplicate Keys

Problem: Same key appears multiple times.

Solution:

• Remove duplicates before import
• Use unique key naming convention
• AZbox warns about duplicates during import

Issue: Missing Columns

Problem: Some rows have fewer columns than headers.

Solution:

• Ensure consistent column count
• Add empty quoted values: key,en,,"",fr
• Validate CSV structure before import

CSV vs Other Formats

Feature	CSV	Excel	JSON
File size	Small	Medium	Small
Human readable	Yes	No (binary)	Yes
Formatting	None	Rich	None
Universal support	Excellent	Good	Good
Version control	Excellent	Poor	Excellent
Nesting support	No	No	Yes
Programming support	Excellent	Moderate	Excellent

AZbox CSV Features

When you use CSV with AZbox, you benefit from:

• Flexible delimiter support - Comma, semicolon, tab, or custom
• Encoding detection - Automatic UTF-8/Latin-1 detection
• Smart column mapping - Auto-detect language columns
• Validation - Check for errors before import
• Merge options - Update existing or add new strings
• Placeholder preservation - Maintains {variables} correctly
• Bulk operations - Import thousands of strings at once
• Export customization - Choose format, encoding, languages
• Progress tracking - See translation completion status

Conclusion

CSV files offer a simple, universal format for managing translations that works with virtually any tool or system. With AZbox’s comprehensive CSV support, you can:

1. Import existing CSV files with flexible column mapping
2. Export translations in customizable CSV formats
3. Exchange data easily with any system or translator
4. Maintain compatibility with legacy tools and workflows
5. Process translations programmatically when needed

Ready to streamline your CSV-based localization workflow?

Start Your Free Trial | View Pricing

---

AZbox provides full CSV import and export support, making it easy to exchange translation data with any tool or system. Import, manage, and export your translations with ease.