Política de URLs por idioma

Defina prefixos de idioma, negoceie preferências de idioma e determine redirecionamentos e caminhos alternativos sem depender de uma estrutura de desenvolvimento.

Um URL localizado precisa de uma política coerente: que idiomas estão disponíveis, como aparecem nos caminhos e para onde um caminho sem prefixo deve encaminhar quem o visita. @lingo.dev/locale-router toma essas decisões com Intl nativo. O seu servidor envia o redirecionamento e a sua aplicação carrega o catálogo escolhido.

Definir os idiomas suportados e os respetivos slugs #

sh
npm install @lingo.dev/locale-router@0.2.1
ts
import { createLocaleRouter } from "@lingo.dev/locale-router";

const locales = createLocaleRouter(["en", "de", "pt-BR"] as const, {
  defaultLocale: "en",
  exclude: ["api", "assets"],
  slugs: { "pt-BR": "br" },
});

O idioma pt-BR identifica o português do Brasil; br é apenas o respetivo slug no URL. Por predefinição, os slugs são etiquetas de idioma em minúsculas. Utilize etiquetas válidas, um idioma predefinido que pertença ao conjunto suportado e slugs distintos em minúsculas. O construtor não valida todas as configurações com conflitos.

createLocaleRouter<L extends string>(locales, options) aceita um vetor de idiomas só de leitura e devolve LocaleRouter<L>. defaultLocale é obrigatório; exclude e slugs são opcionais. As exclusões aplicam-se ao primeiro segmento do caminho. Se esse segmento começar por _ ou contiver ., também é excluído, mantendo os caminhos internos e os caminhos de ficheiros fora da localização.

Transformar um URL sem prefixo numa decisão de redirecionamento #

ts
const target = locales.redirect(
  new URL("https://example.com/account?tab=billing#details"),
  "de-CH,de;q=0.8,en;q=0.5",
);

if (target) {
  console.log(target.href);
}

O resultado é https://example.com/de/account?tab=billing#details. A preferência pelo alemão da Suíça corresponde ao idioma alemão suportado. A função auxiliar devolve um novo URL; não envia uma resposta HTTP nem define um cookie. O seu servidor escolhe o código de estado e envia a localização. Um pedido HTTP real não inclui o fragmento do navegador, embora a função auxiliar de URL preserve qualquer fragmento que lhe seja fornecido.

Se uma preferência guardada dever ter prioridade, valide a respetiva etiqueta de idioma através de toLocale e passe o resultado como terceiro argumento opcional de redirect. Não passe uma cadeia de caracteres arbitrária como idioma suportado.

Inspecionar e construir caminhos #

Chamada com a política acimaResultado
locales.toLocale("pt_BR")"pt-BR". Os sublinhados são normalizados antes de se procurar uma correspondência exata de idioma.
locales.toLocale("br")undefined. Um slug de URL não é uma etiqueta de idioma.
locales.split("/br/account"){ locale: "pt-BR", rest: "/account" }.
locales.isLocalized("/account")true. Isto significa que pode ser localizado, não que já tenha um prefixo.
locales.prefix("/account", "de")"/de/account".
locales.prefix("/", "de")"/de".
locales.prefix("/api/status", "de")"/api/status", sem alterações.
locales.canonical("/DE/account")"/de/account".

split devolve undefined quando o slug do primeiro segmento não é reconhecido. Passe aos métodos de caminho apenas o caminho, não uma cadeia de caracteres com parâmetros de consulta ou um fragmento.

prefix e alternates esperam um caminho sem prefixo. Para alterar /br/account para alemão, separe os seus componentes e passe rest:

ts
const current = locales.split("/br/account");
const germanPath = current ? locales.prefix(current.rest, "de") : undefined;

O resultado é /de/account. Adicionar um prefixo diretamente ao caminho original pode acrescentar um segundo segmento de idioma.

Negociar preferências de idioma #

negotiate(acceptLanguage: string | null): L ordena por qualidade as preferências com qualidade superior a zero e experimenta cada uma por essa ordem. Para cada preferência, procura primeiro uma correspondência exata de idioma e, depois, uma correspondência com uma língua suportada. Se várias variantes regionais suportadas partilharem a mesma língua, a ordem em que estão configuradas pode determinar a alternativa escolhida.

Os valores de qualidade inválidos e as preferências com qualidade zero são descartados. As etiquetas inválidas não correspondem a nenhum idioma e um caráter universal não substitui a política predefinida. Se nenhuma preferência corresponder, o método devolve defaultLocale. A seleção do idioma baseia-se nas preferências indicadas, não na geolocalização.

Manter a canonicalização separada dos redirecionamentos de caminhos sem prefixo #

canonical(pathname): string | undefined sugere um slug normalizado quando o primeiro segmento é reconhecido como semelhante a uma etiqueta de idioma. Não é um gerador de URLs canónicos de uso geral. redirect devolve undefined para caminhos que já têm prefixo, caminhos excluídos e caminhos para os quais canonical pode sugerir uma correção.

Trate a normalização de /DE/account separadamente se a sua aplicação o exigir. Um servidor pode substituir o caminho numa cópia do URL do pedido, preservando os parâmetros de consulta, antes de enviar o redirecionamento escolhido. O componente de intermediação do TanStack trata da negociação de caminhos sem prefixo, mas não acrescenta este passo de normalização separado.

Gerar URLs para idiomas alternativos #

ts
const links = locales.alternates("/account").map(({ locale, pathname }) => ({
  hrefLang: locale,
  href: new URL(pathname, "https://example.com").href,
}));

Utilize a origem de confiança do site em vez da apresentada no exemplo. alternates devolve um { locale, pathname } por idioma suportado, além de x-default a apontar para o caminho do idioma predefinido. A entrada do idioma pt-BR utiliza /br/account; a entrada do inglês predefinido utiliza /en/account segundo esta política.

O código que faz a chamada apresenta estes elementos como metadados. Os metadados de cabeçalho do TanStack acrescentam campos canónicos e Open Graph em torno desta política. O adaptador Next Pages segue a política de URLs do Next para o idioma predefinido, que é diferente, pelo que os respetivos resultados não são intercambiáveis.