Belgelendirme: intlayer'de getIntlayer Fonksiyonu

Açıklama

getIntlayer işlevi bir anahtar (key) ile bir sözlüğü seçer ve içeriğini belirli bir yerel ayar için yorumlanmış şekilde döndürür. useIntlayer hook'unun framework-agnostik karşılığıdır: aynı içerik, aynı seçiciler, ancak React context'in kullanılamadığı her yerde kullanılabilir, Node scriptleri, server işlevleri, route loaders, metadata builders, Express/Fastify handlers, testler.

Intlayer tarafından .intlayer/ içinde oluşturulan sözlükleri okur, bu nedenle key argümanı sizin kendi içerik bildirimlerinizden türü belirlenmiş ve otomatik tamamlanmıştır, ve döndürülen nesne her yaprakta tam olarak türü belirlenmiştir.

Ana Özellikler:

• Türü belirlenmiş sözlük anahtarları ve türü belirlenmiş döndürülen içerik
• Her içerik düğümünü yorumlar (t(), enu(), cond(), insert(), nest(), md(), html(), file(), gender())
• Yerel ayarı veya seçici nesnesini kabul eder (koleksiyonlar, varyantlar)
• Sonuçlar key + locale + selector başına bellekte tutulur
• Geliştirme sırasında sözlük eksik olduğunda, kilitlenmek yerine güvenli bir proxy'ye geri döner

Fonksiyon İmzası

getIntlayer(
  key: DictionaryKeys,                        // Gerekli
  localeOrSelector?: LocalesValues | DictionarySelector, // İsteğe bağlı
  plugins?: Plugins[]                         // İsteğe bağlı
): DeepTransformContent<...>

Parametreler

• key: DictionaryKeys

  • Açıklama: İçerik dosyalarınızda bildirilen sözlüğün anahtarı.
  • Tür: DictionaryKeys, bildirilen her sözlük anahtarının birleşimi.
  • Gerekli: Evet

• localeOrSelector: LocalesValues | DictionarySelector

  • Açıklama: İçeriği yorumlamak için kullanılacak yerel ayar veya dinamik sözlükler için bir seçici nesnesi.
    • 'fr': bir yerel ayar
    • { item: 2 }: bir koleksiyon öğesi (item öğesini atlayarak tüm öğeleri dizi olarak alabilirsiniz)
    • { variant: 'black-friday' }: adlandırılmış bir varyant (varsayılan olanı almak için atlayın)
    • { variant: { id: 'prod_abc', userId: '123' } }: yapılandırılmış bir varyant
    • Herhangi bir seçici yerel ayar taşıyabilir: { item: 2, locale: 'fr' }
  • Tür: LocalesValues | DictionarySelector
  • Gerekli: Hayır (İsteğe bağlı). Verilmezse Locale olmadan bölümüne bakın.

• plugins: Plugins[]

  • Açıklama: Temel yorumlayıcı eklentilerinin yerini alan özel düğüm dönüştürücüleri. Yalnızca ileri kullanım için; varsayılan davranışı korumak için atlayın.
  • Tür: Plugins[]
  • Gerekli: Hayır (İsteğe bağlı)

Döndürülen Değerler

• Tür: Sözlüğünüzün deklarasyonundan yazılan, yorumlanan içerik.
• Açıklama: Sözlüğünüzün content alanını yansıtan düz bir nesne; burada her Intlayer düğümü, istenen locale için nihai değerine çözülmüştür.

Örnek Kullanım

Temel Kullanım

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

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

export default appContent;

import { getIntlayer } from "intlayer";

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

Locale olmadan

Hiçbir locale verilmediğinde getIntlayer doğrudan varsayılan locale'e düşmez. Sırasıyla şunları çözümler:

1. Geçerli isteğin locale'i, sunucuda, isteği bir Intlayer entegrasyonu işlediğinde: express-intlayer, fastify-intlayer, hono-intlayer, adonis-intlayer ve elysia-intlayer middleware'leri, remix-intlayer ve astro-intlayer middleware'leri ve React Server Components içindeki IntlayerProvider / setLocale. Her istek kendi cookie'lerinden ve header'larından çözümlenir, bu nedenle eşzamanlı kullanıcılar asla aynı locale'i paylaşmaz.
2. Tarayıcıda saklanan locale (cookie, localStorage, sessionStorage), yani bir dil değiştiricinin kaydettiği locale.
3. Yapılandırmanızda tanımlanan defaultLocale.

import { getIntlayer } from "intlayer";

const { title } = getIntlayer("app"); // İsteğin locale'i, yoksa saklanan, yoksa varsayılan locale

Aynı çözümleme getDictionary için, build eklentilerinin yeniden yazdığı çağrılar için ve bir provider dışında render edilen useIntlayer / useDictionaryDynamic için de geçerlidir. Açıkça verilen bir locale her zaman önceliklidir.

getIntlayer reaktif değildir: bir locale değişikliğinden sonra yeni locale'i okumak için onu tekrar çağırın. Sunucuda render edilen bir sayfada, herhangi bir provider dışında yapılan bir çağrı sunucuda varsayılan locale'i, tarayıcıda ise saklanan locale'i render eder ve bu bir hydration mismatch'e yol açabilir. Bu durumda framework'ünüzün provider'ını ekleyin veya locale'i verin.

Bir sunucu işleyicisinin içinde

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

Seçici ile (collections ve variants)

import { getIntlayer } from "intlayer";

// Bir collection öğesi
const secondPost = getIntlayer("blog-post", { item: 2, locale: "fr" });

// Collection'ın tüm öğeleri, sıralı bir dizi olarak
const allPosts = getIntlayer("blog-post", { locale: "fr" });

// Adlandırılmış bir variant
const banner = getIntlayer("banner", { variant: "black-friday", locale: "fr" });

Davranış Notları

Önbellekleme

Sonuçlar, key + locale + selector ile anahtarlanan bir modül seviyesi önbelleğinde memoize edilir. getIntlayer("app", "fr") işlemini tekrar tekrar çağırmak sözlüğü bir kez yorumlar ve daha sonra aynı nesneyi döndürür.

Eksik sözlükler

Geliştirme sırasında, oluşturulmuş bir sözlüğü olmayan bir anahtarı istediğinizde, bir uyarı bir kez kaydedilir ve güvenli bir fallback proxy döndürülür: content.title öğesini okuduğunuzda hata atmak yerine "app.title" dizesini verir. Bu, eksik bildirim düzeltilirken bir sayfanın kullanılabilir kalmasını sağlar. Sözlüğün oluşturulması için Intlayer build'ini (veya geliştirme sunucusunu) çalıştırın.

Bundle boyutu

getIntlayer birleştirilmiş sözlüğü okur; bu sözlük her locale'i içerir. İstemci bundle'larında, build eklentileri çağrıyı yeniden yazarak yalnızca gerekli içeriğin gönderilmesini sağlar. Rendering dışında içerik okuyorsanız (metadata, loaders, server functions) ve talep üzerine tek bir locale yüklenmesini istiyorsanız, bunun yerine getIntlayerAsync kullanın.

İlgili Fonksiyonlar

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