Como a Papermark automatizou a localização da documentação com a Lingo.dev

A Papermark é uma plataforma open source de compartilhamento de documentos. Quando a equipe decidiu localizar a documentação, esbarrou no mesmo problema que trava a maioria das equipes de ferramentas para desenvolvedores: fazer o i18n funcionar direito em uma aplicação Next.js é mais difícil do que traduzir.

O desafio da configuração#

"Testei todos os pacotes de automação e ferramentas caseiras que existiam", relembra Iuliia Shnai, fundadora da Papermark. "A maior dor nem estava na etapa de tradução — estava em fazer o i18n funcionar corretamente com a estrutura do nosso app."

Esse é um padrão conhecido. A maioria das ferramentas de localização parte do princípio de que a infraestrutura de i18n já está pronta. Elas resolvem a tradução, mas não a configuração, a estrutura de arquivos, o parsing de MDX nem os casos complexos que variam de framework para framework. Para um projeto open source com uma equipe pequena, gastar tempo de engenharia na configuração da localização é um custo direto para o produto.

Arquivos MDX — documentação escrita em Markdown com componentes React embutidos — adicionam mais uma camada de complexidade. Ferramentas de i18n tradicionais lidam com arquivos JSON de idioma e strings simples. Já conteúdo em MDX, com interpolações de componentes, frontmatter e tags customizadas, exige outra abordagem.

O que mudou#

Max, fundador da Lingo.dev, entrou em contato diretamente e ajudou a configurar o projeto Next.js da Papermark. A implementação resolveu os casos complexos que estavam travando a equipe: processamento de arquivos MDX, a interação entre next-intl e a estrutura de arquivos do app, e a extração de strings traduzíveis de uma documentação carregada de componentes.

"A implementação deu conta de muitos casos complexos que nem tínhamos considerado", diz Shnai. "Ficou claro que eles tinham pensado em toda a complexidade da localização, especialmente no caso dos arquivos MDX, que eram um ponto particularmente difícil para nós."

No primeiro dia: 80 páginas de documentação traduzidas. O engine de localização — configurado com a terminologia de produto da Papermark e conectado ao repositório da equipe — cuidou automaticamente de toda a documentação.

Como funciona hoje#

O engine de localização da Papermark roda a cada push de código. Sempre que uma nova documentação é adicionada ou um conteúdo existente é atualizado, o engine traduz as mudanças automaticamente. Os engenheiros escrevem a documentação em inglês; as versões localizadas aparecem sem nenhuma etapa extra.

A persistência de estado faz toda a diferença aqui. Como o engine de localização mantém a terminologia de produto da Papermark em cada solicitação, termos específicos como "Data Room", "Link tracking" e "NDA flow" são traduzidos com consistência em todos os idiomas. Tanto a primeira página processada pelo engine quanto a centésima seguem o mesmo vocabulário de produto.

"Zero esforço contínuo de engenharia para traduções" é o resultado mensurável — mas o motivo de fundo é que a localização deixou de ser uma tarefa recorrente e passou a ser infraestrutura.

Resultados#

• 80 páginas de documentação traduzidas no primeiro dia
• Zero esforço contínuo de engenharia para localização
• Tratamento automático de documentação MDX complexa
• Tradução contínua a cada push, cobrindo conteúdo novo e atualizado
• Terminologia consistente em todos os idiomas

Para um projeto open source, a conta precisa fechar. Cada hora não gasta com manutenção de localização é uma hora a mais para investir no produto. A Papermark segue expandindo seu engine de localização para incluir a otimização de SEO em vários idiomas.