PTC
Cadastrar-se Fazer upgrade para o Pro Sua conta

Como preparar um arquivo CSV para tradução

Um CSV que é traduzido sem problemas possui chaves estáveis, colunas de texto de origem claras e codificação UTF-8 correta. Este guia cobre cada etapa de preparação. Quando o seu CSV estiver pronto, você poderá traduzi-lo em 3 etapas na PTC (Private Translation Cloud). Para a visão geral do serviço de CSV independente, consulte traduzir arquivos CSV online com IA.

O CSV é o mínimo denominador comum dos formatos de tradução. Toda ferramenta de planilha, toda plataforma de e-commerce, toda exportação de analytics fala CSV. Essa flexibilidade é uma faca de dois gumes. Um CSV que “parece bom” no Excel pode ser impossível de traduzir sem problemas devido à ambiguidade de colunas, chaves ausentes ou problemas de codificação. Este guia aborda o que torna um CSV pronto para tradução.

Como é um CSV pronto para tradução

Um CSV pronto para tradução é um CSV em que:

  • Cada string traduzível tem uma chave estável e exclusiva.
  • A coluna do idioma de origem está claramente identificada.
  • As colunas do idioma de destino já existem (uma coluna por idioma) ou um CSV por idioma de destino é produzido.
  • As colunas de identificador (SKU, ID, URL da imagem, preço) são obviamente não traduzíveis.
  • O arquivo é um UTF-8 válido, sem ambiguidade de codificação.

Dois formatos comuns:

Formato largo (uma coluna por idioma):

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

Formato longo (uma linha por string, um arquivo por idioma):

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

Ambos funcionam. A PTC lê qualquer um deles. Escolha o que melhor se adapta ao seu pipeline existente.

Escolha colunas que os tradutores e a PTC possam ler

Faça da primeira linha o cabeçalho. Use nomes de colunas simples e descritivos como key, source_text e context. Sua ferramenta de tradução e quaisquer revisores humanos saberão exatamente o que cada coluna contém.

Colunas obrigatórias. Todo CSV pronto para tradução precisa, no mínimo, de uma coluna key e de uma coluna de texto de origem.

  • A coluna key contém um identificador exclusivo para cada string. Seu aplicativo a usa para corresponder à tradução certa no tempo de execução. Use uma convenção de nomenclatura consistente - apenas letras minúsculas, sublinhados e pontos. Formatos comuns: button.submit, error.invalid_login, onboarding.welcome_message. Nunca altere uma chave após o início da tradução. Alterar uma chave cria uma nova string e desvincula a tradução existente.
  • A coluna de texto de origem contém o texto original no seu idioma base.

Opcional, mas útil: uma coluna context. Strings curtas como “Save” ou “Back” podem significar coisas diferentes dependendo de onde aparecem na sua interface. Uma breve nota informa ao tradutor (ou IA) para que serve a string:

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

Para arquivos grandes, uma coluna namespace ou group ajuda você a organizar as strings por recurso ou seção.

Colunas de idioma. Se o seu fluxo de trabalho mantém a origem e o destino no mesmo arquivo, adicione uma coluna por idioma de destino usando os códigos de locale como cabeçalho. Use es_ES para espanhol (Espanha), fr_FR para francês (França), pt_BR para português (Brasil).

Use chaves com pontos para hierarquia. cart.items.one e cart.items.other se agrupam naturalmente. Evite espaços nas chaves.

Mantenha as colunas de identificador separadas. Se o seu CSV for um catálogo de produtos, as colunas sku, handle, price e image_url devem ser obviamente não traduzíveis apenas pelos seus nomes. Não as esconda em uma coluna metadata genérica.

Um CSV por escopo lógico. Não misture strings de UI de administração com textos de marketing no mesmo arquivo. Escopos diferentes têm tons diferentes. A voz da marca da PTC funciona melhor quando cada projeto cobre um conjunto coerente de strings.

Marque os placeholders para que a PTC os preserve em todos os idiomas

Placeholders são tokens dentro de uma string que são substituídos no tempo de execução. %s, %d, {name}, {{count}}, %{currency}. A PTC preserva os placeholders literalmente e nunca traduz o próprio token.

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

Convenções que a PTC reconhece sem configuração extra:

  • %s, %d, %f, %1$s, %2$d - estilo printf (gettext, Rails, Java).
  • {name}, {count}, {0} - Python str.format, .NET, sintaxe de índice ICU.
  • {{name}}, {{count}} - i18next, Mustache, Handlebars.
  • %{name}, %{count} - Rails I18n, Ruby.

Se o seu texto de origem incluir tags HTML (<strong>, <br>, <a href="">), trate-as da mesma forma que os placeholders. A PTC as detecta e preserva em todos os formatos, na posição correta em cada idioma de destino. Nunca traduza a própria tag.

Se você usar uma convenção personalizada (ex.: [[token]]), declare-a no glossário do projeto da PTC e a PTC a respeitará em todas as linhas.

Codifique as formas plurais como linhas separadas para que cada idioma receba as formas certas

A maioria dos idiomas tem mais de duas formas plurais. Muitos têm regras que nenhum falante de inglês preveria. O polonês tem one / few / many / other. O árabe tem seis formas. O japonês tem uma (sem distinção de plural). Uma ferramenta de tradução que armazena apenas singular e plural produzirá resultados incorretos para esses idiomas.

Codifique os plurais como linhas separadas com uma convenção de sufixo:

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

A PTC lê os sufixos .zero, .one, .few, .many e .other (categorias de plural do CLDR) e gera as categorias de plural certas para cada idioma de destino.

Não combine formas plurais em uma única string com barras ou parênteses, como "You have {count} item(s) in your cart.". Essa abordagem não é traduzível e quebra a gramática da maioria dos idiomas.

Escape caracteres especiais para que o parser do CSV não quebre as linhas

Regras de escape do CSV (RFC 4180):

  • Vírgulas dentro de um campo: envolva o campo em aspas duplas, caso contrário, o parser dividirá sua string entre as células.
key,source_text
intro,"Welcome to our store, where every product matters"
  • Aspas duplas literais: escape-as duplicando-as.
key,source_text
quote,"He said ""hello"" and waved"
  • Quebras de linha dentro de um campo: OK se o campo estiver entre aspas.
key,source_text
address,"123 Main Street
Springfield, IL 62701"
  • Aspas curvas: sempre use aspas retas (") em vez de aspas curvas (“ ”). Os parsers de CSV não reconhecem aspas curvas e gerarão erros de formatação.
  • Espaços à direita: remova-os de todas as células antes de enviar. Eles são invisíveis na maioria dos editores de planilhas, mas causam falhas de correspondência de strings no seu aplicativo.

Para HTML ou marcação dentro de uma célula, coloque o campo entre aspas e deixe a PTC traduzir apenas o texto:

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

A PTC faz o parse do HTML, traduz apenas o texto legível por humanos e preserva cada tag, atributo e URL.

Salve como UTF-8 para evitar caracteres acentuados corrompidos

A codificação é a causa mais comum de problemas de tradução de CSV. Sem UTF-8, caracteres fora do alfabeto latino básico podem ser exibidos como ???, caixas vazias ou texto ilegível no seu aplicativo.

  • Salve seu CSV como UTF-8 (com ou sem BOM). A maioria das ferramentas modernas usa isso por padrão. Historicamente, o Excel no Windows não usava.
  • Não use a codificação Windows-1252, ISO-8859-1 ou “ANSI”. Caracteres acentuados nos idiomas de destino serão corrompidos.
  • Em caso de dúvida, abra o CSV em um editor de texto como VS Code ou Notepad++ e verifique o indicador de codificação. Salve novamente como UTF-8, se necessário.

Orientação específica para o Excel:

  • Excel para Mac usa UTF-8 por padrão. Nenhuma ação é necessária.
  • Excel para Windows: escolha Arquivo > Salvar como e selecione CSV UTF-8 (delimitado por vírgulas) no menu suspenso de formato. Não apenas “CSV (delimitado por vírgulas)”.
  • Google Sheets: Arquivo > Fazer download > Valores separados por vírgula (.csv). UTF-8 por padrão.

Para CSVs de origem que já estão na codificação incorreta, converta com iconv:

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

Um exemplo prático: um CSV completo de e-commerce que a PTC traduz sem preparação

Um CSV completo e bem preparado para um site de 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

Este arquivo:

  • Tem colunas key, source_text e context claras.
  • Usa chaves hierárquicas com pontos.
  • Lida com placeholders ({{shopName}}, {count}, {currency}, {amount}).
  • Lida com plurais com sufixos .zero / .one / .other.
  • Escapa HTML e aspas corretamente.
  • Está salvo como UTF-8.

A PTC traduz isso diretamente. Nenhuma preparação além do que é mostrado.

Práticas recomendadas para tradução de CSV em uma lista

  • Use uma ferramenta de tradução dedicada. Evite traduzir arquivos CSV manualmente em um editor de texto ou planilha. Ferramentas dedicadas como a PTC preservam a estrutura do seu arquivo, lidam com placeholders corretamente e mantem suas chaves intactas.
  • Use vírgulas padrão como seu delimitador. Algumas ferramentas usam ponto e vírgula por padrão. As vírgulas são as mais amplamente suportadas e têm menos probabilidade de causar erros de importação.
  • Mantenha uma string por linha. Combinar várias strings em uma única linha torna as traduções incontroláveis e quebra a maioria das ferramentas de tradução.
  • Isole colunas traduzíveis. Mantenha as colunas que precisam de tradução separadas das colunas que devem permanecer inalteradas (IDs numéricos, SKUs, parâmetros técnicos). Isso reduz o risco de uma ferramenta ou tradutor modificar acidentalmente dados que devem permanecer intocados.
  • Evite células mescladas e formatação de planilha. CSV é texto simples. Qualquer formatação aplicada por meio de software de planilha é removida quando o arquivo é processado.
  • Remova colunas e metadados desnecessários. Inclua apenas as colunas de que sua ferramenta de tradução precisa.
  • Teste primeiro com uma pequena amostra. Antes de executar um arquivo grande na tradução, teste com uma pequena amostra para detectar problemas estruturais ou de codificação antecipadamente.
  • Valide seu arquivo antes do upload. Verifique se cada linha tem uma chave exclusiva sem duplicatas, se nenhuma chave contém espaços ou caracteres especiais e se não há linhas quebradas.
  • Mantenha um backup. Sempre guarde uma cópia do seu CSV original antes de enviá-lo para tradução.

Revisão visual de tradução do catálogo ou aplicativo renderizado

Depois que a PTC traduz o CSV, as strings são renderizadas no que quer que consuma o CSV. Isso abrange sua vitrine, seu aplicativo e seu painel. Um título de produto traduzido que cabe no arquivo pode causar estouro em um layout de cartão. Um botão de checkout em francês pode usar a palavra errada para “Place Order”. Um endereço longo em alemão pode quebrar uma coluna de largura fixa em uma fatura impressa.

O AI Visual QA da PTC detecta esses problemas. Para vitrines e painéis (baseados em navegador), instale a extensão do navegador da PTC e grave um percurso gravado da sua loja. A PTC o reproduz em cada idioma de destino e corrige problemas de layout e contexto no CSV automaticamente. Para aplicativos nativos que consomem o CSV, em vez disso, faça o upload de capturas de tela das telas relevantes.

Traduza anúncios de lançamento de produtos e e-mails de fornecedores

Os anúncios de lançamento de produtos e os e-mails voltados para o cliente sobre as atualizações do catálogo ficam fora do CSV. O Paste to Translate da PTC lida com esse texto no mesmo projeto, usando o mesmo glossário e a mesma voz da marca das traduções do seu catálogo.

Traduza importações em lote à medida que os dados chegam com a API da PTC

As importações de catálogo em lote que precisam de tradução na chegada podem fluir através da API REST da PTC com autenticação por token Bearer, usando o mesmo glossário e a mesma voz da marca das suas traduções de CSV.

Agora traduza seu CSV com a PTC

Quando o seu CSV estiver preparado, traduza-o em 3 etapas:

  1. Faça o upload do seu CSV e escolha os idiomas de destino.
  2. A PTC traduz enquanto preserva cada coluna, chave e placeholder.
  3. Faça o download dos CSVs traduzidos e importe-os para onde eles pertencem.

Comece seu teste de 30 dias - 20.000 palavras para 2 idiomas, sem cartão de crédito.