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
- "Adicionar comando init"v7.5.930/12/2025
- "Histórico inicial"v7.3.408/12/2025
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 React Router v7 (File-System Routes) usando Intlayer | Internacionalização (i18n)
Este guia demonstra como integrar o Intlayer para internacionalização perfeita em projetos React Router v7 usando roteamento baseado em sistema de arquivos (@react-router/fs-routes) com roteamento consciente de localidade, suporte a TypeScript e práticas modernas de desenvolvimento.
Para roteamento do lado do cliente, consulte o guia Intlayer com React Router v7.
Índice
O que é o Intlayer?
Intlayer é uma biblioteca de internacionalização (i18n) inovadora e de código aberto projetada para simplificar o suporte multilíngue em aplicações web modernas.
Com o Intlayer, você pode:
- Gerenciar traduções facilmente usando dicionários declarativos no nível do componente.
- Localizar dinamicamente metadados, rotas e conteúdo.
- Garantir suporte ao TypeScript com tipos autogerados, melhorando o preenchimento automático e a detecção de erros.
- Aproveitar recursos avançados, como detecção dinâmica de localidade e alternância de idioma.
- Habilitar roteamento consciente de localidade com o sistema de roteamento baseado em sistema de arquivos do React Router v7.
Guia Passo a Passo para Configurar o Intlayer em uma Aplicação React Router v7 com File-System Routes
Veja o Application Template no GitHub.
Passo 1: Instalar Dependências
Instale os pacotes necessários usando seu gerenciador de pacotes preferido:
Copiar o código para a área de transferência
npm install intlayer react-intlayernpm install vite-intlayer --save-devnpm install @react-router/fs-routes --save-devnpx intlayer initintlayer
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.
react-intlayer O pacote que integra o Intlayer com aplicações React. Fornece providers de contexto e hooks para internacionalização em React.
vite-intlayer Inclui o plugin Vite para integrar o Intlayer com o Vite bundler, bem como middleware para detectar a localidade preferida do usuário, gerenciar cookies e lidar com redirecionamento de URL.
@react-router/fs-routes O pacote que habilita roteamento baseado em sistema de arquivos para React Router v7.
Passo 2: Configuração do seu projeto
Crie um arquivo de configuração para configurar os idiomas da sua aplicação:
Copiar o código para a área de transferência
import { type IntlayerConfig, Locales } from "intlayer";
const config: IntlayerConfig = {
internationalization: {
defaultLocale: Locales.ENGLISH,
locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
},
};
export default config;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, desabilitar os logs do Intlayer no console e mais. Para uma lista completa dos parâmetros disponíveis, consulte a documentação de configuração.
Passo 3: Integrar o Intlayer na sua Configuração do Vite
Adicione o plugin intlayer na sua configuração:
Copiar o código para a área de transferência
import { reactRouter } from "@react-router/dev/vite";import { defineConfig } from "vite";import { intlayer } from "vite-intlayer";export default defineConfig({ plugins: [reactRouter(), intlayer()],});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 em modo de desenvolvimento. Ele define variáveis de ambiente do Intlayer dentro da aplicação Vite. Além disso, fornece aliases para otimizar o desempenho.
Passo 4: Configurar Rotas File-System do React Router v7
Configure sua configuração de rotas para usar rotas baseadas em sistema de arquivos com flatRoutes:
Copiar o código para a área de transferência
import type { RouteConfig } from "@react-router/dev/routes";import { flatRoutes } from "@react-router/fs-routes";import { configuration } from "intlayer";const routes: RouteConfig = flatRoutes({ // Ignorar arquivos de declaração de conteúdo para não serem tratados como rotas ignoredRouteFiles: configuration.content.fileExtensions.map( (fileExtension) => `**/*${fileExtension}` ),});export default routes;A funçãoflatRoutesdo@react-router/fs-routeshabilita roteamento baseado em sistema de arquivos, onde a estrutura de arquivos no diretórioroutes/determina as rotas da sua aplicação. A opçãoignoredRouteFilesgarante que os arquivos de declaração de conteúdo do Intlayer (.content.ts, etc.) não sejam tratados como arquivos de rota.
Passo 5: Criar Arquivos de Rota com Convenções File-System
Com roteamento baseado em sistema de arquivos, você usa uma convenção de nomenclatura plana onde pontos (.) representam segmentos de caminho e parênteses () denotam segmentos opcionais.
Crie os seguintes arquivos no seu diretório app/routes/:
Estrutura de Arquivos
Copiar o código para a área de transferência
app/├── root.tsx # Wrapper de layout para rotas de locale└──routes/ ├── ($locale)._index.tsx # Página inicial (/, /es, etc.) ├── ($locale)._index.content.ts # Conteúdo da página inicial ├── ($locale).about.tsx # Página About (/about, /es/about, etc.) └── ($locale).about.content.ts # Conteúdo da página AboutAs convenções de nomenclatura:
($locale)- Segmento dinâmico opcional para o parâmetro locale_layout- Rota de layout que envolve as rotas filhas_index- Rota index (renderiza no caminho pai).(ponto) - Separa segmentos de caminho (ex.:($locale).about→/:locale?/about)
Componente de Layout
Copiar o código para a área de transferência
import { getLocaleFromPath } from "intlayer";import { IntlayerProvider } from "react-intlayer";import { isRouteErrorResponse, Meta, Outlet, Scripts, ScrollRestoration, useLoaderData,} from "react-router";import type { Route } from "./+types/root";import "./app.css";// links and ErrorBoundary codeexport async function loader({ request }: Route.LoaderArgs) { const locale = getLocaleFromPath(request.url); return { locale };}export function Layout({ children,}: { children: React.ReactNode } & Route.ComponentProps) { const data = useLoaderData<typeof loader>(); const { locale } = data ?? {}; return ( <html lang={locale}> <head> <meta charSet="utf-8" /> <meta content="width=device-width, initial-scale=1" name="viewport" /> <Meta /> <Links /> </head> <body> <IntlayerProvider locale={locale}>{children}</IntlayerProvider> <ScrollRestoration /> <Scripts /> </body> </html> );}Página Index
Copiar o código para a área de transferência
import { getIntlayer, validatePrefix } from "intlayer";import { useIntlayer } from "react-intlayer";import { data } from "react-router";import { LocaleSwitcher } from "~/components/locale-switcher";import { Navbar } from "~/components/navbar";import type { Route } from "./+types/($locale)._index";export const loader = ({ params }: Route.LoaderArgs) => { const { locale } = params; const { isValid } = validatePrefix(locale); if (!isValid) { throw data("Locale not supported", { status: 404 }); }};export const meta: Route.MetaFunction = ({ params }) => { const content = getIntlayer("page", params.locale); return [ { title: content.title }, { content: content.description, name: "description" }, ];};export default function Page() { const { title, description, aboutLink } = useIntlayer("page"); return ( <div> <h1>{title}</h1> <p>{description}</p> <nav> <LocalizedLink to="/about">{aboutLink}</LocalizedLink> </nav> </div> );}Página About
Copiar o código para a área de transferência
import { getIntlayer, validatePrefix } from "intlayer";import { useIntlayer } from "react-intlayer";import { data } from "react-router";import { LocaleSwitcher } from "~/components/locale-switcher";import { Navbar } from "~/components/navbar";import type { Route } from "./+types/($locale).about";export const loader = ({ params }: Route.LoaderArgs) => { const { locale } = params; const { isValid } = validatePrefix(locale); if (!isValid) { throw data("Locale not supported", { status: 404 }); }};export const meta: Route.MetaFunction = ({ params }) => { const content = getIntlayer("about", params.locale); return [ { title: content.title }, { content: content.description, name: "description" }, ];};export default function AboutPage() { const { title, content, homeLink } = useIntlayer("about"); return ( <div> <h1>{title}</h1> <p>{content}</p> );}Se a sua aplicação já existe, você pode usar o Intlayer Compiler em conjunto com o comando extract para converter milhares de componentes em um segundo.
Passo 6: Declarar seu Conteúdo
Crie e gerencie suas declarações de conteúdo para armazenar traduções. Coloque os arquivos de conteúdo ao lado dos seus arquivos de rota:
Copiar o código para a área de transferência
import { t, type Dictionary } from "intlayer";const pageContent = { key: "page", content: { title: t({ en: "Welcome to React Router v7 + Intlayer", es: "Bienvenido a React Router v7 + Intlayer", fr: "Bienvenue sur React Router v7 + Intlayer", }), description: t({ en: "Build multilingual applications with ease using React Router v7 and Intlayer.", es: "Cree aplicaciones multilingües fácilmente usando React Router v7 y Intlayer.", fr: "Créez des applications multilingues facilement avec React Router v7 et Intlayer.", }), aboutLink: t({ en: "Learn About Us", es: "Aprender Sobre Nosotros", fr: "En savoir plus sur nous", }), },} satisfies Dictionary;export default pageContent;Copiar o código para a área de transferência
import { t, type Dictionary } from "intlayer";const aboutContent = { key: "about", content: { title: t({ en: "About Us", es: "Sobre Nosotros", fr: "À propos de nous", }), content: t({ en: "This is the about page content.", es: "Este es el contenido de la página de información.", fr: "Ceci est le contenu de la page à propos.", }), homeLink: t({ en: "Home", es: "Inicio", fr: "Accueil", }), },} satisfies Dictionary;export default aboutContent;Suas declarações de conteúdo podem ser definidas em qualquer lugar da sua aplicação, desde que sejam incluídas no diretóriocontentDir(por padrão,./app). E correspondam à extensão de arquivo de declaração de conteúdo (por padrão,.content.{json,ts,tsx,js,jsx,mjs,cjs}).
Para mais detalhes, consulte a documentação de declaração de conteúdo.
Passo 7: Criar Componentes Locale-Aware
Crie um componente LocalizedLink para navegação consciente de localidade:
Copiar o código para a área de transferência
import type { FC } from "react";import { getLocalizedUrl, type LocalesValues } from "intlayer";import { useLocale } from "react-intlayer";import { Link, type LinkProps, type To } from "react-router";const isExternalLink = (to: string) => /^(https?:)?\/\//.test(to);export const locacalizeTo = (to: To, locale: LocalesValues): To => { if (typeof to === "string") { if (isExternalLink(to)) { return to; } return getLocalizedUrl(to, locale); } if (isExternalLink(to.pathname ?? "")) { return to; } return { ...to, pathname: getLocalizedUrl(to.pathname ?? "", locale), };};export const LocalizedLink: FC<LinkProps> = (props) => { const { locale } = useLocale(); return <Link {...props} to={locacalizeTo(props.to, locale)} />;};No caso de você querer navegar para as rotas localizadas, você pode usar o hook useLocalizedNavigate:
Copiar o código para a área de transferência
import { useLocale } from "react-intlayer";import { type NavigateOptions, type To, useNavigate } from "react-router";import { locacalizeTo } from "~/components/localized-link";export const useLocalizedNavigate = () => { const navigate = useNavigate(); const { locale } = useLocale(); const localizedNavigate = (to: To, options?: NavigateOptions) => { const localedTo = locacalizeTo(to, locale); navigate(localedTo, options); }; return localizedNavigate;};Passo 8: Criar um Componente de Alternância de Locale
Crie um componente para permitir que os usuários alterem idiomas:
Copiar o código para a área de transferência
import type { FC } from "react";import { getHTMLTextDir, getLocaleName, getLocalizedUrl, getPathWithoutLocale, Locales,} from "intlayer";import { useIntlayer, useLocale } from "react-intlayer";import { Link, useLocation } from "react-router";export const LocaleSwitcher: FC = () => { const { localeSwitcherLabel } = useIntlayer("locale-switcher"); const { pathname } = useLocation(); const { availableLocales, locale } = useLocale(); const pathWithoutLocale = getPathWithoutLocale(pathname); return ( <ol> {availableLocales.map((localeItem) => ( <li key={localeItem}> <Link aria-current={localeItem === locale ? "page" : undefined} aria-label={`${localeSwitcherLabel.value} ${getLocaleName(localeItem)}`} reloadDocument // Recarregar a página para aplicar o novo locale to={getLocalizedUrl(pathWithoutLocale, localeItem)} > <span> {/* Locale - ex.: FR */} {localeItem} </span> <span> {/* Idioma na sua própria Locale - ex.: Français */} {getLocaleName(localeItem, locale)} </span> <span dir={getHTMLTextDir(localeItem)} lang={localeItem}> {/* Idioma na Locale atual - ex.: Francés com a locale atual definida como Locales.SPANISH */} {getLocaleName(localeItem)} </span> <span dir="ltr" lang={Locales.ENGLISH}> {/* Idioma em inglês - ex.: French */} {getLocaleName(localeItem, Locales.ENGLISH)} </span> </Link> </li> ))} </ol> );};Para saber mais sobre o hook useLocale, consulte a documentação.
Passo 9: Adicionar Gerenciamento de Atributos HTML (Opcional)
Crie um hook para gerenciar os atributos HTML lang e dir:
Copiar o código para a área de transferência
import { getHTMLTextDir } from "intlayer";import { useEffect } from "react";import { useLocale } from "react-intlayer";export const useI18nHTMLAttributes = () => { const { locale } = useLocale(); useEffect(() => { document.documentElement.lang = locale; document.documentElement.dir = getHTMLTextDir(locale); }, [locale]);};Este hook já é usado no componente de layout (root.tsx) mostrado no Passo 5.
(Opcional) Etapa 1 : Extrair o conteúdo dos seus componentes
Se você tiver uma base de código existente, transformar milhares de arquivos pode ser demorado.
Para facilitar esse processo, o Intlayer propõe um compilador / extrator para transformar seus componentes e extrair o conteúdo.
Para configurá-lo, você pode adicionar uma seção compiler no seu arquivo intlayer.config.ts:
Copiar 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 ativado.
*/
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. Dessa forma, o compilador pode ser executado apenas uma vez para transformar o aplicativo e depois removido.
*/
saveComponents: false,
/**
* Prefixo da chave do dicionário
*/
dictionaryKeyPrefix: "",
},
};
export default config;Execute o extrator para transformar seus componentes e extrair o conteúdo
Copiar o código para a área de transferência
npx intlayer extractConfigure TypeScript
Intlayer uses module augmentation to get benefits of TypeScript and make your codebase stronger.
Ensure your TypeScript configuration includes the autogenerated types:
Copiar o código para a área de transferência
{ // ... your existing configurations include: [ // ... your existing includes ".intlayer/**/*.ts", // Include the auto-generated types ],}Git Configuration
It is recommended to ignore the files generated by Intlayer. This allows you to avoid committing them to your Git repository.
To do this, you can add the following instructions to your .gitignore file:
Copiar o código para a área de transferência
# Ignore the files generated by Intlayer.intlayerVS Code Extension
To improve your development experience with Intlayer, you can install the official Intlayer VS Code Extension.
Install from the VS Code Marketplace
This extension provides:
- Autocompletion for translation keys.
- Real-time error detection for missing translations.
- Inline previews of translated content.
- Quick actions to easily create and update translations.
For more details on how to use the extension, refer to the Intlayer VS Code Extension documentation.
Go Further
To go further, you can implement the visual editor or externalize your content using the CMS.
Documentation References
- Intlayer Documentation
- React Router v7 Documentation
- React Router fs-routes Documentation
- useIntlayer hook
- useLocale hook
- Content Declaration
- Configuration
This comprehensive guide provides everything you need to integrate Intlayer with React Router v7 using file-system based routing for a fully internationalized application with locale-aware routing and TypeScript support.
Passo 10: Adicionar middleware (Opcional)
Você também pode usar o intlayerProxy para adicionar roteamento do lado do servidor à sua aplicação. Este plugin detectará automaticamente a localidade atual com base na URL e definirá o cookie de localidade apropriado. Se nenhuma localidade for especificada, o plugin determinará a localidade mais adequada com base nas preferências de idioma do navegador do usuário. Se nenhuma localidade for detectada, ele redirecionará para a localidade padrão.
Note que para usar ointlayerProxyem produção, você precisa mover o pacotevite-intlayerdedevDependenciesparadependencies.
Copiar o código para a área de transferência
import { reactRouter } from "@react-router/dev/vite";import { defineConfig } from "vite";import { intlayer, intlayerProxy } from "vite-intlayer";export default defineConfig({ plugins: [ intlayerProxy(), // should be placed first reactRouter(), intlayer(), ],});Configurar TypeScript
O Intlayer usa module augmentation para aproveitar os benefícios do TypeScript e tornar sua codebase mais robusta.
Certifique-se de que sua configuração do TypeScript inclui os tipos autogerados:
Copiar o código para a área de transferência
{ // ... suas configurações existentes include: [ // ... seus includes existentes ".intlayer/**/*.ts", // Incluir os tipos autogerados ],}Configuração do Git
É recomendado ignorar os arquivos gerados pelo Intlayer. Isso permite que você evite commitá-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
# Ignorar os arquivos gerados pelo Intlayer.intlayerExtensão do VS Code
Para melhorar sua experiência de desenvolvimento com o Intlayer, você pode instalar a extensão oficial Intlayer VS Code Extension.
Instalar no VS Code Marketplace
Esta extensão fornece:
- Autocompletar para chaves de tradução.
- Detecção de erros em tempo real para traduções faltando.
- Pré-visualizações inline do 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 além, você pode implementar o editor visual ou externalizar seu conteúdo usando o CMS.
Referências da Documentação
- Documentação do Intlayer
- Documentação do React Router v7
- Documentação do React Router fs-routes
- Hook useIntlayer
- Hook useLocale
- Declaração de Conteúdo
- Configuração
Este guia completo fornece tudo o que você precisa para integrar o Intlayer com o React Router v7 usando roteamento baseado em sistema de arquivos para uma aplicação totalmente internacionalizada com roteamento consciente de localidade e suporte a TypeScript.