Pular para o conteúdo
SheetForge

Planilhas de Localização

Uma única planilha guarda o texto do seu jogo em todos os idiomas: as linhas são chaves, as colunas são idiomas. Uma planilha de localização é uma planilha comum do SheetForge em tudo o que importa — ela importa, valida, exporta, faz push e round-trip exatamente como uma planilha de dados — e quando o pacote Unity Localization (com.unity.localization) está instalado, toda importação concluída também preenche a partir dela as próprias coleções StringTable do pacote. Seu runtime então consome referências LocalizedString padrão, enquanto a planilha continua sendo a única fonte da verdade.

Esta página trata do texto do seu jogo. A UI em 10 idiomas do próprio produto é um assunto separado — veja Localização.

A forma da planilha (@loc)

Uma planilha se torna uma planilha de localização ao carregar uma linha de marcador @loc. Como @overlap e @style, ela fica em qualquer posição acima dos dados; sua célula em cada coluna nomeia o código de idioma daquela coluna:

@loc     |            | en             | ko          |       |
@name    | codeName   | en             | ko          | smart | comment
@type    | RecordId   | string?        | string?     | bool? | string?
@desc    | key        | source text    | Korean      |       |
         | ui.ok      | OK             | 확인        | false | Confirm button
         | ui.cancel  | Cancel         | 취소        |       |
  • A coluna-chave RecordId é obrigatória — o valor da chave de cada linha (ui.ok) é a chave de localização, e o nome da aba é o nome da coleção StringTable: uma aba = uma coleção.
  • Uma coluna de idioma é uma coluna de string cuja célula @loc carrega o código (en, ko, pt-BR — qualquer identificador do tipo tag; o SheetForge valida a forma da grafia, não a existência do código, e duas colunas cujos códigos diferem apenas por maiúsculas/minúsculas são rejeitadas). Escreva-as como string?: uma célula não traduzida é então uma lacuna de cobertura, não um erro de importação — veja Cobertura abaixo.
  • A primeira coluna de idioma é o idioma de origem. É o texto dela que a célula de referência de uma planilha de dados exibe em linha como prévia, e o que a cunhagem automática grava.
  • Duas colunas opcionais reservadas, associadas por nome: smart (um booleano — marca a entrada como uma Smart String do Unity Localization) e comment (uma string — sincronizada nos metadados de comentário da entrada). Quando presentes, a planilha é a verdade para esses dados; quando ausentes, a ponte deixa os metadados correspondentes da tabela intocados. Uma coluna reservada não pode também carregar um código de idioma.
  • Pelo menos um código de idioma é obrigatório, e uma planilha não pode ser ao mesmo tempo uma planilha de enum e uma planilha de localização (@enum + @loc é um erro de conflito, relatado uma vez).

Tudo o mais é uma planilha comum: staging e Ctrl+Z, edição de estrutura, agrupamento por @style, round-trips de xlsx e Google, Push, e o aplicativo web tratam tudo como uma tabela normal. O que muda é a saída: uma aba de localização não emite nenhuma classe de registro gerada, nenhum ScriptableObject de Database e nenhum endereço Addressables. Em vez disso, ela alimenta duas coisas — as constantes de chave e a ponte.

Referenciando texto a partir de planilhas de dados (LocRef@Tab)

Uma planilha de dados aponta para uma entrada de localização com uma coluna de referência LocRef:

@name    | codeName    | displayName
@type    | RecordId    | LocRef@Strings
@desc    | unique key  | shown in UI
         | item.sword  | item.sword.name

LocRef@Strings se comporta exatamente como as referências embutidas que você já conhece (RecordId@Tab):

  • Validada por integridade na importação — uma chave que não existe na aba Strings é um erro estruturado com uma sugestão de correspondência mais próxima; um erro de digitação morre na importação, não em tempo de execução. O alvo precisa ser uma planilha de localização (senão LocRefTargetNotLocalizationSheet), e um LocRef sem @Target é rejeitado, com a grafia correta sugerida.
  • Trilhos de referência completos — o seletor de chave pesquisável, a propagação de renomeação de chave (renomear uma chave reescreve toda célula que a referencia no mesmo lote), arestas de grafo no canvas de registros, regras de dropdown exportadas, e detecção de órfãs, tudo funciona, tanto no editor quanto no aplicativo web.
  • Se compõe como qualquer referência — List<LocRef@Strings> e a forma opcional LocRef@Strings? (uma célula vazia é uma referência vazia) funcionam ambas.
  • A célula mostra o texto, não apenas a chave. Uma célula LocRef exibe em linha o texto da entrada no idioma de origem como prévia, então uma planilha cheia de chaves ainda se lê como frases. O canvas de registros faz o mesmo — linhas de referência carregam o texto de origem em linha, e um valor truncado sempre guarda o texto completo na dica de ferramenta.
  • Digitar em uma célula vazia cunha a entrada. Digite o texto de origem em uma célula LocRef vazia, e o SheetForge prepara, como um único gesto e um único passo de undo: uma nova chave na planilha de localização de destino (sugerida a partir dos nomes de registro e de campo — renomeie-a livremente depois, a propagação mantém toda referência intacta), o texto que você digitou como seu valor no idioma de origem, e a referência na célula em que você digitou. Ambos os hosts.

O que chega no seu código

O codegen emite o campo como LocRef — uma struct serializável simples (a tabela e a chave de destino) que vive no assembly de runtime do SheetForge e compila esteja o pacote Unity Localization instalado ou não; código gerado e ScriptableObjects cozidos (bake) nunca contêm um tipo do pacote. Com o pacote instalado, uma única chamada de extensão faz a ponte até ele:

var text = definition.displayName.ToLocalizedString(); // UnityEngine.Localization.LocalizedString

ToLocalizedString() só existe quando o pacote está presente (uma version-define, SHEETFORGE_LOCALIZATION, liga a camada de extensão — o mesmo mecanismo que SHEETFORGE_ADDRESSABLES usa). Sem o pacote, o campo continua sendo um par tabela/chave bem formado que você pode consumir por conta própria.

O que uma importação gera

Junto com as saídas regulares, uma importação escreve um único SheetForgeLocalizationKeys.cs para o projeto inteiro — uma classe estática por aba de localização (StringsKeys, …) contendo um public const string por chave, para que o código do jogo possa escrever StringsKeys.ui_ok em vez de um "ui.ok" solto, ganhando segurança em tempo de compilação além de completar no IDE.

  • Os nomes de membro são as chaves higienizadas para identificadores C# (caracteres fora de letras ASCII, dígitos e _ viram _; colisões recebem um sufixo numérico determinístico). Mantenha as chaves em ASCII se quiser constantes utilizáveis — uma chave totalmente não-ASCII se higieniza em uma sopa de sublinhados.
  • Assim como o arquivo de enum definido pela planilha, o arquivo de constantes é uma saída em nível de projeto e sempre é gerado na pasta de código gerado das configurações — a mesma observação sobre assembly em Capacidades e Limites se aplica.
  • Uma aba de localização sem linhas mantém uma classe vazia, então limpar uma planilha não quebra o código que referencia o tipo.

A ponte do Unity Localization

Com o pacote instalado, o SheetForge mantém uma coleção StringTable por aba de localização — chaves, valores, e os dados de smart/comment quando essas colunas existem.

  • Quando ela roda: automaticamente, no momento em que uma importação é concluída — a mesma posição que Exportação e Push têm como saídas — mais uma ação manual de ressincronização para executá-la sob demanda.
  • Direção: de mão única, planilha → tabelas. A planilha é canônica; as tabelas são a saída.
  • Idiomas: um idioma da planilha sem um asset Locale correspondente no projeto é criado automaticamente e nomeado no relatório. Um idioma que só existe no projeto é deixado intocado e relatado como não coberto pela planilha.
  • Renomeações de chave mantêm as referências de cena vivas. Renomear uma chave no Data Studio passa pela mesma maquinaria de renomeação que toda referência usa, e a ponte renomeia a entrada da tabela no lugar, preservando seu id interno — um LocalizedString em uma cena ou prefab se vincula a esse id, então sobrevive à renomeação. O limite honesto: uma renomeação feita fora do Studio — editando a fonte da planilha diretamente no Google Sheets ou no Excel — é indistinguível de excluir uma chave e adicionar outra. A ponte criará uma entrada nova (novo id) e tratará a antiga como órfã; referências de cena para a entrada antiga continuam apontando para a órfã. Renomeie chaves no Studio.
  • Metadados que a planilha não modela são sempre preservados. Comentários (quando não há coluna comment), flags de exclusão, e qualquer outro metadado da tabela passam por toda sincronização intocados.

Edições externas são questionadas, nunca mescladas silenciosamente

A ponte carimba as tabelas que possui e lembra uma impressão digital da última sincronização. Se uma tabela mudou desde então — alguém a editou na janela Localization Tables, ou puxou dados para ela com a própria extensão do Google Sheets da Unity —, a próxima sincronização para e pergunta: sobrescrever a partir da planilha, ou abortar com um relatório de diferenças. Não há mesclagem silenciosa nem sobrescrita silenciosa. Se você quiser um fluxo com duas interfaces graváveis, encaminhe a outra interface pela planilha em vez disso — é para isso que existe a exportação de tradução.

Chaves órfãs são preservadas por padrão

Uma chave que existe na tabela, mas não está mais na planilha, é uma órfã: ela é mantida, listada em um relatório de órfãs, e removível por meio de uma ação explícita de limpeza (todas de uma vez ou uma a uma). Um alternador nas configurações muda para excluir ao sincronizar, se você quiser que a tabela espelhe a planilha exatamente. Nada é jamais destruído como efeito colateral.

Sem o pacote

O pacote Unity Localization é opcional. Sem ele:

  • Planilhas de localização são planilhas completas — autoria, validação, cobertura, Exportação, Push, xlsx, o aplicativo web, constantes de chave e campos LocRef funcionam por completo.
  • A única coisa que espera é a saída de sincronização de StringTable, que mostra um aviso de instalação (uma vez por sessão) e para — o mesmo padrão de orientação do Addressables, e igualmente nunca instalado programaticamente.
  • Todo assembly e toda linha de código gerado compila sem o pacote. Versão de pacote suportada: 1.5 ou mais recente.

Migrando tabelas existentes para uma planilha

Já usa o Unity Localization? Um importador reverso transforma uma coleção StringTable existente em uma planilha de localização, gravada diretamente na sua origem de importação e importada automaticamente — o mesmo caminho que a criação de planilhas percorre. Revise-a e edite-a depois, como qualquer outra planilha. Se não for possível gravar na origem ativa a partir do editor, o arquivo cai ao lado da sua saída de Exportação, com um aviso pedindo que você o mova. Quando a ponte depois sincronizar essa planilha de volta para a mesma coleção, os ids das entradas são herdados por correspondência de nome de chave — referências LocalizedString existentes em cenas e prefabs sobrevivem à migração intactas.

Fluxos de tradução

Cobertura: células não traduzidas são relatadas, não recusadas

Uma célula de idioma vazia não é um erro — a importação relata a cobertura por idioma (quantas chaves cada idioma traduziu, e quais estão faltando), e toda saída continua aberta. O texto chega de forma incremental; a planilha nunca bloqueia por causa de uma tradução inacabada.

A lente de idiomas

Trabalhando em um idioma de cada vez? Uma lente de idiomas alterna quais colunas de idioma ficam visíveis. É metadado de exibição da família @style — nunca toca a impressão digital de importação, o codegen, ou qualquer saída. Ambos os hosts.

Exportação de tradução e reimportação parcial

Para entregar um idioma a um tradutor, exporte uma pasta de trabalho de tradução: escolha os idiomas e obtenha um xlsx de chave + texto de origem + comentário + uma coluna de status, na qual uma entrada cujo texto de origem mudou desde a última exportação é marcada como desatualizada. Quando o arquivo voltar, reimporte-o como uma mesclagem parcial: as linhas são correspondidas por chave e apenas as colunas de idioma são gravadas — a estrutura, outros idiomas e todo o resto na planilha permanecem intocados. Ambos os hosts. Uma assimetria honesta: a memória de status vive em um arquivo local da máquina ao lado do projeto Unity, então uma pasta de trabalho exportada do navegador sempre diz new na coluna de status; o aviso de "traduzido contra um texto de origem mais antigo" na reimportação compara com o texto de origem que o próprio arquivo carrega, então funciona nos dois hosts.

XLIFF e pseudo-idiomas

O SheetForge deliberadamente não reimplementa XLIFF ou pseudolocalização — as tabelas que a ponte preenche são tabelas comuns do Unity Localization, então a exportação/importação XLIFF e o ferramental de pseudo-idioma do próprio pacote funcionam sobre elas como em qualquer projeto. Lembre-se, porém, da autoridade de mão única: a saída que essas ferramentas gravam dentro das tabelas é uma edição externa sobre a qual a próxima sincronização perguntará. Para manter as traduções na fonte da verdade, traga-as de volta pela planilha (a pasta de trabalho de tradução acima), em vez de para dentro das tabelas.

Dois limites relacionados, declarados com honestidade: a ponte cobre apenas StringTables — AssetTables são um item reconhecido no backlog — e o SheetForge não inclui auxiliares de Smart Format específicos de idioma (partículas gramaticais coreanas, por exemplo). A coluna smart marca entradas como Smart Strings; formatadores além do que o pacote oferece são seus para escrever por meio dos próprios pontos de extensão do pacote.

No aplicativo web

Uma planilha de localização é uma planilha comum no navegador: autoria, validação, cobertura, o seletor LocRef com texto de origem em linha, cunhagem, a lente de idiomas, e a pasta de trabalho de tradução funcionam todos em web.sheetforge.workers.dev. A sincronização de StringTable é tarefa do editor Unity — o navegador não tem um projeto Unity no qual gravar tabelas, e não finge o contrário.

Páginas relacionadas