Politique des URL par langue

Définissez les préfixes de langue, négociez les préférences linguistiques et déterminez les redirections et les chemins alternatifs, indépendamment de tout framework.

Une URL localisée exige une politique cohérente : quelles langues sont disponibles, comment elles apparaissent dans les chemins et vers quelle destination un chemin sans préfixe doit diriger le lecteur. @lingo.dev/locale-router prend ces décisions à l'aide de Intl natifs. Votre serveur envoie la redirection et votre application charge le catalogue choisi.

Définir les langues prises en charge et les 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" },
});

La balise de langue pt-BR identifie le portugais brésilien ; br n'est que son slug d'URL. Sans personnalisation explicite, les slugs correspondent aux balises de langue en minuscules. Utilisez des balises valides, une langue par défaut parmi celles prises en charge et des slugs distincts en minuscules. Le constructeur ne détecte pas tous les conflits de configuration.

createLocaleRouter<L extends string>(locales, options) accepte un tableau de langues en lecture seule et renvoie LocaleRouter<L>. defaultLocale est obligatoire ; exclude et slugs sont facultatifs. Les exclusions s'appliquent au premier segment du chemin. Un premier segment commençant par _ ou contenant . est également exclu : les chemins internes et les chemins de fichiers restent ainsi hors du périmètre de la localisation.

Transformer une URL sans préfixe en décision de redirection #

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

On obtient https://example.com/de/account?tab=billing#details. La préférence pour l'allemand suisse correspond à l'allemand pris en charge. La fonction utilitaire renvoie une nouvelle URL ; elle n'envoie aucune réponse HTTP et ne définit aucun cookie. Votre serveur choisit le code de statut et envoie l'adresse de destination. Une requête HTTP réelle ne contient pas le fragment du navigateur, même si la fonction utilitaire conserve le fragment qui lui est fourni.

Si une préférence enregistrée doit être prioritaire, validez sa balise de langue avec toLocale et transmettez le résultat comme troisième argument facultatif de redirect. Ne transmettez pas une chaîne arbitraire comme langue prise en charge.

Inspecter et construire les chemins #

Appel avec la politique ci-dessusRésultat
locales.toLocale("pt_BR")"pt-BR". Les traits de soulignement sont normalisés avant la recherche d'une correspondance exacte de balise de langue.
locales.toLocale("br")undefined. Un slug d'URL n'est pas une balise de langue.
locales.split("/br/account"){ locale: "pt-BR", rest: "/account" }.
locales.isLocalized("/account")true. Cela signifie que le chemin peut être localisé, pas qu'il est déjà préfixé.
locales.prefix("/account", "de")"/de/account".
locales.prefix("/", "de")"/de".
locales.prefix("/api/status", "de")"/api/status", inchangé.
locales.canonical("/DE/account")"/de/account".

split renvoie undefined si le slug du premier segment n'est pas reconnu. Transmettez aux méthodes de gestion des chemins uniquement le chemin de l'URL, sans paramètres de requête ni fragment.

prefix et alternates attendent un chemin sans préfixe. Pour passer /br/account en allemand, décomposez-le et transmettez rest :

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

Le résultat est /de/account. Préfixer directement le chemin d'origine peut ajouter un deuxième segment de langue.

Négocier les préférences linguistiques #

negotiate(acceptLanguage: string | null): L trie les préférences dont le coefficient de qualité est positif selon ce coefficient, puis les essaie dans l'ordre. Pour chaque préférence, la méthode recherche d'abord une correspondance exacte de balise de langue, puis une correspondance avec une langue prise en charge. Si plusieurs variantes régionales prises en charge partagent la même langue, leur ordre dans la configuration peut déterminer la variante de repli.

Les coefficients de qualité invalides et les préférences dont le coefficient est nul sont écartés. Les balises invalides ne correspondent à aucune langue et un caractère générique ne remplace pas la politique par défaut. Si aucune préférence ne correspond, la méthode renvoie defaultLocale. La langue est choisie à partir des préférences exprimées, et non de la géolocalisation.

Séparer la canonicalisation des redirections de chemins sans préfixe #

canonical(pathname): string | undefined suggère un slug normalisé pour un premier segment reconnu comme une balise de langue ou une forme approchante. Ce n'est pas un générateur général d'URL canoniques. redirect renvoie undefined pour les chemins déjà préfixés, les chemins exclus et ceux pour lesquels canonical peut suggérer une correction.

Traitez séparément la normalisation de /DE/account si votre application en a besoin. Un serveur peut remplacer le chemin dans une copie de l'URL de la requête, tout en conservant les paramètres de requête, avant d'envoyer la redirection choisie. Le middleware de TanStack gère la négociation linguistique pour les chemins sans préfixe, mais n'ajoute pas cette étape de normalisation distincte.

Générer des URL dans les autres langues #

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

Utilisez l'origine de confiance du site plutôt que celle de l'exemple. alternates renvoie un { locale, pathname } par langue prise en charge, ainsi que x-default pointant vers le chemin de la langue par défaut. L'entrée correspondant à la langue pt-BR utilise /br/account ; l'entrée anglaise par défaut utilise /en/account selon cette politique.

Le code appelant les restitue sous forme de métadonnées. Les métadonnées d'en-tête de TanStack ajoutent des champs canoniques et Open Graph en complément de cette politique. L'adaptateur Next Pages suit la politique d'URL de Next, qui diffère pour la langue par défaut : leurs résultats ne sont donc pas interchangeables.