Sobre esta série

Esta série cobre tudo o que você precisa para adicionar múltiplos idiomas a um blog, documentação ou qualquer outro site orientado a conteúdo servido a partir de arquivos Markdown - desde a primeira mudança de configuração até uma camada de cache em produção que mantém os custos da API de tradução bem abaixo de $30 mesmo para um catálogo de 500 artigos, e uma fração disso a cada ano seguinte.

Os exemplos ao longo da série usam português e espanhol como locales concretos, mas a arquitetura é idêntica para qualquer idioma: alemão, japonês, coreano, chinês ou qualquer outro que seu público fale. A série está escrita na ordem em que você a implementaria, e cada artigo produz código funcional que você faz commit no seu repositório.

Antes de entrar na implementação, vale a pena dedicar um momento ao panorama mais amplo das abordagens de internacionalização, porque a arquitetura que você escolhe depende quase inteiramente de onde seu conteúdo reside.

Onde o conteúdo reside determina tudo

Existem três modelos comuns de conteúdo para blogs de desenvolvedores e sites de documentação, e cada um leva a uma estratégia de i18n fundamentalmente diferente.

Conteúdo em um CMS

Ferramentas como Contentful, Sanity ou Prismic têm internacionalização embutida. Você cria um tipo de conteúdo com suporte a locale, os autores escrevem diretamente em cada idioma dentro da interface do CMS, e a API retorna o locale correto na requisição. Fluxos de tradução, estados de aprovação e portões de publicação são gerenciados pelo próprio CMS.

Esta é a escolha certa quando autores não técnicos gerenciam conteúdo em múltiplos idiomas e ferramentas de fluxo editorial são um requisito obrigatório. A contrapartida é que o CMS se torna uma dependência para cada renderização de página, o conteúdo fica preso dentro de um sistema proprietário, e a experiência de desenvolvimento é ditada pela API do CMS em vez das suas próprias estruturas de dados.

Conteúdo em um banco de dados

Artigos armazenados em Postgres, MySQL ou um banco de dados de documentos como MongoDB oferecem controle total sobre o esquema. Você adiciona uma coluna locale, consulta por ela e retorna as linhas traduzidas.

Este modelo escala bem para grandes operações de conteúdo com equipes de tradução dedicadas e mantém tudo em um lugar consultável. O custo é a complexidade de infraestrutura: você precisa de um banco de dados em execução, um pool de conexões e uma camada de consulta, e cada carregamento de página acessa o banco de dados a menos que você adicione uma camada de cache por cima.

Conteúdo em arquivos Markdown

Os artigos são arquivos .md commitados no repositório junto com o código da aplicação. Não há banco de dados, sem dependência de API, sem assinatura de CMS. O conteúdo é versionado, passível de diff e implantável com um único git push.

Este é o modelo natural para blogs escritos por desenvolvedores e documentação técnica onde os autores estão confortáveis em um editor de código e o conteúdo evolui junto com o codebase. A contrapartida é que ferramentas editoriais no estilo CMS não existem por padrão, mas para um blog de desenvolvedor, você não precisa delas.

Esta série foca em arquivos Markdown

Se seu conteúdo reside em um CMS, o CMS cuida da internacionalização e esta série não é o ponto de partida correto - consulte a documentação do seu CMS para configuração de locale. Se seu conteúdo reside em um banco de dados, a abordagem é semelhante em espírito, mas a implementação difere - você adicionaria uma coluna locale e consultaria por ela em vez de chamar uma API de tradução no momento da requisição. Esta série foi projetada especificamente para o terceiro modelo: conteúdo em arquivos Markdown, que é o mais comum para blogs e documentação escritos por desenvolvedores.

Por que esta série foca em Markdown

Todos os seis artigos desta série assumem que seu conteúdo reside em arquivos Markdown dentro de src/posts/. Esta é uma escolha deliberada que desbloqueia uma arquitetura específica: a prosa é extraída do arquivo Markdown canônico, enviada à API do Claude para tradução e armazenada no Upstash Redis.

O arquivo .md original nunca é modificado. Ele permanece a única fonte da verdade para blocos de código, estrutura e metadados em todos os idiomas. Os exemplos usam português (pt) e espanhol (es), mas adicionar alemão (de), japonês (ja) ou coreano (ko) requer alterar uma linha na configuração e uma linha no route matcher.

Para projetos com Markdown como base, a tradução sob demanda resolve um problema que nem abordagens CMS nem de banco de dados enfrentam: uma parte substancial de cada artigo - frequentemente de 40 a 60 por cento - é código que jamais deve ser traduzido. O extrator de prosa descrito no artigo 4 remove todos os blocos de código, caminhos de arquivo e referências de código inline antes que a API do Claude sequer veja o conteúdo. Apenas a prosa legível por humanos cruza a fronteira da API.

O resultado traduzido é armazenado no Upstash Redis. Traduções completas são armazenadas permanentemente e só são removidas quando o arquivo-fonte do artigo muda. Traduções incompletas (onde o modelo descartou alguns segmentos) recebem um TTL de 2 horas para que sejam automaticamente refeitas na próxima visita sem intervenção manual. O primeiro visitante de uma combinação de locale e artigo paga o custo de tradução uma vez; cada visitante subsequente recebe o resultado em cache instantaneamente.

O que esta série cobre

Artigo 1 (este artigo) explica o modelo de sobreposição: o que é, por que é melhor do que a duplicação completa de arquivos ou a tradução em tempo de execução do fonte completo, e como projetar a arquitetura para que adicionar qualquer novo idioma posteriormente exija alterar apenas duas linhas de código.

Artigo 2 percorre todas as mudanças de risco zero: configuração de locale com tipos TypeScript adequados, detecção de locale em hooks.server.ts, o atributo lang do HTML, o route matcher (src/params/locale.ts) que impede o grupo de locale de sequestrar rotas existentes, e o grupo de rotas (locale)/[lang=locale]/ que adiciona rotas traduzidas sem modificar uma única rota inglesa existente.

Artigo 3 estende o singleton do índice de conteúdo para expor getContent(locale) - a única função que toda rota traduzida chama. Também cobre +page.server.ts vs +page.ts e por que @types/node é necessário, além do componente +page.svelte completo que renderiza artigos traduzidos.

Artigo 4 cobre o extrator de prosa, o módulo de tradução da API do Claude, o pipeline de renderização marked v15 e Shiki, a configuração da chave da API do Claude, e a implementação completa de +page.server.ts usando translateBatch para tradução em chunks com retentativas.

Artigo 5 adiciona o cache de tradução do Upstash Redis: configuração passo a passo no Vercel Marketplace, o módulo de cache com TTL condicional (permanente para traduções completas, 2 horas para incompletas), escritas de HTML sem aguardar resposta, e o detalhamento completo de custos por tamanho de catálogo.

Artigo 6 implementa o ferramental de desenvolvimento: a rota de prévia /dev/translations para testar traduções antes de chegar tráfego real, o script CLI pnpm translate para pré-traduzir artigos individuais, o script de invalidação de cache no momento do deploy, e o pipeline de tradução de catálogo via Batch API para traduzir centenas de artigos durante a noite com 50 por cento de desconto.

Leia todos os seis em ordem para ter o quadro completo, ou pule para o artigo que cobre a parte que você está pronto para implementar.

A armadilha de um arquivo por idioma

A maneira mais natural de adicionar um segundo idioma a um blog em Markdown é também a mais cara. Você duplica cada arquivo de artigo, adiciona um prefixo de idioma ao caminho e traduz tudo. Cem artigos em inglês se tornam duzentos arquivos com português, e trezentos com traduções em espanhol.

O repositório triplica de tamanho, e toda vez que você corrige um erro de digitação ou atualiza um exemplo de código em inglês, precisa encontrar e corrigir a mesma coisa em cada cópia traduzida. Em seis meses, seus leitores em português estão seguindo código desatualizado que não funciona mais com a versão atual do framework. Esta é a armadilha de um arquivo por idioma, e quase todos os tutoriais de i18n para geradores de sites estáticos levam você diretamente para ela.

A armadilha persiste porque faz a coisa errada parecer óbvia. Quando você pensa "traduzir este artigo", o instinto é copiar o arquivo inteiro e entregá-lo a um tradutor. Isso funciona perfeitamente para um site de marketing onde o conteúdo é pura prosa. Quebra terrivelmente para um blog técnico onde 40 a 60 por cento de cada artigo é código que jamais deve ser traduzido, permanece idêntico em todos os idiomas e se torna um fardo de manutenção no momento em que passa a existir em múltiplos arquivos.

O que um artigo técnico realmente contém

Antes de projetar uma arquitetura de tradução, ajuda categorizar o que está realmente dentro de um artigo técnico.

Nunca traduzido - idêntico em todos os idiomas:

Todos os blocos de código (a implementação real)
Referências de código inline como $state(), load(), +page.server.ts
Caminhos de arquivo como src/routes/(locale)/[lang=locale]/+layout.ts
Comandos CLI como pnpm add @upstash/redis
Termos técnicos usados como substantivos próprios: SvelteKit, Runes, ISR, SSR, hydration, Vite
Campos estruturais do frontmatter: track, topic, tags, difficulty, position

Sempre traduzido - a prosa real:

Introduções e explicações de seções
O raciocínio por trás das decisões
Explicações de mensagens de erro
Descrições de erros comuns
Valores de frontmatter title e description
Valores de metadados SEO

Traduzido com cuidado - prosa técnica:

Frases que misturam explicação com referências de código inline
Comentários dentro de blocos de código (manter em inglês - desenvolvedores do mundo todo esperam comentários de código em inglês)
Analogias e metáforas que podem não se mapear claramente entre idiomas

Em um artigo típico de SvelteKit com 3.000 palavras, aproximadamente 1.200 são prosa, 300 são títulos e texto estrutural, e 1.500 são código. Você precisa traduzir 1.500 palavras para servir bem a um leitor em português. Duplicar o arquivo inteiro de 3.000 palavras significa que você está armazenando e mantendo 1.500 palavras de código idêntico em cada idioma que adicionar.

Como a tradução realmente funciona nesta arquitetura

O arquivo .md canônico nunca muda e nunca se move. Ele permanece a única fonte da verdade para o artigo em todos os idiomas. O que muda por locale é apenas a prosa - as frases e parágrafos que um leitor realmente lê.

O caminho principal de tradução é sob demanda via API do Claude:

first visitor to /pt/[your-article-slug]
  → prose extractor strips all code blocks from the .md
  → prose-only content sent to Claude API
  → pre-rendered HTML stored in Upstash Redis (TTL based on completeness - see article 5)
  → article rendered: translated prose + original code blocks

every subsequent visitor
  → Redis cache hit → serve instantly, zero API cost

Para um exemplo concreto: quando um leitor visita /pt/sveltekit/routing/dynamic-routes pela primeira vez, esse fluxo é executado por completo. Cada leitor depois dele recebe o resultado em cache instantaneamente.

O arquivo .md nunca é duplicado. Os blocos de código nunca saem do servidor. O fonte em inglês permanece intocado em todos os locales.

Para artigos importantes - conteúdo pilar e pontos de entrada de séries - existe um caminho opcional de pré-tradução estática que é executado antes da chegada do primeiro visitante. Um script CLI extrai a prosa do .md, chama a API do Claude em modo batch com 50 por cento de desconto em relação à tarifa padrão, e escreve o resultado diretamente no Redis:

src/posts/
  sveltekit/
    routing/
      dynamic-routes.md          ← canonical English, never changes

src/translations/                  ← optional static YAML overlays
  pt/
    sveltekit/
      routing/
        dynamic-routes.yaml      ← pre-translated prose only, no code

Quando um arquivo de sobreposição estática existe, o servidor o utiliza diretamente sem chamada à API. Quando não existe, o caminho sob demanda trata disso automaticamente.

Por que isso é melhor do que todas as alternativas

vs. duplicação completa de arquivos: Apenas a prosa cruza a fronteira da API e apenas a prosa é armazenada em cache. Quando você atualiza um exemplo de código no arquivo canônico em inglês, todos os idiomas recebem automaticamente a atualização porque o código nunca existiu em outro lugar.

vs. tradução em tempo de execução do arquivo completo: Enviar um artigo Markdown completo para uma API de tradução é custoso e arriscado. Modelos de tradução ocasionalmente corrigem nomes de variáveis, traduzem literais de string ou ajustam a formatação dentro de blocos de código. O modelo de sobreposição extrai a prosa antes da chamada à API, de modo que a API nunca vê um único backtick.

vs. um sistema de gerenciamento de traduções: Ferramentas como Crowdin ou Lokalise são projetadas para strings de UI - rótulos curtos, texto de botões, mensagens de erro. Elas funcionam mal com prosa de formato longo e não têm conceito de "esta seção é código, pule". Elas também adicionam infraestrutura significativa e custo para um blog que precisa traduzir 100 artigos uma vez, não milhares de strings de UI continuamente.

vs. não fazer nada: Servir inglês a um desenvolvedor brasileiro que teria lido o artigo em português é um custo real, mesmo que seja invisível em seus dados analíticos. O modelo de sobreposição torna a tradução barata o suficiente para que não traduzir deixe de ser uma escolha razoável.

Projetando para idiomas que você ainda não adicionou

A restrição arquitetural mais importante é que adicionar um terceiro ou quarto idioma mais tarde não deve exigir tocar em nenhum código existente. Isso é alcançável se você tornar SUPPORTED_LOCALES a única fonte da verdade para tudo relacionado a idiomas.

Cada parte do sistema que varia por locale - validação de rotas, geração de hreflang, namespacing de chaves de cache, scripts de tradução - lê desse único array de configuração. Adicionar coreano significa adicionar 'ko' a SUPPORTED_LOCALES em config.ts e ao route matcher em src/params/locale.ts. As rotas, o índice de conteúdo, o cache Redis e as tags hreflang são todos atualizados automaticamente.

A única exceção é o padrão glob do Vite para carregamento opcional de sobreposição YAML. O Vite analisa strings glob estaticamente em tempo de build e não pode construí-las a partir de uma variável de runtime. Cada idioma precisa de um glob escrito explicitamente:

// src/lib/content/index.ts - add one line per new language
const allOverlays = {
	pt: import.meta.glob('/src/translations/pt/**/*.yaml', { eager: true }),
	es: import.meta.glob('/src/translations/es/**/*.yaml', { eager: true })
	// ko: import.meta.glob('/src/translations/ko/**/*.yaml', { eager: true }),
}

Dois passos para adicionar qualquer idioma: adicionar a SUPPORTED_LOCALES na config, adicionar ao param matcher, descomentar o glob. Todos os outros arquivos o capturam automaticamente.

Uma nota sobre o domínio de integração

Esta série cria artigos com integration: [i18n] no frontmatter. Esse domínio não está na lista padrão em config.ts - adicione-o para manter o índice de conteúdo consistente e alimentar a página hub em /integrations/i18n. Abra src/lib/config.ts e estenda a constante INTEGRATION_DOMAINS ou onde quer que seu site registre os slugs de integração válidos:

// src/lib/config.ts - add i18n to the integration domains
export const INTEGRATION_DOMAINS = [
	'api',
	'authentication',
	'databases',
	'email',
	'ai',
	'cms',
	'animation',
	'deployment',
	'testing',
	'payments',
	'i18n' // ← add this
] as const

Se seu índice de conteúdo valida contra essa lista, os artigos desta série serão compilados sem problemas.

As opções do pipeline de tradução

Uma vez que a arquitetura esteja em vigor, há três maneiras pelas quais as traduções são realmente produzidas:

Sob demanda na primeira requisição: Um leitor visita uma URL traduzida pela primeira vez. O servidor detecta o locale, verifica o Redis, não encontra nada, chama a API do Claude com apenas os segmentos de prosa, armazena o resultado e serve a página. Cada visitante subsequente recebe a versão em cache. Isso lida com a longa cauda de artigos que são ocasionalmente visitados, mas que não valem a pena pré-traduzir manualmente.

Pré-tradução via CLI: Para artigos pilares e pontos de entrada de séries, você executa pnpm translate --slug <slug> --lang pt para traduzir antes da chegada do primeiro visitante. O script escreve diretamente no Redis.

Tradução de catálogo via Batch API: Para o lançamento inicial de um novo idioma, pnpm translate:catalog --lang pt submete todos os artigos como um único job em batch processado em 24 horas com 50 por cento de desconto em relação à tarifa padrão.

Quando arquivos YAML sidecar estáticos fazem mais sentido

A abordagem com a API do Claude sob demanda funciona bem para a maioria dos blogs de desenvolvedores onde os artigos são longos, o tráfego por locale é imprevisível e manter centenas de arquivos de tradução manualmente é impraticável. Arquivos YAML sidecar estáticos commitados no repositório são o mecanismo primário mais adequado para:

Catálogos pequenos e estáveis com menos de 30 artigos aproximadamente: Quando todo o seu conjunto de conteúdo é pequeno o suficiente para ser pré-traduzido em uma única execução em batch e muda com pouca frequência, commitar arquivos YAML sidecar para cada artigo elimina completamente a dependência do Upstash Redis.

Sites de documentação: A documentação técnica tende a ser altamente estável uma vez escrita. O custo de tradução é pago uma vez no momento do lançamento da documentação, em vez de sob demanda. Ferramentas como Docusaurus e VitePress adotam essa abordagem nativamente.

Equipes com tradutores dedicados: Se um tradutor humano produz as traduções em vez de uma API de máquina, ele precisa de um arquivo para trabalhar. Um YAML sidecar é um entregável natural.

O híbrido: Para um blog em crescimento, a escolha prática é arquivos YAML sidecar estáticos para os 10 a 15 pontos de entrada com maior tráfego (artigos pilares, aberturas de séries), e tradução com a API do Claude sob demanda em cache no Upstash Redis para todo o resto. O primeiro visitante de qualquer artigo não traduzido paga uma espera de 3 a 6 segundos uma única vez; cada visitante subsequente não paga nada.

O que esta série constrói

Esta série implementa a abordagem híbrida - tradução via API do Claude sob demanda em cache no Upstash Redis como mecanismo primário, com arquivos YAML sidecar estáticos opcionais para artigos pilares que merecem latência zero no cold start.

A duplicação completa de arquivos falha: 100 artigos em 3 idiomas se tornam 300 arquivos para manter sincronizados. Um sistema de gerenciamento de traduções é projetado para strings de UI, não para prosa técnica de formato longo com muito conteúdo de código. Uma abordagem YAML estática pura para cada artigo exige pré-traduzir todo o conteúdo antecipadamente - impraticável para um blog que publica regularmente.

O híbrido corresponde à forma real do problema. A longa cauda de artigos, que pode receber visitas ocasionais de leitores em português ou alemão, é tratada automaticamente na primeira requisição e armazenada permanentemente no Upstash Redis. Adicionar um terceiro locale posteriormente requer duas linhas de código.

Custo e escalabilidade

A tradução inicial em batch é o maior custo único: aproximadamente $4 para 100 artigos e $22 para 500 artigos usando a Batch API com 50 por cento de desconto. Depois disso, o custo contínuo é determinado inteiramente por quantos novos artigos você publica - cinco novos artigos por mês em dois locales custa cerca de $0,44 por mês independentemente do tamanho do catálogo. O segundo ano e os seguintes custam muito menos do que o primeiro. Em ambos os casos, a API de tradução é o item de menor valor no seu orçamento de infraestrutura.

Principais conclusões

CMS, banco de dados e Markdown são três modelos de conteúdo fundamentalmente diferentes - cada um requer uma estratégia de i18n diferente
O modelo de sobreposição é especificamente projetado para projetos com Markdown como base, onde blocos de código tornam a duplicação completa de arquivos impraticável
Artigos técnicos têm de 40 a 60 por cento de código que jamais deve ser traduzido - o extrator de prosa remove todo o código antes de chegar à API do Claude
SUPPORTED_LOCALES como única fonte da verdade significa que adicionar um idioma toca em duas linhas de código - a config e o route matcher
O route matcher (src/params/locale.ts) é crítico - sem ele o grupo de locale sequestra rotas existentes como /svelte/ e /sveltekit/
Adicione i18n aos seus domínios de integração em config.ts para que a página hub em /integrations/i18n seja alimentada corretamente

E quanto ao Paraglide JS?

Paraglide JS merece ser abordado diretamente porque é a própria integração de i18n oficialmente recomendada pelo SvelteKit. É uma excelente biblioteca - mas resolve um problema diferente do que esta série aborda.

Paraglide é uma biblioteca de i18n baseada em compilador para strings de UI: rótulos de navegação, texto de botões, rótulos de formulários, mensagens de erro. Você define mensagens com chaves em arquivos JSON e as chama em seus componentes - o compilador gera funções de mensagem com tipos seguros e faz tree-shaking das não utilizadas, produzindo bundles de i18n significativamente menores.

É a ferramenta errada para conteúdo de artigos por três razões concretas. Primeiro, chaves de mensagem não se mapeiam para prosa - uma introdução de artigo de 2.000 palavras não é um rótulo curto, e codificá-la como uma chave de mensagem JSON é impraticável. Segundo, todas as traduções devem existir em tempo de build, então você não pode gerar traduções sob demanda a partir de uma API. Terceiro, a otimização de tree-shaking do Paraglide não se aplica a prosa de formato longo que não deveria estar no bundle de forma alguma.

O relacionamento correto é aditivo: um blog SvelteKit completamente internacionalizado usaria ambos. O Paraglide cuida do shell de UI - navegação, rodapé, botões, rótulos de metadados - e a abordagem com a API do Claude cuida do conteúdo dos artigos. Eles operam em dados completamente separados e nunca conflitam. Esta série omite o Paraglide por simplicidade; adicioná-lo posteriormente para a camada de UI não requer tocar na arquitetura de tradução de artigos.

Leitura adicional

Documentação do Paraglide JS - a recomendação oficial de i18n do SvelteKit para strings de UI
Documentação de roteamento do SvelteKit - entendendo grupos de rotas e param matchers
Documentação da API do Anthropic Claude - a API usada para tradução sob demanda
Upstash Redis no Vercel Marketplace - a camada de cache coberta no artigo 5, gratuita no plano Hobby
Localização do Contentful - a abordagem CMS referenciada neste artigo
Documentação de i18n do Sanity - outra abordagem CMS para comparação