Yeni Intlayer v7 - Yenilikler Neler?

Intlayer v7'ye hoş geldiniz! Bu büyük sürüm, performans, tür güvenliği ve geliştirici deneyiminde önemli iyileştirmeler sunuyor. Aşağıda, geçiş notları ve pratik örneklerle birlikte öne çıkanlar yer almaktadır.

İçindekiler

Öne Çıkanlar

• Daha hızlı derlemeler için önbellekleme stratejisi
• Yerel dil türlerine göre geliştirilmiş TypeScript türü oluşturma
• Paket optimizasyonu: Enum yerine string olarak yereller
• Yeni yönlendirme modları: prefix-no-default, prefix-all, no-prefix, search-params
• GDPR uyumlu yerel depolama, varsayılan olarak localStorage kullanımı
• Esnek depolama yapılandırması: çerezler, localStorage, sessionStorage veya birden fazla
• Görsel Düzenleyici bundle boyutunda %30 küçülme
• Geliştirilmiş ara katman (middleware) yapılandırma seçenekleri
• Daha iyi içerik yönetimi için güncellenmiş fill komutu davranışı
• Tam içerik beyan dosyası güncellemeleri ile artırılmış kararlılık
• Çeviri doğruluğu için akıllı yeniden deneme yönetimi
• Daha hızlı çeviri işlemi için paralelleştirme
• AI bağlam sınırları içinde büyük dosyaları yönetmek için akıllı parçalara ayırma

Performans: Daha hızlı derlemeler için önbellekleme

Her derlemede esbuild ile içerik beyanlarını yeniden oluşturmak yerine, v7 derleme sürecini hızlandıran bir önbellekleme stratejisi uygular.

npx intlayer build

Yeni önbellekleme sistemi:

• Derlenmiş içerik beyanlarını saklayarak gereksiz işlemleri önler
• Değişiklikleri algılar ve sadece değiştirilmiş dosyaları yeniden oluşturur
• Büyük projelerde derleme sürelerini önemli ölçüde azaltır

TypeScript: Yerel dil bazlı tür oluşturma

TypeScript türleri artık her yerel dil için ayrı ayrı oluşturulmakta, böylece daha güçlü türlendirme sağlanmakta ve tüm yereller arasında birleşik türler ortadan kaldırılmaktadır.

v6 davranışı:

const content = getIntlayer("my-title-content", "en");
// typeof content = { title: "My title" } | { title: "Mon titre" } | { title: "Mi título" }

v7 davranışı:

const content = getIntlayer("my-title-content", "en");
// typeof content = { title: "Başlığım" }

Faydalar:

• IDE'nizde daha hassas otomatik tamamlama
• Yereller arası tür kirliliği olmadan daha iyi tür güvenliği
• Tür karmaşıklığını azaltarak geliştirilmiş performans

Paket optimizasyonu: Yereller string olarak

Locales türü artık bir enum değil, bu da tamamen tree-shakeable olduğu ve binlerce kullanılmayan yerel kayıtla paketinizin şişmesini engellediği anlamına gelir.

v6:

import { Locales } from "intlayer";
// Tüm yerelleri içeren enum -> tree-shakeable değil

const locale: Locales = Locales.ENGLISH;

v7:

import { Locales, Locale } from "intlayer";
// String türü -> tamamen tree-shakeable

const locale: Locale = Locales.ENGLISH;

Çünkü Locales artık bir enum değil, yerel türü olarak almak için türü Locales'den Locale'a değiştirmeniz gerekecek.

Daha fazla bilgi için uygulama detaylarına bakınız.

Daha fazla esneklik için yeni yönlendirme modları

v7, önceki prefixDefault ve noPrefix seçeneklerinin yerini alan birleşik bir routing.mode yapılandırması sunar ve URL yapısı üzerinde daha ayrıntılı kontrol sağlar.

Mevcut yönlendirme modları

• prefix-no-default (varsayılan): Varsayılan yerel için önek yok, diğer yerellerde var
  • /dashboard (en) veya /fr/dashboard (fr)
• prefix-all: Tüm yerellerde önek var
  • /en/dashboard (en) veya /fr/dashboard (fr)
• no-prefix: URL'lerde yerel önek yok (yerel ayar depolama/başlıklar aracılığıyla yönetilir)
  • Tüm yereller için /dashboard
• search-params: Yerel ayar sorgu parametresi olarak iletilir
  • /dashboard?locale=en veya /dashboard?locale=fr

Temel yapılandırma

// intlayer.config.ts
export default {
  internationalization: {
    locales: ["en", "fr", "es"],
    defaultLocale: "en",
  },
  routing: {
    mode: "prefix-no-default", // varsayılan
  },
};

GDPR uyumluluğu: localStorage / çerez depolama

v7, kullanıcı gizliliğini ön planda tutarak varsayılan depolama mekanizması olarak çerezler yerine localStorage kullanır. Bu değişiklik, yerel tercihleri için çerez onayı gereksinimini ortadan kaldırarak GDPR uyumluluğuna yardımcı olur.

Depolama yapılandırma seçenekleri

Yeni routing.storage alanı, önceki middleware.cookieName ve middleware.serverSetCookie seçeneklerine ek olarak kullanılabilir durumdadır ve esnek depolama yapılandırmaları sunar:

// Depolamayı devre dışı bırak
storage: false

// Basit depolama türleri
storage: 'cookie'
storage: 'localStorage'
storage: 'sessionStorage'

// Özel özelliklere sahip çerez
storage: {
  type: 'cookie',
  name: 'custom-locale',
  domain: '.example.com',
  secure: true,
  sameSite: 'strict'
}

// Özel anahtarla localStorage
storage: {
  type: 'localStorage',
  name: 'custom-locale'
}

// Yedeklilik için birden fazla depolama türü
storage: ['cookie', 'localStorage']

GDPR uyumlu yapılandırma örneği

Fonksiyonellik ile GDPR uyumluluğunu dengelemek zorunda olan üretim uygulamaları için:

// intlayer.config.ts
export default {
  internationalization: {
    locales: ["en", "fr", "es"],
    defaultLocale: "en",
  },
  routing: {
    mode: "prefix-no-default",
    storage: [
      {
        type: "localStorage", // Birincil depolama (izin gerekmez)
        name: "user-locale",
      },
      {
        type: "cookie", // Opsiyonel çerez depolama (izin gerektirir)
        name: "user-locale",
        secure: true,
        sameSite: "strict",
        httpOnly: false,
      },
    ],
  },
};

Çerez depolamasını etkinleştirme / devre dışı bırakma

React / Next.js kullanarak örnek:

Genel olarak tanımlanabilir:

<IntlayerProvider isCookieEnabled={false}>
  <App />
</IntlayerProvider>

Her hook için yerel olarak geçersiz kılınabilir:

const { setLocale } = useLocale({ isCookieEnabled: false });

setLocale("en");

Not: Çerezler varsayılan olarak etkinleştirilmiştir. Not: Özel kullanım durumunuz için GDPR çerez gereksinimlerini kontrol edin.

Görsel Düzenleyici: %30 daha küçük paket

Görsel Düzenleyici paketi, önceki sürüme göre %30 daha küçük olacak şekilde optimize edilmiştir, bunun sebepleri:

• Kod düzenleyici performans iyileştirmeleri
• Intlayer çekirdek paketlerine olan gereksiz bağımlılıkların kaldırılması
• Daha iyi tree-shaking ve modül paketleme

Bu, uygulamanız için daha hızlı indirme süreleri ve geliştirilmiş çalışma zamanı performansı sağlar.

Otomatik Kod Biçimlendirmesi: formatCommand configuration

v7, editör yapılandırmasında formatCommand seçeneğini tanıtarak, Intlayer tarafından yazıldığında içerik dosyalarını otomatik olarak biçimlendirmenizi sağlar. Bu, içerik bildirimi dosyalarınız arasında tutarlı kod stili ve biçimlendirmesini sağlar.

Ayarlanmadığında, Intlayer biçim komutunu otomatik olarak algılamaya çalışacaktır. Şu komutları çözmeyi deneyerek: prettier, biome, eslint.

Konfigürasyon

formatCommand seçeneği, {{file}} ifadesinin gerçek dosya yolu ile değiştirildiği bir string şablonunu kabul eder:

export default {
  content: {
    formatCommand: 'bun x biome format "{{file}}" --write --log-level none',
  },
};

Desteklenen formatters

Dosya yollarını argüman olarak kabul eden herhangi bir kod formatteri kullanabilirsiniz:

Biome kullanarak:

formatCommand: 'bun x biome format "{{file}}" --write --log-level none';

Prettier kullanarak:

formatCommand: 'npx prettier --write "{{file}}" --log-level silent';

ESLint kullanarak:

formatCommand: 'npx eslint --fix "{{file}}" --quiet';

Bun'ın yerleşik formatteri kullanarak:

formatCommand: 'bun format "{{file}}"';

Faydalar

• Tutarlı biçimlendirme: Tüm içerik dosyaları, projenizin stil yönergelerine göre otomatik olarak biçimlendirilir
• Geliştirici deneyimi: Intlayer dosyaları yazdıktan sonra dosyaları manuel olarak biçimlendirmeye gerek yoktur
• Takım tutarlılığı: Tüm takım üyelerinin içerik dosyalarına aynı biçimlendirmenin uygulanmasını sağlar
• CI/CD entegrasyonu: İçerik dosyaları, otomatik iş akışlarında tutarlı biçimlendirmeyi korur

Nasıl çalışır

Intlayer bir içerik bildirimi dosyasını (.content.ts, .content.js, vb.) yazdığında veya güncellediğinde, dosya üzerinde belirtilen format komutunu otomatik olarak çalıştırır. {{file}} yer tutucu gerçek dosya yolu ile değiştirilir ve komut projenin temel dizininde yürütülür.

Sözlük Yapılandırması: Daha İyi Organizasyon ve Yapı

v7, sözlük ile ilgili ayarlar için daha iyi bir organizasyon ve geliştirilmiş içerik yönetimi sağlayan yeni bir adanmış dictionary yapılandırma bölümü sunar.

Yeni dictionary yapılandırması

fill özelliği, content bölümünden yeni dictionary bölümüne taşınmış, sorumlulukların daha net bir şekilde ayrılmasını sağlamıştır:

v6 yapılandırması:

export default {
  content: {
    autoFill: "./{{fileName}}.content.json",
    contentDir: ["src"],
  },
};

v7 yapılandırması:

export default {
  content: {
    contentDir: ["src"],
  },
  dictionary: {
    fill: "./{{fileName}}.content.json",
  },
};

Yeni yapının faydaları

• Daha net organizasyon: Sözlüğe özgü ayarlar artık bir arada gruplandırılıyor
• Daha iyi sorunların ayrılması: İçerik keşfi vs. sözlük işlemleri açıkça ayrılıyor
• Geliştirilmiş bakım kolaylığı: Sözlükle ilgili konfigürasyonları anlamak ve değiştirmek daha kolay
• Gelecekteki genişletilebilirlik: Sözlük bölümü ek sözlüğe özgü ayarları barındırabiliyor
• Kapsamlı sözlük yönetimi: Yeni sözlükler oluşturmak ve yönetmek için title, live, priority, tags, version ve description gibi özellikleri içeriyor

Yapılandırma kullanımı

Sözlük yapılandırması iki ana amaca hizmet eder:

1. Varsayılan Değerler: İçerik bildirim dosyaları oluştururken varsayılan değerleri tanımlama
2. Fallback Davranışı: Belirli alanlar tanımlanmadığında fallback değerleri sağlama, sözlük işlem davranışını global olarak tanımlamanıza izin verme

Sözlük bölümü, sözlük yönetimi için kapsamlı özellikler içerir:

• fill: İçerik oluşturma için otomatik doldurma davranışı
• title: Yeni sözlükler için varsayılan başlık
• live: Gerçek zamanlı güncellemeler için live senkronizasyon yapılandırması
• priority: Sözlük çözümlemesi için öncelik ayarları
• tags: İçerik organizasyonu için varsayılan etiketler
• version: Sözlük güncellemeleri için sürüm yönetimi
• description: Yeni içerik için varsayılan açıklama

İçerik bildirim dosyaları ve yapılandırma değerlerinin nasıl uygulandığı hakkında daha fazla bilgi için bkz. İçerik Dosyası Belgeleri.

Fill komutu: Daha iyi içerik yönetimi için güncellenmiş davranış

v7, fill komutu için daha öngörülebilir ve esnek içerik yönetimi sağlayan geliştirilmiş bir davranış sunar:

Yeni fill davranışı

• fill: true - Tüm yereller için doldurulmuş içerikle mevcut dosyayı yeniden yazar
• fill: "path/to/file" - Mevcut dosyayı değiştirmeden belirtilen dosyayı doldurur
• fill: false - Otomatik doldurmayı tamamen devre dışı bırakır

Karmaşık içerik yapıları için geliştirilmiş destek

Fill komutu artık aşağıdakiler dahil karmaşık içerik beyanı yapılarını desteklemektedir:

• Bileşik nesneler: Diğer nesnelere referans veren içerik beyanları
• Yapı bozma (destructuring) içeriği: Yapı bozma desenleri kullanan içerik
• İç içe referanslar: Karmaşık hiyerarşilerde birbirini çağıran nesneler
• Dinamik içerik yapıları: Koşullu veya hesaplanmış özelliklere sahip içerik

Faydalar

• Daha net niyet: Davranış artık neyin değiştirildiği konusunda daha açık
• Daha iyi ayrım: İçerik dosyaları, doldurulmuş çevirilerden ayrı tutulabilir
• Geliştirilmiş iş akışı: Geliştiriciler, çevirilerin nerede saklanacağı üzerinde daha fazla kontrole sahiptir
• Karmaşık yapı desteği: Birbirine bağlı birden fazla nesne içeren karmaşık içerik mimarilerini yönetir

Örnek kullanım

// Mevcut dosyayı tüm yerellerle yeniden yaz
const content = {
  key: "example",
  fill: true, // Bu dosyayı yeniden yazar
  content: {
    title: "Hello World",
  },
};

// Mevcut dosyayı değiştirmeden ayrı dosyayı doldur
const content = {
  key: "example",
  fill: "./translations.json", // translations.json dosyasını oluşturur/günceller
  content: {
    title: "Hello World",
  },
};

// Otomatik doldurmayı devre dışı bırak
const content = {
  key: "example",
  fill: false, // Otomatik doldurma yok
  content: {
    title: "Merhaba Dünya",
  },
};

// Bileşik nesnelerle karmaşık içerik yapısı
const sharedContent = {
  buttons: {
    save: "Kaydet",
    cancel: "İptal",
  },
};

const content = {
  key: "karmaşık-örnek",
  fill: true,
  content: {
    // Diğer nesnelere referanslar
    sharedContent,

    // Yapılandırılmış içerik
    ...sharedContent,

    // İç içe referanslar
    sections: [
      {
        ...sharedContent.buttons,
        header: "Bölüm 1",
      },
    ],
  },
};

Geliştirilmiş kararlılık ve çeviri yönetimi

v7, içerik çevirisini daha güvenilir ve verimli hale getirmek için birkaç iyileştirme sunar:

Tam içerik beyan dosyası güncellemeleri

Sistem artık kısmi güncellemeler yerine .content.{ts,js,cjs,mjs} dosyalarını günceller, böylece şunları sağlar:

• Veri bütünlüğü: Tam dosya yeniden yazımları, içeriğin bozulmasına yol açabilecek kısmi güncellemeleri engeller
• Tutarlılık: Tüm yereller atomik olarak güncellenir, senkronizasyon korunur
• Güvenilirlik: Eksik veya hatalı içerik dosyası riskini azaltır

Akıllı yeniden deneme yönetimi

Yeni yeniden deneme mekanizmaları, içeriğin yanlış formatlarda gönderilmesini önler ve bir isteğin başarısız olması durumunda tüm doldurma sürecinin kırılmasını engeller.

Daha hızlı işlem için paralelleştirme

Çeviri işlemleri artık paralel çalıştırılmak üzere bir kuyruğa alınır. Bu, süreci önemli ölçüde hızlandırır.

Büyük dosyalar için akıllı parçalara ayırma

Gelişmiş parçalara ayırma stratejileri, AI bağlam pencerelerini aşmadan büyük içerik dosyalarını yönetir:

Örnek iş akışı

// Büyük içerik dosyası otomatik olarak parçalara ayrılır
const content = {
  key: "large-documentation",
  fill: true,
  content: {
    // AI işleme için büyük içerik otomatik olarak parçalara ayrılır
    introduction: "..." // 5000+ karakter
    sections: [
      // Birden çok büyük bölüm
    ]
  }
};

Sistem otomatik olarak:

1. İçerik boyutunu ve yapısını analiz eder
2. İçeriği uygun şekilde parçalara böler
3. Parçaları paralel olarak işler
4. Gerekirse doğrulama yapar ve yeniden dener
5. Tam dosyayı yeniden oluşturur

v6'dan geçiş notları

Kaldırılan yapılandırmalar

• middleware.cookieName: routing.storage ile değiştirildi
• middleware.serverSetCookie: routing.storage ile değiştirildi
• middleware.prefixDefault: routing.mode ile değiştirildi
• middleware.noPrefix: routing.mode ile değiştirildi

Yeni konfigürasyonlar

• editor.formatCommand: İçerik dosyalarının otomatik kod formatlaması için yeni seçenek

Geçiş eşlemesi

Konfigürasyon eşlemesi

Örnek geçiş

Önce (v6):

export default {
  middleware: {
    headerName: "x-intlayer-locale",
    cookieName: "intlayer-locale",
    prefixDefault: false,
    basePath: "",
    serverSetCookie: "always",
    noPrefix: false,
  },
};

Sonra (v7):

export default {
  routing: {
    mode: "prefix-no-default",
    storage: "localStorage", // veya çerez depolama gerekiyorsa 'cookie'
    headerName: "x-intlayer-locale",
    basePath: "",
  },
};

Sözlük içerik eşlemesi

Örnek geçiş

Önce (v6):

const content = {
  key: "example",
  autoFill: true, // Bu dosyayı yeniden yazar
  content: {
    title: "Merhaba Dünya",
  },
};

Sonrası (v7):

const content = {
  key: "example",
  fill: true, // Bu dosyayı yeniden yazar
  content: {
    title: "Merhaba Dünya",
  },
};

v5'ten v6'ya Geçiş Notları

Daha fazla bilgi için v5'ten v6'ya geçiş notlarını kontrol edin.

Faydalı bağlantılar

• Yapılandırma Referansı
• Middleware Dokümantasyonu
• TypeScript Türleri
• GDPR Çerez Rehberi