Dokumentasi: Fungsi getLocalizedUrl di intlayer

Deskripsi

Fungsi getLocalizedUrl menghasilkan URL yang dilokalisasi dengan menambahkan prefix locale yang ditentukan pada URL yang diberikan. Fungsi ini menangani URL absolut maupun relatif, memastikan bahwa prefix locale yang benar diterapkan berdasarkan konfigurasi.

Fitur Utama:

• Hanya 2 parameter yang diperlukan: url dan currentLocale
• 3 parameter opsional: locales, defaultLocale, dan prefixDefault
• Menggunakan konfigurasi internasionalisasi proyek Anda sebagai default
• Dapat digunakan dengan parameter minimal untuk kasus sederhana atau dikustomisasi sepenuhnya untuk skenario kompleks

Tanda Tangan Fungsi

getLocalizedUrl(
  url: string,                   // Wajib
  currentLocale: Locales,        // Wajib
  locales?: Locales[],           // Opsional
  defaultLocale?: Locales,       // Opsional
  prefixDefault?: boolean        // Opsional
): string

Parameter

Parameter Wajib

• url: string

  • Deskripsi: String URL asli yang akan diberi prefix locale.
  • Tipe: string
  • Wajib: Ya

• currentLocale: Locales

  • Deskripsi: Locale saat ini yang digunakan untuk melokalisasi URL.
  • Tipe: Locales
  • Wajib: Ya

Parameter Opsional

• options?: object

  • Description: Objek konfigurasi untuk perilaku lokalisasi URL.
  • Type: object
  • Required: Tidak (Opsional)

• locales?: Locales[]

  • Deskripsi: Array locale yang didukung. Jika tidak disediakan, menggunakan locale yang dikonfigurasi dari konfigurasi proyek Anda.
  • Tipe: Locales[]
  • Wajib: Tidak (Opsional)
  • Default: Konfigurasi Proyek

• defaultLocale?: Locales

  • Deskripsi: Locale default untuk aplikasi. Jika tidak disediakan, menggunakan locale default yang dikonfigurasi dari konfigurasi proyek Anda.
  • Tipe: Locales
  • Wajib: Tidak (Opsional)
  • Default: Konfigurasi Proyek

• prefixDefault?: boolean

  • Deskripsi: Apakah akan menambahkan prefix pada URL untuk locale default. Jika tidak disediakan, menggunakan nilai yang dikonfigurasi dari konfigurasi proyek Anda.
  • Tipe: boolean
  • Wajib: Tidak (Opsional)
  • Default: Konfigurasi Proyek

Mengembalikan

• Tipe: string
• Deskripsi: URL yang sudah dilokalisasi untuk locale yang ditentukan.

Contoh Penggunaan

Penggunaan Dasar (Hanya Parameter Wajib)

Ketika Anda telah mengonfigurasi proyek Anda dengan pengaturan internasionalisasi, Anda dapat menggunakan fungsi ini hanya dengan parameter yang wajib:

import { getLocalizedUrl, Locales } from "intlayer";

// Menggunakan konfigurasi proyek Anda untuk locales, defaultLocale, dan prefixDefault
getLocalizedUrl("/about", Locales.FRENCH);
// Output: "/fr/about" (asumsi Bahasa Perancis didukung dalam konfigurasi Anda)

getLocalizedUrl("/about", Locales.ENGLISH);
// Output: "/about" atau "/en/about" (tergantung pada pengaturan prefixDefault Anda)

Penggunaan Lanjutan (Dengan Parameter Opsional)

Anda dapat mengganti konfigurasi default dengan menyediakan parameter options opsional:

URL Relatif (Semua Opsi Ditentukan)

import { getLocalizedUrl, Locales } from "intlayer";

// Secara eksplisit memberikan semua parameter opsional
getLocalizedUrl("/about", Locales.FRENCH, {
  locales: [Locales.ENGLISH, Locales.FRENCH],
  defaultLocale: Locales.ENGLISH,
  mode: "prefix-no-default",
});
// Output: "/fr/about" untuk locale Prancis

getLocalizedUrl("/about", Locales.ENGLISH, {
  locales: [Locales.ENGLISH, Locales.FRENCH],
  defaultLocale: Locales.ENGLISH,
  mode: "prefix-no-default",
});
// Output: "/about" untuk locale default (Inggris)

Partial Configuration Override

Anda juga dapat memberikan hanya beberapa parameter opsional. Fungsi akan menggunakan konfigurasi proyek Anda untuk parameter yang tidak Anda tentukan:

import { getLocalizedUrl, Locales } from "intlayer";

// Hanya override locales, gunakan konfigurasi proyek untuk defaultLocale dan prefixDefault
getLocalizedUrl(
  "/about",
  Locales.SPANISH,
  [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH] // Hanya tentukan locales
);

// Hanya override prefixDefault, gunakan konfigurasi proyek untuk locales dan defaultLocale
getLocalizedUrl(
  "/about",
  Locales.ENGLISH,
  undefined, // Gunakan konfigurasi proyek untuk locales
  undefined, // Gunakan konfigurasi proyek untuk defaultLocale
  true // Paksa prefix untuk locale default
);

URL Absolut

getLocalizedUrl(
  "https://example.com/about",
  Locales.FRENCH, // Locale Saat Ini
  [Locales.ENGLISH, Locales.FRENCH], // Locale yang Didukung
  Locales.ENGLISH, // Locale Default
  false // Prefix Locale Default
); // Output: "https://example.com/fr/about" untuk bahasa Perancis

getLocalizedUrl(
  "https://example.com/about",
  Locales.ENGLISH, // Locale Saat Ini
  [Locales.ENGLISH, Locales.FRENCH], // Locale yang Didukung
  Locales.ENGLISH, // Locale Default
  false // Prefix Locale Default
); // Output: "https://example.com/about" untuk bahasa Inggris

getLocalizedUrl(
  "https://example.com/about",
  Locales.ENGLISH, // Locale Saat Ini
  [Locales.ENGLISH, Locales.FRENCH], // Locale yang Didukung
  Locales.ENGLISH, // Locale Default
  true // Prefix Locale Default
); // Output: "https://example.com/en/about" untuk bahasa Inggris

Locale Tidak Didukung

getLocalizedUrl(
  "/about",
  Locales.ITALIAN, // Locale Saat Ini
  [Locales.ENGLISH, Locales.FRENCH], // Locale yang Didukung
  Locales.ENGLISH // Locale Default
); // Output: "/about" (tidak ada prefix yang diterapkan untuk locale yang tidak didukung)

Kasus Tepi

• Tidak Ada Segmen Locale:

  • Jika URL tidak mengandung segmen locale, fungsi dengan aman menambahkan prefix locale yang sesuai.

• Locale Default:

  • Ketika prefixDefault adalah false, fungsi tidak menambahkan prefix pada URL untuk locale default.

• Locale Tidak Didukung:

  • Untuk locale yang tidak tercantum dalam locales, fungsi tidak menerapkan prefix apapun.

• Mode Routing:

  • 'prefix-no-default': Locale default tidak memiliki prefix, yang lain memiliki (mis., /about, /fr/about)
  • 'prefix-all': Semua locale memiliki prefix (mis., /en/about, /fr/about)
  • 'no-prefix': Tidak ada prefix locale di URL (locale ditangani di tempat lain)
  • 'search-params': Locale ditentukan melalui parameter query (mis., /about?locale=fr)

Penggunaan dalam Aplikasi

Dalam aplikasi multibahasa, mengonfigurasi pengaturan internasionalisasi dengan locales dan defaultLocale sangat penting untuk memastikan bahasa yang benar ditampilkan. Berikut adalah contoh bagaimana getLocalizedUrl dapat digunakan dalam pengaturan aplikasi:

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

// Konfigurasi untuk locale yang didukung dan locale default
export default {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
    defaultLocale: Locales.ENGLISH,
  },
} satisfies IntlayerConfig;

export default config;

Konfigurasi di atas memastikan bahwa aplikasi mengenali ENGLISH, FRENCH, dan SPANISH sebagai bahasa yang didukung dan menggunakan ENGLISH sebagai bahasa cadangan.

Dengan menggunakan konfigurasi ini, fungsi getLocalizedUrl dapat secara dinamis menghasilkan URL yang dilokalkan berdasarkan preferensi bahasa pengguna:

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

Dengan mengintegrasikan getLocalizedUrl, pengembang dapat mempertahankan struktur URL yang konsisten di berbagai bahasa, meningkatkan pengalaman pengguna sekaligus SEO.