Implementação de Reescritas de URL Personalizadas

O Intlayer suporta reescritas de URL personalizadas, permitindo que você defina caminhos específicos por locale que diferem da estrutura padrão /locale/path. Isso possibilita URLs como /about para inglês e /a-propos para francês, mantendo a lógica interna da aplicação canônica.

Configuração

Regras de reescrita personalizadas são configuradas na seção routing do seu arquivo intlayer.config.ts usando formatadores específicos do framework. Esses formatadores fornecem a sintaxe correta para o router que você prefere.

import { Locales, type IntlayerConfig } from "intlayer";
import { nextjsRewrite } from "intlayer/routing";

const config: IntlayerConfig = {
// ...
routing: {
  mode: "prefix-no-default",
  rewrite: nextjsRewrite({
    "/[locale]/about": {
      fr: "/[locale]/a-propos",
      es: "/[locale]/acerca-de",
    },
    "/[locale]/products/[id]": {
      fr: "/[locale]/produits/[id]",
      es: "/[locale]/productos/[id]",
    },
  }),
},
};

export default config;

import { Locales, type IntlayerConfig } from "intlayer";
import { reactRouterRewrite } from "intlayer/routing";

const config: IntlayerConfig = {
// ...
routing: {
  mode: "prefix-all",
  rewrite: reactRouterRewrite({
    "/:locale/about": {
      fr: "/:locale/a-propos",
      es: "/:locale/acerca-de",
    },
    "/:locale/products/:id": {
      fr: "/:locale/produits/:id",
      es: "/:locale/productos/:id",
    },
  }),
},
};

export default config;

import { Locales, type IntlayerConfig } from "intlayer";
import { tanstackRouterRewrite } from "intlayer/routing";

const config: IntlayerConfig = {
// ...
routing: {
  mode: "prefix-all",
  rewrite: tanstackRouterRewrite({
    "/$locale/about": {
      fr: "/$locale/a-propos",
      es: "/$locale/acerca-de",
    },
    "/$locale/products/$id": {
      fr: "/$locale/produits/$id",
      es: "/$locale/productos/$id",
    },
  }),
},
};

export default config;

import { Locales, type IntlayerConfig } from "intlayer";
import { vueRouterRewrite } from "intlayer/routing";

const config: IntlayerConfig = {
// ...
routing: {
  mode: "prefix-all",
  rewrite: vueRouterRewrite({
    "/:locale/about": {
      fr: "/:locale/a-propos",
      es: "/:locale/acerca-de",
    },
    "/:locale/products/:id": {
      fr: "/:locale/produits/:id",
      es: "/:locale/productos/:id",
    },
  }),
},
};

export default config;

import { Locales, type IntlayerConfig } from "intlayer";
import { svelteKitRewrite } from "intlayer/routing";

const config: IntlayerConfig = {
// ...
routing: {
  mode: "prefix-all",
  rewrite: svelteKitRewrite({
    "/[locale]/about": {
      fr: "/[locale]/a-propos",
      es: "/[locale]/acerca-de",
    },
    "/[locale]/products/[id]": {
      fr: "/[locale]/produits/[id]",
      es: "/[locale]/productos/[id]",
    },
  }),
},
};

export default config;

import { Locales, type IntlayerConfig } from "intlayer";
import { solidRouterRewrite } from "intlayer/routing";

const config: IntlayerConfig = {
// ...
routing: {
  mode: "prefix-all",
  rewrite: solidRouterRewrite({
    "/:locale/about": {
      fr: "/:locale/a-propos",
      es: "/:locale/acerca-de",
    },
    "/:locale/products/:id": {
      fr: "/:locale/produits/:id",
      es: "/:locale/productos/:id",
    },
  }),
},
};

export default config;

import { Locales, type IntlayerConfig } from "intlayer";
import { nuxtRewrite } from "intlayer/routing";

const config: IntlayerConfig = {
// ...
routing: {
  mode: "prefix-all",
  rewrite: nuxtRewrite({
    "/[locale]/about": {
      fr: "/[locale]/a-propos",
      es: "/[locale]/acerca-de",
    },
    "/[locale]/products/[id]": {
      fr: "/[locale]/produits/[id]",
      es: "/[locale]/productos/[id]",
    },
  }),
},
};

export default config;

Formatadores Disponíveis

Intlayer fornece formatadores para todos os frameworks populares:

• nextjsRewrite: Para Next.js App Router. Suporta [slug], [...slug] (1+), e [[...slug]] (0+).
• svelteKitRewrite: Para SvelteKit. Suporta [slug], [...path] (0+), e [[optional]] (0-1).
• reactRouterRewrite: Para React Router. Suporta :slug e * (0+).
• vueRouterRewrite: Para Vue Router 4. Suporta :slug, :slug? (0-1), :slug* (0+), e :slug+ (1+).
• solidRouterRewrite: Para Solid Router. Suporta :slug e *slug (0+).
• tanstackRouterRewrite: Para TanStack Router. Suporta $slug e * (0+).
• nuxtRewrite: Para Nuxt 3. Suporta [slug] e [...slug] (0+).
• viteRewrite: Formatador genérico para qualquer projeto baseado em Vite. Normaliza a sintaxe para o proxy do Vite.

Padrões Avançados

O Intlayer normaliza internamente esses padrões para uma sintaxe unificada, permitindo correspondência de caminhos e geração mais sofisticadas:

• Segmentos Opcionais: [[optional]] (SvelteKit) ou :slug? (Vue/React) são suportados.
• Catch-all (Zero ou mais): [[...slug]] (Next.js), [...path] (SvelteKit/Nuxt) ou * (React/TanStack) permitem corresponder múltiplos segmentos.
• Catch-all Obrigatório (Um ou mais): [...slug] (Next.js) ou :slug+ (Vue) garantem que pelo menos um segmento esteja presente.

Correção de URL no Lado do Cliente: useRewriteURL

Para garantir que a barra de endereço do navegador reflita sempre a URL localizada "bonita", o Intlayer fornece o hook useRewriteURL. Este hook atualiza silenciosamente a URL usando window.history.replaceState quando um usuário acessa um caminho canônico.

Uso em Frameworks

'use client';

import { useRewriteURL } from "next-intlayer";

const MyLayout = ({ children }) => {
useRewriteURL(); // Corrige automaticamente /fr/about para /fr/a-propos
return <>{children}</>;
};

'use client';

import { useRewriteURL } from "react-intlayer";

const MyLayout = ({ children }) => {
useRewriteURL(); // Corrige automaticamente /fr/about para /fr/a-propos

return <>{children}</>;
};

<script setup>
import { useRewriteURL } from "vue-intlayer";

useRewriteURL();
</script>

import { useRewriteURL } from "solid-intlayer";

const Layout = (props) => {
useRewriteURL();
return <>{props.children}</>;
};

<script>
import { useRewriteURL } from "svelte-intlayer";

useRewriteURL();
</script>

Integração com o Router & Proxies

Os proxies server-side do Intlayer (Vite & Next.js) tratam automaticamente reescritas personalizadas para garantir consistência de SEO.

1. Reescritas Internas: Quando um utilizador visita /fr/a-propos, o proxy mapeia internamente para /fr/about para que o seu framework corresponda à rota correta.
2. Redirecionamentos Autoritativos: Se um utilizador digitar manualmente /fr/about, o proxy emite um redirecionamento 301/302 para /fr/a-propos, garantindo que os motores de busca indexem apenas uma versão da página.

Integração com Next.js

A integração com Next.js é totalmente gerida através do middleware intlayerProxy.

import { intlayerProxy } from "next-intlayer/middleware";
import { NextRequest } from "next/server";

export function middleware(request: NextRequest) {
  return intlayerProxy(request);
}

Integração com Vite

Para SolidJS, Vue e Svelte, o plugin Vite intlayerProxy gerencia as reescritas durante o desenvolvimento.

Desde Intlayer v9, intlayerProxy() é 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 retroativa e para configurações que precisam controlar a ordem dos plugins. Defina routing.enableProxy: false para desativar. Consulte as notas de versão v9.

import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

export default defineConfig({
  plugins: [
    intlayer({
      proxy: {
        ignore: (req) => req.url?.startsWith("/api"),
      },
    }),
  ],
});

Principais Funcionalidades

1. Reescritas Multi-Contexto

Cada formatter gera um RewriteObject contendo regras especializadas para diferentes consumidores:

• url: Otimizado para geração de URLs do lado do cliente (remove segmentos de locale).
• nextjs: Preserva [locale] para o middleware do Next.js.
• vite: Preserva :locale para os proxies do Vite.

2. Normalização Automática de Padrões

O Intlayer normaliza internamente todas as sintaxes de padrão (por exemplo, convertendo [param] para :param) para que o matching permaneça consistente independentemente do framework de origem.

3. URLs canônicas de SEO

Ao impor redirecionamentos de caminhos canônicos para aliases localizados mais apresentáveis, o Intlayer evita problemas de conteúdo duplicado e melhora a descoberta do site.

Utilitários principais

• getLocalizedUrl(url, locale): Gera uma URL localizada respeitando as regras de reescrita.
• getCanonicalPath(path, locale): Resolve uma URL localizada de volta para o seu caminho canônico interno.
• getRewritePath(pathname, locale): Detecta se um pathname precisa ser corrigido para o seu alias localizado mais amigável.