PTC
Registrati Passa a Pro Il tuo account

Come preparare un file CSV per la traduzione

Un CSV che si traduce senza problemi ha chiavi stabili, colonne del testo di origine chiare e la corretta codifica UTF-8. Questa guida copre ogni passaggio 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 tradurre file CSV online con l'IA.

Il CSV è il formato di traduzione che rappresenta il minimo comune denominatore. Ogni strumento per fogli di calcolo, ogni piattaforma di e-commerce, ogni esportazione di dati analitici parla il linguaggio CSV. Questa flessibilità è un'arma a doppio taglio. Un CSV che «sembra a posto» in Excel potrebbe essere impossibile da tradurre in modo pulito a causa dell'ambiguità delle colonne, di chiavi mancanti o di problemi di codifica. Questa guida spiega cosa rende un CSV pronto per la traduzione.

Che aspetto ha un CSV pronto per la traduzione

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

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

Due formati comuni:

Il formato wide (una colonna per lingua):

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

Il formato long (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 li legge entrambi. Scegli quello che si adatta meglio alla tua pipeline esistente.

Scegli colonne che i traduttori e PTC possano leggere

Usa la prima riga come riga di intestazione. Usa nomi di colonna semplici e descrittivi come key, source_text e context. In questo modo, il tuo strumento di traduzione e qualsiasi revisore umano 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 del testo di origine.

  • La colonna key contiene un identificatore univoco per ogni stringa. La tua applicazione la usa per abbinare la traduzione corretta a runtime. 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 base.

Opzionale ma utile: una colonna context. Stringhe brevi come «Save» o «Back» possono avere significati diversi a seconda di dove appaiono nella tua interfaccia. Una breve nota dice 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 delle lingue. Se il tuo flusso di lavoro mantiene l'origine e la destinazione nello stesso file, aggiungi una colonna per 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 con notazione a punti per la gerarchia. cart.items.one e cart.items.other si raggruppano in modo naturale. Evita gli spazi nelle chiavi.

Mantieni separate le colonne degli identificatori. Se il tuo CSV è un catalogo di prodotti, le colonne sku, handle, price e image_url dovrebbero essere palesemente non traducibili già solo dai loro nomi. Non seppellirle in una colonna metadata generica.

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

Contrassegna i segnaposto in modo che PTC li preservi in tutte le lingue

I segnaposto sono token all'interno di una stringa che vengono sostituiti a runtime. %s, %d, {name}, {{count}}, %{currency}. PTC preserva i segnaposto alla lettera 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} - str.format di Python, .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 usi una convenzione personalizzata (ad esempio, [[token]]), dichiarala nel glossario del progetto PTC e PTC la rispetterà in ogni riga.

Codifica le forme plurali come righe separate in modo che ogni lingua ottenga le forme corrette

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

Codifica i plurali come righe separate con una convenzione per i 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 giuste categorie plurali per ogni lingua di destinazione.

Non combinare le forme plurali in un'unica stringa con barre o parentesi, come "You have {count} item(s) in your cart.". Questo approccio non è traducibile e viola la grammatica della maggior parte delle lingue.

Usa l'escape per i caratteri speciali in modo che il parser CSV non interrompa le righe

Regole di escape del CSV (RFC 4180):

  • Virgole all'interno di un campo: racchiudi il campo tra virgolette doppie, altrimenti il parser divide la tua stringa in più celle.
key,source_text
intro,"Welcome to our store, where every product matters"
  • Virgolette doppie letterali: effettua l'escape raddoppiandole.
key,source_text
quote,"He said ""hello"" and waved"
  • Ritorni a capo all'interno di un campo: OK se il campo è racchiuso tra virgolette.
key,source_text
address,"123 Main Street
Springfield, IL 62701"
  • Virgolette tipografiche: usa sempre le virgolette diritte (") anziché le virgolette tipografiche (“ ”). I parser CSV non riconoscono le virgolette tipografiche 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 l'HTML o il markup all'interno di una cella, racchiudi 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 come UTF-8 per evitare caratteri accentati corrotti

La codifica è la causa in assoluto più comune dei problemi di traduzione dei CSV. Senza UTF-8, i caratteri al di fuori dell'alfabeto latino di base potrebbero essere visualizzati come ???, riquadri vuoti 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. Storicamente, Excel su Windows non lo faceva.
  • Non usare la codifica Windows-1252, ISO-8859-1 o «ANSI». I caratteri accentati nelle lingue di destinazione verranno corrotti.
  • In caso di dubbi, apri il CSV in un editor di testo come VS Code o Notepad++ e controlla l'indicatore di codifica. Salvalo di nuovo come UTF-8 se necessario.

Indicazioni specifiche per Excel:

  • Excel per Mac usa UTF-8 per impostazione predefinita. Non è necessaria alcuna azione.
  • Excel per Windows: scegli File > Salva con nome e seleziona CSV UTF-8 (delimitato da virgole) (*.csv) dal menu a discesa dei formati. Non il semplice «CSV (delimitato da virgole)».
  • Fogli Google: File > Scarica > Valori separati da virgola (.csv). UTF-8 per impostazione predefinita.

Per i CSV di origine che hanno già la codifica sbagliata, convertili con iconv:

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

Un esempio pratico: un CSV per e-commerce completo 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.
  • Usa chiavi gerarchiche con notazione a punti.
  • Gestisce i segnaposto ({{shopName}}, {count}, {currency}, {amount}).
  • Gestisce i plurali con i suffissi .zero / .one / .other.
  • Effettua correttamente l'escape dell'HTML e delle virgolette.
  • È salvato come UTF-8.

PTC lo traduce direttamente. Nessuna preparazione oltre a quanto mostrato.

Le best practice per la traduzione dei CSV in un'unica lista

  • 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 tuo file, gestiscono correttamente i segnaposto e mantengono intatte le tue chiavi.
  • Usa le virgole standard come delimitatore. Alcuni strumenti usano il punto e virgola per impostazione predefinita. Le virgole sono le più ampiamente supportate e quelle che 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 manda in blocco la maggior parte degli strumenti di traduzione.
  • Isola le colonne traducibili. Mantieni le colonne che necessitano di traduzione separate da quelle che dovrebbero rimanere invariate (ID numerici, SKU, parametri tecnici). Questo riduce il rischio che uno strumento o un traduttore modifichino accidentalmente dati che dovrebbero rimanere intatti.
  • Evita le celle unite e la formattazione del foglio di calcolo. Il CSV è puro testo. Qualsiasi formattazione applicata tramite un software per fogli di calcolo viene rimossa quando il file viene elaborato.
  • Rimuovi le colonne e i metadati non necessari. Includi solo le colonne di cui il tuo strumento di traduzione ha bisogno.
  • Fai prima un test con un piccolo campione. Prima di passare un file di grandi dimensioni alla traduzione, fai un test con un piccolo campione per individuare tempestivamente eventuali problemi strutturali o di codifica.
  • Convalida il tuo 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.
  • Mantieni un backup. Conserva sempre una copia del tuo CSV originale prima di inviarlo per la traduzione.

Revisione visiva della traduzione del catalogo o dell'app visualizzati

Una volta che PTC traduce il CSV, le stringhe vengono visualizzate in qualsiasi cosa consumi il CSV. Questo copre la tua vetrina, la tua app e il tuo pannello di controllo. Il titolo di un prodotto tradotto che si adatta al file potrebbe causare l'overflow in un layout a schede. Un pulsante di checkout in francese potrebbe usare la parola 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 intercetta questi problemi. Per le vetrine e i pannelli di controllo (basati su browser), installa l'estensione del browser di PTC e registra un percorso guidato del tuo store. PTC lo riproduce in ogni lingua di destinazione e risolve automaticamente i problemi di layout e contesto nel CSV. Per le app native che consumano il CSV, carica invece le schermate delle relative videate.

Traduci gli annunci di lancio dei prodotti e le email ai fornitori

Gli annunci di lancio dei prodotti e le email dirette ai clienti sugli aggiornamenti del catalogo vivono al di fuori del CSV. Paste to Translate di PTC gestisce quei testi nello stesso progetto, usando lo stesso glossario e la stessa voce del brand delle traduzioni del tuo catalogo.

Traduci le importazioni in blocco man mano che i dati arrivano con l'API di PTC

Le importazioni in blocco del catalogo che necessitano di traduzione all'arrivo possono passare attraverso l'API REST di PTC con autenticazione tramite token Bearer, usando lo stesso glossario e la stessa voce del brand 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 di 30 giorni: 20.000 parole in 2 lingue, nessuna carta di credito.