로캘 주소 정책

프레임워크에 종속되지 않고 로캘 접두사를 정의하고, 언어 선호도에 따라 언어를 선택하며, 리디렉션과 대체 경로를 결정하세요.

현지화된 주소에는 일관된 정책이 필요합니다. 어떤 언어를 지원할지, 경로에 언어를 어떻게 표시할지, 접두사 없는 경로로 들어온 사용자를 어디로 보낼지 정해야 합니다. @lingo.dev/locale-router는 기본 제공 Intl를 사용해 이를 결정합니다. 서버는 리디렉션을 전송하고, 애플리케이션은 선택된 카탈로그를 불러옵니다.

지원 로캘과 슬러그 정의하기 #

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

로캘 pt-BR는 브라질 포르투갈어를 나타내며, br는 주소에 사용하는 슬러그일 뿐입니다. 별도로 지정하지 않으면 소문자 로캘 태그가 슬러그로 사용됩니다. 유효한 태그를 사용하고, 지원 로캘 중에서 기본값을 선택하고, 서로 겹치지 않는 소문자 슬러그를 지정하세요. 생성자가 충돌하는 모든 설정을 검증하지는 않습니다.

createLocaleRouter<L extends string>(locales, options)는 읽기 전용 로캘 배열을 받아 LocaleRouter<L>를 반환합니다. defaultLocale는 필수이며, exclude와 slugs는 선택 사항입니다. 제외 항목은 경로명의 첫 번째 세그먼트를 기준으로 일치 여부를 확인합니다. 첫 번째 세그먼트가 _로 시작하거나 .를 포함하는 경우에도 제외되므로, 내부 경로와 파일 경로는 현지화 대상에서 제외됩니다.

접두사 없는 주소의 리디렉션 결정하기 #

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

이렇게 하면 https://example.com/de/account?tab=billing#details가 생성됩니다. 선호 언어인 스위스 독일어는 지원 언어인 독일어와 일치합니다. 이 도우미 함수는 새 주소를 반환할 뿐, HTTP 응답을 보내거나 쿠키를 설정하지 않습니다. 상태 코드를 선택하고 이동할 주소를 전송하는 것은 서버의 역할입니다. 주소 도우미 함수는 전달받은 프래그먼트를 보존하지만, 실제 HTTP 요청에는 브라우저의 프래그먼트가 포함되지 않습니다.

저장된 선호 언어를 우선 적용하려면 toLocale로 해당 로캘 태그를 검증한 뒤, 그 결과를 redirect의 선택 사항인 세 번째 인수로 전달하세요. 임의의 문자열을 지원 로캘로 전달하지 마세요.

경로 확인하고 생성하기 #

위 정책을 적용한 호출결과
locales.toLocale("pt_BR")"pt-BR". 밑줄을 정규화한 뒤 정확히 일치하는 로캘을 찾습니다.
locales.toLocale("br")undefined. 주소 슬러그는 로캘 태그가 아닙니다.
locales.split("/br/account"){ locale: "pt-BR", rest: "/account" }.
locales.isLocalized("/account")true. 이미 접두사가 있다는 뜻이 아니라 현지화 대상이라는 뜻입니다.
locales.prefix("/account", "de")"/de/account".
locales.prefix("/", "de")"/de".
locales.prefix("/api/status", "de")"/api/status", 변경 없음.
locales.canonical("/DE/account")"/de/account".

split는 첫 번째 세그먼트의 슬러그를 인식하지 못하면 미정의 값을 반환합니다. 경로 메서드에는 쿼리 매개변수나 해시가 포함된 문자열이 아니라 경로명을 전달하세요.

prefix와 alternates에는 접두사 없는 경로를 전달해야 합니다. /br/account를 독일어로 바꾸려면 경로를 분리한 뒤 rest를 전달하세요.

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

결과는 /de/account입니다. 원래 경로에 접두사를 바로 붙이면 로캘 세그먼트가 하나 더 추가될 수 있습니다.

언어 선호도에 맞춰 언어 선택하기 #

negotiate(acceptLanguage: string | null): L는 품질 값이 양수인 선호 항목을 품질 값에 따라 정렬한 뒤 순서대로 확인합니다. 각 항목에 대해 먼저 정확히 일치하는 로캘을 찾고, 다음으로 일치하는 지원 언어를 찾습니다. 지원되는 여러 지역 로캘이 같은 언어를 사용한다면 설정된 순서에 따라 대체 언어가 결정될 수 있습니다.

유효하지 않은 품질 값과 품질 값이 0인 선호 항목은 제외됩니다. 유효하지 않은 태그는 일치하는 것으로 처리되지 않으며, 와일드카드가 기본 정책을 대체하지도 않습니다. 일치하는 선호 항목이 없으면 메서드는 defaultLocale를 반환합니다. 지리적 위치가 아니라 명시된 선호도를 바탕으로 언어를 선택하는 방식입니다.

주소 정규화와 접두사 없는 경로의 리디렉션 분리하기 #

canonical(pathname): string | undefined는 첫 번째 세그먼트를 로캘 형식으로 인식하면 정규화된 슬러그를 제안합니다. 범용 표준 주소 생성기는 아닙니다. redirect는 이미 접두사가 있는 경로, 제외 대상 경로, canonical가 수정을 제안할 수 있는 경로에 대해 미정의 값을 반환합니다.

애플리케이션에 /DE/account 정규화가 필요하다면 별도로 처리하세요. 서버는 요청 주소의 사본에서 쿼리 문자열은 보존하고 경로명을 바꾼 뒤, 선택한 리디렉션을 전송할 수 있습니다. 탠스택 미들웨어는 접두사 없는 경로의 언어 선택을 처리하지만, 이 별도의 정규화 단계까지 수행하지는 않습니다.

대체 언어 주소 생성하기 #

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

예시에 나온 오리진 대신 사이트의 신뢰할 수 있는 오리진을 사용하세요. alternates는 지원 로캘마다 { locale, pathname }를 하나씩 반환하고, 기본 로캘의 경로를 가리키는 x-default도 함께 반환합니다. 이 정책에서 pt-BR 언어 항목은 /br/account를 사용하고, 기본 언어인 영어 항목은 /en/account를 사용합니다.

호출하는 쪽에서 이 결과를 메타데이터로 렌더링합니다. 탠스택 헤드 메타데이터는 이 정책을 바탕으로 표준 주소와 오픈 그래프 필드를 추가합니다. 넥스트 페이지 어댑터는 기본 로캘 주소에 대해 넥스트의 별도 정책을 따르므로, 두 방식의 출력을 서로 바꿔 사용하지 마세요.