Dokumentasi: Fungsi getIntlayer di intlayer

Deskripsi

Fungsi getIntlayer memilih satu kamus berdasarkan kuncinya dan mengembalikan isinya yang diinterpretasikan untuk lokal yang diberikan. Ini adalah pasangan yang independen dari kerangka kerja dari hook useIntlayer: konten yang sama, pemilih yang sama, tetapi dapat digunakan di mana pun konteks React tidak tersedia — skrip Node, fungsi server, pemuat rute, pembuat metadata, penangan Express/Fastify, tes.

Ini membaca kamus yang dihasilkan oleh Intlayer di .intlayer/, jadi argumen key diketik dan selesai otomatis dari deklarasi konten Anda sendiri, dan objek yang dikembalikan sepenuhnya diketik hingga setiap daun.

Fitur Utama:

• Kunci kamus yang diketik dan konten yang dikembalikan diketik
• Menginterpretasikan setiap node konten (t(), enu(), cond(), insert(), nest(), md(), html(), file(), gender())
• Menerima lokal atau objek pemilih (koleksi, varian)
• Hasil di-cache per key + locale + selector
• Kembali ke proksi yang aman dalam pengembangan ketika kamus hilang, alih-alih mengalami kegagalan

Function Signature

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

Parameter

• key: DictionaryKeys

  • Deskripsi: Kunci kamus yang akan dibaca, seperti yang dideklarasikan dalam file konten Anda.
  • Tipe: DictionaryKeys — sebuah union dari setiap kunci kamus yang dideklarasikan.
  • Diperlukan: Ya

• localeOrSelector: LocalesValues | DictionarySelector

  • Deskripsi: Locale untuk menginterpretasi konten dengan, atau objek selector untuk dynamic dictionaries.
    • 'fr' — sebuah locale
    • { item: 2 } — sebuah collection item (abaikan item untuk mendapatkan setiap item sebagai array)
    • { variant: 'black-friday' } — sebuah variant bernama (abaikan untuk yang default)
    • { variant: { id: 'prod_abc', userId: '123' } } — sebuah variant terstruktur
    • Setiap selector dapat membawa sebuah locale: { item: 2, locale: 'fr' }
  • Tipe: LocalesValues | DictionarySelector
  • Diperlukan: Tidak (Opsional) — default ke defaultLocale yang dikonfigurasi.

• plugins: Plugins[]

  • Deskripsi: Custom node transformers menggantikan plugin interpreter dasar. Penggunaan lanjutan saja; abaikan ini untuk mempertahankan perilaku default.
  • Tipe: Plugins[]
  • Diperlukan: Tidak (Opsional)

Returns

• Type: Konten dictionary yang diinterpretasi, diketik dari deklarasi Anda.
• Description: Objek biasa yang mencerminkan bidang content dari dictionary Anda, di mana setiap node Intlayer telah diselesaikan ke nilai akhirnya untuk locale yang diminta.

Contoh Penggunaan

Penggunaan Dasar

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

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

export default appContent;

import { getIntlayer } from "intlayer";

const { title } = getIntlayer("app", "fr"); // "Bonjour"

Tanpa locale

Menghilangkan locale menginterpretasi konten dengan defaultLocale yang dideklarasikan dalam konfigurasi Anda.

import { getIntlayer } from "intlayer";

const { title } = getIntlayer("app"); // Diinterpretasi dengan locale default

Di dalam 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 });
};

Dengan selector (koleksi dan varian)

import { getIntlayer } from "intlayer";

// Item koleksi tunggal
const secondPost = getIntlayer("blog-post", { item: 2, locale: "fr" });

// Setiap item dari koleksi, sebagai array yang terurut
const allPosts = getIntlayer("blog-post", { locale: "fr" });

// Varian bernama
const banner = getIntlayer("banner", { variant: "black-friday", locale: "fr" });

Catatan Perilaku

Caching

Hasil disimpan dalam cache tingkat modul dengan kunci key + locale + selector. Memanggil getIntlayer("app", "fr") berulang kali menginterpretasi dictionary sekali dan mengembalikan objek yang sama setelahnya.

Kamus yang Hilang

Dalam pengembangan, meminta kunci yang tidak memiliki kamus yang dihasilkan mencatat peringatan sekali dan mengembalikan proxy fallback yang aman: membaca content.title menghasilkan string "app.title" alih-alih melempar. Ini membuat halaman tetap dapat digunakan sementara deklarasi yang hilang diperbaiki. Jalankan build Intlayer (atau dev server) agar kamus dihasilkan.

Ukuran Bundle

getIntlayer membaca dictionary yang digabungkan, yang menyimpan setiap locale. Dalam client bundles, build plugins menulis ulang panggilan sehingga hanya konten yang diperlukan yang dikirim. Ketika Anda membaca konten di luar rendering (metadata, loaders, server functions) dan ingin satu locale dimuat sesuai permintaan, gunakan getIntlayerAsync sebagai gantinya.

Fungsi Terkait

• getIntlayerAsync: Counterpart async yang memuat satu chunk locale.
• getDictionary: Menginterpretasikan object dictionary yang Anda berikan sendiri, alih-alih yang dicari berdasarkan key.
• useIntlayer: Equivalent React hook, membaca locale dari provider.

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>
>;