ドキュメント: intlayer の getLocalizedUrl 関数

説明

getLocalizedUrl 関数は、指定されたロケールを与えられた URL の前に付加することでローカライズされた URL を生成します。絶対 URL と相対 URL の両方を処理し、設定に基づいて正しいロケールのプレフィックスが適用されることを保証します。

主な機能:

• 必須パラメータは url と currentLocale の2つのみ
• locales、defaultLocale、mode を含むオプションの options オブジェクト
• プロジェクトの国際化設定をデフォルトとして使用
• シンプルなケースでは最小限のパラメータで使用でき、複雑なシナリオでは完全にカスタマイズ可能
• 複数のルーティングモードをサポート: prefix-no-default、prefix-all、no-prefix、search-params

関数署名

getLocalizedUrl(
  url: string,                   // 必須
  currentLocale: Locales,        // 必須
  options?: {                    // オプション
    locales?: Locales[];
    defaultLocale?: Locales;
    mode?: 'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params';
  }
): string

パラメータ

必須パラメータ

• url: string

  • Description: ロケールをプレフィックスとして付与する元のURL文字列。
  • Type: string
  • Required: Yes

• currentLocale: Locales

  • Description: URLがローカライズされている現在のロケール。
  • Type: Locales
  • Required: Yes

オプションパラメータ

• options?: object

  • Description: URL ローカライゼーション動作の設定オブジェクト。
  • Type: object

  • Required: No (Optional)

  • options.locales?: Locales[]

    • Description: サポートされているロケールの配列。指定されない場合、プロジェクト設定から設定されたロケールを使用します。
    • Type: Locales[]
    • Default: プロジェクト設定

  • options.defaultLocale?: Locales

    • Description: アプリケーションのデフォルトロケール。指定されない場合、プロジェクト設定から設定されたデフォルトロケールを使用します。
    • Type: Locales
    • Default: プロジェクト設定

  • options.mode?: 'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params'

    • Description: ロケール処理のための URL ルーティングモード。指定されない場合、プロジェクト設定から設定されたモードを使用します。
    • Type: 'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params'
    • Default: プロジェクト設定
    • Modes:
      • prefix-no-default: デフォルトロケールにはプレフィックスなし、その他すべてにプレフィックスあり
      • prefix-all: すべてのロケール（デフォルトを含む）にプレフィックスあり
      • no-prefix: URL にロケールプレフィックスなし
      • search-params: ロケールのクエリパラメータを使用（例：?locale=fr）

戻り値

• 型: string
• 説明: 指定されたロケールに対応するローカライズされた URL。

使用例

基本的な使用方法（必須パラメータのみ）

プロジェクトを国際化設定で構成した後、必須パラメータだけで関数を使用できます:

import { getLocalizedUrl, Locales } from "intlayer";

// プロジェクトの設定（locales、defaultLocale、mode）を使用します
getLocalizedUrl("/about", Locales.FRENCH);
// 出力: "/fr/about" (フランス語がサポートされており、modeが'prefix-no-default'の場合)

getLocalizedUrl("/about", Locales.ENGLISH);
// 出力: "/about" または "/en/about" (modeの設定に応じて異なります)

Advanced Usage (With Optional Parameters)

オプションの options パラメーターを提供することで、デフォルト設定をオーバーライドできます:

相対 URL

import { getLocalizedUrl, Locales } from "intlayer";

getLocalizedUrl(
  "/about",
  Locales.FRENCH,
  [Locales.ENGLISH, Locales.FRENCH],
  Locales.ENGLISH,
  false
);

// 出力: フランス語ロケールの場合 "/fr/about"
// 出力: デフォルト（英語）ロケールの場合 "/about"

部分的な設定のオーバーライド

オプションパラメータの一部のみを指定することもできます。指定しないパラメータについては、関数はプロジェクト設定を使用します:

import { getLocalizedUrl, Locales } from "intlayer";

// localesのみをオーバーライドし、defaultLocaleとmodeはプロジェクト設定を使用
getLocalizedUrl("/about", Locales.SPANISH, {
  locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
});

// modeのみをオーバーライドし、localesとdefaultLocaleはプロジェクト設定を使用
getLocalizedUrl("/about", Locales.ENGLISH, {
  mode: "prefix-all", // デフォルトロケールを含むすべてのロケールにプリフィックスを強制
});

// 複数のオプションをオーバーライド
getLocalizedUrl("/about", Locales.FRENCH, {
  defaultLocale: Locales.ENGLISH,
  mode: "search-params", // クエリパラメータを使用: /about?locale=fr
});

絶対URL

getLocalizedUrl(
  "https://example.com/about",
  Locales.FRENCH, // 現在のロケール
  [Locales.ENGLISH, Locales.FRENCH], // サポートされているロケール
  Locales.ENGLISH, // デフォルトロケール
  false // デフォルトロケールにプレフィックスを付けるかどうか
); // フランス語の場合の出力: "https://example.com/fr/about"

getLocalizedUrl(
  "https://example.com/about",
  Locales.ENGLISH, // 現在のロケール
  [Locales.ENGLISH, Locales.FRENCH], // サポートされているロケール
  Locales.ENGLISH, // デフォルトロケール
  false // デフォルトロケールにプレフィックスを付けるかどうか
); // 英語の場合の出力: "https://example.com/about"

getLocalizedUrl(
  "https://example.com/about",
  Locales.ENGLISH, // 現在のロケール
  [Locales.ENGLISH, Locales.FRENCH], // サポートされているロケール
  Locales.ENGLISH, // デフォルトロケール
  true // デフォルトロケールにプレフィックスを付けるかどうか
); // 英語の場合の出力: "https://example.com/en/about"

サポートされていないロケール

getLocalizedUrl(
  "/about",
  Locales.ITALIAN, // 現在のロケール
  [Locales.ENGLISH, Locales.FRENCH], // サポートされているロケール
  Locales.ENGLISH // デフォルトロケール
); // 出力: "/about"（サポートされていないロケールにはプレフィックスが適用されません）

エッジケース

• ロケールセグメントがない場合:

  • URLにロケールセグメントが含まれていない場合、関数は適切なロケールを安全にプレフィックスします。

• デフォルトロケール:

  • prefixDefault が false の場合、関数はデフォルトロケールのURLにプレフィックスを付けません。

• サポートされていないロケール:

  • locales にリストされていないロケールには、関数はプレフィックスを適用しません。

• ルーティングモード:

  • 'prefix-no-default': デフォルトロケールにはプレフィックスがなく、他のロケールにはある (例: /about, /fr/about)
  • 'prefix-all': すべてのロケールにプレフィックスがある (例: /en/about, /fr/about)
  • 'no-prefix': URLにロケールプレフィックスがない (ロケールは他の場所で処理される)
  • 'search-params': ロケールはクエリパラメータで指定される (例: /about?locale=fr)

アプリケーションでの使用方法

多言語対応アプリケーションでは、locales と defaultLocale を使用して国際化設定を構成することが、正しい言語を表示するために非常に重要です。以下は、getLocalizedUrl をアプリケーションのセットアップでどのように使用できるかの例です。

import { Locales, type IntlayerConfig } from "intlayer";

// サポートされているロケールとデフォルトロケールの設定
export default {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
    defaultLocale: Locales.ENGLISH,
  },
} satisfies IntlayerConfig;

export default config;

上記の設定により、アプリケーションは ENGLISH、FRENCH、SPANISH をサポート言語として認識し、フォールバック言語として ENGLISH を使用します。

この設定を使用すると、getLocalizedUrl 関数はユーザーの言語設定に基づいて動的にローカライズされたURLを生成できます：

getLocalizedUrl("/about", Locales.FRENCH); // 出力: "/fr/about"
getLocalizedUrl("/about", Locales.SPANISH); // 出力: "/es/about"
getLocalizedUrl("/about", Locales.ENGLISH); // 出力: "/about"

getLocalizedUrl を統合することで、開発者は複数言語にわたって一貫したURL構造を維持でき、ユーザー体験とSEOの両方を向上させることができます。