Archivos CSV: Guía Completa de Localización Basada en CSV

¿Qué Son los Archivos CSV para Localización?

Los archivos CSV (Comma-Separated Values o Valores Separados por Comas) son un formato de texto simple y universal para almacenar datos tabulares. Se usan ampliamente en localización porque pueden abrirse con prácticamente cualquier aplicación de hojas de cálculo, editor de texto o lenguaje de programación, haciéndolos una excelente opción para intercambiar datos de traducción entre diferentes sistemas y equipos.

Los archivos CSV almacenan datos en texto plano con valores separados por comas (u otros delimitadores), haciéndolos ligeros, fáciles de parsear y compatibles con casi cualquier herramienta o plataforma.

Por Qué AZbox Soporta el Formato CSV

En AZbox, entendemos que CSV es frecuentemente el denominador común cuando se intercambian datos entre diferentes herramientas de localización y flujos de trabajo. Por eso AZbox soporta completamente la importación y exportación de archivos CSV, permitiéndote:

• Importar archivos CSV existentes directamente a tu proyecto AZbox
• Exportar traducciones a CSV para usar en cualquier sistema
• Intercambiar datos con herramientas externas y traductores
• Migrar desde sistemas legacy que exportan a CSV
• Integrar con flujos de trabajo personalizados y scripts
• Procesar traducciones programáticamente con facilidad

Estructura de Archivos CSV para Localización

Estructura Básica

Un archivo CSV simple para localización:

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

Con Comentarios y Contexto

Estructura mejorada con metadatos adicionales:

key,en,es,comment,context
welcome_title,Welcome,Bienvenido,Título pantalla inicio,Se muestra arriba de la página principal
button_save,Save,Guardar,Botón de acción,Usado en formularios
button_cancel,Cancel,Cancelar,Botón de acción,Usado en diálogos
error_network,Network error,Error de red,Mensaje de error,Se muestra cuando no hay conexión

Archivo Multi-Idioma

Todos los idiomas en un solo archivo:

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

Delimitadores y Formatos CSV

Delimitadores Comunes

Delimitador	Nombre	Ejemplo	Uso Común
,	Coma	key,en,es	CSV estándar
;	Punto y coma	key;en;es	Locales europeos
\t	Tabulador	key en es	Archivos TSV
`	`	Barra vertical	`key

Separado por Punto y Coma (Formato Europeo)

Muchos sistemas europeos usan punto y coma porque las comas se usan como separadores decimales:

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

Valores Separados por Tabulador (TSV)

Los archivos TSV evitan conflictos de delimitador dentro del texto:

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

Manejar Caracteres Especiales

Reglas de Entrecomillado

Los valores que contienen caracteres especiales deben entrecomillarse:

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"

Reglas de Escape

Carácter	Cómo Manejar	Ejemplo
Coma	Envolver en comillas	"Hola, mundo"
Comilla	Duplicar la comilla	"Di ""Hola"""
Salto de línea	Envolver en comillas	"Línea1\nLínea2"
Espacio inicial/final	Envolver en comillas	" espacio "

Ejemplo con Caracteres Especiales

key,en,es,notes
terms,"Terms & Conditions","Términos y Condiciones","Página legal"
quote,"She said ""Yes!""","Ella dijo ""¡Sí!""","Ejemplo de cita"
list,"Red, Green, Blue","Rojo, Verde, Azul","Lista de colores"
multiline,"First line
Second line","Primera línea
Segunda línea","Texto multilínea"

Estructura CSV Recomendada

Configuración de Columnas

Para importación óptima a AZbox:

Columna	Encabezado	Descripción	Requerido
1	key	Identificador único de string	✅ Sí
2	en o source	Idioma fuente	✅ Sí
3+	es, fr, etc.	Idiomas destino	✅ Al menos uno
N	comment	Notas para traductores	Opcional
N+1	context	Dónde aparece la string	Opcional
N+2	max_length	Límite de caracteres	Opcional

Ejemplo Completo

key,en,es,fr,comment,max_length
app_name,My Application,Mi Aplicación,Mon Application,Nombre mostrado de app,30
welcome_message,"Welcome back, {name}!","¡Bienvenido, {name}!","Bienvenue, {name}!",Saludo de inicio,50
items_count,{count} items,{count} artículos,{count} articles,Conteo del carrito,20
btn_checkout,Checkout,Pagar,Commander,Botón del carrito,15
error_login,Invalid credentials,Credenciales inválidas,Identifiants invalides,Error de login,40

Manejar Marcadores de Posición

Marcadores de Variables

Documenta los marcadores en tu CSV:

key,en,es,placeholder_info
greeting,"Hello, {username}!","¡Hola, {username}!","{username} = nombre de usuario"
order,"Order #{id} - {status}","Pedido #{id} - {status}","{id} = número pedido, {status} = estado"
price,"Price: {currency}{amount}","Precio: {amount} {currency}","{currency} = $, €; {amount} = número"

Formas Plurales

Para manejar plurales, usa filas o claves separadas:

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

Formato ICU Message

Para mensajes complejos:

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

Codificación de Caracteres

Codificación UTF-8

Siempre usa codificación UTF-8 para archivos CSV para soportar todos los idiomas:

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

BOM (Byte Order Mark)

Algunas aplicaciones requieren UTF-8 BOM para detección correcta de codificación:

• Con BOM: Mejor compatibilidad con Excel
• Sin BOM: UTF-8 estándar, mejor para programación

Problemas de Codificación y Soluciones

Problema	Causa	Solución
é en lugar de é	Codificación incorrecta	Guardar como UTF-8
Caracteres ???	Codificación faltante	Añadir BOM o especificar UTF-8
Mojibake (texto ilegible)	Desajuste de codificación	Re-exportar con codificación correcta

Importar CSV a AZbox

Paso 1: Prepara tu Archivo CSV

Asegúrate de que tu archivo sigue las mejores prácticas:

1. Primera fila: Encabezados de columna
2. Delimitador consistente: Usa coma o punto y coma en todo el archivo
3. Entrecomillado correcto: Entrecomilla valores con caracteres especiales
4. Codificación UTF-8: Guarda con codificación UTF-8
5. Sin filas vacías: Elimina líneas en blanco

Paso 2: Importar vía Panel de AZbox

1. Inicia sesión en tu panel de AZbox
2. Navega a tu proyecto
3. Ve a la sección Importar/Exportar
4. Selecciona Importar y elige CSV
5. Sube tu archivo CSV
6. Configura los ajustes de importación:
   • Selecciona delimitador (coma, punto y coma, tabulador)
   • Especifica codificación (UTF-8, UTF-8 BOM)
   • Mapea columnas a campos
7. Previsualiza y confirma la importación

Paso 3: Mapeo de Columnas

Mapea las columnas de tu CSV a campos de AZbox:

Columna CSV → Campo AZbox
─────────────────────────
key        → Key
en         → English (fuente)
es         → Spanish
fr         → French
comment    → Comment
context    → Context

Exportar CSV desde AZbox

Opciones de Exportación

Personaliza tu exportación CSV:

Opción	Descripción
Idiomas	Selecciona qué idiomas incluir
Delimitador	Elige coma, punto y coma o tabulador
Codificación	UTF-8 o UTF-8 con BOM
Incluir metadatos	Añade columnas de comentarios, contexto
Traducciones vacías	Incluir u omitir sin traducir

Pasos de Exportación

1. Ve a Importar/Exportar en tu proyecto
2. Selecciona Exportar y elige CSV
3. Configura las opciones de exportación
4. Descarga el archivo CSV generado

Formatos de Exportación

Un solo archivo con todos los idiomas:

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

Un archivo por idioma:

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

Trabajar con CSV en Diferentes Herramientas

Microsoft Excel

Abrir CSV:

1. Archivo → Abrir → Selecciona archivo CSV
2. Aparece el Asistente de importación de texto
3. Selecciona “Delimitado” y codificación UTF-8
4. Elige delimitador (coma)
5. Termina la importación

Guardar CSV:

1. Archivo → Guardar como
2. Elige “CSV UTF-8 (delimitado por comas)”
3. Clic en Guardar

Google Sheets

Abrir CSV:

1. Archivo → Importar → Subir
2. Selecciona archivo CSV
3. Elige “Reemplazar hoja de cálculo” o “Insertar nueva hoja”
4. Separador: Detectar automáticamente o Coma

Exportar CSV:

1. Archivo → Descargar → Valores separados por comas (.csv)

LibreOffice Calc

Abrir CSV:

1. Archivo → Abrir → Selecciona CSV
2. Elige Juego de caracteres: UTF-8
3. Selecciona separador: Coma
4. Clic en Aceptar

Guardar CSV:

1. Archivo → Guardar como
2. Elige “Texto CSV (.csv)”
3. Marca “Editar configuración de filtros”
4. Juego de caracteres: UTF-8
5. Delimitador de campo: ,
6. Delimitador de texto: “

Línea de Comandos (Unix/Linux/macOS)

Ver CSV:

# Ver con alineación de columnas
column -s, -t archivo.csv | less -S

# Ver columnas específicas
cut -d, -f1,3 archivo.csv

# Contar líneas
wc -l archivo.csv

Convertir codificación:

# Convertir a UTF-8
iconv -f ISO-8859-1 -t UTF-8 input.csv > output.csv

# Añadir BOM para Excel
printf '\xEF\xBB\xBF' > output.csv && cat input.csv >> output.csv

Python

Leer 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']}")

Escribir 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

Leer 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}`);
});

Escribir 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);

Mejores Prácticas para Localización con CSV

1. Siempre Usa UTF-8

# Verificar codificación del archivo
file -I translations.csv

# Salida esperada
translations.csv: text/plain; charset=utf-8

2. Nombres de Claves Consistentes

Mal:

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

Bien:

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

3. Entrecomilla Todos los Valores de Texto

Enfoque más seguro - entrecomilla todo:

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

4. Incluye Fila de Encabezado

Siempre incluye encabezados descriptivos:

key,en,es,fr,comment
welcome,Welcome,Bienvenido,Bienvenue,Saludo pantalla inicio

5. Valida Antes de Importar

Verifica tu CSV:

• Sin claves duplicadas
• Número consistente de columnas
• Entrecomillado correcto
• Codificación válida

6. Documenta los Marcadores de Posición

key,en,es,placeholders
greeting,"Hello, {name}!","¡Hola, {name}!","{name}: nombre del usuario"
count,"{n} items","{n} artículos","{n}: número de elementos"

7. Maneja Valores Vacíos

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

Las celdas vacías indican strings sin traducir.

Problemas Comunes y Soluciones

Problema: Problemas de Codificación

Problema: Los caracteres especiales aparecen corruptos (é → é).

Solución:

1. Abre en editor de texto
2. Guarda como con codificación UTF-8
3. O convierte: iconv -f ISO-8859-1 -t UTF-8 input.csv > output.csv

Problema: Conflictos de Delimitador

Problema: Las comas en el texto rompen la estructura.

Solución:

• Entrecomilla todos los valores de texto: "Hola, mundo"
• O usa un delimitador diferente (punto y coma, tabulador)

Problema: Excel Cambia los Datos

Problema: Excel convierte valores (fechas, números) incorrectamente.

Solución:

• Importa vía Asistente de importación de texto
• Formatea columnas como “Texto” antes de importar
• Usa una aplicación diferente (Google Sheets, VS Code)

Problema: Saltos de Línea en Valores

Problema: El texto multilínea rompe la estructura CSV.

Solución: Entrecomilla el valor completo:

key,en
message,"Primera línea
Segunda línea
Tercera línea"

Problema: Claves Duplicadas

Problema: La misma clave aparece múltiples veces.

Solución:

• Elimina duplicados antes de importar
• Usa convención de nombres de claves únicas
• AZbox advierte sobre duplicados durante la importación

Problema: Columnas Faltantes

Problema: Algunas filas tienen menos columnas que los encabezados.

Solución:

• Asegura conteo consistente de columnas
• Añade valores vacíos entrecomillados: key,en,,"",fr
• Valida estructura CSV antes de importar

CSV vs Otros Formatos

Característica	CSV	Excel	JSON
Tamaño de archivo	Pequeño	Mediano	Pequeño
Legible por humanos	Sí	No (binario)	Sí
Formato	Ninguno	Rico	Ninguno
Soporte universal	Excelente	Bueno	Bueno
Control de versiones	Excelente	Pobre	Excelente
Soporte de anidamiento	No	No	Sí
Soporte programático	Excelente	Moderado	Excelente

Funcionalidades CSV de AZbox

Cuando usas CSV con AZbox, te beneficias de:

• Soporte flexible de delimitadores - Coma, punto y coma, tabulador o personalizado
• Detección de codificación - Detección automática UTF-8/Latin-1
• Mapeo inteligente de columnas - Auto-detecta columnas de idioma
• Validación - Verifica errores antes de importar
• Opciones de fusión - Actualiza existentes o añade nuevas strings
• Preservación de marcadores - Mantiene {variables} correctamente
• Operaciones masivas - Importa miles de strings a la vez
• Personalización de exportación - Elige formato, codificación, idiomas
• Seguimiento de progreso - Ve estado de completitud de traducción

Conclusión

Los archivos CSV ofrecen un formato simple y universal para gestionar traducciones que funciona con prácticamente cualquier herramienta o sistema. Con el soporte completo de CSV de AZbox, puedes:

1. Importar archivos CSV existentes con mapeo flexible de columnas
2. Exportar traducciones en formatos CSV personalizables
3. Intercambiar datos fácilmente con cualquier sistema o traductor
4. Mantener compatibilidad con herramientas legacy y flujos de trabajo
5. Procesar traducciones programáticamente cuando sea necesario

¿Listo para optimizar tu flujo de trabajo de localización basado en CSV?

Comienza tu Prueba Gratuita | Ver Precios

---

AZbox proporciona soporte completo de importación y exportación CSV, facilitando el intercambio de datos de traducción con cualquier herramienta o sistema. Importa, gestiona y exporta tus traducciones con facilidad.