i18n Paket Boyutu ve Performans Optimizasyonu

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

Örneğin, 10 dilde çevrilmiş 10 sayfalı bir uygulama, bir kullanıcının yalnızca birine (geçerli dilde geçerli sayfaya) ihtiyacı olmasına rağmen 100 sayfanın içeriğini indirmesine neden olabilir. Bu da israf edilen bant genişliği ve daha yavaş yükleme süreleri anlamına gelir.

Intlayer bu sorunu build zamanı optimizasyonlarıyla çözer. Kodunuzu analiz ederek her bileşen (component) için gerçekte hangi sözlüklerin kullanıldığını tespit eder ve yalnızca gerekli içeriği paketinizin (bundle) içine yeniden enjekte eder.

İçindekiler

Paketinizi analiz edin

Paketinizi analiz etmek, "ağır" JSON dosyalarını ve kod bölme (code-splitting) fırsatlarını belirlemede atılacak ilk adımdır. Bu araçlar, uygulamanızın derlenmiş (compiled) kodunun görsel bir treemap'ini oluşturarak tam olarak hangi kütüphanelerin en çok yer kapladığını görmenize olanak tanır.

npm install -D rollup-plugin-visualizer

import { defineConfig } from "vite";
import { visualizer } from "rollup-plugin-visualizer";

export default defineConfig({
  plugins: [
    visualizer({
      open: true, // Raporu otomatik olarak tarayıcınızda açar
      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 bir yaklaşım kullanır. Global JSON dosyalarının aksine, içeriğiniz bileşenlerinizin yanında veya içinde tanımlanır. Derleme işlemi sırasında Intlayer şunları gerçekleştirir:

1. useIntlayer çağrılarını bulmak için kodunuzu analiz eder.
2. Karşılık gelen sözlük (dictionary) içeriğini oluşturur.
3. useIntlayer çağrısını, yapılandırmanıza göre optimize edilmiş kod ile değiştirir.

Bu şu anlamlara gelir:

• Bir bileşen (component) import edilmezse, içeriği de pakete (bundle) dahil edilmez (Dead Code Elimination).
• Bir bileşen lazy-loaded (tembel yükleme) ile çağrılırsa, içeriği de lazy-loaded olur.

Eklenti (Plugin) Referansı

Intlayer'ın derleme optimizasyonu, her birinin tek bir sorumluluğu olduğu birkaç ayrı eklentiye bölünmüştür. Her birinin ne işe yaradığını anlamak yapılandırma sırasında karışıklığı önler.

Babel eklentileri (@intlayer/babel)

Bunlar doğrudan Webpack tabanlı yapılandırmalarda (Babel ile kullanılan Next.js, CRA, özel Webpack vb.) babel.config.js içinde kullanılır.

Aşağıdaki tablo bunları gerekli pipeline sırasına göre listeler (babel.config.js içinde görünmeleri gereken sırayla aynı):

Eklenti sırası önemlidir. babel.config.js dosyanızda purge ve minify eklentileri optimize eklentisinden önce gelmelidir. Optimize aşaması useIntlayer('key') öğesini belirsiz bir useDictionary(hash) çağrısı ile değiştirdiğinden, purge ve minify işlemlerinin hangi alanların kullanıldığını tespit edebilmesi için gerekli olan sözlük anahtar bilgisi kaybolur.

Her Babel eklentisi, yapılandırma yüklenme zamanında intlayer.config.ts'yi bir kez okuyan ve önceden çözümlenmiş değerler döndüren, kendisine eşlik eden bir opsiyon yardımcısı (options helper) içerir:

Vite eklentileri (vite-intlayer)

Vite kullanıcıları bunları asla doğrudan yapılandırmaz. Bunlar vite.config.ts içinde withIntlayer() fonksiyonu çağrıldığında otomatik olarak bağlanır. intlayer.config.ts içindeki build.purge ve build.minify bayrakları, ek bir eklenti kaydına (registration) gerek kalmadan karşılık gelen davranışı etkinleştirip kapatır.

SWC eklentisi (@intlayer/swc)

Next.js kullanıcıları da bunları asla doğrudan yapılandırmaz. v9.2.1'den itibaren next.config.ts içindeki withIntlayer(), yalnızca build.purge ve build.minify bayraklarına dayanarak tüm pipeline'ı — purge, minify ve import yeniden yazımını — çalıştırır.

İş ikiye bölünmüştür, çünkü bir SWC Wasm eklentisi her seferinde tek bir dosyayı dönüştürür ve dosya sistemine erişimi yoktur:

Hangi alanların kullanılmadığına ve her birinin hangi takma adı alacağına karar vermek dosyalar arası durum ve dosya G/Ç gerektirir; bu nedenle bu yarısı Node'da çalışır ve SWC eklentisi yalnızca ortaya çıkan tabloları alır.

Platforma Göre Kurulum

npm install -D @intlayer/swc

[dependencies]
intlayer-swc-plugin = "*"

import { withIntlayer } from "next-intlayer/server";
import type { NextConfig } from "next";

const nextConfig: NextConfig = {/* yapılandırmanız */};

export default withIntlayer(nextConfig);

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  build: {
    purge: true, // paketlenen JSON'dan kullanılmayan içerik alanlarını kaldırır
    minify: true, // içerik alanı anahtarlarını kısa takma adlara dönüştürür
  },
};

export default config;

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  build: {
    purge: true, // derlenmiş paketlenmiş JSON içinden kullanılmayan içerik alanlarını kaldır
    minify: true, // içerik alanı anahtarlarını daha kısa isimlere (alias) yeniden adlandır
  },
};

export default config;

npm install -D @intlayer/babel

const {
  intlayerExtractBabelPlugin,
  intlayerPurgeBabelPlugin,
  intlayerMinifyBabelPlugin,
  intlayerOptimizeBabelPlugin,
  getExtractPluginOptions,
  getPurgePluginOptions,
  getMinifyPluginOptions,
  getOptimizePluginOptions,
} = require("@intlayer/babel");

module.exports = {
  plugins: [
    // Extract: .content.ts dosyalarını → .intlayer/**/*.json olacak şekilde derler
    [intlayerExtractBabelPlugin, getExtractPluginOptions()],

    // Purge: kullanılmayan alanları .intlayer/**/*.json dosyalarından kaldırır
    //    (intlayer.config.ts içerisindeki build.purge seçeneğini okur)
    [intlayerPurgeBabelPlugin, getPurgePluginOptions()],

    // Minify: JSON ve kaynak kodundaki alan anahtarlarını kısaltarak yeniden adlandırır
    //    (intlayer.config.ts içerisindeki build.minify seçeneğini okur)
    [intlayerMinifyBabelPlugin, getMinifyPluginOptions()],

    // Optimize: useIntlayer('key') çağrılarını → useDictionary(hash) çağrısına çevirir
    //    Sözlük anahtarını tamamen değiştirdiği için en sonda bulunmalıdır.
    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],
  ],
};

Yapılandırma

Intlayer'ın paketinizi (bundle) 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.TURKISH],
    defaultLocale: Locales.ENGLISH,
  },
  dictionary: {
    importMode: "dynamic",
  },
  build: {
    // Derleme zamanında useIntlayer() çağrılarını doğrudan sözlük içe aktarmalarıyla (import) değiştirir.
    // undefined = otomatik (üretim/production ortamında etkin), true = daima, false = asla.
    optimize: undefined,

    // Derlenmiş sözlüklerdeki içerik alanı anahtarlarını kısa alfabetik isimlerle (alias) yeniden
    // adlandırır (örneğin title → a). JSON boyutunu küçültür; optimize işlemi (optimize: true) gerektirir.
    minify: true,

    // Kaynak kodda asla erişilmeyen içerik alanlarını kaldırır.
    // optimize işlemi gerektirir.
    purge: true,
  },
};

export default config;

Çoğu durumda optimize ayarı için varsayılan değeri (undefined) korumak önerilir.

Tüm seçenekler için yapılandırma referansına bakın: Configuration

Derleme (Build) Seçenekleri

Minification (alan anahtarını yeniden adlandırma)

build.minify komutu JavaScript paketinizi minify etmez — bunu bundler'ınız (Webpack, Rollup vb.) halleder. Bunun yerine, kullanıcı tarafından tanımlanmış her içerik alanının adını kısa bir harfe çevirerek derlenmiş olan JSON sözlük dosyalarını küçültür:

// Minify öncesi
{ "title": "Merhaba", "subtitle": "Dünya" }

// Minify sonrası
{ "a": "Merhaba", "b": "Dünya" }

Aynı yeniden adlandırma işlemi kaynak kodunuzdaki erişim özelliklerine de yansır; bu nedenle derlenmiş kodda content.title erişimi content.a haline gelir. Çalışma zamanı (runtime) davranışı tamamen aynı kalır.

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  build: {
    minify: true,
  },
};

export default config;

optimize false olduğunda minification atlanır. editor.enabled true olduğunda yine çalışır, ancak alan adı değiştirme adımı olmadan — görsel düzenleyici düzenlemeleri keyPath üzerinden çözer, bu yüzden orijinal alan adlarının korunması gerekir.

Next.js'te minifikasyon, @intlayer/swc kurulu değilse veya yüklenemiyorsa (16.1.0 altındaki Next.js) da atlanır. Eklenti, kaynak kodundaki erişimleri yeniden yazan yarıdır; onsuz sözlükleri yeniden adlandırmak kodunuzun artık var olmayan alan adlarını okumasına yol açardı.

Ayrıca, JSON'ların orijinal isimleriyle uzak (remote) API'den getirildiği durumlarda, yani sözlüklerin importMode: 'fetch' ile yüklendiği durumlarda da atlanır — istemci tarafındaki (client-side) isimleri değiştirmek sunucu/istemci sözleşmesini bozacaktır.

Purging (kullanılmayan alanların silinmesi)

build.purge, kaynak kodunuzda gerçekte hangi içerik alanlarına erişildiğini analiz eder ve derlenen JSON dosyalarından diğer tüm kullanılmayan alanları kaldırır.

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  build: {
    purge: true,
  },
};

export default config;

Örnek: Beş alanı olan ve sadece ikisinin kullanıldığı bir sözlük:

// Purge öncesi
{ "title": "…", "subtitle": "…", "cta": "…", "footer": "…", "badge": "…" }

// Purge sonrası (kaynak kodda sadece title + subtitle kullanılıyor)
{ "title": "…", "subtitle": "…" }

optimize false olduğunda Purge işlemi atlanır. editor.enabled true olduğunda etkin kalmaya devam eder — temizlenen bir alan hiçbir bileşen tarafından okunmaz, bu yüzden düzenleyici onu asla render etmez. Next.js'te ayrıca @intlayer/swc kullanılamadığında ve uyumluluk adaptörü çağıranları yapılandırıldığında atlanır.

Ayrıca, bir kaynak dosyasının ayrıştırılamadığı veya useIntlayer sonucunun bir değişkene atanıp (örneğin objeye yayılması, parçalama (destructuring) yapılmadan bir prop olarak iletilmesi gibi) statik analiz aracının takip edemeyeceği yollarla gönderildiği durumlarda Purge işlemi tedbir amaçlı olarak atlanır. Bu durumlarda tüm sözlük bozulmadan korunur.

İçe Aktarım Modu (Import Mode)

Farklı sayfalar ve yerel ayarlar (locales) içeren büyük uygulamalarda, JSON dosyalarınız toplam paket boyutunun önemli bir bölümünü oluşturabilir. Intlayer, importMode seçeneğini kullanarak sözlüklerin nasıl yükleneceğini belirlemenize olanak tanır.

Global tanımlama

İçe aktarım modu (import mode), genel kullanım için intlayer.config.ts dosyanızda tanımlanabilir.

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  dictionary: {
    importMode: "dynamic", // Varsayılan değer 'static'
  },
};

export default config;

Sözlük bazlı (Per-dictionary) tanımlama

Ayrıca tek bir sözlüğün içe aktarma modunu (import mode), kendisine ait olan .content.{{ts|tsx|js|jsx|mjs|cjs|json|jsonc|json5|md|mdx|yaml|yml}} dosyasında kolayca üzerine yazabilirsiniz (override).

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

const appContent: Dictionary = {
  key: "app",
  importMode: "dynamic", // Sözlüğün varsayılan import modunu ezer
  content: {
    // ...
  },
};

export default appContent;

importMode ayarı, sözlük içeriğinin bileşeniniz içine (component) nasıl enjekte edileceğini belirler. Bunu intlayer.config.ts dosyasında dictionary altında genel olarak ayarlayabilir veya .content.ts dosyasında sözlük bazlı olacak şekilde değiştirebilirsiniz.

1. Static Mode (default)

Statik modda Intlayer, useIntlayer kullanımını useDictionary ile değiştirir ve sözlüğü doğrudan JavaScript paketi içerisine koyar.

• Artıları: Anında işleme (senkron), hydration işlemi sırasında hiç fazladan ağ (network) isteği gerektirmez.
• Eksileri: Paket, bileşen için desteklenen tüm dillerdeki (locales) içerikleri beraberinde yükler.
• Kullanım Senaryosu: Tek Sayfalı Uygulamalar (Single Page Applications - SPA).

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

// Yazdığınız kod
const content = useIntlayer("my-key");

// (Statik Mod için) dönüştürülmüş en iyi kodun temsili
// Bu sadece temsili bir gösterimdir; asıl kod yapılandırma ve optimizasyona bağlı olarak farklı olabilir.
const content = useDictionary({
  key: "my-key",
  content: {
    nodeType: "translation",
    translation: {
      en: "My title",
      tr: "Benim başlığım",
    },
  },
});

2. Dynamic Mode

Dinamik modda Intlayer, useIntlayer işlevini useDictionaryAsync işleviyle değiştirir. Bu, mevcut geçerli dile (locale) ait JSON verisini özel olarak ve sonradan yüklemek için import() işlevini (Suspense benzeri bir mekanizma) kullanır.

• Artıları: Yerel (locale) seviyesinde tree shaking sağlar. Türkçe sürümü görüntüleyen bir kullanıcı yalnızca Türkçe sözlüğü indirir. İngilizce sözlük ise hiçbir zaman indirilmez veya yüklenmez.
• Eksileri: İlk açılışta (hydration esnasında) bileşen başına bir veri getirme ağ (network) isteğini tetikler.
• Kullanım Senaryosu: Büyük metin blokları barındıran uygulamalar, makaleler veya paket boyutunun (bundle size) oldukça kritik olduğu çok fazla dilli projeler.

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

// Yazdığınız kod
const content = useIntlayer("my-key");

// (Dinamik Mod için) dönüştürülmüş en iyi kodun temsili
// Bu sadece temsili bir gösterimdir; asıl kod optimizasyon nedenleriyle değişebilir
const content = useDictionaryAsync({
  en: () =>
    import(".intlayer/dynamic_dictionary/my-key/en.json").then(
      (mod) => mod.default
    ),
  tr: () =>
    import(".intlayer/dynamic_dictionary/my-key/tr.json").then(
      (mod) => mod.default
    ),
});

importMode: 'dynamic' seçeneği kullanıyorken bir bileşende (component) useIntlayer kullanan 100 ayrı alanınız varsa, sistem bu alanlara ayrı ayrı olarak ulaşmak için 100 adet istek yapmaya çalışacaktır. Bu tür karmaşık olan istek (request) trafiğinden ve performans kaybından kaçınmak için atom parçalar (atom component) yerine içeriği genel alanlara ayırarak .content (örneğin sayfa bölümüne özel bir sözlük dosyası) gruplandırmalarına koyun. Ek olarak aynı isme sahip birkaç .content dosyasını kullanmak da mümkündür. İsimler (keyler) aynı ise Intlayer bunları tamamen tek bir sözlük dosyası altında gruplandıracaktır.

3. Fetch Mode

Dinamik modla fazlasıyla benzer şekilde çalışır ancak ilk olarak uzak sözlükleri bulup almak için Intlayer Live Sync API'ye başvurmaya çalışır. Uzak (Remote API) isteği başarısız olursa veya içeriğin anlık senkronizasyona tabi (live updates) olmadığı belirlenirse yedek (fallback) olan statik duruma, yani dinamik içe aktarım işlemine (dynamic import) geçer.

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

// Yazdığınız kod
const content = useIntlayer("my-key");

// Optimize Edilmiş Kod Örneği (Fetch - İçe Aktarım İçin)
const content = useDictionaryAsync({
  en: () =>
    fetch("https://intlayer.my-domain.com/dictionary/my-key/en").then((res) =>
      res.json()
    ),
  tr: () =>
    fetch("https://intlayer.my-domain.com/dictionary/my-key/tr").then((res) =>
      res.json()
    ),
});

CMS (İçerik Yönetim Sistemi) için doküman detayına bakın: CMS

API tarafında verilerin tamamen orijinal alan (key) bilgisi barındırması gerektiği için uzak (fetch) çalışma alanlarında (minify) küçültme ve (purge) tamamen temizleme sistemleri uygulanmaz.

Özet: Static (Statik) vs Dynamic (Dinamik)