27 de jun. de 2025·8 min
Como construir um app web para gerenciar localização e traduções
Planeje um app web que gerencia workflows de tradução, dados de locale, revisões, checagens de QA e releases. Inclui modelo de dados, UX e integrações.
Planeje um app web que gerencia workflows de tradução, dados de locale, revisões, checagens de QA e releases. Inclui modelo de dados, UX e integrações.
A gestão de localização é o trabalho diário de fazer com que os textos do seu produto (e às vezes imagens, datas, moedas e regras de formatação) sejam traduzidos, revisados, aprovados e entregues — sem quebrar o build ou confundir usuários.
Para um time de produto, o objetivo não é “traduzir tudo”. É manter cada versão de idioma precisa, consistente e atualizada conforme o produto muda.
A maioria das equipes começa com boas intenções e acaba com uma bagunça:
Um app útil de gerenciamento de localização suporta múltiplos papéis:
Você vai construir um MVP que centraliza strings, rastreia status por locale e suporta revisão básica e exportação. Um sistema mais completo adiciona automação (sync, checagens de QA), contexto mais rico e ferramentas como glossário e memória de tradução.
Antes de desenhar tabelas ou telas, decida pelo que seu app de gerenciamento de localização é realmente responsável. Um escopo enxuto torna a primeira versão utilizável — e evita que você reconstrua tudo depois.
Traduções raramente vivem em um só lugar. Anote o que precisa suportar desde o dia 1:
Essa lista ajuda a evitar um “um workflow serve para tudo”. Por exemplo, copy de marketing pode precisar de aprovações, enquanto strings de UI exigem iteração rápida.
Escolha 1–2 formatos para o MVP e expanda depois. Opções comuns incluem JSON, YAML, PO e CSV. Uma escolha prática para MVP é JSON ou YAML (para strings do app), mais CSV apenas se você já depende de importação por planilha.
Seja explícito sobre requisitos como formas plurais, chaves aninhadas e comentários. Esses detalhes afetam o gerenciamento de arquivos de locale e a confiabilidade futura de importação/exportação.
Defina uma língua fonte (geralmente en) e regras de fallback:
Decida também o que significa “pronto” por locale: 100% traduzido, revisado ou publicado.
Para o MVP, foque no processo de revisão de tradução e no fluxo básico de i18n: criar/editar strings, atribuir trabalho, revisar e exportar.
Planeje complementos posteriores — capturas de tela/contexto, glossário, memória de tradução básica e integração com MT — mas não os construa até validar o fluxo central com conteúdo real.
Um app de tradução vence ou perde pelo seu modelo de dados. Se as entidades e campos forem claros, todo o resto — UI, workflow, integrações — fica mais simples.
A maioria das equipes cobre 80% das necessidades com um conjunto pequeno de tabelas/coleções:
en, en-GB, pt-BR).checkout.pay_button).Modele as relações explicitamente: um Project tem vários Locales; uma Key pertence a um Project; uma Translation pertence a uma Key e a um Locale.
Adicione um status a cada tradução para que o sistema guie as pessoas:
draft → in_review → approvedblocked para strings que não devem ser lançadas ainda (revisão legal, contexto faltando etc.)Guarde mudanças de status como eventos (ou em uma tabela de histórico) para poder responder “quem aprovou e quando?” depois.
Traduções precisam de mais que texto simples. Capture:
{name}, %d) e se eles devem corresponder ao sourceNo mínimo, persista: created_by, updated_by, timestamps e um breve change_reason. Isso acelera revisões e gera confiança quando equipes comparam o que está no app com o que foi enviado.
Decisões de armazenamento moldam tudo: UX de edição, velocidade de import/export, diffing e com que confiança você pode lançar.
Linha-por-chave (uma linha por string por locale) é ótima para dashboards e workflows. Dá para filtrar facilmente “faltando em francês” ou “precisa de revisão”, atribuir donos e calcular progresso. O porém: reconstruir um arquivo de locale para exportar requer agrupar e ordenar, e você precisará de campos extras para caminhos de arquivo e namespaces.
Documento-por-arquivo (armazenar cada arquivo de locale como JSON/YAML) mapeia melhor para repositórios. É mais rápido exportar e mais fácil manter a formatação idêntica. Mas buscar e filtrar fica mais difícil, a menos que você mantenha também um índice de keys, status e metadados.
Muitas equipes usam um híbrido: armazenam linha-por-chave como fonte de verdade e snapshots gerados de arquivos para exportação.
Mantenha histórico de revisões no nível da unidade de tradução (key + locale). Cada mudança deve registrar: valor anterior, novo valor, autor, timestamp e comentário. Isso facilita revisão e rollback.
Separadamente, rastreie snapshots de release: “o que exatamente foi enviado em v1.8”. Um snapshot pode ser uma tag que aponta para um conjunto consistente de revisões aprovadas em todos os locales. Isso evita que edições tardias alterem silenciosamente um build já publicado.
Não trate “plural” como um booleano. Use ICU MessageFormat ou categorias CLDR (ex.: one, few, many, other) para que línguas como polonês ou árabe não sejam forçadas a regras em inglês.
Para gênero e outras variações, modele-as como variantes da mesma key (ou mensagem) em vez de chaves ad hoc separadas, assim tradutores veem o contexto completo.
Implemente busca full-text sobre key, source text, tradução e notas do dev. Combine com filtros que refletem o trabalho real: status (novo/traduzido/revisado), tags, file/namespace e missing/empty.
Indexe esses campos cedo — busca é o recurso usado centenas de vezes por dia.
Um app de gerenciamento de localização normalmente começa simples — faça upload de um arquivo, edite strings, baixe de novo. Fica complicado quando você tem múltiplos produtos, muitos locales, releases frequentes e fluxo constante de automação (sync, QA, MT, revisões).
A maneira mais fácil de manter flexibilidade é separar responsabilidades cedo.
Uma configuração comum e escalável é API + UI web + jobs em background + banco de dados:
Essa separação permite adicionar mais workers para tarefas pesadas sem reescrever o app inteiro.
Se quiser avançar mais rápido na primeira versão, uma plataforma de scaffold como Koder.ai pode ajudar a gerar a UI (React), API (Go) e schema PostgreSQL a partir de um spec estruturado e algumas iterações em chat — e exportar o código quando estiver pronto para ter o repo e o deploy.
Mantenha a API centrada em poucos recursos principais:
checkout.button.pay).Projete endpoints para suportar edição humana e automação. Por exemplo, listar keys deve aceitar filtros como “faltando no locale”, “mudou desde” ou “precisa de revisão”.
Trate automação como trabalho assíncrono. Uma fila normalmente lida com:
Faça jobs idempotentes (seguros para retry) e registre logs de job por projeto para que equipes possam diagnosticar falhas sozinhas.
Mesmo times pequenos podem gerar grandes datasets. Adicione paginação para listas (keys, histórico, jobs), cache para leituras comuns (estatísticas de locale por projeto) e aplique rate limits para proteger endpoints de import/export e tokens públicos.
Detalhes “chatos” como esses evitam que seu sistema de gerenciamento de tradução fique lento exatamente quando a adoção cresce.
Se seu app armazena strings fontes e histórico de tradução, controle de acesso não é opcional — é como você evita edições acidentais e mantém decisões auditáveis.
Um conjunto simples de papéis cobre a maioria:
Trate cada ação como uma permissão para evoluir depois. Regras comuns:
Isso mapeia bem para um sistema de gerenciamento de tradução mantendo flexibilidade para contratados.
Se sua empresa já usa Google Workspace, Azure AD ou Okta, SSO reduz risco de senhas e facilita offboarding. E-mail/senha funciona para times pequenos — exija senhas fortes e fluxo de reset.
Use sessões seguras e de curta duração (cookies HTTP-only), proteção CSRF, rate limiting e 2FA onde possível.
Registre quem mudou o quê e quando: edições, aprovações, mudanças de locale, exports e updates de permissões. Combine o log com “desfazer” via histórico de versão para que rollbacks sejam seguros e rápidos (veja /blog/plan-storage-and-versioning).
Sua UI é onde o trabalho de localização realmente acontece, então priorize telas que reduzam trocas e tornem o status óbvio de relance.
Comece com um dashboard que responda três perguntas rápidas: o que está feito, o que falta e o que está bloqueado.
Mostre progresso por locale (percentual traduzido, percentual revisado), mais um contador claro de “strings faltando”. Adicione um widget de fila de revisão que destaque itens aguardando aprovação e um feed de “recentemente alterado” para que revisores detectem edições arriscadas.
Filtros importam mais que gráficos: locale, área do produto, status, responsável e “mudou desde o último release”.
Um bom editor é lado a lado: source à esquerda, target à direita, com contexto sempre visível.
Contexto pode incluir a key, captura de tela (se houver), limites de caracteres e placeholders (ex.: {name}, %d). Inclua histórico e comentários na mesma visão para que tradutores não precisem de uma tela separada de “discussão”.
Faça o fluxo de status com um clique: Draft → In review → Approved.
Trabalho de localização é frequentemente “muitas pequenas mudanças”. Adicione seleção em massa com ações como atribuir a usuário/time, mudar status e exportar/importar por locale ou módulo.
Mantenha ações em massa restritas por papéis (veja /blog/roles-permissions-for-translators se cobrir isso em outro lugar).
Tradutores intensivos passam horas no editor. Suporte navegação completa por teclado, estados de foco visíveis e atalhos como:
Também suporte leitores de tela e modo alto contraste — acessibilidade acelera o trabalho para todos.
Um app de gerenciamento de localização vence ou perde pelo fluxo. Se as pessoas não souberem o que traduzir a seguir, quem toma uma decisão ou por que uma string está bloqueada, você terá atrasos e qualidade inconsistente.
Comece com uma unidade clara de trabalho: um conjunto de keys para um locale em uma versão específica. Permita que PMs (ou leads) atribuam trabalho por locale, arquivo/módulo e prioridade, com uma data de entrega opcional.
Torne atribuições visíveis em uma caixa “Meu Trabalho” que responda: o que está atribuído, o que está atrasado e o que espera por outros. Para times maiores, adicione sinais de carga (contagem de itens, estimativa de palavras, última atividade) para que atribuições sejam justas e previsíveis.
Construa um pipeline de status simples, por exemplo: Untranslated → In progress → Ready for review → Approved.
Revisão deve ser mais que um check binário. Suporte comentários inline, sugestões de edição e aprovar/rejeitar com motivo. Quando um revisor rejeita, mantenha o histórico — não sobrescreva.
Isso torna o processo auditável e reduz erros repetidos.
O texto fonte vai mudar. Quando isso ocorrer, marque traduções existentes como Needs update e mostre um diff ou resumo do “o que mudou”. Mantenha a tradução anterior como referência, mas evite que ela seja re-aprovada sem decisão explícita.
Notifique em eventos que bloqueiam progresso: nova atribuição, pedido de revisão, rejeição, prazo se aproximando e mudança na fonte que afeta traduções aprovadas.
Mantenha notificações acionáveis com links profundos como /projects/{id}/locales/{locale}/tasks para que as pessoas resolvam problemas em um clique.
Brincar manualmente com arquivos é onde projetos de localização começam a se desgarrar: tradutores trabalham em strings desatualizadas, desenvolvedores esquecem de puxar atualizações e releases publicam locales pela metade.
Um bom app de localização trata import/export como pipeline repetível, não como tarefa única.
Suporte caminhos comuns que equipes realmente usam:
Ao exportar, permita filtrar por project, branch, locale e status (ex.: “apenas approved”) para evitar vazar strings parcialmente revisadas para produção.
Sync só funciona se as keys permanecerem consistentes. Decida cedo como strings são geradas:
checkout.button.pay_now), proteja-as contra renomeações acidentais.\n- Se usar keys por hash, armazene o source string e contexto para que updates não criem duplicatas silenciosamente.Seu app deve detectar quando o source string mudou mas a key não, e marcar traduções como needs review em vez de sobrescrevê-las.
Adicione webhooks para que o sync ocorra automaticamente:
main → importa strings fontes atualizadas.\n- Tag de release criada → exporta traduções “approved” e abre um PR.Webhooks devem ser idempotentes (seguros para retry) e gerar logs claros: o que mudou, o que foi ignorado e por quê.
Se estiver implementando isso, documente a configuração end-to-end mais simples (acesso ao repo + webhook + export via PR) e linke-a da UI, por exemplo: /docs/integrations.
QA de localização é onde o app deixa de ser um editor simples e começa a prevenir bugs em produção.
O objetivo é pegar problemas antes de strings chegarem à produção — especialmente os que só aparecem em arquivos de locale específicos.
Comece com checagens que podem quebrar a UI ou travar formatação:
{count} presente no inglês mas faltando no francês, ou plurais inconsistentes).\n- HTML inválido em strings que permitem marcação (tags quebradas, entidades não fechadas).\n- Caracteres não escapados para o formato de arquivo (aspas em JSON, % solto em strings estilo printf, ICU malformado).Trate esses como “bloqueadores de release” por padrão, com mensagem clara e apontando a key e o locale exatos.
Não quebram sempre o app, mas afetam qualidade e consistência da marca:
Um texto pode estar correto e ainda parecer errado. Adicione a possibilidade de solicitar captura de tela/contexto por key (ou anexar screenshot a uma key), para que revisores validem truncamento, quebras de linha e tom na UI.
Antes de cada release, gere um resumo de QA por locale: erros, avisos, strings não traduzidas e principais problemas.
Facilite exportar ou linkar internamente (ex.: /releases/123/qa) para que o time tenha uma visão única de “go/no-go”.
Adicionar glossário, tradução por memória (TM) e machine translation (MT) pode acelerar muito a localização — mas só se o app tratá-los como orientação e automação, não como conteúdo “pronto para publicar”.
Glossário é uma lista curada de termos com traduções aprovadas por locale (nomes de produto, conceitos de UI, frases legais).
Armazene entradas como termo + locale + tradução aprovada + notas + status.
Para reforçar, adicione checagens no editor:
TM reutiliza segmentos aprovados antes. Mantenha simples:
Trate TM como sistema de sugestão: usuários podem aceitar, editar ou rejeitar; apenas traduções aceitas retornam para o TM.
MT é útil para rascunhos e backlog, mas não deve ser saída final padrão.
Torne MT opt-in por projeto e por job, e passe strings preenchidas por MT pelo fluxo normal de revisão.
Times têm restrições diferentes. Permita que admins escolham provedores (ou desativem MT), definam limites de uso e escolham que dados são enviados (ex.: excluir keys sensíveis).
Logue requisições para visibilidade de custo e auditoria, e documente opções em /settings/integrations.
Um app de localização não deve apenas “armazenar traduções” — deve ajudar a enviá-las com segurança.
A ideia chave é release: um snapshot congelado de strings aprovadas para um build específico, para que o que é deployado seja previsível e reproduzível.
Trate um release como um bundle imutável:
Isso permite responder: “O que enviamos no v2.8.1 para fr-FR?” sem adivinhação.
Times querem validar traduções antes dos usuários verem. Modele exports por ambiente:
Deixe o endpoint de export explícito (por exemplo: /api/exports/production?release=123) para evitar vazamento acidental de textos não revisados.
Rollback é mais fácil quando releases são imutáveis. Se um release causar problemas (placeholders quebrados, terminologia errada), você deve poder:\n
Evite “editar produção no lugar” — isso quebra trilhas de auditoria e dificulta análise de incidentes.
Notavelmente, essa mentalidade de “snapshot + rollback” casa bem com plataformas de build modernas. Por exemplo, Koder.ai inclui snapshots e rollback como fluxo nativo, o que é um bom modelo mental ao desenhar releases imutáveis.
Após deploy, rode um checklist operacional simples:\n
Se você mostrar histórico de releases na UI, inclua um “diff vs release anterior” para que equipes detectem mudanças arriscadas rapidamente.
Segurança e visibilidade são a diferença entre uma ferramenta útil de localização e uma em que equipes confiam. Quando o fluxo rodar, trave o sistema e comece a medir.
Siga o princípio do menor privilégio por padrão: tradutores não devem alterar configurações do projeto, revisores não devem ver cobrança ou exports apenas de admin. Faça papéis explícitos e auditáveis.
Armazene segredos com segurança. Mantenha credenciais de DB, chaves de webhook e tokens de terceiros em um gerenciador de segredos ou variáveis de ambiente criptografadas — nunca no repo. Rode rotação de chaves periodicamente e ao remover alguém da equipe.
Backups não são opcionais. Faça backups automáticos do banco e do storage (arquivos de locale, anexos), teste restores e defina retenção. Um “backup que não restaura” é só custo extra.
Se strings podem conter conteúdo de usuário (tickets, nomes, endereços), evite armazená-las no sistema de tradução. Prefira placeholders ou referências e remova valores sensíveis dos logs.
Se for preciso processar esse texto, defina regras de retenção e restrições de acesso.
Meça algumas métricas que reflitam saúde do fluxo:\n
traduzido a aprovado\n- Keys que mais mudam: identifique áreas de UI instáveis e replanejeUm dashboard simples mais export CSV já basta para começar.
Com a fundação estável, considere:\n
Se planeja oferecer isso como produto, adicione um caminho claro de upgrade e call-to-action (veja /pricing).
Se seu objetivo imediato é validar o fluxo com usuários reais, você também pode prototipar o MVP no Koder.ai: descreva papéis, fluxo de status e formatos de import/export em planning mode, itere na UI React e na API Go via chat e depois exporte a base de código quando for endurecer para produção.
Um app web de gerenciamento de localização centraliza suas strings e gerencia o fluxo de trabalho ao redor delas — tradução, revisão, aprovações e exportação — para que as equipes possam lançar atualizações sem chaves quebradas, placeholders faltando ou status confuso.
Comece definindo:
JSON/YAML)pt-BR → pt → en)Um escopo fechado evita o erro de “uma só workflow para tudo” e mantém o MVP utilizável.
A maioria das equipes cobre o fluxo principal com:
Armazene metadados que evitam erros em produção e retrabalho nas revisões:
Depende do que você prioriza:
Uma abordagem comum é híbrida: linha-por-chave como fonte da verdade e snapshots de arquivos gerados para exportação.
Use duas camadas:
Isso evita edições “silenciosas” que alteram o que já foi enviado e facilita a investigação de incidentes.
Comece com papéis que refletem trabalho real:
Centre a API em alguns recursos principais:
Projects, Locales, Keys, TranslationsDepois torne os endpoints de listagem filtráveis para tarefas reais, por exemplo:
Execute trabalhos demorados de forma assíncrona:
Torne os jobs idempotentes (seguros para reexecutar) e armazene logs por projeto para que as equipes possam diagnosticar falhas sem fuçar nos logs do servidor.
Priorize checagens que evitam UI quebrada:
{count}, %d) e cobertura de pluralTrate essas checagens como bloqueadoras de release por padrão e adicione avisos mais suaves para consistência de glossário e espaçamento/case para melhorar qualidade sem bloquear tudo.
draft → in_review → approved)Com essas entidades claras, telas, permissões e integrações ficam mais simples de construir e manter.
created_by, updated_by, timestamps, motivo da mudança)Isso separa “um editor de texto” de um sistema em que equipes confiam.
Defina permissões por ação (editar fonte, aprovar, exportar, gerenciar locales) para poder evoluir o sistema sem quebrar fluxos.
Isso atende tanto à edição humana na UI quanto à automação via CLI/CI.