Doğru React i18n kütüphanesi nasıl seçilir

React yerleşik bir i18n primitive'i sunmaz. İlk gün seçtiğiniz kütüphane, çevirilerin nasıl saklanacağını, bundle'a nasıl ulaşacağını ve önümüzdeki birkaç yıl boyunca iş yükünün ne kadarının size kalacağını belirler. Çoğu ekip popülariteye göre seçim yapar, ardından 2.000 anahtara ulaştığında trade-off'ları keşfeder.

Bu rehber tersi bir yaklaşım izler: önce projeniz hakkında birkaç soruyu yanıtlayın, ardından bu yanıtları uygun kütüphanelerle eşleştirin. Bu rehber düz React (Vite, React Router, TanStack Start) projelerine odaklanır. Next.js'in kendine has kısıtlamaları vardır ve bunlar Next.js karşılaştırması yazısında ele alınmıştır.

İçindekiler

Kütüphaneleri karşılaştırmadan önce yanıtlanması gereken altı soru

Hangi satırların sizin için önemli olduğunu bilmeden bir özellik tablosu işe yaramaz. Öncelikle bunları gözden geçirin.

1. Uygulama nasıl render ediliyor? Yalnızca SPA, hydration ile SSR veya React Server Components. Context tabanlı hook'lar bir SPA'da her yerde çalışır. RSC ile bir hook, metin render eden her bileşende "use client" kullanımını zorunlu kılar, bu nedenle sunucu tarafı bir API'ye de ihtiyacınız olacaktır.
2. Çevirileri kim yazıyor? Geliştiriciler, bir TMS kullanan şirket içi bir ekip, ICU dosyaları teslim eden bir ajans veya bir AI pipeline'ı. Bu durum, herhangi bir API detayından çok katalog formatını belirler.
3. Kaç locale ve sayfa var? İki locale ve beş sayfa her şeyi tek seferde sunabilir. On locale ve elli route bunu kaldıramaz ve yükleme stratejisi ana maliyet haline gelir.
4. Anahtarlarda type kontrolüne ihtiyacınız var mı? t("checkout.totl") ifadesindeki bir yazım hatası, typeları kendiniz bağlamadığınız sürece her anahtar tabanlı kütüphanede derlenir. Bunun kabul edilebilir olup olmadığına karar verin.
5. Dize ne içeriyor? Düz metin, çoğullar veya ortasında bir <Link> bulunan cümleler. Zengin içerik, çoğu API'nin hantallaştığı yerdir.
6. Proje ne kadar süre yaşayacak? Üç aylık bir prototip ile beş yıllık bir ürün aynı miktarda build aracına ihtiyaç duymaz.

Yanıtları bir yere not edin. Aşağıdaki her şey bunlara atıfta bulunacaktır.

Tek bir resimde genel görünüm

JavaScript i18n dünyasının on beş yılı dört mimari dalgaya sığar ve karşılaştıracağınız React kütüphaneleri bu farklı dalgalardan gelir.

JavaScript i18n tarihi, her dalganın bir öncekinin sorunlarına nasıl yanıt verdiğini ayrıntılı olarak açıklamaktadır.

En önemli karar: içerik nerede yaşar ve ne zaman yüklenir

Her React i18n kütüphanesi aynı yapıya sahiptir: bir store, bir provider, bir hook. Provider ne alırsa alsın, client bundle'ında veya hydration payload'ında son bulur. Dolayısıyla iki yapısal seçenek şunlardır:

• Merkezi veya kapsamlı (scoped) içerik. Uygulama için tek bir en.json ya da bileşen başına (veya namespace başına) bir bildirim.
• Statik veya dinamik import. Başlangıçta paketlenen her şey veya isteğe bağlı olarak yüklenen aktif locale ve route.

Aşağıdaki grafik, sayfa başına yaklaşık 30 KB metin içeren, 1 ila 10 sayfadan oluşan ve 1 ila 10 dile çevrilmiş teorik bir uygulamanın payload boyutunu tahmin etmektedir.

Statik import'lara sahip merkezi içerik her iki eksende de büyür: 10 sayfa çarpı 10 locale, her sayfada 300 KB metin demektir. Dinamik import'lar locale eksenini ortadan kaldırır. Scoping sayfa eksenini ortadan kaldırır. Yalnızca bu ikisinin kombinasyonu grafiği sabit tutar.

Bu bir kütüphane özelliği değil, bir disiplin özelliğidir. react-i18next namespace'ler ve lazy backend'ler ile sınırlandırılabilir. use-intl route başına bölünebilir. Ancak hiçbir şey bunu zorlamaz ve t("common:cta") çağıran paylaşılan bir <Button>, common namespace'ini sessizce her route'un bağımlılığı haline getirir. Benchmark bunu "diğer route'lardan sızıntı" ve "diğer locale'lerden sızıntı" olarak ölçer ve kütüphaneler arasındaki farkın çoğu buradan kaynaklanır.

3. soruya yanıtınız "çok sayıda locale, çok sayıda sayfa" olduysa, bu bölüme herhangi bir API tercihinden daha fazla önem verin. Bileşen bazlı vs merkezi i18n yazısı, aynı tercihin bakım tarafını daha derinlemesine inceler.

Adaylar

Kütüphane boyutları TanStack Start benchmark çalışmasından alınmıştır: boş bir bileşende provider artı hook, bundling, tree-shaking ve minification sonrası, 10 sayfa ve 10 locale. İçerik ayrıca ölçülür.

Rakamlar, benchmark sırasındaki sürümlerin anlık bir görüntüsüdür ve yeni sürümlerle değişebilir. Yalnızca boyuta göre karar vermeden önce benchmark'ı kendi uygulamanızda çalıştırın.

Tablonun göstermediği iki nokta var. Paraglide, kodları doğrudan deponuza (repo) ürettiği için neredeyse hiçbir kütüphane kodu içermez; bu da her commit öncesinde bir yeniden üretim adımı ve üretilen dosyalarda merge conflict'leri anlamına gelir. Intlayer ise bir bundler eklentisi (vite-intlayer veya eşdeğeri) gerektirir, bu nedenle build adımı olmayan bir kurulumda çalışamaz.

Yanıtlarınızı bir kütüphaneyle eşleştirin

Her kütüphanenin yetersiz kaldığı noktalar

Her seçeneğin sınırları vardır, dürüst limitler:

• react-i18next: Grubun en ağırı, kendine has çoğul formatı, typeların bakımını sizin yapmanız gerekir, ölü anahtarlar sessizce birikir.
• react-intl: Ayrıntılı (verbose) DX (useIntl() ardından formatMessage({ id })), birçok düğüme bağlı global instance.
• use-intl: Başlaması basit, optimize etmesi zahmetli. Namespace'ler, dinamik yükleme ve typelar bir araya geldiğinde geliştirmeyi oldukça yavaşlatır.
• Lingui: Ekstra extract / compile derleme adımı, hem insanları hem de AI asistanlarını karıştıran birkaç örtüşen sözdizimi (t(), tagged template, i18n.t(), <Trans>).
• Paraglide: Depoda üretilen dosyalar, React benchmark'ında tree-shaking etkili olmadı ve locale bir store yerine her düğümde depolamadan (storage) okunur.
• Tolgee: Anahtar typeları yok, alışması daha zor, öne çıkan satış noktası in-context düzenleme.
• Intlayer: Zorunlu build eklentisi, daha küçük ekosistem, kısmi ICU desteği, içerik tasarım gereği kod tabanına yayıldığından bir çevirmen için tek bir JSON dışa aktarmak araç gerektirir.
• gt-react, lingo.dev: Benchmark'ta önerilmedi: derlemede kota hataları, satıcı bağımlılığı (vendor lock-in) ve provider'ı zorla yeniden render etmeyi gerektiren reaktivite sorunları.

Her seçeneğin kodda görünümü

Aynı bileşen, başlık ve çoğul içeren bir sepet özeti, her aday ile yazılmıştır. İlginç olan kısım bileşen değil, içeriğin nerede yaşadığı ve type checker'ın bunun hakkında ne bildiğidir.

{
  "title": "Your cart",
  "items_one": "{{count}} item",
  "items_other": "{{count}} items"
}

import type { FC } from "react";
import { useTranslation } from "react-i18next";

export const CartSummary: FC<{ count: number }> = ({ count }) => {
  const { t } = useTranslation("cart");

  return (
    <section>
      <h2>{t("title")}</h2>
      <p>{t("items", { count })}</p>
    </section>
  );
};

{
  "cart.title": "Your cart",
  "cart.items": "{count, plural, one {# item} other {# items}}"
}

import type { FC } from "react";
import { FormattedMessage, useIntl } from "react-intl";

export const CartSummary: FC<{ count: number }> = ({ count }) => {
  const intl = useIntl();

  return (
    <section>
      <h2>
        <FormattedMessage id="cart.title" />
      </h2>
      <p>{intl.formatMessage({ id: "cart.items" }, { count })}</p>
    </section>
  );
};

{
  "Cart": {
    "title": "Your cart",
    "items": "{count, plural, one {# item} other {# items}}"
  }
}

import type { FC } from "react";
import { useTranslations } from "use-intl";

export const CartSummary: FC<{ count: number }> = ({ count }) => {
  const t = useTranslations("Cart");

  return (
    <section>
      <h2>{t("title")}</h2>
      <p>{t("items", { count })}</p>
    </section>
  );
};

msgid "Your cart"
msgstr "Votre panier"

msgid "{count, plural, one {# item} other {# items}}"
msgstr "{count, plural, one {# article} other {# articles}}"

import type { FC } from "react";
import { Plural, Trans } from "@lingui/react/macro";

export const CartSummary: FC<{ count: number }> = ({ count }) => (
  <section>
    <h2>
      <Trans>Your cart</Trans>
    </h2>
    <p>
      <Plural value={count} one="# item" other="# items" />
    </p>
  </section>
);

{
  "cart_title": "Your cart",
  "cart_items": "{count} items"
}

import type { FC } from "react";
import { m } from "../paraglide/messages.js";

export const CartSummary: FC<{ count: number }> = ({ count }) => (
  <section>
    <h2>{m.cart_title()}</h2>
    <p>{m.cart_items({ count })}</p>
  </section>
);

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

const cartSummaryContent = {
  key: "cart-summary",
  content: {
    title: t({
      tr: "Sepetiniz",
      en: "Your cart",
      fr: "Votre panier",
      es: "Tu carrito",
    }),
    items: t({
      tr: plural({ one: "{{count}} ürün", other: "{{count}} ürün" }),
      en: plural({ one: "{{count}} item", other: "{{count}} items" }),
      fr: plural({ one: "{{count}} article", other: "{{count}} articles" }),
      es: plural({ one: "{{count}} artículo", other: "{{count}} artículos" }),
    }),
  },
} satisfies Dictionary;

export default cartSummaryContent;

import type { FC } from "react";
import { useIntlayer } from "react-intlayer";

export const CartSummary: FC<{ count: number }> = ({ count }) => {
  const { title, items } = useIntlayer("cart-summary");

  return (
    <section>
      <h2>{title}</h2>
      <p>{items(count)}</p>
    </section>
  );
};

Halihazırda react-i18next, react-intl veya Lingui kullanıyor musunuz? Uyumluluk adaptörleri (react-i18next, react-intl, Lingui), import'ları bundler düzeyinde alias haline getirir; böylece siz bileşen bazında geçiş yaparken mevcut API çalışmaya devam eder. Geçiş rehberi geri kalan detayları kapsar.

Karar vermeden önce

Bir özellik tablosu bir kütüphanenin bugün ne yaptığını gösterir. Bu maddeler ise onunla yaşamanın nasıl bir şey olacağını anlatır.

Repository aktivitesini kontrol edin.

Commitler, issue yanıt süreleri ve son minör sürümün bu yıl çıkıp çıkmadığı. Bakımı yapılmayan iyi bir mimari, ertelenmiş bir göç sürecidir.

npm indirme sayılarına göre seçim yapmayın.

En çok indirilen kütüphane, 2026 React kod tabanına en uygun olan değil, ilk yayınlanan kütüphanedir. İndirmeler uyumu değil, geçmişi ölçer.

Kütüphaneyi kimin finanse ettiğini ve ne sattıklarını sorun.

i18next, Locize tarafından desteklenmektedir. next-intl / use-intl, vue-i18n, svelte-i18n ve Lingui, Crowdin tarafından desteklenmektedir. Tolgee, Paraglide (inlang) ve Intlayer kendi platformlarını yürütmektedir. Geliri barındırılan çevirilerden gelen bir sağlayıcının, araç zinciriniz içinde çeviriyi ücretsiz hale getirmek için çok az nedeni vardır. Intlayer, kendi API anahtarınızla CLI üzerinden AI çevirisi sunan ve self-host edebileceğiniz bir CMS sağlayan tek seçenektir.

AI agent kullanımına hazır mı?

Agent'lar i18n konusunda hâlâ zorlanmaktadır: locale'leri unuturlar, anahtarlar uydururlar ve mesaj sözdizimlerini karıştırırlar. Kütüphane, agent'ın içeriği listelemesi, doldurması ve test etmesi için Agent Skills veya bir MCP sunucusu sunuyor mu? İçerik yüklemesi varsayılan olarak optimize edilmiş mi, yoksa birinin her çeyrekte namespace'leri ve lazy import'ları gözden geçirmesi mi gerekiyor?

Kutudan çıktığı gibi Type Güvenliği.

"Ekstra yapılandırmayla type güvenli hale getirilebilir" değil, "yanlış bir anahtar temiz bir kurulumda tsc derlemesini durdurur". Var olmayan bir anahtarda ve bir çevirisi eksik olan bir locale durumunda ne olduğunu kontrol edin.

Kullanılmayan içeriğin tespiti.

Kataloglar sadece büyür. Intlayer'ın derleme adımı kullanılmayan alanları temizler ve bunları loglar (build.purge). Paraglide çağrılmayan mesaj fonksiyonunu tree-shaking ile elediğinden mimari olarak buna ulaşır. Diğer tüm kütüphaneler temizlik işini size bırakır.

Geliştirici deneyimi (DX).

İlk çevrilmiş dizeye kadar geçen kurulum süresi, fareyle üzerine gelindiğinde çeviriyi gösteren ve bildirime atlayan bir LSP veya VS Code eklentisi, doldurma, test etme ve push için bir CLI ve geliştirici olmayanların bir pull request açmadan içeriği düzenlemesi için bir yol (görsel düzenleyici veya CMS).

Sıkça Sorulan Sorular

Daha fazlası

• i18n kütüphane benchmark'ı: bundle boyutu, sızıntı ve locale geçiş süreleri ve TanStack Start raporu
• React i18n: provider modeli nasıl çalışır ve maliyeti nedir
• Özellik özellik: react-i18next vs react-intl vs Intlayer
• next-i18next vs next-intl vs Intlayer
• JavaScript i18n tarihi
• Derleyici vs bildirimsel i18n
• Bileşen bazlı vs merkezi i18n
• Build zamanında bundle optimizasyonu nasıl çalışır
• Vite + React uygulamasında i18n kurulumu
• Aynı rehber: Vue, Svelte ve Solid