Dokumentation: getLocalizedUrl Funktion in intlayer

Beschreibung

Die getLocalizedUrl-Funktion generiert eine lokalisierte URL, indem sie die gegebene URL mit dem angegebenen Locale präfixiert. Sie verarbeitet sowohl absolute als auch relative URLs und stellt sicher, dass das richtige Locale-Präfix basierend auf der Konfiguration angewendet wird.

Wichtigste Funktionen:

• Nur 2 Parameter erforderlich: url und currentLocale
• Optionales options-Objekt mit locales, defaultLocale und mode
• Verwendet die Internationalisierungskonfiguration deines Projekts als Standard
• Kann mit minimalen Parametern für einfache Fälle oder vollständig angepasst für komplexe Szenarien verwendet werden
• Unterstützt mehrere Routing-Modi: prefix-no-default, prefix-all, no-prefix und search-params

Funktionssignatur

getLocalizedUrl(
  url: string,                   // Erforderlich
  currentLocale: Locales,        // Erforderlich
  options?: {                    // Optional
    locales?: Locales[];
    defaultLocale?: Locales;
    mode?: 'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params';
  }
): string

Parameter

Erforderliche Parameter

• url: string

  • Beschreibung: Die ursprüngliche URL-Zeichenkette, der ein Locale vorangestellt wird.
  • Type: string
  • Erforderlich: Ja

• currentLocale: Locales

  • Beschreibung: Das aktuelle Locale, für das die URL lokalisiert wird.
  • Type: Locales
  • Erforderlich: Ja

Optionale Parameter

• options?: object

  • Description: Konfigurationsobjekt für das URL-Lokalisierungsverhalten.
  • Type: object

  • Required: No (Optional)

  • options.locales?: Locales[]

    • Description: Array von unterstützten Locales. Falls nicht angegeben, werden die konfigurierten Locales aus Ihrer Projektkonfiguration verwendet.
    • Type: Locales[]
    • Default: Project Configuration

  • options.defaultLocale?: Locales

    • Description: Das Standard-Locale für die Anwendung. Falls nicht angegeben, wird das konfigurierte Standard-Locale aus Ihrer Projektkonfiguration verwendet.
    • Type: Locales
    • Default: Project Configuration

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

    • Description: Der URL-Routing-Modus für die Locale-Verwaltung. Falls nicht angegeben, wird der konfigurierte Modus aus Ihrer Projektkonfiguration verwendet.
    • Type: 'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params'
    • Default: Project Configuration
    • Modes:
      • prefix-no-default: Kein Präfix für Standard-Locale, Präfix für alle anderen
      • prefix-all: Präfix für alle Locales einschließlich Standard
      • no-prefix: Kein Locale-Präfix in der URL
      • search-params: Abfrageparameter für Locale verwenden (z. B. ?locale=fr)

Rückgabewert

• Typ: string
• Beschreibung: Die lokalisierte URL für das angegebene Locale.

Beispielhafte Verwendung

Grundlegende Verwendung (Nur erforderliche Parameter)

Wenn Sie Ihr Projekt mit Internationalisierungseinstellungen konfiguriert haben, können Sie die Funktion nur mit den erforderlichen Parametern verwenden:

import { getLocalizedUrl, Locales } from "intlayer";

// Verwendet die Konfiguration Ihres Projekts für locales, defaultLocale und mode
getLocalizedUrl("/about", Locales.FRENCH);
// Ausgabe: "/fr/about" (angenommen, Französisch wird unterstützt und mode ist 'prefix-no-default')

getLocalizedUrl("/about", Locales.ENGLISH);
// Ausgabe: "/about" oder "/en/about" (je nach Ihrer mode-Einstellung)

Erweiterte Verwendung (Mit optionalen Parametern)

Sie können die Standardkonfiguration überschreiben, indem Sie den optionalen Parameter options bereitstellen:

Relative URLs

import { getLocalizedUrl, Locales } from "intlayer";

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

// Ausgabe: "/fr/about" für das französische Locale
// Ausgabe: "/about" für das Standard-Locale (Englisch)

Partielle Konfigurationsüberschreibung

Sie können auch nur einige der optionalen Parameter bereitstellen. Die Funktion verwendet Ihre Projektkonfiguration für alle Parameter, die Sie nicht angeben:

import { getLocalizedUrl, Locales } from "intlayer";

// Nur die Locales überschreiben, Projektkonfiguration für defaultLocale und mode verwenden
getLocalizedUrl("/about", Locales.SPANISH, {
  locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
});

// Nur mode überschreiben, Projektkonfiguration für locales und defaultLocale verwenden
getLocalizedUrl("/about", Locales.ENGLISH, {
  mode: "prefix-all", // Präfix für alle Locales einschließlich Standard erzwingen
});

// Mehrere Optionen überschreiben
getLocalizedUrl("/about", Locales.FRENCH, {
  defaultLocale: Locales.ENGLISH,
  mode: "search-params", // Abfrageparameter verwenden: /about?locale=fr
});

Absolute URLs

getLocalizedUrl(
  "https://example.com/about",
  Locales.FRENCH, // Aktuelles Locale
  [Locales.ENGLISH, Locales.FRENCH], // Unterstützte Locales
  Locales.ENGLISH, // Standard-Locale
  false // Standard-Locale voranstellen
); // Ausgabe: "https://example.com/fr/about" für das französische Locale

getLocalizedUrl(
  "https://example.com/about",
  Locales.ENGLISH, // Aktuelles Locale
  [Locales.ENGLISH, Locales.FRENCH], // Unterstützte Locales
  Locales.ENGLISH, // Standard-Locale
  false // Standard-Locale voranstellen
); // Ausgabe: "https://example.com/about" für das englische Locale

getLocalizedUrl(
  "https://example.com/about",
  Locales.ENGLISH, // Aktuelles Locale
  [Locales.ENGLISH, Locales.FRENCH], // Unterstützte Locales
  Locales.ENGLISH, // Standard-Locale
  true // Standard-Locale voranstellen
); // Ausgabe: "https://example.com/en/about" für das englische Locale

Nicht unterstütztes Locale

getLocalizedUrl(
  "/about",
  Locales.ITALIAN, // Aktuelles Locale
  [Locales.ENGLISH, Locales.FRENCH], // Unterstützte Locales
  Locales.ENGLISH // Standard-Locale
); // Ausgabe: "/about" (kein Präfix für nicht unterstütztes Locale angewendet)

Randfälle

• Kein Locale-Segment:

  • Wenn die URL kein Locale-Segment enthält, fügt die Funktion sicher das passende Locale-Präfix hinzu.

• Standard-Locale:

  • Wenn prefixDefault auf false gesetzt ist, wird für das Standard-Locale kein Präfix vorangestellt.

• Nicht unterstützte Locales:

  • Für Locales, die nicht in locales aufgeführt sind, wird kein Präfix angewendet.

• Routing-Modi:

  • 'prefix-no-default': Standardgebietsschema hat kein Präfix, andere haben eines (z. B. /about, /fr/about)
  • 'prefix-all': Alle Gebietsschemata haben Präfixe (z. B. /en/about, /fr/about)
  • 'no-prefix': Keine Gebietsschema-Präfixe in URLs (Gebietsschema wird anderswo behandelt)
  • 'search-params': Gebietsschema wird über Abfrageparameter angegeben (z. B. /about?locale=fr)

Verwendung in Anwendungen

In einer mehrsprachigen Anwendung ist die Konfiguration der Internationalisierungseinstellungen mit locales und defaultLocale entscheidend, um sicherzustellen, dass die richtige Sprache angezeigt wird. Nachfolgend ein Beispiel, wie getLocalizedUrl in einer Anwendungs-Konfiguration verwendet werden kann:

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

// Konfiguration für unterstützte Locales und Standard-Locale
export default {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
    defaultLocale: Locales.ENGLISH,
  },
} satisfies IntlayerConfig;

export default config;

Die obige Konfiguration stellt sicher, dass die Anwendung ENGLISCH, FRANZÖSISCH und SPANISCH als unterstützte Sprachen erkennt und ENGLISCH als Fallback-Sprache verwendet.

Mit dieser Konfiguration kann die Funktion getLocalizedUrl dynamisch lokalisierte URLs basierend auf der Sprachpräferenz des Benutzers generieren:

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

Durch die Integration von getLocalizedUrl können Entwickler konsistente URL-Strukturen über mehrere Sprachen hinweg beibehalten, was sowohl die Benutzererfahrung als auch die SEO verbessert.