Política de URLs por idioma

Defina prefixos de idioma, negocie preferências de idioma e determine redirecionamentos e caminhos alternativos sem depender de um framework.

Uma URL localizada precisa de uma política consistente: quais idiomas estão disponíveis, como aparecem nos caminhos e para onde um caminho sem prefixo deve levar o leitor. @lingo.dev/locale-router toma essas decisões com Intl nativo. Seu servidor envia o redirecionamento, e sua aplicação carrega o catálogo escolhido.

Defina os idiomas e slugs compatíveis #

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 brasileiro; br é apenas o slug usado na URL. Por padrão, os slugs são as tags de idioma em letras minúsculas. Use tags válidas, um idioma padrão entre os compatíveis e slugs distintos em letras minúsculas. O construtor não verifica todos os possíveis conflitos de configuração.

createLocaleRouter<L extends string>(locales, options) aceita um array de idiomas somente leitura e retorna LocaleRouter<L>. defaultLocale é obrigatório; exclude e slugs são opcionais. As exclusões são verificadas pelo primeiro segmento do caminho. Se esse segmento começar com _ ou contiver ., o caminho também será excluído. Assim, caminhos internos e de arquivos ficam fora da localização.

Transforme uma URL sem prefixo em uma 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);
}

Isso gera https://example.com/de/account?tab=billing#details. A preferência por alemão suíço encontra correspondência no alemão, que é um dos idiomas compatíveis. A função auxiliar retorna uma nova URL; não envia uma resposta HTTP nem define um cookie. Seu servidor escolhe o código de estado e envia o endereço de destino. Uma requisição HTTP real não inclui o fragmento do navegador, embora a função auxiliar de URL preserve o fragmento quando ele é fornecido.

Se uma preferência salva deve ter prioridade, valide a tag de idioma com toLocale e passe o resultado como terceiro argumento opcional de redirect. Não passe uma string arbitrária como idioma compatível.

Inspecione e construa caminhos #

Chamada com a política acimaResultado
locales.toLocale("pt_BR")"pt-BR". Os sublinhados são normalizados antes da busca por uma correspondência exata de idioma.
locales.toLocale("br")undefined. Um slug de URL não é uma tag de idioma.
locales.split("/br/account"){ locale: "pt-BR", rest: "/account" }.
locales.isLocalized("/account")true. Isso indica que o caminho 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 retorna undefined quando não reconhece o slug do primeiro segmento. Passe aos métodos de caminho apenas o caminho, sem parâmetros de consulta nem fragmento.

prefix e alternates esperam um caminho sem prefixo. Para mudar /br/account para alemão, separe 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 o prefixo diretamente ao caminho original pode acrescentar um segundo segmento de idioma.

Negocie preferências de idioma #

negotiate(acceptLanguage: string | null): L ordena as preferências com valor de qualidade positivo por esse valor e testa cada uma em sequência. Para cada preferência, busca primeiro uma correspondência exata da tag de idioma e, depois, uma correspondência com um idioma compatível. Se várias variantes regionais compatíveis compartilharem o mesmo idioma, a ordem configurada pode determinar qual delas será usada como alternativa.

Valores de qualidade inválidos e preferências com qualidade zero são descartados. Tags inválidas não encontram correspondência, e um curinga não substitui a política padrão. Se nenhuma preferência encontrar correspondência, o método retorna defaultLocale. A seleção do idioma se baseia nas preferências declaradas, não na geolocalização.

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

canonical(pathname): string | undefined sugere um slug normalizado quando o primeiro segmento é reconhecido como uma possível tag de idioma. Não é um gerador de URLs canônicas de uso geral. redirect retorna 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 sua aplicação precisar dela. Um servidor pode substituir o caminho em uma cópia da URL da requisição, preservando os parâmetros de consulta, antes de enviar o redirecionamento escolhido. O middleware do TanStack trata a negociação de caminhos sem prefixo, mas não executa essa etapa separada de normalização.

Gere URLs para idiomas alternativos #

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

Use a origem confiável do site no lugar da origem do exemplo. alternates retorna um { locale, pathname } por idioma compatível, além de x-default apontando para o caminho do idioma padrão. A entrada do idioma pt-BR usa /br/account; a entrada padrão em inglês usa /en/account conforme esta política.

O código que faz a chamada renderiza esses elementos como metadados. Os metadados de cabeçalho do TanStack acrescentam campos canônicos e do Open Graph a essa política. O adaptador Next Pages segue a política de URLs do idioma padrão do Next, que é diferente. Por isso, não use os resultados de um no lugar dos resultados do outro.