Documentazione: Funzione getLocalizedUrl in intlayer

Descrizione

La funzione getLocalizedUrl genera un URL localizzato aggiungendo un prefisso locale all'URL fornito. Gestisce sia gli URL assoluti che relativi, garantendo che il corretto prefisso locale sia applicato in base alla configurazione.

Caratteristiche principali:

• Solo 2 parametri sono obbligatori: url e currentLocale
• Oggetto options facoltativo con locales, defaultLocale e mode
• Utilizza la configurazione di internazionalizzazione del tuo progetto come impostazioni predefinite
• Può essere utilizzato con parametri minimi per casi semplici o completamente personalizzato per scenari complessi
• Supporta più modalità di routing: prefix-no-default, prefix-all, no-prefix e search-params

Firma della Funzione

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

Parametri

Parametri Obbligatori

• url: string

  • Description: La stringa URL originale da prefissare con una locale.
  • Type: string
  • Required: Yes

• currentLocale: Locales

  • Description: La locale corrente per cui l'URL è in corso di localizzazione.
  • Type: Locales
  • Required: Yes

Parametri Opzionali

• options?: object

  • Description: Oggetto di configurazione per il comportamento della localizzazione degli URL.
  • Type: object

  • Required: No (Opzionale)

  • options.locales?: Locales[]

    • Description: Array di locale supportate. Se non fornito, utilizza le locale configurate dalla configurazione del tuo progetto.
    • Type: Locales[]
    • Default: Project Configuration

  • options.defaultLocale?: Locales

    • Description: La locale predefinita per l'applicazione. Se non fornito, utilizza la locale predefinita configurata dalla configurazione del tuo progetto.
    • Type: Locales
    • Default: Project Configuration

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

    • Description: La modalità di routing degli URL per la gestione delle locale. Se non fornito, utilizza la modalità configurata dalla configurazione del tuo progetto.
    • Type: 'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params'
    • Default: Project Configuration
    • Modes:
      • prefix-no-default: Nessun prefisso per la locale predefinita, prefisso per tutte le altre
      • prefix-all: Prefisso per tutte le locale inclusa quella predefinita
      • no-prefix: Nessun prefisso di locale nell'URL
      • search-params: Utilizza i parametri di query per la locale (es. ?locale=fr)

Ritorna

• Tipo: string
• Descrizione: L'URL localizzato per la locale specificata.

Esempio di Utilizzo

Utilizzo di Base (Solo Parametri Obbligatori)

Quando hai configurato il tuo progetto con le impostazioni di internazionalizzazione, puoi utilizzare la funzione con solo i parametri obbligatori:

import { getLocalizedUrl, Locales } from "intlayer";

// Utilizza la configurazione del tuo progetto per locales, defaultLocale e mode
getLocalizedUrl("/about", Locales.FRENCH);
// Output: "/fr/about" (assumendo che il francese sia supportato e mode sia 'prefix-no-default')

getLocalizedUrl("/about", Locales.ENGLISH);
// Output: "/about" o "/en/about" (a seconda dell'impostazione di mode)

Advanced Usage (With Optional Parameters)

You can override the default configuration by providing the optional options parameter:

URL Relativi

import { getLocalizedUrl, Locales } from "intlayer";

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

// Output: "/fr/about" per la locale francese
// Output: "/about" per la locale predefinita (inglese)

Override parziale della configurazione

Puoi fornire anche solo alcuni dei parametri opzionali. La funzione utilizzerà la configurazione del tuo progetto per qualsiasi parametro non specificato:

import { getLocalizedUrl, Locales } from "intlayer";// Sovrascrivi solo le locales, usa la config del progetto per defaultLocale e modegetLocalizedUrl("/about", Locales.SPANISH, {  locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],});// Sovrascrivi solo mode, usa la config del progetto per locales e defaultLocalegetLocalizedUrl("/about", Locales.ENGLISH, {  mode: "prefix-all", // Forza il prefisso per tutte le locales inclusa quella predefinita});// Sovrascrivi più opzionigetLocalizedUrl("/about", Locales.FRENCH, {  defaultLocale: Locales.ENGLISH,  mode: "search-params", // Usa parametri di query: /about?locale=fr});

URL Assoluti

getLocalizedUrl(  "https://example.com/about",  Locales.FRENCH, // Locale corrente  [Locales.ENGLISH, Locales.FRENCH], // Locali supportate  Locales.ENGLISH, // Locale predefinita  false // Prefisso per la lingua predefinita); // Output: "https://example.com/fr/about" per la lingua francesegetLocalizedUrl(  "https://example.com/about",  Locales.ENGLISH, // Lingua corrente  [Locales.ENGLISH, Locales.FRENCH], // Lingue supportate  Locales.ENGLISH, // Lingua predefinita  false // Prefisso per la lingua predefinita); // Output: "https://example.com/about" per la lingua inglesegetLocalizedUrl(  "https://example.com/about",  Locales.ENGLISH, // Lingua corrente  [Locales.ENGLISH, Locales.FRENCH], // Lingue supportate  Locales.ENGLISH, // Lingua predefinita  true // Prefisso per la lingua predefinita); // Output: "https://example.com/en/about" per la lingua inglese

Lingua non supportata

getLocalizedUrl(  "/about",  Locales.ITALIAN, // Lingua corrente  [Locales.ENGLISH, Locales.FRENCH], // Lingue supportate  Locales.ENGLISH // Lingua predefinita); // Output: "/about" (nessun prefisso applicato per lingua non supportata)

Casi Limite

• Nessun segmento di lingua:

  • Se l'URL non contiene alcun segmento di lingua, la funzione aggiunge in modo sicuro il prefisso della lingua appropriata.

• Lingua predefinita:

  • Quando prefixDefault è false, la funzione non aggiunge il prefisso all'URL per la lingua predefinita.

• Lingue non supportate:

  • Per le lingue non elencate in locales, la funzione non applica alcun prefisso.

Utilizzo nelle Applicazioni

In un'applicazione multilingue, configurare le impostazioni di internazionalizzazione con locales e defaultLocale è fondamentale per garantire che venga visualizzata la lingua corretta. Di seguito è riportato un esempio di come getLocalizedUrl può essere utilizzato in una configurazione dell'applicazione:

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

// Configurazione delle lingue supportate e della lingua predefinita
export default {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
    defaultLocale: Locales.ENGLISH,
  },
} satisfies IntlayerConfig;

export default config;

La configurazione sopra garantisce che l'applicazione riconosca ENGLISH, FRENCH e SPANISH come lingue supportate e utilizzi ENGLISH come lingua di riserva.

Utilizzando questa configurazione, la funzione getLocalizedUrl può generare dinamicamente URL localizzati in base alla preferenza linguistica dell'utente:

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

Integrando getLocalizedUrl, gli sviluppatori possono mantenere strutture URL coerenti attraverso più lingue, migliorando sia l'esperienza utente che la SEO.