Yeni Intlayer v9 - Yenilikler Neler?

Intlayer v9'a hoş geldiniz! Bu ana sürüm, büyük i18n kütüphaneleri (react-i18next, next-intl, vue-i18n vb.) için sunulan Compat Adapter Paketleri ile Intlayer'a geçiş sürecini basitleştirmede dev bir adımı temsil ediyor ve zengin içerik yapıları için destek ekliyor: Koleksiyonlar (Collections) ve Varyantlar (Variants).

İçindekiler

Compat Adapter Paketleri

Popüler i18n kütüphanelerinden Intlayer'a geçiş yapmak artık her zamankinden daha kolay. Standart i18n kütüphaneleriyle birebir aynı genel API'leri (public APIs) sunan ancak çalışma zamanında (runtime) tüm çeviri işlerini Intlayer'a devreden beş adet uyumluluk (compat) paketi oluşturduk.

Sıkı Tiplendirme ile Aynı Genel API'yi Sunma

İçe aktarmaları (imports) değiştirerek, minimum kod değişikliğiyle Intlayer'ın tüm avantajlarından (gerçek sözlüklerinize karşı derleme zamanı tip güvenliği dahil) yararlanabilirsiniz:

• @intlayer/i18next
• @intlayer/react-i18next
• @intlayer/next-intl
• @intlayer/react-intl
• @intlayer/next-i18next
• @intlayer/vue-i18n
• @intlayer/lingui

Örneğin, sadece şunu değiştirin:

import { useTranslation } from "react-i18next";

şuna:

import { useTranslation } from "@intlayer/react-i18next";

Anahtarlarınız artık Intlayer sözlüklerinize karşı sıkı bir şekilde tiplendirilecek (strictly typed) ve IDE'nizde tam nokta yolu (dot-path) otomatik tamamlama desteği sunacak!

Bundler Alias Eklentileri (Vite, Next.js, Turbopack)

Tüm içe aktarma ifadelerinizi manuel olarak yeniden yazmadan geçiş yapabilmenizi sağlamak için, her compat adapter paketi /plugin alt yolu altında özel bir bundler eklentisi (Vite veya Next.js) içerir.

Bu eklentiler, derleme zamanında (build time) mevcut içe aktarmaları (örneğin react-i18next veya next-intl) otomatik olarak @intlayer/* eşdeğerlerine dönüştürür.

Next.js (Webpack / Turbopack) Örneği

withIntlayer yerine, Next.js yapılandırmanızı compat eklentisi ile sarmalayın:

import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";import type { NextConfig } from "next";const withIntlayer = createNextI18nPlugin();const nextConfig: NextConfig = {};export default withIntlayer(nextConfig);

Vite (React, Vue, Solid, Svelte) Örneği

import vueI18nVitePlugin from "@intlayer/vue-i18n/plugin";export default defineConfig({  plugins: [vueI18nVitePlugin()],});

Ortaklaştırılmış Çalışma Zamanı Çözümleyicisi (Mutualized Runtime Resolver)

Tüm compat adapter'lar artık çeviri çözümlemesini tek ve son derece optimize edilmiş bir çalışma zamanı ayrıştırıcısı (runtime parser) üzerinden yönlendiriyor: @intlayer/core/messageFormat.

• Mesaj Değişkeni Ekleme (Interpolate Message): Standart {{var}} (boşluklar ve nokta yolları), ICU biçimlendirilmiş argümanlar ({v, number, percent} vb.) ve yalın {var} şablonlarını çözümler.
• Mesaj Düğümü Çözümleyici (Message Node Resolver): İç içe geçmiş düğümleri çözümler: insert(), plural() (CLDR çoğul kuralları), enu() (numaralandırma), gender(), HTML etiketleri, diziler ve çağrılabilir fonksiyon düğümleri.
• Tokenized Tag Parser: Zengin metin (rich-text) oluşturmayı kutudan çıktığı gibi desteklemek için satır içi XML/HTML etiketlerini ve numaralandırılmış etiketleri (örneğin, <1>children</1>) destekler.

Özellik Detayları: Koleksiyonlar ve Varyantlar

Intlayer v9, statik anahtar-değer nesnelerinin ötesine geçerek sözlüklerin uçtan uca tam tiplendirilmiş dinamik düzen yapıları tanımlamasına olanak tanır.

1. Koleksiyonlar (Collections)

CMS tarafından yönetilen sıralı öğelerin bir listesini tanımlayın (örneğin SSS'ler, ürünler veya blog listeleri):

import { t, type Dictionary } from "intlayer";export default {  key: "faq",  item: 1,  content: {    question: t({ en: "What is Intlayer?", fr: "Qu'est-ce qu'Intlayer ?" }),    answer: t({ en: "An i18n toolkit.", fr: "Une boîte à outils i18n." }),  },} satisfies Dictionary;

import { t, type Dictionary } from "intlayer";export default {  key: "faq",  item: 2,  content: {    question: t({ en: "Is it free?", fr: "Est-ce gratuit ?" }),    answer: t({ en: "Yes, open-source.", fr: "Oui, open-source." }),  },} satisfies Dictionary;

Kullanım:

// Fetch all items as an arrayconst allFaqs = useIntlayer("faq"); // -> { question: string, answer: string }[]// Fetch a single item by indexconst faq = useIntlayer("faq", { item: 2 }); // -> { question: string, answer: string }

2. Varyantlar (Variants)

A/B testleri, mevsimsel başlıklar, özellik bayrakları (feature flags) veya özel açılış sayfaları sunun:

Dize varyantları (örneğin, A/B testleri)

import { t, type Dictionary } from "intlayer";export default {  key: "hero-banner",  variant: "default",  content: {    control: t({ tr: "Hoş geldiniz", en: "Welcome", fr: "Bienvenue" }),    black_friday: t({      tr: "Şimdi alışveriş yap",      en: "Shop now",      fr: "Acheter maintenant",    }),  },} satisfies Dictionary;

Kullanım:

const banner = useIntlayer("hero-banner", { variant: "black_friday" });

Nesne varyantları (örneğin, Dinamik Kayıtlar)

import { t, type Dictionary } from "intlayer";export default {  key: "product-copy",  variant: {    id: "prod_123",    category: "books",  },  content: {    title: t({ tr: "Temiz Kod", en: "Clean Code", fr: "Code Propre" }),  },} satisfies Dictionary;

Kullanım:

// Yalnızca talep edilen öğeyi dinamik olarak getirir (Suspense gerektirir)const product = useIntlayer("product-copy", {  variant: { id: "prod_123", category: "books" },});

Vite Plugin: Bundled Compiler & Proxy

intlayer() Vite eklentisi artık compiler ve locale-routing proxy'i doğrudan içeriyor, bu nedenle çoğu proje vite.config.ts içinde yalnızca tek bir eklentiye ihtiyaç duyuyor:

import { defineConfig } from "vite";import { intlayer } from "vite-intlayer";export default defineConfig({  plugins: [intlayer()],});

• Compiler: compiler.enabled true olarak ayarlandığında ve compiler.output yolu yapılandırıldığında otomatik olarak etkinleştirilir. Artık intlayerCompiler()'ı ayrı olarak kaydetmeniz gerekmez.
• Proxy: Yeni routing.enableProxy seçeneğine göre otomatik olarak etkinleştirilir (varsayılan olarak true). Geliştirme, önizleme ve üretim SSR'de locale algılama / yönlendirme / yeniden yazma middleware'ini bağlar. Artık intlayerProxy()'ı ayrı olarak kaydetmeniz gerekmez.

routing.enableProxy seçeneği

Yeni routing.enableProxy seçeneği, locale-routing proxy'sinin bağlanıp bağlanmadığını kontrol eder. Varsayılan değer true'dur. Locale yönlendirmesini kendiniz işlemek istediğinizde devre dışı bırakın:

import type { IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  routing: {    enableProxy: false, // Varsayılan: true  },};export default config;

Bağımsız intlayerCompiler() ve intlayerProxy() eklentileri gelişmiş kurulumlar için dışa aktarılmaya devam eder. Bunları intlayer() ile birlikte kaydetmek güvenlidir — her eklenti kendisini çoğaltır ve yalnızca bir kez çalışır.

Derleyici varsayılan olarak devre dışı

Intlayer v9'dan itibaren, derleyici varsayılan olarak devre dışıdır (compiler.enabled artık varsayılan olarak false'tur). .content.ts dosyalarınızın derleme zamanı çıkarımını etkinleştirmek için yapılandırmanızda compiler.enabled: true olarak ayarlayın:

import type { IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  compiler: {    enabled: true, // Varsayılan: false — v9'dan itibaren derleyiciyi etkinleştirmek için gereklidir    output: ({ fileName }) => `./${fileName}.content.ts`,  },};export default config;

Derleyici devre dışı bırakıldığında, Intlayer derleme zamanı çıkarım adımını atlar ve önceden bildirdiğiniz sözlüklere dayanır. Yalnızca bundler eklentisinin (@intlayer/swc, @intlayer/babel veya intlayer() Vite eklentisi) içeriği otomatik olarak çıkarmasını istediğinizde etkinleştirin.

React Native: tek paket içe aktarmaları

Bir React Native veya Expo uygulamasında, artık react-intlayer ve react-native-intlayer arasında gidip gelmenize gerek yok. react-native-intlayer paketi artık tüm react-intlayer API'sini yeniden dışa aktarıyor (hook'lar, yardımcı programlar ve /format, /html ve /markdown alt yolları) ve IntlayerProvider'ı React Native polyfill'lerini otomatik olarak uyguluyor.

Her şeyi tek react-native-intlayer paketinden içe aktarın:

import {  IntlayerProvider,  useIntlayer,  useLocale,} from "react-native-intlayer";

npm install intlayer react-native-intlayer

react-intlayer'dan içe aktarmak çalışmaya devam eder, ancak react-native-intlayer artık React Native için önerilen tek giriş noktasıdır — sağlayıcısı, web odaklı react-intlayer sağlayıcısının sahip olmadığı polyfill'leri içerir.

CMS SDK: Intlayer'ı başsız içerik veritabanı olarak kullanın

Intlayer v9, CMS ile programatik olarak etkileşim kurmak için @intlayer/api içinde temiz ve kendi kendine kimlik doğrulayan bir SDK sunar — projeleri getirin, sözlükleri getirin ve bunları kendi sunucunuzdan, betiklerinizden veya CI'nizden gönderin ya da güncelleyin. Kimlik doğrulama (OAuth2 client_credentials) sizin için yönetilir ve yenilenir.

SDK iki ayrı içe aktarmaya bölünmüştür; böylece paketiniz yalnızca gerçekten kullandığınız alanları içerir:

1. createIntlayerCMS — kimlik bilgilerini ve yönetilen jetonu tutan hafif bir kimlik doğrulayıcı (hiçbir alan istemcisi pakete dahil edilmez).
2. dictionaryEndpoint, projectEndpoint, … — her biri kendi alt yolundan içe aktarılan, alan başına endpoint bağlayıcıları.

import { createIntlayerCMS } from "@intlayer/api";import { dictionaryEndpoint } from "@intlayer/api/dictionary";// Yapılandırma isteğe bağlıdır: kimlik bilgileri INTLAYER_CLIENT_ID /// INTLAYER_CLIENT_SECRET değerlerine geri döner (`@intlayer/config/built` tarafından çözülür).const cms = createIntlayerCMS();// Okumaconst { data: dictionaries } = await dictionaryEndpoint(cms).getDictionaries();// Yazma — CMS'i bir veritabanı gibi kullanınawait dictionaryEndpoint(cms).pushDictionaries([myDictionary]);

Güvenlik: CMS kimlik bilgileri içeriğinize yazma erişimi verir. Kimlik doğrulayıcıyı her zaman yalnızca sunucu tarafında oluşturun — clientId / clientSecret değerlerini asla tarayıcıya göndermeyin.

Kendi Sunucunuzda Barındırma

Intlayer v9, tek bir komutla kendi Intlayer örneğinizi çalıştırmak için birinci sınıf destek sunuyor — Intlayer Cloud hesabı gerekmez.

curl -fsSL https://intlayer.org/install.sh | sh

Yükleyici, bir docker-compose.yml ve bir .env dosyasını indirir, gerekli gizli anahtarları otomatik olarak oluşturur ve docker compose up -d komutunu çalıştırır. Kontrol paneli, API, veritabanı, nesne depolama ve işlemsel e-posta dahil her şey yerel olarak kapsayıcılarda çalışır.

v8'den Geçiş Notları

v8'den yükseltme yapıyorsanız, v9'un yıkıcı değişiklikler (breaking changes) içermediğini unutmayın. Ancak işte temel değişiklikler:

• Derleyici varsayılan olarak devre dışı: compiler.enabled artık varsayılan olarak false'tur. .content.ts dosyalarınızın derleme zamanı çıkarımına güveniyorsanız, intlayer.config.ts dosyanızda compiler.enabled: true olarak ayarlayın.
• Diller ve Lehçeler (Locales & Dialects): Harici i18n bağımlılıkları kullanıyorsanız, içe aktarmaları otomatik olarak yeniden yazmak için yapılandırmanıza veya bundler kurulumunuza ilgili compat adapter eklentilerini ekleyin.
• Özel Seçiciler (Custom Selectors): useIntlayer çağrılırken, ikinci parametre artık { locale, item, variant } içeren bir seçenek nesnesine ayrılmıştır. Daha önce doğrudan bir dil (locale) dizesi geçirdiyseniz bunu yapmaya devam edebilirsiniz, ancak gelişmiş seçimler için seçenekler nesnesini kullanmanız önerilir.

Faydalı bağlantılar

• Compat Adapter Paketleri Kılavuzu
• Dinamik Sözlükler - Koleksiyonlar ve Varyantlar
• Yapılandırma Referansı
• CMS SDK - @intlayer/api ile programatik erişim
• Kendi Sunucuda Barındırma Kılavuzu