Localização de jogos no Unity: as melhores maneiras de traduzir suas Tabelas de Strings

O Unity exporta String Tables em CSV, XLIFF ou JSON, e o formato escolhido define como será todo o trabalho. Não a qualidade, nem o custo: o formato do trabalho. O CSV entrega um único arquivo com uma coluna para cada idioma. O XLIFF entrega um arquivo por idioma. Escolher o formato errado para o seu fluxo de trabalho pode transformar um trabalho de duas horas em algo que leva duas semanas.

Este guia apresenta os dois formatos importantes para tradução, o que realmente há em cada exportação e como fazer a tradução sem editar manualmente nenhuma linha. O Google Sheets também aparece, mas como recurso de sincronização, não como formato de exportação.

Os formatos de exportação e a sincronização com o Google Sheets

O manual atual do Unity lista CSV, XLIFF e JSON como formatos de exportação, além da exportação de conjuntos de caracteres para fontes. O Google Sheets é outra coisa: o pacote pode sincronizar uma planilha com uma String Table Collection. Isso é uma sincronização, não um arquivo exportado. O AI Glot lê CSV e XLIFF nativamente, então nenhum dos dois precisa ser convertido.

Eles não são intercambiáveis, porém, e esta é a parte que merece dois minutos de atenção:

O CSV mantém seus idiomas juntos. Uma tabela pode ter quantas colunas você quiser, então um único arquivo carrega inglês, francês, japonês e todo o resto de uma vez, e um único trabalho de tradução pode preencher cada coluna vazia em uma única passagem.

O XLIFF separa os idiomas. Por definição, um arquivo XLIFF associa uma origem a um destino. Por isso, o Unity cria um arquivo para cada idioma e acrescenta o código do idioma ao nome: uma coleção chamada MyGame é exportada como MyGame-ru para russo e MyGame-ja para japonês. Isso não é uma limitação do Unity, é próprio do formato. O Unity é compatível com XLIFF 1.2 e 2.0, os padrões da OASIS 1.2 e 2.0, e o AI Glot lê ambos. Na versão 1.2, cada texto é um trans-unit com origem e destino, neste formato:

<xliff version="1.2">
  <file source-language="en" target-language="fr" datatype="plaintext" original="MyGame">
    <body>
      <trans-unit id="4102">
        <source>Start game</source>
        <target>Commencer</target>
      </trans-unit>
    </body>
  </file>
</xliff>

O Google Sheets é um recurso de sincronização, não um formato de exportação. Você mantém uma planilha sincronizada com a coleção e importa as alterações quando ela estiver preenchida. Se esse já for o seu fluxo de trabalho, exporte a planilha para CSV ou XLSX e siga o mesmo processo usado com CSV. Quando perguntaram a um funcionário do Unity como exportar todas as tabelas para CSV, ele indicou o Google Sheets ou o XLIFF. O manual também informa que, ao exportar para XLIFF, você pode selecionar quais tabelas incluir.

Recomendação direta: escolha CSV, a menos que alguma etapa seguinte exija XLIFF. A próxima seção explica por que as Smart Strings reforçam essa escolha. Dez idiomas em um único arquivo significam um trabalho para executar, um plano para consultar e um arquivo para importar de volta.

O que realmente há dentro da exportação CSV

Abra o arquivo uma vez e todo o fluxo de trabalho deixa de ser misterioso. Uma exportação básica tem uma coluna Key, uma coluna Id e uma coluna por localidade, nomeada conforme o idioma e seu código, como English(en) e French(fr). Ao exportar com comentários, você também terá uma coluna Shared Comments e uma coluna por localidade, como French(fr) Comments.

Duas colunas ali decidem se a sua importação funcionará ou não.

Key e Id são o que conecta as linhas. Na reimportação, o Unity usa esses valores para associar as linhas e os nomes dos cabeçalhos das colunas para localizá-los. O Unity precisa que Key ou Id corresponda para identificar uma linha. Se o valor de Key mudar, a entrada será tratada como outra. Por isso, uma Key traduzida deixa de corresponder à entrada usada pelas outras localidades. Basta indicar com clareza quais colunas devem ser traduzidas e quais devem permanecer intactas para evitar esse problema.

As colunas de comentários são contexto, não conteúdo. Se a sua equipe escreve notas para tradutores em Shared Comments, essas notas são úteis para leitura, mas erradas para traduzir. Identifique-as.

Ao importar o arquivo de volta, o Unity pede que você escolha um modo de importação. Merge atualiza as chaves correspondentes, adiciona as novas e mantém todo o resto. Replace faz a coleção corresponder ao arquivo e remove as chaves que não estão nele. Portanto, use Merge, a menos que queira excluir entradas.

O que cada formato preserva

A mesma página da versão 6000.7 lista o que é preservado em cada exportação. O XLIFF leva apenas as chaves, os IDs e os valores, sem sinalizadores Smart, variantes ou comentários. O CSV preserva as chaves, os IDs, os sinalizadores Smart, os valores e os comentários, enquanto o JSON preserva as chaves, os IDs, os sinalizadores Smart, os valores e as variantes, mas não os comentários. Se a tabela tiver muitas Smart Strings, o CSV é a opção mais segura para ida e volta, porque o sinalizador Smart acompanha cada linha. Se o fornecedor exigir XLIFF, mantenha a coleção original como matriz e importe o arquivo de volta usando Merge.

O que causa problemas, e não é o prazo

As Smart Strings da Unity são o real perigo em uma String Table de jogo, e são invisíveis para qualquer ferramenta que traduza palavra por palavra.

Uma Smart String contém lógica no próprio texto. Um marcador de posição vazio é {}. Um marcador nomeado dá contexto ao tradutor, como {PlayerName}. As formas do plural seguem as regras do Unicode CLDR por meio do formatador de plural do Unity. Assim, uma única entrada pode ser {0:plural:is 1 item|are {} items}. Também é possível aninhar marcadores: {User.Address:{Street}, {City}}. O número de formas de plural varia de um idioma para outro: o japonês tem uma, enquanto o russo tem três ou mais (one, few, many e other no CLDR). Por isso, uma única entrada de plural em inglês assume formas diferentes em cada idioma.

Um tradutor que não conhece a sintaxe pode reordenar as chaves, traduzir a palavra plural ou, tentando ajudar, transformar {PlayerName} em {NomDuJoueur}. Cada um desses casos é uma quebra de runtime, e não apenas um erro de digitação, que você só descobrirá quando um jogador enviar um print screen.

Isso deve estar na instrução ao nível de string, e acertar essa distinção é a coisa mais útil de todo este artigo.

Se você colocar uma regra de placeholder no plano, ela não terá utilidade. Se colocar uma regra de coluna no slot de nível de string, ela não fará absolutamente nada, silenciosamente, pois não há arquivo visível naquele momento. Ambas as falhas são silenciosas, e é por isso que merecem trinta segundos de atenção.

Outro ponto bem específico de jogos: um botão que cabe em inglês pode estourar o espaço em alemão. Dependendo do par de idiomas, o texto traduzido costuma ficar mais longo, e as strings curtas são as que mais se expandem. O artigo da W3C sobre o tamanho dos textos cita uma recomendação da IBM de 200 a 300% para strings de até 10 caracteres. Você pode incluir uma instrução para limitar o tamanho da string, para que o texto já seja escrito dentro do espaço disponível, em vez de ser cortado depois. Basta indicar isso uma vez para as entradas exibidas em uma interface com largura fixa.

Executando, rota um: o navegador

Faça o upload do CSV no tradutor de CSV ou no app, e então descreva o trabalho em uma frase. Algo como isto, e de forma deliberadamente simples:

The source is the English(en) column. Fill the empty French(fr), German(de)
and Japanese(ja) columns. Leave Key, Id, English(en) and every Comments
column exactly as they are.

Você recebe um plano antes de qualquer gasto: as colunas encontradas, o escopo, a contagem de palavras e o custo. Se houver um erro na leitura do seu arquivo, corrija em uma frase e ele planeja novamente. Tudo até a aprovação é gratuito, então uma leitura errada não custa nada além do tempo para reescrever uma cláusula.

Depois, baixe um CSV, com as mesmas colunas, as mesmas Key e Id, e importe-o novamente no Unity.

Executando, rota dois: seu agente faz todo o ciclo

Se você trabalha com Claude, Cursor, Copilot ou qualquer agente que consiga executar comandos no seu projeto, ele pode fazer tudo isso sem que você precise abrir um navegador, e pode colocar os resultados exatamente onde o Unity espera.

Instale e faça login uma vez:

npm install --global @ai-glot/cli
aiglot auth login

Aqui está um prompt que você pode entregar ao seu agente. Ele foi escrito para ser colado, e as partes importantes estão explicadas abaixo.

Our Unity String Table export is at Assets/Localization/Export/MyGame.csv.
Columns: Key, Id, English(en), and empty columns for French(fr), German(de)
and Japanese(ja).

Use the aiglot CLI to translate it. Run `aiglot batches create --help` and
`aiglot batches approve --help` first so you use the real flags.

Plan instruction: the source is English(en); fill only the empty French(fr),
German(de) and Japanese(ja) cells; leave Key, Id, English(en) and any
Comments column untouched.

Approval instructions: keep every curly-brace placeholder exactly as written,
including plural formatters and nested ones; never translate a placeholder
name; keep entries whose Key starts with MENU_ or HUD_ under 20 characters.

Use the lite quality tier. Show me the plan and the total cost BEFORE you
approve anything, then wait for me to confirm.

After I confirm, poll until it reaches a terminal status, download the result
over the original path, and tell me the row count so I can re-import in Unity.

Ele instrui o agente a ler a ajuda primeiro. Um agente que tenta adivinhar nomes de flags falha na primeira chamada e depois inventa um motivo para isso.

Ele separa explicitamente os dois tipos de instrução, que é todo o objetivo da seção acima. Escrito desta forma, o agente coloca cada item no lugar certo em vez de fundi-los em um bloco que funciona apenas metade.

Ele para antes do gasto. aiglot batches approve é o único comando que consome créditos. Tudo antes disso é gratuito e repetível, então um agente processando seus locais sem supervisão não poderá surpreendê-lo com uma fatura. Essa característica é o que torna a entrega disso a um agente algo razoável, e não imprudente.

Ele termina com um número para verificação. Solicitar a contagem de linhas oferece um teste de sanidade de um segundo antes de você reimportar.

Para referência, a sequência que ele segue:

# 1. Create the job. Free. Returns a plan and an id.
id=$(aiglot batches create Assets/Localization/Export/MyGame.csv \
      --instruction "The source is English(en). Fill only the empty French(fr), German(de) and Japanese(ja) cells. Leave Key, Id, English(en) and Comments columns unchanged." \
      --json | jq -r '.data.id')

# 2. Read the plan for free, and only then commit.
aiglot batches get "$id" --json | jq '.data.plan'

# 3. The only step that spends credits.
aiglot batches approve "$id" --quality lite --yes \
  --instructions "Keep every curly-brace placeholder exactly as written. Never translate a placeholder name. Keep MENU_ and HUD_ entries under 20 characters."

# 4. Wait for a TERMINAL status, not for a specific one.
until status=$(aiglot batches get "$id" --json | jq -r '.data.status'); \
  [ "$status" = "completed" ] || [ "$status" = "failed" ] || [ "$status" = "cancelled" ]; do
  sleep 5
done

# 5. Back into the project.
[ "$status" = "completed" ] && \
  aiglot batches download "$id" --output Assets/Localization/Export/MyGame.csv

Também existe um servidor MCP, aiglot mcp, caso seu agente prefira ferramentas a um shell. Comece com a CLI: funciona em scripts, funciona em CI, e você pode ler exatamente o que foi executado.

Se você optou pela rota XLIFF

Um arquivo por idioma significa um trabalho por idioma, e isso funciona bem até chegar a dez. Existem duas formas de lidar com isso.

Coloque-os em um único ZIP. Até 200 arquivos e 20 MB, com 4 MB por arquivo. Cada XLIFF no arquivo deve ser da mesma versão, 1.2 ou 2.0, mas podem ter idiomas de destino diferentes, que é exatamente a estrutura que a exportação do Unity produz. Um único trabalho, uma instrução e um glossário aplicados a todo o conjunto.

Ou faça um loop com a CLI, da mesma forma que o prompt acima, com um lote por arquivo. São mais trabalhos, mas cada plano pode ser revisado separadamente, o que algumas equipes preferem em uma primeira execução. De qualquer maneira, os arquivos retornam como XLIFF na versão em que chegaram, com os segmentos de origem intactos e apenas os de destino preenchidos.

A parte que decide a qualidade: seu próprio vocabulário

Tudo acima é infraestrutura. O motivo de um jogo traduzido soar bem ou mal é se os seus termos são consistentes.

Insira as palavras que não podem variar em um glossário de workspace uma única vez: nomes de personagens, nomes de itens e feitiços, nomes de facções, a tradução oficial de uma frase recorrente. Ele pertence ao workspace, e não a um único trabalho, portanto se aplica a cada String Table que você enviar depois, inclusive à exportação que fizer daqui a seis meses, quando o jogo tiver crescido quatro mil entradas. É isso que faz o arquivo número vinte concordar com o arquivo número um.

Deixe seu agente rascunhá-lo. O glossário está acessível via MCP, com ferramentas para listar, ler e editar termos, portanto, o mesmo agente que acabou de ler suas String Tables pode extrair os substantivos próprios e palavras inventadas recorrentes, entregar a lista a você e escrever os termos aprovados no workspace antes da primeira tradução ser executada. Um glossário que ninguém preenche não protege nada, e para um jogo com mil termos inventados, preenchê-lo manualmente é a tarefa que acaba sendo adiada indefinidamente.

É aqui que um tradutor automático generalista falha, e o motivo é mecânico, não uma questão de gosto. O glossário dele substitui um termo sempre que há uma correspondência, sem reconsiderar a frase ao redor. Aqui, o glossário é incorporado como significado enquanto a linha é escrita, para que um nome se flexione na gramática em vez de ser apenas jogado no meio dela.

A real abrangência disso

Não passe a sua primeira hora de jogo por isso e publique. Os primeiros trinta minutos de um jogo, a página da loja e qualquer coisa que um jogador provavelmente citaria são escrita, e a escrita merece uma pessoa. São algumas centenas de palavras que carregam a maior parte do seu risco reputacional, então pagar um especialista nativo para isso é barato em termos absolutos e obviamente vale a pena.

As outras nove mil entradas são um trabalho diferente, e esta é a divisão que vale a pena internalizar: volume e importância não estão correlacionados. Rótulos de menu, tooltips, descrições de itens, registros de missões, textos de conquistas, strings de erro: é onde as horas realmente são gastas, e é miserável de fazer à mão e banal em uma única passagem. Processe o volume aqui, depois escolha seu próprio teto: envie direto para a build, ou adicione revisão profissional nos seus dois maiores mercados, ou apenas no texto das missões, e deixe o resto como vier. Nenhuma dessas opções é o conserto de uma primeira passagem ruim, e todas elas fazem o revisor gastar tempo com a linguagem em vez de com planilhas.

Se você quiser ver isso em um arquivo real antes de se comprometer com um pipeline, o tradutor de CSV aceita exportações sem a necessidade de conta. A visão geral está em nosso guia de tradução de video games, e a página de localização de jogos cobre os formatos além do Unity, caso seu estúdio lance em mais de um engine.

As informações sobre o comportamento das exportações do Unity descritas aqui vêm da documentação da versão 1.5 do pacote Localization: o layout das colunas CSV, a correspondência por Key e Id, as colunas de comentários, a compatibilidade com XLIFF 1.2 e 2.0, os nomes dos arquivos XLIFF por idioma, o conteúdo de cada formato e os modos Merge e Replace descritos no manual atual da versão 6000.7. Confira a versão do pacote que você usa se a exportação estiver diferente. Os limites dos arquivos citados são os que estavam em vigor quando este texto foi escrito.