i18n Bundle Boyutu ve Performans Optimizasyonu

JSON dosyalarına dayalı geleneksel i18n çözümlerindeki en yaygın zorluklardan biri içerik boyutunu yönetmektir. Geliştiriciler içeriği manuel olarak ad alanlarına (namespaces) ayırmazlarsa, kullanıcılar genellikle tek bir sayfayı görüntülemek için her sayfanın ve potansiyel olarak her dilin çevirilerini indirmek zorunda kalırlar.

Örneğin, 10 dilde çevrilmiş 10 sayfası olan bir uygulama, kullanıcının sadece bir sayfaya (mevcut dildeki mevcut sayfa) ihtiyacı olmasına rağmen 100 sayfalık içerik indirmesine neden olabilir. Bu durum bant genişliği israfına ve daha yavaş yükleme sürelerine yol açar.

Intlayer bu sorunu build zamanı optimizasyonu ile çözer. Her bileşen başına hangi sözlüklerin gerçekten kullanıldığını tespit etmek için kodunuzu analiz eder ve bundle'ınıza yalnızca gerekli içeriği yeniden yerleştirir.

İçindekiler

Bundle'ınızı Tarayın

Bundle'ınızı analiz etmek, "ağır" JSON dosyalarını ve kod bölme (code-splitting) fırsatlarını belirlemenin ilk adımıdır. Bu araçlar, uygulamanızın derlenmiş kodunun görsel bir ağaç haritasını (treemap) oluşturarak hangi kütüphanelerin en çok yer kapladığını tam olarak görmenizi sağlar.

npm install -D rollup-plugin-visualizer

import { defineConfig } from "vite";import { visualizer } from "rollup-plugin-visualizer";export default defineConfig({ plugins: [   visualizer({     open: true, // Raporu tarayıcınızda otomatik olarak aç     filename: "stats.html",     gzipSize: true,     brotliSize: true,   }), ],});

npx next experimental-analyze

npm install -D @next/bundle-analyzer

const withBundleAnalyzer = require("@next/bundle-analyzer")({ enabled: process.env.ANALYZE === "true",});module.exports = withBundleAnalyzer({ // Next.js yapılandırmanız});

ANALYZE=true npm run build

npm install -D webpack-bundle-analyzer

import { BundleAnalyzerPlugin } from "webpack-bundle-analyzer";export default { plugins: [   new BundleAnalyzerPlugin({     analyzerMode: "static",     reportFilename: "bundle-analyzer.html",     openAnalyzer: false,   }), ],};

Nasıl Çalışır?

Intlayer, bileşen başına yaklaşımı kullanır. Global JSON dosyalarının aksine içeriğiniz, bileşenlerinizin yanında veya içinde tanımlanır. Build süreci sırasında Intlayer:

1. useIntlayer çağrılarını bulmak için kodunuzu analiz eder.
2. Karşılık gelen sözlük içeriğini oluşturur.
3. useIntlayer çağrısını yapılandırmanıza bağlı olarak optimize edilmiş kodla değiştirir.

Bu şu avantajları sağlar:

• Bir bileşen içe aktarılmazsa, içeriği bundle'a dahil edilmez (Gereksiz Kod Ayıklama - Dead Code Elimination).
• Bir bileşen geç yüklenirse (lazy-loaded), içeriği de geç yüklenir.

Platforma Göre Kurulum

npm install -D @intlayer/swc

npm install -D @intlayer/babel

const { getOptimizePluginOptions, intlayerOptimizeBabelPlugin,} = require("@intlayer/babel");module.exports = { plugins: [[intlayerOptimizeBabelPlugin, getOptimizePluginOptions()]],};

Yapılandırma

Intlayer'ın bundle'ınızı nasıl optimize edeceğini intlayer.config.ts dosyanızdaki build özelliği aracılığıyla kontrol edebilirsiniz.

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH, Locales.FRENCH],    defaultLocale: Locales.ENGLISH,  },  dictionary: {    importMode: "dynamic",  },  build: {    /**     * Bundle boyutunu küçültmek için sözlükleri minify et.     */     minify: true;    /**     * Sözlüklerdeki kullanılmayan anahtarları temizle (purge)     */     purge: true;    /**     * Build'in TypeScript tiplerini kontrol edip etmeyeceğini belirtir     */    checkTypes: false;  },};export default config;

Çoğu durumda optimize seçeneğini varsayılan halinde bırakmanız önerilir.

Daha fazla detay için yapılandırma dökümanına bakın: Yapılandırma

Build Seçenekleri

build yapılandırma nesnesi altında aşağıdaki seçenekler mevcuttur:

Küçültme (Minification)

Sözlükleri küçültmek gereksiz boşlukları, yorumları temizler ve JSON içeriğinin boyutunu azaltır. Bu, özellikle büyük sözlükler için çok faydalıdır.

import type { IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  build: {    minify: true,  },};export default config;

Not: optimize devre dışıysa veya Visual Editor etkinse (editörün düzenleme yapmak için tam içeriğe ihtiyacı olduğundan) küçültme yoksayılır.

Temizleme (Purging)

Temizleme, yalnızca kodunuzda gerçekten kullanılan anahtarların nihai sözlük paketine dahil edilmesini sağlar. Uygulamanızın her yerinde kullanılmayan birçok anahtara sahip büyük sözlükleriniz varsa, bu özellik bundle boyutunu önemli ölçüde azaltabilir.

import type { IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  build: {    purge: true,  },};export default config;

Not: optimize devre dışıysa temizleme yoksayılır.

İçe Aktarma Modu (Import Mode)

Birkaç sayfa ve dil içeren büyük uygulamalarda, JSON dosyalarınız bundle boyutunuzun önemli bir kısmını oluşturabilir. Intlayer, sözlüklerin nasıl yükleneceğini kontrol etmenize olanak tanır.

İçe aktarma modu varsayılan olarak intlayer.config.ts dosyanızda global olarak tanımlanabilir.

import type { IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  build: {    minify: true,  },};export default config;

Ayrıca her bir sözlük için .content.{{ts|tsx|js|jsx|mjs|cjs|json|jsonc|json5}} dosyalarınızda da tanımlanabilir.

import { type Dictionary, t } from "intlayer";const appContent: Dictionary = {  key: "app",  importMode: "dynamic", // Varsayılan içe aktarma modunu geçersiz kıl  content: {    // ...  },};export default appContent;

importMode ayarı, sözlük içeriğinin bileşeninize nasıl enjekte edileceğini belirler. Bunu intlayer.config.ts dosyasında dictionary nesnesi altında global olarak tanımlayabilir veya belirli bir sözlük için .content.ts dosyasında geçersiz kılabilirsiniz.

1. Statik Mod (default)

Statik modda Intlayer, useIntlayer yöntemini useDictionary ile değiştirir ve sözlüğü doğrudan JavaScript bundle'ına enjekte eder.

• Artıları: Anında işleme (senkron), hidratasyon sırasında fazladan ağ isteği yok.
• Eksileri: Bundle, o belirli bileşen için tüm dillerdeki çevirileri içerir.
• En iyi kullanım alanı: Tek Sayfa Uygulamaları (SPA).

Dönüştürülmüş Kod Örneği:

// Sizin kodunuzconst content = useIntlayer("my-key");// Optimize edilmiş kod (Statik)const content = useDictionary({  key: "my-key",  content: {    nodeType: "translation",    translation: {      en: "My title",      fr: "Mon titre",    },  },});

2. Dinamik Mod

Dinamik modda Intlayer, useIntlayer yöntemini useDictionaryAsync ile değiştirir. Bu, mevcut dile özel JSON'u geç yüklemek (lazy-load) için import() (Suspense benzeri mekanizma) kullanır.

• Artıları: Dil düzeyinde tree shaking. İngilizce versiyonunu görüntüleyen bir kullanıcı yalnızca İngilizce sözlüğü indirir. Fransızca sözlüğü asla yüklenmez.
• Eksileri: Hidratasyon sırasında bileşen başına bir ağ isteği (varlık getirme) tetikler.
• En iyi kullanım alanı: Bundle boyutunun kritik olduğu çok sayıda dil desteği sağlayan sayfalar veya büyük metin blokları.

Dönüştürülmüş Kod Örneği:

// Sizin kodunuzconst content = useIntlayer("my-key");// Optimize edilmiş kod (Dinamik)const content = useDictionaryAsync({  en: () =>    import(".intlayer/dynamic_dictionary/my-key/en.json").then(      (mod) => mod.default    ),  fr: () =>    import(".intlayer/dynamic_dictionary/my-key/fr.json").then(      (mod) => mod.default    ),});

importMode: 'dynamic' kullanırken tek bir sayfada useIntlayer kullanan 100 bileşeniniz varsa, tarayıcı 100 ayrı getirme (fetch) isteği deneyecektir. Bu istek "şelalesinden" (waterfall) kaçınmak için içeriği atom bileşen başına bir tane yerine daha az sayıda .content dosyasında (örneğin sayfa bölümü başına bir sözlük) gruplandırın.

3. Getirme Modu (Fetch Mode)

Dinamik mod gibi davranır ancak önce sözlükleri Intlayer Live Sync API'den getirmeye çalışır. API çağrısı başarısız olursa veya içerik canlı güncellemeler için işaretlenmemişse dinamik içe aktarmaya (dynamic import) geri döner.

Daha fazla detay için CMS dökümanına bakın: CMS

Getirme modunda temizleme (purge) ve küçültme (minification) kullanılamaz.

Özet: Statik vs Dinamik