Faça sua pergunta e obtenha um resumo do documento referenciando esta página e o provedor AI de sua escolha
Histórico de versões
- "Atualizar o uso da API useIntlayer do Solid para acesso direto a propriedades"v8.9.004/05/2026
- "Adicionado para Tanstack Start Solid.js"v8.5.125/03/2026
O conteúdo desta página foi traduzido com uma IA.
Veja a última versão do conteúdo original em inglêsSe você tiver uma ideia para melhorar esta documentação, sinta-se à vontade para contribuir enviando uma pull request no GitHub.
Link do GitHub para a documentaçãoCopiar o Markdown do documento para a área de transferência
Traduza seu site Tanstack Start com Solid.js usando Intlayer | Internacionalização (i18n)
Índice
Este guia demonstra como integrar o Intlayer para uma internacionalização perfeita em projetos Tanstack Start com Solid.js, roteamento ciente de localidade, suporte a TypeScript e práticas de desenvolvimento modernas.
Por que Intlayer em vez de alternativas?
Comparado com soluções principais como react-i18next ou i18next, Intlayer é uma solução que vem com otimizações integradas como:
O Intlayer é otimizado para funcionar perfeitamente com TanStack Start e Solid, oferecendo roteamento multilíngue, mapa do site e todos os recursos necessários para dimensionar a internacionalização (i18n).
Em vez de carregar arquivos JSON enormes em suas páginas, carregue apenas o conteúdo necessário. O Intlayer ajuda a reduzir o tamanho do bundle e das páginas em até 50%.
Definir o escopo do conteúdo do seu aplicativo facilita a manutenção de aplicativos de grande escala. Você pode duplicar ou excluir uma única pasta de recursos sem o fardo mental de revisar toda a base de código de seu conteúdo. Além disso, o Intlayer é totalmente tipado (fully typed) para garantir a precisão do seu conteúdo.
A co-localização de conteúdo reduz o contexto necessário pelos Large Language Models (LLMs). O Intlayer também vem com um conjunto de ferramentas, como uma CLI para testar traduções ausentes,LSP, MCP, e habilidades do agente, para tornar a experiência do desenvolvedor (DX) ainda mais tranquila para os agentes de IA.
Use a automação para traduzir seu pipeline de CI/CD usando o LLM de sua escolha às custas de seu provedor de IA. O Intlayer também oferece um compilador para automatizar a extração de conteúdo, bem como uma plataforma web para ajudar a traduzir em segundo plano.
Conectar arquivos JSON enormes a componentes pode levar a problemas de desempenho e reatividade. O Intlayer otimiza o carregamento do seu conteúdo no momento da construção.
Mais do que apenas uma solução i18n, o Intlayer fornece um [editor visual] auto-hospedado(/pt/doc/concept/editor) e um CMS completo para ajudá-lo a gerenciar seu conteúdo multilíngue em tempo real, facilitando a colaboração com tradutores, redatores e outros membros da equipe. O conteúdo pode ser armazenado local e/ou remotamente.
Guia Passo a Passo para Configurar o Intlayer numa Aplicação Tanstack Start
Veja o Modelo de Aplicação no GitHub.
Criar o Projeto
Comece criando um novo projeto TanStack Start seguindo o guia Iniciar novo projeto no site do TanStack Start.
Instalar os Pacotes Intlayer
Instale os pacotes necessários usando o seu gerenciador de pacotes preferido:
bashCopiar códigoCopiar o código para a área de transferência
intlayer
O pacote principal que fornece ferramentas de internacionalização para gerenciamento de configuração, tradução, declaração de conteúdo, transpilação e comandos CLI.
solid-intlayer O pacote que integra o Intlayer com a aplicação Solid. Ele fornece provedores de contexto e hooks para a internacionalização em Solid.
vite-intlayer Inclui o plugin Vite para integrar o Intlayer com o bundler Vite, bem como o middleware para detectar a localidade preferida do usuário, gerenciar cookies e lidar com redirecionamento de URL.
Configuração do seu projeto
Crie um arquivo de configuração para configurar as línguas da sua aplicação:
intlayer.config.tsCopiar códigoCopiar o código para a área de transferência
Através deste arquivo de configuração, você pode configurar URLs localizadas, redirecionamento de middleware, nomes de cookies, a localização e extensão das suas declarações de conteúdo, desativar logs do Intlayer no console e muito mais. Para uma lista completa de parâmetros disponíveis, consulte a documentação de configuração.
Integrar o Intlayer na sua Configuração Vite
Adicione o plugin intlayer na sua configuração:
vite.config.tsCopiar códigoCopiar o código para a área de transferência
O plugin Vite
intlayer()é usado para integrar o Intlayer com o Vite. Ele garante a construção dos arquivos de declaração de conteúdo e os monitora no modo de desenvolvimento. Ele define as variáveis de ambiente do Intlayer dentro da aplicação Vite. Adicionalmente, ele fornece aliases para otimizar a performance.Criar o Layout Raiz
Configure o seu layout raiz para suportar internacionalização usando
useParamspara detectar a localidade atual e definindo os atributoslangedirna taghtml.src/routes/__root.tsxCopiar códigoCopiar o código para a área de transferência
Criar o Layout de Localidade
Crie um layout que lide com o prefixo de localidade e realize a validação. Este layout garantirá que apenas localidades válidas sejam processadas.
Este passo é opcional se você não precisar validar o prefixo de localidade ao nível da rota.
src/routes/{-$locale}/route.tsxCopiar códigoCopiar o código para a área de transferência
Aqui,
{-$locale}é um parâmetro de rota dinâmico que é substituído pela localidade atual. Esta notação torna o slot opcional, permitindo que funcione com modos de roteamento como'prefix-no-default'etc.Esteja ciente de que este slot pode causar problemas se você usar múltiplos segmentos dinâmicos na mesma rota (ex:
/{-$locale}/outro-caminho/$outroCaminhoDinamico/...). Para o modo'prefix-all', você pode preferir mudar o slot para$locale. Para o modo'no-prefix'ou'search-params', você pode remover o slot inteiramente.Declarar o Seu Conteúdo
Crie e gerencie as suas declarações de conteúdo para armazenar traduções:
src/contents/page.content.tsCopiar códigoCopiar o código para a área de transferência
As suas declarações de conteúdo podem ser definidas em qualquer lugar da sua aplicação, desde que sejam incluídas no diretório
contentDir(por padrão,./app). E correspondam à extensão do arquivo de declaração de conteúdo (por padrão,.content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).Para mais detalhes, consulte a documentação de declaração de conteúdo.
Utilizar Componentes e Hooks Cientes de Localidade
Crie um componente
LocalizedLinkpara navegação ciente de localidade:src/components/LocalizedLink.tsxCopiar códigoCopiar o código para a área de transferência
Este componente tem dois objetivos:
- Remover o prefixo desnecessário
{-$locale}da URL. - Injetar o parâmetro de localidade na URL para garantir que o usuário seja diretamente redirecionado para a rota localizada.
Depois, podemos criar um hook
useLocalizedNavigatepara navegação programática:src/hooks/useLocalizedNavigate.tsxCopiar códigoCopiar o código para a área de transferência
- Remover o prefixo desnecessário
Utilizar o Intlayer em Suas Páginas
Acesse seus dicionários de conteúdo através da sua aplicação:
Página Inicial Localizada
src/routes/{-$locale}/index.tsxCopiar códigoCopiar o código para a área de transferência
Se você quiser usar seu conteúdo em um atributo do tipo
string, comoalt,title,href,aria-label, etc., você deve chamar o valor da função, assim:htmlCopiar códigoCopiar o código para a área de transferência
No Solid,
useIntlayerretorna conteúdo reativo (por exemplo,content). Você pode acessar suas propriedades diretamente.Para aprender mais sobre o hook
useIntlayer, consulte a documentação.Criar um Componente Seletor de Localidade
Crie um componente para permitir que os usuários mudem de língua:
src/components/LocaleSwitcher.tsxCopiar códigoCopiar o código para a área de transferência
No Solid,
localedeuseLocaleé um signal accessor. Uselocale()(com parênteses) para ler o seu valor atual de forma reativa.Para aprender mais sobre o hook
useLocale, consulte la documentação.Gerenciamento de Atributos HTML
Como visto no Passo 5, você pode gerenciar os atributos
langedirda taghtmlusandouseParamsno seu componente raiz. Isso garante que os atributos corretos sejam definidos no servidor e no cliente.src/routes/__root.tsxCopiar códigoCopiar o código para a área de transferência
Adicionar Middleware
Você também pode usar o
intlayerProxypara adicionar roteamento do lado do servidor à sua aplicação. Este plugin detectará automaticamente a localidade atual baseada na URL e definirá o cookie de localidade apropriado. Se nenhuma localidade for especificada, o plugin determinará a localidade mais apropriada baseada nas preferências de língua do navegador do usuário. Se nenhuma localidade for detectada, ele redirecionará para a localidade padrão.Note que para usar o
intlayerProxyem produção, você precisa trocar o pacotevite-intlayerdedevDependenciesparadependencies.vite.config.tsCopiar códigoCopiar o código para a área de transferência
Internacionalizar Seus Metadados
Você também pode usar a função
getIntlayerpara acessar seus dicionários de conteúdo dentro do loaderheadpara metadados cientes de localidade:src/routes/{-$locale}/index.tsxCopiar códigoCopiar o código para a área de transferência
Recuperar a localidade nas suas server actions
Você pode querer acessar a localidade atual de dentro das suas server actions ou endpoints de API. Você pode fazer isso usando o helper
getLocaledointlayer.Aqui está um exemplo usando as server functions do TanStack Start:
src/routes/{-$locale}/index.tsxCopiar códigoCopiar o código para a área de transferência
Gerenciar páginas não encontradas
Quando um usuário visita uma página inexistente, você pode exibir uma página personalizada de não encontrado e o prefixo de localidade pode impactar a maneira como a página de não encontrado é disparada.
Entendendo o Processamento de 404 do TanStack Router com Prefixos de Localidade
No TanStack Router, processar páginas 404 com rotas localizadas requer uma abordagem multicamada:
- Rota de 404 dedicada: Uma rota específica para exibir a UI do 404
- Validação ao nível da rota: Valida os prefixos de localidade e redireciona os inválidos para o 404
- Rota catch-all: Captura quaisquer caminhos não correspondentes dentro do segmento de localidade
src/routes/{-$locale}/404.tsxCopiar códigoCopiar o código para a área de transferência
src/routes/{-$locale}/route.tsxCopiar códigoCopiar o código para a área de transferência
src/routes/{-$locale}/$.tsxCopiar códigoCopiar o código para a área de transferência
Extrair o conteúdo dos seus componentes
OpcionalSe você tem uma base de código existente, transformar milhares de arquivos pode ser demorado.
Para facilitar este processo, o Intlayer propõe um compilador / extrator para transformar os seus componentes e extrair o conteúdo.
Para configurá-lo, você pode adicionar uma seção
compilerno seu arquivointlayer.config.ts:intlayer.config.tsCopiar códigoCopiar o código para a área de transferência
import { type IntlayerConfig } from "intlayer"; const config: IntlayerConfig = { // ... Resto da sua configuração compiler: { /** * Indica se o compilador deve ser habilitado. */ enabled: true, /** * Define o caminho dos arquivos de saída */ output: ({ fileName, extension }) => `./${fileName}${extension}`, /** * Indica se os componentes devem ser salvos após serem transformados. * * - Se `true`, o compilador reescreverá o arquivo do componente no disco. Assim, a transformação será permanente, e o compilador pulará a transformação para o próximo processo. Dessa forma, o compilador pode transformar a aplicação e depois pode ser removido. * * - Se `false`, o compilador injetará a chamada de função `useIntlayer()` no código apenas no output da build, mantendo a base de código intacta. A transformação será feita apenas em memória. */ saveComponents: false, /** * Prefixo da chave do dicionário */ dictionaryKeyPrefix: "", }, }; export default config;Rode o extrator para transformar os seus componentes e extrair o conteúdo
bashCopiar códigoCopiar o código para a área de transferência
Gerar um Sitemap
O Intlayer vem com um gerador de sitemap integrado para ajudá-lo a criar facilmente um sitemap para sua aplicação. Ele cuida das rotas localizadas e adiciona os metadados necessários para os mecanismos de busca.
O sitemap gerado pelo Intlayer suporta o namespace
xhtml:link(Hreflang XML Extensions). Ao contrário dos geradores de sitemap padrão que apenas listam URLs brutos, o Intlayer cria automaticamente os links bidirecionais necessários entre todas as versões de idioma de uma página (por exemplo,/about,/about?lang=fre/about?lang=es). Isso garante que os mecanismos de busca indexem e sirvam corretamente a versão de idioma certa para o público certo.Para usá-lo, você primeiro precisa configurar o seu
vite.config.tspara habilitar a pré-renderização de suas rotas localizadas e desabilitar a geração de sitemap padrão do TanStack Start.vite.config.tsCopiar códigoCopiar o código para a área de transferência
Em seguida, crie uma rota
src/routes/sitemap[.]xml.tsque use a funçãogenerateSitemap:src/routes/sitemap[.]xml.tsCopiar códigoCopiar o código para a área de transferência
Configurar TypeScript
O Intlayer usa a ampliação de módulo para obter os benefícios do TypeScript e tornar a sua base de código mais forte.
Certifique-se de que a sua configuração do TypeScript inclua os tipos autogerados:
tsconfig.jsonCopiar códigoCopiar o código para a área de transferência
Configuração Git
É recomendado ignorar os arquivos gerados pelo Intlayer. Isso permite que você evite committá-los no seu repositório Git.
Para fazer isso, você pode adicionar as seguintes instruções ao seu arquivo .gitignore:
Copiar o código para a área de transferência
Extensão VS Code
Para melhorar a sua experiência de desenvolvimento com o Intlayer, você pode instalar a Extensão oficial do Intlayer VS Code.
Instalar a partir do VS Code Marketplace
Esta extensão oferece:
- Autocompletar para chaves de tradução.
- Detecção de erros em tempo real para traduções ausentes.
- Previsões inline de conteúdo traduzido.
- Ações rápidas para criar e atualizar traduções facilmente.
Para mais detalhes sobre como usar a extensão, consulte a documentação da Extensão Intlayer VS Code.
Ir Além
Para ir mais além, você pode implementar o editor visual ou externalizar o seu conteúdo usando o CMS.