A Papermark é uma plataforma open-source de partilha de documentos. Quando a equipa decidiu localizar a sua documentação, deparou-se com o problema que trava a maioria das equipas de ferramentas para programadores: pôr o i18n a funcionar corretamente numa aplicação Next.js é mais difícil do que a própria tradução.

O problema da implementação#

"Experimentei todos os pacotes de automação e ferramentas caseiras que havia", recorda Iuliia Shnai, fundadora da Papermark. "A maior dor nem sequer era a etapa da tradução — era conseguir pôr o i18n a funcionar corretamente com a estrutura da nossa aplicação."

Este é um padrão familiar. A maioria das ferramentas de localização parte do princípio de que a infraestrutura de i18n já está implementada. Tratam da tradução. Não tratam da configuração, da estrutura de ficheiros, da análise de MDX nem dos casos limite que variam consoante a framework. Para um projeto open-source com uma equipa pequena, gastar tempo de engenharia na implementação da localização é um custo direto para o produto.

Os ficheiros MDX — documentação escrita em Markdown com componentes React integrados — acrescentam outra camada de complexidade. As ferramentas de i18n convencionais lidam com ficheiros JSON de idioma e cadeias de texto simples. Já o conteúdo MDX com interpolações de componentes, frontmatter e tags personalizadas exige uma abordagem diferente.

O que mudou#

Max, fundador da Lingo.dev, entrou diretamente em contacto e ajudou a configurar o projeto Next.js da Papermark. A implementação resolveu os casos limite que estavam a bloquear a equipa: o processamento de ficheiros MDX, a interação entre o next-intl e a estrutura de ficheiros da aplicação, e a extração de cadeias traduzíveis de documentação com forte uso de componentes.

"A implementação resolveu tantos casos limite em que nem sequer tínhamos pensado", diz Shnai. "Ficou claro que tinham pensado a fundo em todas as complexidades da localização, especialmente no caso dos ficheiros MDX, que eram um ponto particularmente crítico para nós."

Logo no primeiro dia: 80 páginas de documentação traduzidas. O motor de localização — configurado com a terminologia de produto da Papermark e ligado ao seu repositório — tratou automaticamente de todo o conjunto de documentação.

Como funciona agora#

O motor de localização da Papermark corre em cada push de código. Sempre que é adicionada nova documentação ou o conteúdo existente é atualizado, o motor traduz automaticamente as alterações. Os engenheiros escrevem a documentação em inglês; as versões localizadas surgem sem quaisquer passos adicionais.

A persistência faz toda a diferença aqui. Como o motor de localização mantém a terminologia de produto da Papermark em todos os pedidos, termos específicos do produto como "Data Room", "Link tracking" e "NDA flow" são traduzidos de forma consistente em todos os idiomas. Tanto a primeira página de documentação processada pelo motor como a centésima aplicam o mesmo vocabulário de produto.

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

Resultados#

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

Num projeto open-source, a componente económica conta. Cada hora não gasta na manutenção da localização é uma hora disponível para o produto. A Papermark continua a expandir o seu motor de localização para abranger a otimização de SEO entre idiomas.