Traduza seu React Router v7 com Intlayer | Internacionalização (i18n)

Este guia demonstra como integrar o Intlayer para uma internacionalização perfeita em projetos React Router v7 com roteamento sensível à localidade, suporte a TypeScript e práticas modernas de desenvolvimento.

Este guia se concentra no roteamento de frontend. Para roteamento fs-routes, consulte o guia Intlayer com React Router v7 File-System Routes.

Table of Contents

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:

Guia Passo a Passo para Configurar o Intlayer em uma Aplicação React Router v7

VideoCódigo (baseado em configuração)Código (rotas baseadas no sistema de arquivos)Demo (baseado em configuração)

www.youtube.com

Open embedded page in fullscreen

ide.intlayer.org

Open embedded page in fullscreen

ide.intlayer.org

Open embedded page in fullscreen

intlayer-react-router-v7.vercel.app

Open embedded page in fullscreen

See the Config-Based Routing Template or File-System Routes Template on GitHub.

1. 1

   Instalar Dependências

   Instale os pacotes necessários usando seu gerenciador de pacotes preferido:

   bash

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   npx intlayer init --interactive
   

   a flag --interactive é opcional. Use intlayer-cli init se você for um agente de IA.

   Este comando detectará seu ambiente e instalará os pacotes necessários. Por exemplo:

   bash

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   npm install intlayer react-intlayer
   npm install vite-intlayer --save-dev
   

   • intlayer

     O pacote principal que fornece ferramentas de internacionalização para gerenciamento de configuração, tradução, declaração de conteúdo, transpiração e comandos CLI.

   • react-intlayer O pacote que integra o Intlayer com a aplicação React. Ele fornece provedores de contexto e hooks para internacionalização em React.

   • vite-intlayer Inclui o plugin do Vite para integrar o Intlayer com o empacotador Vite, bem como middleware para detectar a localidade preferida do usuário, gerenciar cookies e lidar com redirecionamento de URL.

2. 2

   Configuração do seu projeto

   Crie um arquivo de configuração para configurar os idiomas da sua aplicação:

   intlayer.config.ts

   Copiar conteúdo

   Copiar código

   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.TURKISH],
     },
     middleware: {
       prefixDefault: true, // Sempre prefixar o idioma padrão nas URLs
     },
   };
   
   export default config;
   

   Através deste arquivo de configuração, você pode configurar URLs localizadas, redirecionamento via middleware, nomes de cookies, a localização e extensão das suas declarações de conteúdo, desabilitar logs do Intlayer no console, e muito mais. Para uma lista completa dos parâmetros disponíveis, consulte a documentação de configuração.

3. 3

   Integrar Intlayer na sua Configuração Vite

   Adicione o plugin intlayer na sua configuração:

   vite.config.ts

   Copiar conteúdo

   Copiar código

   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 Intlayer com Vite. Ele garante a construção de arquivos de declaração de conteúdo e os monitora em modo de desenvolvimento. Define variáveis de ambiente do Intlayer dentro da aplicação Vite. Além disso, fornece aliases para otimizar o desempenho.

4. 4

   Configurar Rotas do React Router v7

   Config-based routingFile-system routes

   Configure sua configuração de rotas com rotas que reconhecem o idioma:

   app/routes.ts

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   import { layout, route, type RouteConfig } from "@react-router/dev/routes";
   
   export default [
     route("/:locale?", "routes/page.tsx"), // Página inicial localizada
     route("/:locale?/about", "routes/about/page.tsx"), // Página sobre localizada
   ] satisfies RouteConfig;
   

   Set up your routing configuration to use file-system based routes with flatRoutes:

   app/routes.ts

   Copiar conteúdo

   Copiar código

   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({
     // Ignore content declaration files from being treated as routes
     ignoredRouteFiles: configuration.content.fileExtensions.map(
       (fileExtension) => `**/*${fileExtension}`
     ),
   });
   
   export default routes;
   

   The flatRoutes function from @react-router/fs-routes enables file-system based routing, where the file structure in the routes/ directory determines your application's routes. The ignoredRouteFiles option ensures that Intlayer content declaration files (.content.ts, etc.) are not treated as route files.

5. 5

   Criar Componentes de Layout

   Configure seu layout raiz e layouts específicos para cada localidade:

   Layout Raiz

   app/root.tsx

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   import { getLocaleFromPath } from "intlayer";
   import { IntlayerProvider } from "react-intlayer";
   import {
     data,
     Meta,
     Scripts,
     ScrollRestoration,
     useLoaderData,
   } from "react-router";
   import type { Route } from "./+types/root";
   
   // ... Unchanged App, links and ErrorBoundary code
   
   export async function loader({ request }: Route.LoaderArgs) {
     const locale = getLocaleFromPath(request.url);
   
     if (!locale) {
       throw data("Language not supported", { status: 404 });
     }
   
     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>
     );
   }
   

6. 6

   Declare Seu Conteúdo

   Crie e gerencie suas declarações de conteúdo para armazenar traduções:

   app/routes/[lang]/page.content.ts

   Copiar conteúdo

   Copiar código

   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",
         tr: "React Router v7 + Intlayer'a Hoş Geldiniz",
       }),
       description: t({
         en: "Build multilingual applications with ease using React Router v7 and Intlayer.",
         tr: "React Router v7 e Intlayer para construir aplicações multilíngues com facilidade.",
       }),
       aboutLink: t({
         en: "Saiba Mais Sobre Nós",
         tr: "Hakkımızda Öğrenin",
       }),
       homeLink: t({
         en: "Início",
         tr: "Ana Sayfa",
       }),
     },
   } satisfies Dictionary;
   
   export default pageContent;
   

   Suas declarações de conteúdo podem ser definidas em qualquer lugar da sua aplicação, desde que estejam 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}).

   Could be placed in app/routes/($locale)._index.content.ts in case of using file-system based routing.

   Para mais detalhes, consulte a documentação de declaração de conteúdo.

7. 7

   Crie Componentes Sensíveis ao Locale

   Crie um componente LocalizedLink para navegação sensível ao idioma:

   app/components/localized-link.tsx

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   // app/components/localized-link.tsx
   import { getLocalizedUrl } from "intlayer";
   import { useLocale } from "react-intlayer";
   import React from "react";
   import { Link, useLocation } from "react-router";
   
   type RouterLinkProps = React.ComponentProps<typeof Link>;
   
   export default function LocalizedLink({ to, ...props }: RouterLinkProps) {
     const { locale } = useLocale();
     const location = useLocation();
   
     const isExternal = (path: string) =>
       /^([a-z][a-z0-9+.-]*:)?\/\//i.test(path) || path.startsWith("mailto:");
   
     if (typeof to === "string") {
       if (to.startsWith("/") && !isExternal(to)) {
         return <Link to={getLocalizedUrl(to, locale)} {...props} />;
       }
       return <Link to={to} {...props} />;
     }
   
     if (to && typeof to === "object") {
       const pathname = (to as { pathname?: string }).pathname;
       if (pathname && pathname.startsWith("/") && !isExternal(pathname)) {
         return (
           <Link
             to={{ ...to, pathname: getLocalizedUrl(pathname, locale) }}
             {...props}
           />
         );
       }
       return <Link to={to} {...props} />;
     }
   
     return (
       <Link
         to={getLocalizedUrl(location.pathname + location.search, locale)}
         {...props}
       />
     );
   }
   

   No caso de querer navegar para as rotas localizadas, você pode usar o hook useLocalizedNavigate:

   app/hooks/useLocalizedNavigate.ts

   Copiar conteúdo

   Copiar código

   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;
   };
   

8. 8

   Utilize o Intlayer nas Suas Páginas

   Acesse seus dicionários de conteúdo em toda a sua aplicação:

   Página Inicial Localizada

   Config-based routingFile-system routes

   app/routes/page.tsx

   Copiar conteúdo

   Copiar código

   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/page";
   
   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>
     );
   }
   

   app/routes/($locale)._index.tsx

   Copiar conteúdo

   Copiar código

   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>
     );
   }
   

   Para saber mais sobre o hook useIntlayer, consulte a documentação.

   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.

9. 9

   Crie um Componente de Seletor de Idioma

   Crie um componente para permitir que os usuários mudem de idioma:

   Config-based routingFile-system routes

   app/components/locale-switcher.tsx

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   import { getLocalizedUrl, getLocaleName } from "intlayer";
   import { useLocale } from "react-intlayer";
   import { useLocation, useNavigate } from "react-router";
   
   export default function LocaleSwitcher() {
     const { locale, availableLocales, setLocale } = useLocale();
     const location = useLocation();
     const navigate = useNavigate();
   
     const handleLocaleChange = (newLocale: string) => {
       const localizedUrl = getLocalizedUrl(
         location.pathname + location.search,
         newLocale
       );
       setLocale(newLocale);
       navigate(localizedUrl);
     };
   
     return (
       <div style={{ margin: "1rem 0" }}>
         <label htmlFor="locale-select">Escolha o idioma: </label>
         <select
           id="locale-select"
           value={locale}
           onChange={(e) => handleLocaleChange(e.target.value)}
           style={{ padding: "0.25rem", marginLeft: "0.5rem" }}
         >
           {availableLocales.map((availableLocale) => (
             <option key={availableLocale} value={availableLocale}>
               {getLocaleName(availableLocale)}
             </option>
           ))}
         </select>
       </div>
     );
   }
   

   app/components/locale-switcher.tsx

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   import type { FC } from "react";
   
   import {
     getHTMLTextDir,
     getLocaleName,
     getLocalizedUrl,
     getPathWithoutLocale,
     defaultLocale,
   } 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, setLocale } = 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)}`}
               onClick={() => setLocale(localeItem)}
               reloadDocument // Reload the page to apply the new locale
               to={getLocalizedUrl(pathWithoutLocale, localeItem)}
             >
               <span>
                 {/* Locale - e.g. FR */}
                 {localeItem}
               </span>
               <span>
                 {/* Language in its own Locale - e.g. Français */}
                 {getLocaleName(localeItem, locale)}
               </span>
               <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
                 {/* Language in current Locale - e.g. Francés with current locale set to Locales.SPANISH */}
                 {getLocaleName(localeItem)}
               </span>
               <span dir="ltr" lang={defaultLocale}>
                 {/* Language in English - e.g. French */}
                 {getLocaleName(localeItem, defaultLocale)}
               </span>
             </Link>
           </li>
         ))}
       </ol>
     );
   };
   

   Para saber mais sobre o hook useLocale, consulte a documentação.

10. 10

    Adicionar Gerenciamento de Atributos HTML

    Crie um hook para gerenciar os atributos lang e dir do HTML:

    app/hooks/useI18nHTMLAttributes.tsx

    Copiar conteúdo

    Copiar código

    Copiar o código para a área de transferência

    // app/hooks/useI18nHTMLAttributes.tsx
    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]);
    };
    

    Então use-o no seu componente raiz:

    app/root.tsx

    Copiar conteúdo

    Copiar código

    Copiar o código para a área de transferência

    // app/routes/layout.tsx
    import { Outlet } from "react-router";
    import { IntlayerProvider } from "react-intlayer";
    
    import { useI18nHTMLAttributes } from "app/hooks/useI18nHTMLAttributes"; // importa o hook
    
    export default function RootLayout() {
      useI18nHTMLAttributes(); // chama o hook
    
      return (
        <IntlayerProvider>
          <Outlet />
        </IntlayerProvider>
      );
    }
    

11. 11

    Compile e Execute Sua Aplicação

12. 12

    Configurar TypeScript

    O Intlayer utiliza a ampliação de módulos para aproveitar os benefícios do TypeScript e tornar sua base de código mais robusta.

    Certifique-se de que sua configuração do TypeScript inclua os tipos gerados automaticamente:

    tsconfig.json

    Copiar conteúdo

    Copiar código

    Copiar o código para a área de transferência

    {
      compilerOptions: {
        // ... suas configurações existentes do TypeScript
      },
      include: [
        // ... seus includes existentes
        ".intlayer/**/*.ts", // Incluir os tipos gerados automaticamente
      ],
    }
    

13. 12

    Extrair o conteúdo dos seus componentes

    Opcional

    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:

    intlayer.config.ts

    Copiar conteúdo

    Copiar código

    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;
    

    Comando de extraçãoCompilador Babel

    Execute o extrator para transformar seus componentes e extrair o conteúdo

    bash

    Copiar conteúdo

    Copiar código

    Copiar o código para a área de transferência

    npx intlayer extract
    

    Since v9, the intlayerCompiler is included in the intlayer plugin. So you don't need to add it manually.

    Atualize seu vite.config.ts para incluir o plugin intlayerCompiler:

    vite.config.ts

    Copiar conteúdo

    Copiar código

    Copiar o código para a área de transferência

    import { defineConfig } from "vite";
    import { intlayer, intlayerCompiler } from "vite-intlayer";
    
    export default defineConfig({
      plugins: [
        intlayer(),
        intlayerCompiler(), // Adds the compiler plugin
      ],
    });
    

    bash

    Copiar conteúdo

    Copiar código

    Copiar o código para a área de transferência

    npm run build # Ou npm run dev
    

Configure TypeScript

Intlayer uses module augmentation to get benefits of TypeScript and make your codebase stronger.

Ensure your TypeScript configuration includes the autogenerated types:

{
  // ... your existing configurations
  include: [
    // ... your existing includes
    ".intlayer/**/*.ts", // Include the auto-generated types
  ],
}

Configuração do Git

Recomenda-se ignorar os arquivos gerados pelo Intlayer. Isso permite evitar comitá-los no seu repositório Git.

Para fazer isso, adicione as seguintes instruções ao seu arquivo .gitignore:

# Ignorar os arquivos gerados pelo Intlayer
.intlayer

Extensão do VS Code

Para melhorar sua experiência de desenvolvimento com o Intlayer, você pode instalar a extensão oficial do Intlayer para VS Code.

Instalar no VS Code Marketplace

Esta extensão oferece:

• Autocompletar para chaves de tradução.
• Detecção de erros em tempo real para traduções ausentes.
• Visualizações inline de conteúdo traduzido.
• Ações rápidas para criar e atualizar traduções facilmente.

Para mais detalhes sobre o uso da extensão, consulte a documentação da Extensão do VS Code.

Ir Além

Para ir mais longe, você pode implementar o editor visual ou externalizar seu conteúdo usando o CMS.

Referências de Documentação

• Documentação do Intlayer
• Documentação do React Router v7
• Hook useIntlayer
• Hook useLocale
• Declaração de Conteúdo
• Configuração

Este guia abrangente fornece tudo o que você precisa para integrar o Intlayer com o React Router v7 para uma aplicação totalmente internacionalizada com roteamento ciente de locale e suporte completo a TypeScript.

Perguntas Frequentes