Traduza seu Tanstack Start com Intlayer | Internacionalização (i18n)

Índice

Este guia demonstra como integrar o Intlayer para uma internacionalização perfeita em projetos Tanstack Start com roteamento sensível ao locale, suporte a TypeScript e práticas modernas de desenvolvimento.

Por que Intlayer em vez de alternativas?

Comparado com soluções principais como react-i18next ou use-intl, ou paraglide, Intlayer é uma solução que vem com otimizações integradas como:

Guia Passo a Passo para Configurar o Intlayer em uma Aplicação Tanstack Start

Veja o Template de aplicação no GitHub.

1. 1

   Criar o Projeto

   Comece criando um novo projeto TanStack Start seguindo o guia Iniciar novo projeto no site do TanStack Start.

2. 2

   Instalar os Pacotes do Intlayer

   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 aplicações React. Ele fornece provedores de contexto e hooks para internacionalização em React.

   • vite-intlayer Inclui o plugin Vite para integrar o Intlayer com o empacotador Vite, assim como middleware para detectar o locale preferido do usuário, gerenciar cookies e lidar com redirecionamento de URLs.

3. 3

   Configuração do seu projeto

   Arquitetura

   Nesta arquitetura, todas as rotas localizadas são aninhadas sob o segmento de rota {-$locale}. Essa abordagem garante que cada idioma tenha um URL dedicado, ao mesmo tempo que permite prefixação automática de localidade, validação e otimização de SEO.

   bash

   Copiar conteúdo

   Copiar código

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

   .
   ├── src
   │   ├── components
   │   │   ├── Header.tsx
   │   │   ├── locale-switcher.content.ts
   │   │   ├── locale-switcher.tsx
   │   │   └── localized-link.tsx
   │   ├── hooks
   │   │   ├── useI18nHTMLAttributes.tsx
   │   │   └── useLocalizedNavigate.ts
   │   ├── routes
   │   │   ├── {-$locale}
   │   │   │   ├── 404.content.ts
   │   │   │   ├── 404.tsx
   │   │   │   ├── about.content.ts
   │   │   │   ├── about.tsx
   │   │   │   ├── index.content.tsx
   │   │   │   ├── index.tsx
   │   │   │   └── route.tsx             # Locale layout & prefix validation
   │   │   ├── __root.tsx                # Root route with IntlayerProvider
   │   │   └── sitemap[.]xml.ts
   │   ├── router.tsx
   │   └── styles.css
   ├── intlayer.config.ts
   ├── package.json
   ├── tsconfig.json
   └── vite.config.ts
   

   Configuração

   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 } from "intlayer";
   
   import { 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 logs do Intlayer no console, e muito mais. Para uma lista completa dos parâmetros disponíveis, consulte a documentação de configuração.

4. 4

   Integre o Intlayer na sua Configuração do 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 { tanstackStart } from "@tanstack/react-start/plugin/vite";
   import viteReact from "@vitejs/plugin-react";
   import { nitro } from "nitro/vite";
   import { defineConfig } from "vite";
   import { intlayer } from "vite-intlayer";
   
   const config = defineConfig({
     plugins: [
       nitro(),
       intlayer({
         proxy: {
           ignore: (req) => req.url?.startsWith("/api"),
         },
       }),
       tanstackStart({
         router: {
           routeFileIgnorePattern:
             ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5|md|mdx|yaml|yml)$",
         },
       }),
       viteReact(),
     ],
   });
   
   export default config;
   

   O plugin intlayer() para Vite é 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. Define as variáveis de ambiente do Intlayer dentro da aplicação Vite. Além disso, fornece aliases para otimizar o desempenho.

5. 5

   Criar Layout Raiz

   Configure seu layout raiz para suportar internacionalização usando useParams para detectar o locale atual e configurando os atributos lang e dir na tag html.

   src/routes/__root.tsx

   Copiar conteúdo

   Copiar código

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

   import {
     createRootRouteWithContext,
     getRouteApi,
     HeadContent,
     Scripts,
   } from "@tanstack/react-router";
   import { defaultLocale, getHTMLTextDir } from "intlayer";
   import { type ReactNode } from "react";
   import { IntlayerProvider } from "react-intlayer";
   
   const localeRoute = getRouteApi("/{-$locale}");
   
   export const Route = createRootRouteWithContext<{}>()({
     head: () => ({
       meta: [
         {
           charSet: "utf-8",
         },
         {
           content: "width=device-width, initial-scale=1",
           name: "viewport",
         },
         {
           title: "TanStack Start Starter",
         },
       ],
     }),
   
     shellComponent: RootDocument,
   });
   
   function RootDocument({ children }: { children: ReactNode }) {
     const params = localeRoute.useParams();
     const locale = params?.locale ?? defaultLocale;
   
     return (
       <html dir={getHTMLTextDir(locale)} lang={locale}>
         <head>
           <HeadContent />
         </head>
         <body>
           <IntlayerProvider locale={locale}>{children}</IntlayerProvider>
           <Scripts />
         </body>
       </html>
     );
   }
   

6. 6

   Criar Layout de Localidade

   Crie um layout que lide com o prefixo de locale e realize a validação.

   src/routes/{-$locale}/route.tsx

   Copiar conteúdo

   Copiar código

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

   import { createFileRoute, Outlet, redirect } from "@tanstack/react-router";
   import { validatePrefix } from "intlayer";
   
   export const Route = createFileRoute("/{-$locale}")({
     beforeLoad: ({ params }) => {
       const localeParam = params.locale;
   
       // Validar o prefixo de locale
       const { isValid, localePrefix } = validatePrefix(localeParam);
   
       if (!isValid) {
         throw redirect({
           to: "/{-$locale}/404",
           params: { locale: localePrefix },
         });
       }
     },
     component: Outlet,
   });
   

   Aqui, {-$locale} é um parâmetro de rota dinâmica que é substituído pelo locale 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}/other-path/$anotherDynamicPath/...). Para o modo 'prefix-all', você pode preferir mudar o slot para $locale em vez disso. Para o modo 'no-prefix' ou 'search-params', você pode remover o slot inteiramente.

7. 7

   Declare Seu Conteúdo

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

   src/contents/page.content.ts

   Copiar conteúdo

   Copiar código

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

   import type { Dictionary } from "intlayer";
   
   import { t } from "intlayer";
   
   const appContent = {
     content: {
       links: {
         about: t({
           en: "About",
           es: "Acerca de",
           fr: "À propos",
         }),
         home: t({
           en: "Home",
           es: "Inicio",
           fr: "Accueil",
         }),
       },
       meta: {
         title: t({
           en: "Welcome to Intlayer + TanStack Router",
           es: "Bienvenido a Intlayer + TanStack Router",
           fr: "Bienvenue à Intlayer + TanStack Router",
         }),
         description: t({
           en: "This is an example of using Intlayer with TanStack Router",
           es: "Este es un exemplo de uso de Intlayer con TanStack Router",
           fr: "Ceci est un exemplo d'utilisation d'Intlayer avec TanStack Router",
         }),
       },
     },
     key: "app",
   } satisfies Dictionary;
   
   export default appContent;
   export default appContent;
   

   Suas declarações de conteúdo podem ser definidas em qualquer lugar da sua aplicação assim que forem incluídas no diretório contentDir (por padrão, ./app). E devem corresponder à 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.

8. 8

   Crie Componentes e Hooks Sensíveis ao Locale

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

   src/components/localized-link.tsx

   Copiar conteúdo

   Copiar código

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

   import type { FC } from "react";
   
   import { Link, type LinkComponentProps } from "@tanstack/react-router";
   import { useLocale } from "react-intlayer";
   import { getPrefix } from "intlayer";
   
   export const LOCALE_ROUTE = "{-$locale}" as const;
   
   export type To = StripLocalePrefix<LinkComponentProps["to"]>;
   
   export type StripLocalePrefix<T extends string | undefined> = T extends
     `/${typeof LOCALE_ROUTE}/` | `/${typeof LOCALE_ROUTE}`
     ? "/"
     : T extends `/${typeof LOCALE_ROUTE}/${infer Rest}`
       ? `/${Rest}`
       : T;
   
   type LocalizedLinkProps = {
     to?: To;
   } & Omit<LinkComponentProps, "to">;
   
   export const LocalizedLink: FC<LocalizedLinkProps> = (props) => {
     const { locale } = useLocale();
     const { localePrefix } = getPrefix(locale);
   
     return (
       <Link
         {...props}
         params={{
           locale: localePrefix,
           ...(typeof props?.params === "object" ? props?.params : {}),
         }}
         to={`/${LOCALE_ROUTE}${props.to}` as LinkComponentProps["to"]}
       />
     );
   };
   

   Este componente tem dois objetivos:

   • Remover o prefixo {-$locale} desnecessário da URL.
   • Injetar o parâmetro de locale na URL para garantir que o usuário seja redirecionado diretamente para a rota localizada.

   Então, podemos criar um hook useLocalizedNavigate para navegação programática:

   src/hooks/useLocalizedNavigate.tsx

   Copiar conteúdo

   Copiar código

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

   import { useNavigate } from "@tanstack/react-router";
   import { getPrefix } from "intlayer";
   import { useLocale } from "react-intlayer";
   import type { StripLocalePrefix } from "@/components/localized-link";
   import type { FileRouteTypes } from "@/routeTree.gen";
   
   type NavigateFn = ReturnType<typeof useNavigate>;
   type BaseNavigateOptions = Parameters<NavigateFn>[0];
   
   type LocalizedTo = StripLocalePrefix<FileRouteTypes["to"]>;
   
   export type LocalizedNavigateOptions = Omit<
     BaseNavigateOptions,
     "to" | "params"
   > & {
     to: LocalizedTo;
     params?: Omit<NonNullable<BaseNavigateOptions["params"]>, "locale">;
   };
   
   type LocalizedNavigate = (
     options: LocalizedNavigateOptions
   ) => ReturnType<NavigateFn>;
   
   export const useLocalizedNavigate = () => {
     const navigate = useNavigate();
   
     const { locale } = useLocale();
   
     const localizedNavigate: LocalizedNavigate = (args: any) => {
       const { localePrefix } = getPrefix(locale);
   
       if (typeof args === "string") {
         return navigate({
           to: `/${LOCALE_ROUTE}${args}`,
           params: { locale: localePrefix },
         });
       }
   
       const { to, ...rest } = args;
   
       const localizedTo = `/${LOCALE_ROUTE}${to}` as any;
   
       return navigate({
         to: localizedTo,
         params: { locale: localePrefix, ...rest } as any,
       });
     };
   
     return localizedNavigate;
   };
   

9. 9

   Utilize o Intlayer em Suas Páginas

   Use useIntlayer por padrão: é a forma recomendada de ler conteúdo dentro dos componentes, e o compilador o resolve para a localidade que está sendo renderizada. Recorra a getIntlayer / getIntlayerAsync apenas fora da árvore React: o head das rotas, os loaders e as server functions.

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

   Página Inicial Localizada

   src/routes/{-$locale}/index.tsx

   Copiar conteúdo

   Copiar código

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

   import { createFileRoute } from "@tanstack/react-router";
   import { useIntlayer } from "react-intlayer";
   
   import LocaleSwitcher from "@/components/locale-switcher";
   import { LocalizedLink } from "@/components/localized-link";
   import { useLocalizedNavigate } from "@/hooks/useLocalizedNavigate";
   
   export const Route = createFileRoute("/{-$locale}/")({
     component: RouteComponent,
   });
   
   function RouteComponent() {
     const content = useIntlayer("app");
     const navigate = useLocalizedNavigate();
   
     return (
       <div>
         <div>
           {content.title}
           <LocaleSwitcher />
           <div>
             <LocalizedLink to="/">{content.links.home}</LocalizedLink>
             <LocalizedLink to="/about">{content.links.about}</LocalizedLink>
           </div>
           <div>
             <button onClick={() => navigate({ to: "/" })}>
               {content.links.home}
             </button>
             <button onClick={() => navigate({ to: "/about" })}>
               {content.links.about}
             </button>
           </div>
         </div>
       </div>
     );
   }
   

   Se você deseja usar seu conteúdo em um atributo string, como alt, title, href, aria-label, etc., você pode usar o valor da função, como:

   tsx

   Copiar conteúdo

   Copiar código

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

   <img src={content.image.src.value} alt={content.image.value} />
   <img src={content.image.src.toString()} alt={content.image.toString()} />
   <img src={String(content.image.src)} alt={String(content.image)} />
   

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

10. 9

    Criar um Componente de Alternador de Localidade

    Crie um componente para permitir que os usuários alterem idiomas:

    src/components/locale-switcher.tsx

    Copiar conteúdo

    Copiar código

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

    import { useLocation } from "@tanstack/react-router";
    import {
      getHTMLTextDir,
      getLocaleName,
      getPathWithoutLocale,
      getPrefix,
      Locales,
    } from "intlayer";
    import type { FC } from "react";
    import { useLocale } from "react-intlayer";
    
    import { LocalizedLink, type To } from "./localized-link";
    
    export const LocaleSwitcher: FC = () => {
      const { pathname } = useLocation();
    
      const { availableLocales, locale, setLocale } = useLocale();
    
      const pathWithoutLocale = getPathWithoutLocale(pathname);
    
      return (
        <ol>
          {availableLocales.map((localeEl) => (
            <li key={localeEl}>
              <LocalizedLink
                aria-current={localeEl === locale ? "page" : undefined}
                onClick={() => setLocale(localeEl)}
                params={{ locale: getPrefix(localeEl).localePrefix }}
                to={pathWithoutLocale as To}
              >
                <span>
                  {/* Localidade - ex. FR */}
                  {localeEl}
                </span>
                <span>
                  {/* Idioma em sua própria localidade - ex. Français */}
                  {getLocaleName(localeEl, locale)}
                </span>
                <span dir={getHTMLTextDir(localeEl)} lang={localeEl}>
                  {/* Idioma em localidade atual - ex. Francés com localidade atual definida como Locales.SPANISH */}
                  {getLocaleName(localeEl)}
                </span>
                <span dir="ltr" lang={Locales.ENGLISH}>
                  {/* Idioma em inglês - ex. French */}
                  {getLocaleName(localeEl, Locales.ENGLISH)}
                </span>
              </LocalizedLink>
            </li>
          ))}
        </ol>
      );
    };
    

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

11. 10

    Gerenciamento de Atributos HTML

    Como visto na Etapa 5, você pode gerenciar os atributos lang e dir da tag html usando useParams no seu componente raiz. Isso garante que os atributos corretos sejam definidos no servidor e no cliente.

    src/routes/__root.tsx

    Copiar conteúdo

    Copiar código

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

    const localeRoute = getRouteApi("/{-$locale}");
    
    function RootDocument({ children }: { children: ReactNode }) {
      const params = localeRoute.useParams();
      const locale = params?.locale ?? defaultLocale;
    
      return (
        <html dir={getHTMLTextDir(locale)} lang={locale}>
          {/* ... */}
        </html>
      );
    }
    

12. 11

    Adicionar middleware

    Você também pode usar intlayerProxy para adicionar roteamento no 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 apropriada com base nas preferências de idioma do navegador do usuário. Se nenhuma localidade for detectada, ela será redirecionada para a localidade padrão.

    Observe que para usar intlayerProxy em produção, você precisa mudar o package vite-intlayer de devDependencies para dependencies.

    Desde o Intlayer v9, intlayerProxy() está agrupado diretamente no plugin intlayer() e ativado por padrão através da opção routing.enableProxy (true por padrão). Registrá-lo separadamente como mostrado abaixo é agora opcional: é mantido para compatibilidade com versões anteriores e para setups que precisam controlar a ordem dos plugins. Defina routing.enableProxy: false para desativar. Consulte as notas de lançamento v9.

    vite.config.ts

    Copiar conteúdo

    Copiar código

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

    import { tanstackStart } from "@tanstack/react-start/plugin/vite";
    import viteReact from "@vitejs/plugin-react";
    import { nitro } from "nitro/vite";
    import { defineConfig } from "vite";
    import { intlayer } from "vite-intlayer";
    
    export default defineConfig({
      plugins: [
        nitro(),
        intlayer({
          proxy: {
            ignore: (req) => req.url?.startsWith("/api"),
          },
        }),
        tanstackStart({
          router: {
            routeFileIgnorePattern:
              ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5|md|mdx|yaml|yml)$",
          },
        }),
        viteReact(),
      ],
    });
    

13. 12

    Internacionalizar seus Metadados

    Resolução estáticaResolução dinâmicaResolução dinâmica em cache

    getIntlayer resolve de forma síncrona contra o dicionário mesclado, aquele que contém cada localidade declarada. head permanece síncrono e nada é aguardado, mas todo o dicionário multilíngue é incorporado ao chunk de rota enviado ao navegador.

    src/routes/{-$locale}/index.tsx

    Copiar conteúdo

    Copiar código

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

    import { createFileRoute } from "@tanstack/react-router";
    import {
      defaultLocale,
      getIntlayer,
      getLocalizedUrl,
      localeMap,
    } from "intlayer";
    
    export const Route = createFileRoute("/{-$locale}/")({
      component: RouteComponent,
      head: ({ params }) => {
        const { locale = defaultLocale } = params;
        const path = "/"; // O caminho para esta rota
    
        const metaContent = getIntlayer("app", locale);
    
        return {
          links: [
            // Link canônico: aponta para a página localizada atual
            { rel: "canonical", href: getLocalizedUrl(path, locale) },
    
            // Hreflang: informar ao Google sobre todas as versões localizadas
            ...localeMap(({ locale: mapLocale }) => ({
              rel: "alternate",
              hrefLang: mapLocale,
              href: getLocalizedUrl(path, mapLocale),
            })),
    
            // x-default: para usuários em idiomas não correspondidos
            // Define a localidade de fallback padrão (geralmente seu idioma principal)
            {
              rel: "alternate",
              hrefLang: "x-default",
              href: getLocalizedUrl(path, defaultLocale),
            },
          ],
          meta: [
            { title: metaContent.title },
            { name: "description", content: metaContent.meta.description },
          ],
        };
      },
    });
    

    Melhor para pequenos dicionários de metadados, um punhado de localidades ou durante prototipagem.

    getIntlayerAsync (disponível a partir de v9.4) se comporta como getIntlayer, mas o plugin de build a aponta para o chunk por localidade em .intlayer/dynamic_dictionaries/ em vez do dicionário mesclado. Uma página, portanto, envia apenas a localidade que renderiza. Como esse chunk é carregado sob demanda, head se torna async:

    src/routes/{-$locale}/index.tsx

    Copiar conteúdo

    Copiar código

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

    import { createFileRoute } from "@tanstack/react-router";
    import {
      defaultLocale,
      getIntlayerAsync,
      getLocalizedUrl,
      localeMap,
    } from "intlayer";
    
    export const Route = createFileRoute("/{-$locale}/")({
      component: RouteComponent,
      head: async ({ params }) => {
        const { locale = defaultLocale } = params;
        const path = "/"; // O caminho para esta rota
    
        const metaContent = await getIntlayerAsync("app", locale);
    
        return {
          links: [
            // Link canônico: aponta para a página localizada atual
            { rel: "canonical", href: getLocalizedUrl(path, locale) },
    
            // Hreflang: informar ao Google sobre todas as versões localizadas
            ...localeMap(({ locale: mapLocale }) => ({
              rel: "alternate",
              hrefLang: mapLocale,
              href: getLocalizedUrl(path, mapLocale),
            })),
    
            // x-default: para usuários em idiomas não correspondidos
            // Define a localidade de fallback padrão (geralmente seu idioma principal)
            {
              rel: "alternate",
              hrefLang: "x-default",
              href: getLocalizedUrl(path, defaultLocale),
            },
          ],
          meta: [
            { title: metaContent.title },
            { name: "description", content: metaContent.meta.description },
          ],
        };
      },
    });
    

    Se um head lê vários dicionários, resolva-os com Promise.all: aguardar cada getIntlayerAsync em sua própria linha encadeia as solicitações em vez de executá-las em paralelo.

    O trade-off: a importação dinâmica é resolvida enquanto head é executado, no caminho crítico da renderização do documento. Em uma rota fria isso atrasa o head por alguns milissegundos e pode degradar ligeiramente o LCP.

    Resolva o dicionário no loader da rota e leia-o de volta de loaderData em head. Os loaders das rotas correspondidas são executados em paralelo e staleTime: Infinity diz ao TanStack Router que o resultado nunca fica obsoleto, então o chunk por localidade é resolvido uma vez e servido do cache do roteador depois, deixando head síncrono.

    src/routes/{-$locale}/index.tsx

    Copiar conteúdo

    Copiar código

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

    import { createFileRoute } from "@tanstack/react-router";
    import {
      defaultLocale,
      getIntlayerAsync,
      getLocalizedUrl,
      localeMap,
    } from "intlayer";
    
    export const Route = createFileRoute("/{-$locale}/")({
      component: RouteComponent,
      // Resolvido em paralelo com as outras rotas correspondidas, fora do caminho crítico do head
      loader: async ({ params }) => {
        const { locale = defaultLocale } = params;
    
        return { metaContent: await getIntlayerAsync("app", locale) };
      },
      // O dicionário nunca muda para uma determinada localidade: resolver o chunk uma vez
      staleTime: Infinity,
      head: ({ params, loaderData }) => {
        const { locale = defaultLocale } = params;
        const path = "/"; // O caminho para esta rota
    
        return {
          links: [
            // Link canônico: aponta para a página localizada atual
            { rel: "canonical", href: getLocalizedUrl(path, locale) },
    
            // Hreflang: informar ao Google sobre todas as versões localizadas
            ...localeMap(({ locale: mapLocale }) => ({
              rel: "alternate",
              hrefLang: mapLocale,
              href: getLocalizedUrl(path, mapLocale),
            })),
    
            // x-default: para usuários em idiomas não correspondidos
            // Define a localidade de fallback padrão (geralmente seu idioma principal)
            {
              rel: "alternate",
              hrefLang: "x-default",
              href: getLocalizedUrl(path, defaultLocale),
            },
          ],
          meta: [
            { title: loaderData?.metaContent.title },
            {
              name: "description",
              content: loaderData?.metaContent.meta.description,
            },
          ],
        };
      },
    });
    

    head pode ser chamado antes do loader ser resolvido, então loaderData é digitado como possivelmente undefined. Mantenha o encadeamento opcional ou retorne um título de fallback.

    Você mantém o chunk por localidade sem pagar seu custo no caminho crítico do head. O preço é a experiência do desenvolvedor: o conteúdo deve ser conectado explicitamente do loader ao head através de loaderData.

    Qual resolução devo escolher?

    Mostrar todo o conteúdo da tabela

    Mostrar todo o conteúdo da tabela

    Abrir a tabela em um modal para ver todo o conteúdo claramente

    	Static resolution	Dynamic resolution	Cached dynamic resolution
    API	getIntlayer	getIntlayerAsync (v9.4+)	getIntlayerAsync in loader (v9.4+)
    head signature	synchronous	async	synchronous, reads loaderData
    Locales shipped	every declared locale	requested locale only	requested locale only
    Client navigations	nothing to resolve	re-entered on every match	served from the router cache
    Developer experience	simplest	one await	content threaded through loaderData

14. 13

    Recuperar a locale em suas server actions

    Você pode querer acessar a locale atual de dentro de suas server actions ou API endpoints. Você pode fazer isso usando o helper getLocale de intlayer.

    Aqui está um exemplo usando as funções de servidor do TanStack Start:

    src/routes/{-$locale}/index.tsx

    Copiar conteúdo

    Copiar código

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

    import { createServerFn } from "@tanstack/react-start";
    import {
      getRequestHeader,
      getRequestHeaders,
    } from "@tanstack/react-start/server";
    import { getCookie, getIntlayer, getLocale } from "intlayer";
    
    export const getLocaleServer = createServerFn().handler(async () => {
      const locale = await getLocale({
        // Obter o cookie da solicitação (padrão: 'INTLAYER_LOCALE')
        getCookie: (name) => {
          const cookieString = getRequestHeader("cookie");
    
          return getCookie(name, cookieString);
        },
        // Obter o header da solicitação (padrão: 'x-intlayer-locale')
        // Fallback usando negociação Accept-Language
        getHeader: (name) => getRequestHeader(name),
      });
    
      // Recuperar algum conteúdo usando getIntlayerAsync()
      const content = getIntlayer("app", locale);
    
      return { locale, content };
    });
    

15. 14

    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 encontrada e o prefixo de locale pode afetar a forma como a página de não encontrada é acionada.

    Entendendo o tratamento de 404 do TanStack Router com prefixos de locale

    No TanStack Router, lidar com páginas 404 com rotas localizadas requer uma abordagem multicamadas:

    1. Rota 404 dedicada: Uma rota específica para exibir a interface 404
    2. Validação no nível da rota: Valida os prefixos de locale e redireciona os inválidos para 404
    3. Rota catch-all: Captura todos os caminhos não correspondentes dentro do segmento de locale

    src/routes/{-$locale}/404.tsx

    Copiar conteúdo

    Copiar código

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

    import { createFileRoute } from "@tanstack/react-router";
    
    // Isso cria uma rota dedicada /[locale]/404
    // É usada tanto como uma rota direta quanto importada como um componente em outros arquivos
    export const Route = createFileRoute("/{-$locale}/404")({
      component: NotFoundComponent,
    });
    
    // Exportado separadamente para que possa ser reutilizado em notFoundComponent e rotas catch-all
    export function NotFoundComponent() {
      return (
        <div>
          <h1>404</h1>
        </div>
      );
    }
    

    src/routes/{-$locale}/route.tsx

    Copiar conteúdo

    Copiar código

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

    import { createFileRoute, Outlet, redirect } from "@tanstack/react-router";
    import { validatePrefix } from "intlayer";
    import { NotFoundComponent } from "./404";
    
    export const Route = createFileRoute("/{-$locale}")({
      // beforeLoad executa antes da rota ser renderizada (tanto no servidor quanto no cliente)
      // É o lugar ideal para validar o prefixo de locale
      beforeLoad: ({ params }) => {
        const localeParam = params.locale;
    
        // validatePrefix verifica se o locale é válido de acordo com sua configuração intlayer
        const { isValid, localePrefix } = validatePrefix(localeParam);
    
        if (!isValid) {
          // Prefixo de locale inválido - redirecionar para a página 404 com um prefixo de locale válido
          throw redirect({
            to: "/{-$locale}/404",
            params: { locale: localePrefix },
          });
        }
      },
      component: Outlet,
      // notFoundComponent é chamado quando uma rota filha não existe
      // por exemplo, /en/pagina-inexistente dispara isso dentro do layout /en
      notFoundComponent: NotFoundComponent,
    });
    

    src/routes/{-$locale}/$.tsx

    Copiar conteúdo

    Copiar código

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

    import { createFileRoute } from "@tanstack/react-router";
    
    import { NotFoundComponent } from "./404";
    
    // A rota $ (splat/catch-all) corresponde a qualquer caminho que não corresponda a outras rotas
    // por exemplo, /en/algum/caminho/profundamente/aninhado/invalido
    // Isso garante que TODOS os caminhos não correspondentes dentro de um locale mostrem a página 404
    // Sem isso, caminhos profundos não correspondentes podem mostrar uma página em branco ou erro
    export const Route = createFileRoute("/{-$locale}/$")({
      component: NotFoundComponent,
    });
    

16. 15

    Extrair o conteúdo dos seus componentes

    Opcional

    isOptional={true}>

    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
    

    intlayer >= 9intlayer < 9

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

    Compile sua aplicação 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

    npm run build # Ou npm run dev
    

17. 16

    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=fr e /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.ts para habilitar a pré-renderização de suas rotas localizadas e desabilitar a geração de sitemap padrão do TanStack Start.

    vite.config.ts

    Copiar conteúdo

    Copiar código

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

    import { localeFlatMap } from "intlayer";
    // ... outras importações
    
    export const pathList = ["", "/about", "/404"];
    
    const localizedPages = localeFlatMap(({ urlPrefix }) =>
      pathList.map((path) => ({
        path: `${urlPrefix}${path}`,
        prerender: {
          enabled: true,
        },
      }))
    );
    
    export default defineConfig({
      plugins: [
        // ... outros plugins
        tanstackStart({
          // ... outras configurações
          sitemap: {
            enabled: false,
          },
          prerender: {
            enabled: true,
            crawlLinks: false,
            concurrency: 10,
          },
          pages: localizedPages,
        }),
      ],
    });
    

    Em seguida, crie uma rota src/routes/sitemap[.]xml.ts que use a função generateSitemap:

    src/routes/sitemap[.]xml.ts

    Copiar conteúdo

    Copiar código

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

    import { createFileRoute } from "@tanstack/react-router";
    import { generateSitemap } from "intlayer";
    
    export const Route = createFileRoute("/sitemap.xml")({
      server: {
        handlers: {
          GET: async () => {
            const sitemap = generateSitemap(
              [
                { path: "/", changefreq: "daily", priority: 1.0 },
                { path: "/about", changefreq: "monthly", priority: 0.8 },
              ],
              { siteUrl: "https://example.com" }
            );
    
            return new Response(sitemap, {
              headers: { "Content-Type": "application/xml" },
            });
          },
        },
      },
    });
    

18. 17

    Configurar TypeScript

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

    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

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

Configuração do Git

É recomendado ignorar os arquivos gerados pelo Intlayer. Isso permite evitar que eles sejam comitados no seu repositório Git.

Para isso, você pode adicionar as seguintes instruções ao seu arquivo .gitignore:

# Ignorar os arquivos gerados pelo Intlayer
.intlayer

Extensão VS Code

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

Instalar do VS Code Marketplace

Esta extensão fornece:

• Autocompleção 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 como usar a extensão, consulte a documentação da Intlayer VS Code Extension.

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 Intlayer
• Documentação Tanstack Start
• hook useIntlayer
• hook useLocale
• Declaração de Conteúdo
• Configuração

Perguntas Frequentes