Documentazione: Funzione getIntlayer in intlayer

Descrizione

La funzione getIntlayer seleziona un dizionario dalla sua chiave e restituisce il suo contenuto interpretato per una determinata locale. È l'equivalente indipendente dal framework dell'hook useIntlayer: stesso contenuto, stessi selettori, ma utilizzabile ovunque un contesto React non sia disponibile, script Node, funzioni server, route loader, generatori di metadati, handler Express/Fastify, test.

Legge i dizionari generati da Intlayer in .intlayer/, quindi l'argomento key è tipizzato e autocompleto dalle tue dichiarazioni di contenuto, e l'oggetto restituito è completamente tipizzato fino a ogni foglia.

Caratteristiche principali:

• Chiavi di dizionario tipizzate e contenuto restituito tipizzato
• Interpreta ogni nodo di contenuto (t(), enu(), cond(), insert(), nest(), md(), html(), file(), gender())
• Accetta una locale o un oggetto selettore (collezioni, varianti)
• I risultati sono memorizzati nella cache per key + locale + selector
• Ricade su un proxy sicuro in sviluppo quando un dizionario è mancante, invece di bloccarsi

Firma della Funzione

getIntlayer(
  key: DictionaryKeys,                        // Obbligatorio
  localeOrSelector?: LocalesValues | DictionarySelector, // Opzionale
  plugins?: Plugins[]                         // Opzionale
): DeepTransformContent<...>

Parametri

• key: DictionaryKeys

  • Descrizione: La chiave del dizionario da leggere, come dichiarato nei tuoi file di contenuto.
  • Tipo: DictionaryKeys, un'unione di ogni chiave di dizionario dichiarata.
  • Obbligatorio: Sì

• localeOrSelector: LocalesValues | DictionarySelector

  • Descrizione: La locale per interpretare il contenuto con, o un oggetto selettore per dizionari dinamici.
    • 'fr': una locale
    • { item: 2 }: un elemento collection (ometti item per ottenere ogni elemento come array)
    • { variant: 'black-friday' }: un variant denominato (ometti per quello default)
    • { variant: { id: 'prod_abc', userId: '123' } }: un variant strutturato
    • Qualsiasi selettore può portare una locale: { item: 2, locale: 'fr' }
  • Tipo: LocalesValues | DictionarySelector
  • Obbligatorio: No (opzionale). Se omessa, vedi Senza una locale.

• plugins: Plugins[]

  • Descrizione: Custom node transformers che sostituiscono i plugin dell'interprete base. Solo uso avanzato; omettilo per mantenere il comportamento predefinito.
  • Tipo: Plugins[]
  • Obbligatorio: No (opzionale)

Restituzioni

• Tipo: Il contenuto interpretato del dizionario, tipizzato dalla tua dichiarazione.
• Descrizione: Un oggetto semplice che rispecchia il campo content del tuo dizionario, dove ogni nodo Intlayer è stato risolto al suo valore finale per la locale richiesta.

Esempio di utilizzo

Utilizzo di Base

import { t, type Dictionary } from "intlayer";

const appContent = {
  key: "app",
  content: {
    title: t({
      it: "Ciao",
      en: "Hello",
      fr: "Bonjour",
    }),
  },
} satisfies Dictionary;

export default appContent;

import { getIntlayer } from "intlayer";

const { title } = getIntlayer("app", "it"); // "Ciao"

Senza una locale

Quando non viene passata alcuna locale, getIntlayer non ricade subito sulla locale predefinita. Risolve, in ordine:

1. La locale della richiesta corrente, sul server, quando un'integrazione Intlayer la gestisce: i middleware express-intlayer, fastify-intlayer, hono-intlayer, adonis-intlayer ed elysia-intlayer, i middleware remix-intlayer e astro-intlayer, e IntlayerProvider / setLocale nei React Server Components. Ogni richiesta viene risolta dai propri cookie e header, quindi utenti simultanei non condividono mai la locale.
2. La locale salvata nel browser (cookie, localStorage, sessionStorage), quella che un selettore di lingua rende persistente.
3. La defaultLocale dichiarata nella tua configurazione.

import { getIntlayer } from "intlayer";

const { title } = getIntlayer("app"); // Locale della richiesta, altrimenti quella salvata, altrimenti quella predefinita

La stessa risoluzione si applica a getDictionary, alle chiamate riscritte dai plugin di build e a useIntlayer / useDictionaryDynamic renderizzati fuori da un provider. Una locale passata esplicitamente ha sempre la precedenza.

getIntlayer non è reattiva: dopo un cambio di locale, richiamala per leggere la nuova locale. In una pagina renderizzata sul server, una chiamata fatta fuori da qualsiasi provider renderizza la locale predefinita sul server e quella salvata nel browser, il che può causare un hydration mismatch. In quel caso, monta il provider del tuo framework o passa la locale.

All'interno di un server handler

import { getIntlayer, getLocale } from "intlayer";

export const greetingHandler = async (request: Request) => {
  const locale = await getLocale({
    getHeader: (name) => request.headers.get(name) ?? undefined,
  });

  const { title } = getIntlayer("app", locale);

  return Response.json({ title });
};

Con un selettore (collezioni e varianti)

import { getIntlayer } from "intlayer";

// Un singolo elemento della collezione
const secondPost = getIntlayer("blog-post", { item: 2, locale: "fr" });

// Ogni elemento della collezione, come un array ordinato
const allPosts = getIntlayer("blog-post", { locale: "fr" });

// Una variante denominata
const banner = getIntlayer("banner", { variant: "black-friday", locale: "fr" });

Note sul comportamento

Caching

I risultati sono memoizzati in una cache a livello di modulo con chiave key + locale + selector. Chiamare getIntlayer("app", "fr") ripetutamente interpreta il dizionario una sola volta e restituisce lo stesso oggetto in seguito.

Dizionari mancanti

Durante lo sviluppo, richiedere una chiave che non ha un dizionario generato registra un avviso una volta e restituisce un proxy di fallback sicuro: leggere content.title produce la stringa "app.title" invece di generare un errore. Questo mantiene una pagina utilizzabile mentre la dichiarazione mancante viene corretta. Eseguire il build di Intlayer (o il server di sviluppo) affinché il dizionario sia generato.

Dimensione del bundle

getIntlayer legge il dizionario unito, che contiene ogni locale. Nei bundle client, i plugin di build riscrivono la chiamata in modo che solo il contenuto richiesto venga spedito. Quando leggi contenuto al di fuori del rendering (metadata, loader, funzioni server) e vuoi che una singola locale sia caricata su richiesta, usa invece getIntlayerAsync.

Funzioni Correlate

TypeScript

function getIntlayer<
  const T extends DictionaryKeys,
  const A extends LocalesValues | DictionarySelector = DeclaredLocales,
>(
  key: T,
  localeOrSelector?: A,
  plugins?: Plugins[]
): DeepTransformContent<
  DictionaryRegistryResult<T, A>,
  IInterpreterPluginState,
  ExtractSelectorLocale<A>
>;