PTC
Registrati Passa a Pro Il tuo account

Come preparare un file CSV per la traduzione

Un file CSV facile da tradurre ha chiavi stabili, colonne del testo di origine chiare e una corretta codifica UTF-8. Questa guida copre ogni fase della preparazione. Una volta che il tuo CSV è pronto, puoi tradurlo in 3 passaggi su PTC (Private Translation Cloud). Per una panoramica del servizio CSV autonomo, vedi traduci file CSV online con l'IA.

Il formato CSV è il minimo comune denominatore per la traduzione. Ogni strumento di foglio di calcolo, ogni piattaforma di e-commerce e ogni esportazione di analisi parla il linguaggio CSV. Questa flessibilità è un'arma a doppio taglio. Un CSV che “sembra a posto” in Excel potrebbe essere impossibile da tradurre correttamente a causa dell'ambiguità delle colonne, della mancanza di chiavi o di problemi di codifica. Questa guida spiega cosa rende un CSV pronto per la traduzione.

Com'è fatto un CSV pronto per la traduzione

Un CSV pronto per la traduzione è un file in cui:

  • Ogni stringa traducibile ha una chiave univoca e stabile.
  • La colonna della lingua di origine è chiaramente identificata.
  • Le colonne della lingua di destinazione esistono già (una colonna per lingua) oppure viene prodotto un CSV per ogni lingua di destinazione.
  • Le colonne identificative (SKU, ID, URL dell'immagine, prezzo) sono palesemente non traducibili.
  • Il file è in formato UTF-8 valido senza ambiguità di codifica.

Due strutture comuni:

Formato orizzontale (una colonna per lingua):

key,en,es,fr,de
welcome,Welcome,,,
cart.empty,Your cart is empty,,,
cart.items_one,"You have %{count} item",,,

Formato verticale (una riga per stringa, un file per lingua):

key,source
welcome,Welcome
cart.empty,Your cart is empty
cart.items_one,"You have %{count} item"

Entrambi funzionano. PTC legge entrambi. Scegli quello che meglio si adatta alla tua pipeline esistente.

Scegli colonne che i traduttori e PTC possano leggere

Usa la prima riga come intestazione. Utilizza nomi di colonna semplici e descrittivi come key, source_text e context. In questo modo, il tuo strumento di traduzione e i revisori umani sapranno esattamente cosa contiene ogni colonna.

Colonne obbligatorie. Ogni CSV pronto per la traduzione necessita come minimo di una colonna key e di una colonna per il testo di origine.

  • La colonna key contiene un identificatore univoco per ogni stringa. La tua applicazione lo usa per abbinare la traduzione corretta in fase di esecuzione. Usa una convenzione di denominazione coerente: solo lettere minuscole, trattini bassi e punti. Formati comuni: button.submit, error.invalid_login, onboarding.welcome_message. Non cambiare mai una chiave dopo l'inizio della traduzione. Cambiare una chiave crea una nuova stringa e rende orfana la traduzione esistente.
  • La colonna del testo di origine contiene il testo originale nella tua lingua di base.

Opzionale ma utile: una colonna context. Stringhe brevi come “Salva” o “Indietro” possono significare cose diverse a seconda di dove appaiono nell'interfaccia. Una breve nota spiega al traduttore (o all'IA) a cosa serve la stringa:

key,source_text,context
button.save,Save,Document editor toolbar
checkout.button.save,Save,Checkout address form

Per i file di grandi dimensioni, una colonna namespace o group ti aiuta a organizzare le stringhe per funzionalità o sezione.

Colonne della lingua. Se il tuo flusso di lavoro mantiene l'origine e la destinazione nello stesso file, aggiungi una colonna per ogni lingua di destinazione usando i codici locale come intestazione. Usa es_ES per lo spagnolo (Spagna), fr_FR per il francese (Francia), pt_BR per il portoghese (Brasile).

Usa chiavi puntate per la gerarchia. cart.items.one e cart.items.other si raggruppano naturalmente. Evita gli spazi nelle chiavi.

Mantieni separate le colonne identificative. Se il tuo CSV è un catalogo prodotti, le colonne sku, handle, price e image_url dovrebbero essere chiaramente non traducibili già dal nome. Non nasconderle in una colonna generica metadata.

Un CSV per ogni ambito logico. Non mescolare le stringhe dell'interfaccia amministrativa con i testi di marketing nello stesso file. Ambiti diversi hanno toni diversi. La brand voice di PTC funziona meglio quando ogni progetto copre un insieme coerente di stringhe.

Contrassegna i segnaposto affinché PTC li preservi in tutte le lingue

I segnaposto sono token all'interno di una stringa che vengono sostituiti in fase di esecuzione. %s, %d, {name}, {{count}}, %{currency}. PTC preserva i segnaposto parola per parola e non traduce mai il token stesso.

key,source_text
greeting,"Hello, %{name}!"
cart.total,"Total: %{currency}%{amount}"
notification,"You have %{count} new messages"

Convenzioni che PTC riconosce fin da subito:

  • %s, %d, %f, %1$s, %2$d - stile printf (gettext, Rails, Java).
  • {name}, {count}, {0} - Python str.format, .NET, sintassi degli indici ICU.
  • {{name}}, {{count}} - i18next, Mustache, Handlebars.
  • %{name}, %{count} - Rails I18n, Ruby.

Se il tuo testo di origine include tag HTML (<strong>, <br>, <a href="">), trattali allo stesso modo dei segnaposto. PTC li rileva e li preserva in tutti i formati, nella posizione corretta in ogni lingua di destinazione. Non tradurre mai il tag stesso.

Se utilizzi una convenzione personalizzata (ad es. [[token]]), dichiarala nel glossario del progetto PTC e PTC la rispetterà in ogni riga.

Codifica le forme plurali come righe separate affinché ogni lingua riceva le forme corrette

La maggior parte delle lingue ha più di due forme plurali. Molte hanno regole che nessun anglofono potrebbe prevedere. Il polacco ha one / few / many / other. L'arabo ha sei forme. Il giapponese ne ha una (nessuna distinzione di plurale). Uno strumento di traduzione che memorizza solo singolare e plurale produrrà risultati errati per queste lingue.

Codifica i plurali come righe separate con una convenzione di suffissi:

key,source_text,context
cart.items.zero,Your cart is empty,Zero state
cart.items.one,"You have {count} item in your cart.",Singular: count = 1
cart.items.other,"You have {count} items in your cart.",Plural: count > 1

PTC legge i suffissi .zero, .one, .few, .many e .other (categorie plurali CLDR) e genera le categorie plurali corrette per ogni lingua di destinazione.

Non combinare le forme plurali in un'unica stringa con barre o parentesi, come "Hai {count} articolo(i) nel carrello.". Questo approccio non è traducibile e rompe la grammatica della maggior parte delle lingue.

Esegui l'escape dei caratteri speciali affinché il parser CSV non interrompa le righe

Regole di escape CSV (RFC 4180):

  • Virgole all'interno di un campo: racchiudi il campo tra virgolette doppie, altrimenti il parser dividerà la tua stringa tra più celle.
key,source_text
intro,"Welcome to our store, where every product matters"
  • Virgolette doppie letterali: esegui l'escape raddoppiandole.
key,source_text
quote,"He said ""hello"" and waved"
  • Interruzioni di riga all'interno di un campo: OK se il campo è tra virgolette.
key,source_text
address,"123 Main Street
Springfield, IL 62701"
  • Virgolette curve: usa sempre virgolette dritte (") invece di virgolette curve (“ ”). I parser CSV non riconoscono le virgolette curve e genereranno errori di formattazione.
  • Spazi finali: rimuovili da tutte le celle prima dell'invio. Sono invisibili nella maggior parte degli editor di fogli di calcolo ma causano errori di corrispondenza delle stringhe nella tua applicazione.

Per HTML o markup all'interno di una cella, metti il campo tra virgolette e lascia che PTC traduca solo il testo:

key,source_text
disclaimer,"<p>By signing up, you agree to our <a href=""/terms"">terms</a>.</p>"

PTC analizza l'HTML, traduce solo il testo leggibile dall'uomo e preserva ogni tag, attributo e URL.

Salva in formato UTF-8 per evitare caratteri accentati corrotti

La codifica è la causa più comune di problemi nella traduzione dei CSV. Senza UTF-8, i caratteri al di fuori dell'alfabeto latino di base potrebbero apparire come ???, caselle vuote o testo incomprensibile nella tua applicazione.

  • Salva il tuo CSV come UTF-8 (con o senza BOM). La maggior parte degli strumenti moderni lo fa per impostazione predefinita. Excel su Windows storicamente non lo faceva.
  • Non usare la codifica Windows-1252, ISO-8859-1 o “ANSI”. I caratteri accentati nelle lingue di destinazione risulteranno corrotti.
  • Se hai dubbi, apri il CSV in un editor di testo come VS Code o Notepad++ e controlla l'indicatore di codifica. Salva nuovamente come UTF-8 se necessario.

Guida specifica per Excel:

  • Excel per Mac usa UTF-8 per impostazione predefinita. Nessuna azione richiesta.
  • Excel per Windows: scegli File > Salva con nome e seleziona CSV UTF-8 (delimitato da virgole) (*.csv) dal menu a discesa del formato. Non il semplice “CSV (delimitato da virgole)”.
  • Google Sheets: File > Scarica > Valori separati da virgola (.csv). UTF-8 per impostazione predefinita.

Per i CSV di origine già nella codifica errata, convertili con iconv:

iconv -f WINDOWS-1252 -t UTF-8 source.csv > source-utf8.csv

Un esempio pratico: un CSV completo per e-commerce che PTC traduce senza preparazione

Un CSV completo e ben preparato per un sito di e-commerce:

key,source_text,context
header.welcome,"Welcome to {{shopName}}",Top of page
header.cart.zero,"Your cart is empty",Cart icon - zero state
header.cart.one,"{count} item in cart",Cart icon - singular
header.cart.other,"{count} items in cart",Cart icon - plural
product.add_to_cart,"Add to Cart",Product page CTA
product.out_of_stock,"Out of Stock",Product availability badge
product.price,"{currency}{amount}",Price display
checkout.shipping,"Shipping address",Checkout step heading
checkout.payment,"Payment method",Checkout step heading
checkout.confirm,"Place Order",Final checkout button
errors.email.required,"Email is required",Form validation
errors.email.invalid,"Please enter a valid email address",Form validation
errors.card.declined,"Your card was declined. Please try a different payment method.",Checkout error
promo.tagline,"Sale ends Sunday, grab your deal!",Promo banner - contains comma
tooltip.save,"Click ""Save"" to keep your changes.",Tooltip - contains quotes
disclaimer,"<p>By placing this order, you agree to our <a href=""/terms"">terms and conditions</a>.</p>",Footer legal

Questo file:

  • Ha colonne key, source_text e context chiare.
  • Utilizza chiavi gerarchiche puntate.
  • Gestisce i segnaposto ({{shopName}}, {count}, {currency}, {amount}).
  • Gestisce i plurali con i suffissi .zero / .one / .other.
  • Esegue correttamente l'escape di HTML e virgolette.
  • È salvato in formato UTF-8.

PTC traduce tutto questo direttamente. Nessuna preparazione oltre a quanto mostrato.

Le migliori pratiche per la traduzione di CSV in un unico elenco

  • Usa uno strumento di traduzione dedicato. Evita di tradurre i file CSV manualmente in un editor di testo o in un foglio di calcolo. Strumenti dedicati come PTC preservano la struttura del file, gestiscono correttamente i segnaposto e mantengono intatte le chiavi.
  • Usa le virgole standard come delimitatore. Alcuni strumenti usano i punti e virgola per impostazione predefinita. Le virgole sono le più ampiamente supportate e hanno meno probabilità di causare errori di importazione.
  • Mantieni una stringa per riga. Combinare più stringhe in una singola riga rende le traduzioni ingestibili e rompe la maggior parte degli strumenti di traduzione.
  • Isola le colonne traducibili. Mantieni le colonne che necessitano di traduzione separate da quelle che devono rimanere invariate (ID numerici, SKU, parametri tecnici). Ciò riduce il rischio che uno strumento o un traduttore modifichi accidentalmente dati che dovrebbero restare intatti.
  • Evita celle unite e formattazione del foglio di calcolo. Il CSV è testo semplice. Qualsiasi formattazione applicata tramite software di fogli di calcolo viene rimossa quando il file viene elaborato.
  • Rimuovi colonne e metadati non necessari. Includi solo le colonne di cui il tuo strumento di traduzione ha bisogno.
  • Testa prima con un piccolo campione. Prima di sottoporre a traduzione un file di grandi dimensioni, fai un test con un piccolo campione per individuare tempestivamente problemi strutturali o di codifica.
  • Valida il file prima di caricarlo. Controlla che ogni riga abbia una chiave univoca senza duplicati, che nessuna chiave contenga spazi o caratteri speciali e che non ci siano righe interrotte.
  • Conserva un backup. Tieni sempre una copia del tuo CSV originale prima di inviarlo per la traduzione.

Revisione visiva della traduzione del catalogo o dell'app renderizzati

Una volta che PTC ha tradotto il CSV, le stringhe vengono renderizzate in qualunque sistema consumi il CSV. Questo include la tua vetrina, la tua app e il tuo pannello di controllo. Il titolo di un prodotto tradotto che sta bene nel file potrebbe causare un overflow nel layout di una scheda. Un pulsante di checkout in francese potrebbe usare l'espressione sbagliata per “Place Order”. Un lungo indirizzo in tedesco potrebbe rompere una colonna a larghezza fissa in una fattura stampata.

L'AI Visual QA di PTC rileva questi problemi. Per vetrine e pannelli di controllo (basati su browser), installa l'estensione del browser PTC e registra un percorso guidato del tuo negozio. PTC lo riproduce in ogni lingua di destinazione e corregge automaticamente i problemi di layout e contesto nel CSV. Per le app native che consumano il CSV, carica invece le schermate delle sezioni pertinenti.

Traduci annunci di lancio prodotti ed email ai fornitori

Gli annunci di lancio prodotti e le email rivolte ai clienti sugli aggiornamenti del catalogo vivono al di fuori del CSV. La funzione Incolla per tradurre di PTC gestisce questi testi nello stesso progetto, utilizzando lo stesso glossario e la stessa brand voice delle traduzioni del tuo catalogo.

Traduci importazioni di massa all'arrivo dei dati con l'API di PTC

Le importazioni di massa del catalogo che necessitano di traduzione all'arrivo possono fluire attraverso l' API REST di PTC con autenticazione Bearer-token, utilizzando lo stesso glossario e la stessa brand voice delle traduzioni del tuo CSV.

Ora traduci il tuo CSV con PTC

Una volta preparato il tuo CSV, traducilo in 3 passaggi:

  1. Carica il tuo CSV e scegli le lingue di destinazione.
  2. PTC traduce preservando ogni colonna, chiave e segnaposto.
  3. Scarica i CSV tradotti e importali dove servono.

Inizia la tua prova gratuita di 30 giorni - 20.000 parole in 2 lingue, senza carta di credito.