문서: intlayer의 getLocalizedPath 함수

설명

getLocalizedPath 함수는 캐노니컬 경로(애플리케이션 내부 경로)를 제공된 로케일 및 리라이트 규칙에 따라 로컬라이즈된 등가 경로로 변환합니다. 언어별로 달라지는 SEO 친화적 URL을 생성할 때 특히 유용합니다.

이것은 getLocalizedUrl의 상대 경로 버전입니다 — 상대 입력의 경우 둘 다 같은 값을 반환합니다. getLocalizedUrl과 달리 절대 URL을 반환하지 않습니다: domains 설정이 무시되므로 자신의 도메인에서 제공되는 로케일도 경로를 반환합니다. 절대 입력은 허용되지만 원본은 제거됩니다 — 경로, 쿼리 문자열 및 해시만 유지됩니다.

주요 기능:

• [param] 구문을 사용한 동적 라우트 매개변수를 지원합니다.
• 구성(configuration)에 정의된 커스텀 리라이트(rewrite) 규칙에 따라 경로를 해석합니다.
• 지정된 로케일에 대한 리라이트 규칙이 없으면 자동으로 캐노니컬 경로로 폴백합니다.

함수 시그니처

getLocalizedPath(
  canonicalPath: string,         // 필수
  locale: Locales,               // 필수
  rewriteRules?: RoutingConfig['rewrite'] // 선택사항
): string

매개변수

필수 매개변수

• canonicalPath: string
  • 설명: 내부 애플리케이션 경로(예: /about, /product/[id]).
  • 타입: string
  • 필수: 예

선택적 매개변수

• rewriteRules?: RoutingConfig['rewrite']

  • 설명: 사용자 정의 리라이트 규칙을 정의하는 객체입니다. 제공하지 않으면 프로젝트 구성의 routing.rewrite 속성이 기본값으로 사용됩니다.
  • 타입: RoutingConfig['rewrite']
  • 기본값: configuration.routing.rewrite

• options?: object

  • Description: 라우팅 오버라이드. 모든 항목은 프로젝트의 구성으로 기본값이 설정됩니다.

  • Type: object

  • options.locales?: Locales[] — 지원하는 로케일. 기본값: configuration.internationalization.locales
  • options.defaultLocale?: Locales — 기본 로케일. 기본값: configuration.internationalization.defaultLocale
  • options.mode?: 'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params' — 경로에 로케일이 표시되는 방식. 기본값: configuration.routing.mode
  • options.rewrite?: RoutingConfig['rewrite'] — 사용자 정의 rewrite 규칙. 기본값: configuration.routing.rewrite

반환값

• 타입: string
• 설명: 지정된 로케일에 대한 로컬라이즈된 경로입니다.

타입은 구성에서 선언된 재작성 규칙으로부터 좁혀지므로, 편집기는 단순 string이 아닌 확인된 경로를 표시합니다:

// 설정: mode 'prefix-no-default', defaultLocale 'en',
//                { '/about': { fr: '/a-propos' }, '/product/[id]': { fr: '/produit/[id]' } }
const about = getLocalizedPath("/about", Locales.FRENCH);
//    ^? '/fr/a-propos'
const product = getLocalizedPath("/product/123", Locales.FRENCH);
//    ^? '/fr/produit/123'
const contact = getLocalizedPath("/contact", Locales.FRENCH);
//    ^? '/fr/contact'  (재작성 규칙이 일치하지 않음, 접두사만 적용됨)
const home = getLocalizedPath("/", Locales.FRENCH);
//    ^? '/fr'

같은 좁혀진 범위가 getLocalizedUrl으로 흐르며, 이는 locale을 prefixing하기 전에 rewrite 규칙을 적용합니다.

두 가지 경우는 컴파일 타임에 해결할 수 없기 때문에 string으로 확대됩니다:

• 문자열 리터럴이 아닌 경로 (예: 변수에서 생성된 경로);
• 다중 세그먼트 또는 선택적 매개변수를 사용하는 규칙과 일치하는 경로 ([...slug], [[...slug]], :param?).

예시 사용법

기본 사용법 (구성 포함)

intlayer.config.ts에 사용자 지정 리라이트 규칙을 구성한 경우:

import { getLocalizedPath, Locales } from "intlayer";

// 구성: { '/about': { en: '/about', fr: '/a-propos' } }
getLocalizedPath("/about", Locales.FRENCH);
// 출력: "/a-propos"

getLocalizedPath("/about", Locales.ENGLISH);
// 출력: "/about"

동적 라우트 사용법

import { getLocalizedPath, Locales } from "intlayer";

// 구성: { '/product/[id]': { en: '/product/[id]', fr: '/produit/[id]' } }
getLocalizedPath("/product/123", Locales.FRENCH);
// 출력: "/produit/123"

수동 리라이트 규칙

함수에 수동 리라이트 규칙을 직접 전달할 수도 있습니다:

import { getLocalizedPath, Locales } from "intlayer";

const manualRules = {
  "/contact": {
    en: "/contact-us",
    fr: "/contactez-nous",
  },
};

getLocalizedPath("/contact", Locales.FRENCH, manualRules);
// 출력: "/contactez-nous"

로케일 생략

로케일이 주어지지 않으면 경로는 구성된 기본 로케일에 대해 로컬화됩니다:

import { getLocalizedPath } from "intlayer";

// Configuration: defaultLocale = Locales.ENGLISH, { '/about': { en: '/about', fr: '/a-propos' } }
getLocalizedPath("/about");
// 출력: "/about"

관련 함수

• getCanonicalPath: 로컬라이즈된 경로를 내부 정규 경로로 되돌립니다.
• getLocalizedUrl: 프로토콜, 호스트, 로케일 접두사를 포함한 완전한 로컬라이즈된 URL을 생성합니다.