Shopify Hydrogen'a i18n Nasıl Eklenir (Kapsamlı Rehber)

Shopify Hydrogen, özel mağaza vitrinleri oluşturmanın modern yoludur — ancak uluslararasılaştırma (i18n) eklemek zorlu olabilir. Yerel ayar bazlı yönlendirme, CDN üzerinden çeviri dağıtımı ve Shopify Storefront API ile sorunsuz entegrasyon gerekir.

Better i18n tüm bunları tek bir paketle çözer: @better-i18n/remix. Arayüz çevirilerini CDN üzerinden yönetirken, Shopify ürün içeriklerini yönetir — her iki dünyanın en iyisini sunar.

Ücretsiz başlayın — kredi kartı gerekmez. Hydrogen mağazanızı dakikalar içinde kurun.

Hydrogen Neden Özel Bir i18n Çözümüne İhtiyaç Duyar?

Shopify Hydrogen, React Router v7 ile Cloudflare Workers üzerinde çalışır. Bu benzersiz kısıtlamalar yaratır:

• remix-i18next çalışmaz — React Router v7 middleware gerektirir, Hydrogen'ın Worker fetch() işleyicisi bunu desteklemez
• Shopify Storefront API ürün verilerini yönetir ancak arayüz metinlerini (düğmeler, navigasyon, formlar, hata mesajları) yönetmez
• Edge çalışma zamanı dosya sistemi erişimi olmadığı anlamına gelir — çeviriler CDN'den gelmeli veya paketlenmelidir

Better i18n, edge çalışma zamanları için tasarlanmış CDN-öncelikli mimarisiyle bu boşluğu doldurur.

Mimari: Çift Kaynaklı Yerelleştirme

URL: /tr/products/hat
  ├─ Better i18n CDN → Türkçe arayüz çevirileri (düğmeler, nav, formlar)
  └─ Shopify Storefront API @inContext(language: TR) → Türkçe ürün verileri

Bu mimari şu anlama gelir:

• Arayüz metinleri (navigasyon, düğmeler, altbilgi, hata mesajları) → Better i18n panelinde yönetilir, CDN üzerinden dağıtılır
• Ürün verileri (başlıklar, açıklamalar, fiyatlar, varyantlar) → Shopify'da yönetilir, @inContext direktifi ile Storefront API üzerinden dağıtılır
• URL yerel ayarı her iki sistemi aynı anda yönlendirir

Adım 1: Paketi Yükleyin

npm install @better-i18n/remix i18next react-i18next

@better-i18n/remix paketi şunları sağlar:

• createRemixI18n() — sunucu tarafı i18n singleton'ı
• getLocaleFromRequest() — URL segmentlerinden yerel ayar algılama
• Yerleşik önbellekleme ile CDN destekli çeviri yükleme
• React bileşenleri (LocaleDropdown, LanguageSwitcher)

Adım 2: Better i18n Projenizi Oluşturun

1. better-i18n.com adresine gidin ve ücretsiz hesap oluşturun
2. Yeni bir proje oluşturun (örn. my-org/hydrogen-store)
3. Hedef dillerinizi ekleyin
4. Arayüz metinleriniz için çeviri anahtarları ekleyin

Adım 3: i18n Singleton'ını Oluşturun

app/i18n.server.ts dosyasını oluşturun:

import { createRemixI18n } from "@better-i18n/remix";

export const i18n = createRemixI18n({
  project: "my-org/hydrogen-store",
  defaultLocale: "en",
});

Adım 4: Sunucu Girişini Bağlayın

import { i18n } from "./app/i18n.server";

const locale = await i18n.getLocaleFromRequest(request);
const isDefaultLocale = locale === "en";
const languages = await i18n.getLanguages();
const shopifyI18n = deriveShopifyLocale(locale, isDefaultLocale);

const { storefront } = createStorefrontClient({
  i18n: shopifyI18n,
});

deriveShopifyLocale yardımcı fonksiyonu:

function deriveShopifyLocale(locale: string, isDefault: boolean) {
  const parts = locale.split("-");
  const language = parts[0].toUpperCase();
  const country = parts[1]?.toUpperCase() ?? language;
  return {
    language,
    country: isDefault ? "US" : country,
    pathPrefix: isDefault ? "" : `/${locale}`,
  };
}

Adım 5: Yerel Ayar Rotalarını Kurun

app/routes/
  ($locale)._index.tsx          → /  ve  /tr/
  ($locale).products._index.tsx → /products  ve  /tr/products
  ($locale).products.$handle.tsx → /products/hat  ve  /tr/products/hat
  ($locale).cart.tsx             → /cart  ve  /tr/cart

Adım 6: Rota Yükleyicilerinde Çevirileri Yükleyin

export async function loader({ params, context }: LoaderFunctionArgs) {
  const locale = params.locale ?? "en";
  const [messages, { products }] = await Promise.all([
    i18n.getMessages(locale),
    context.storefront.query(PRODUCTS_QUERY),
  ]);
  return { locale, messages, products };
}

Adım 7: Root Provider'ı Kurun

import { I18nextProvider } from "react-i18next";
import i18next from "i18next";

function createI18nextInstance(locale: string, messages: Record<string, any>) {
  const instance = i18next.createInstance();
  instance.init({
    lng: locale,
    resources: { [locale]: messages },
    interpolation: { escapeValue: false },
    initImmediate: false,
  });
  return instance;
}

Önemli: initImmediate: false kritiktir — sunucu tarafı render için senkron başlatmayı sağlar.

Adım 8: Bileşenlerde Çevirileri Kullanın

import { useTranslation } from "react-i18next";

function HeroSection({ products }) {
  const { t: tc } = useTranslation("common");
  const { t: th } = useTranslation("home");
  return (
    <section>
      <h1>{th("hero_title")}</h1>
      <p>{th("hero_subtitle")}</p>
      <a href="/products">{tc("shop_now")}</a>
    </section>
  );
}

Adım 9: msg() ile SEO Meta Etiketleri

import { msg } from "@better-i18n/remix";

export const meta: MetaFunction<typeof loader> = ({ data }) => {
  return [
    { title: msg(data?.messages?.common, "meta_title", "My Store") },
    { name: "description", content: msg(data?.messages?.common, "meta_description", "Shop our products") },
  ];
};

Adım 10: Dil Değiştirici Ekleyin

import { LocaleDropdown } from "@better-i18n/remix/react";

<LocaleDropdown locale={locale} languages={languages} currentPath={location.pathname} />

İçerik Güvenlik Politikası (CSP)

const { nonce, header, NonceProvider } = createContentSecurityPolicy({
  connectSrc: ["'self'", "cdn.better-i18n.com"],
});

Yapay Zeka Destekli Çeviri İş Akışı

1. Anahtarları ekleyin — kaynak dilinizde

2. "Yapay Zeka ile Çevir"e tıklayın — Better i18n, sözlüğünüzü ve marka sesinizi anlayan bağlam duyarlı yapay zeka kullanır

3. İnceleyin ve onaylayın

4. Yayınlayın — çeviriler anında CDN üzerinden kullanılabilir, yeniden derleme gerekmez

   

Çeviri Özellikleri

Neden Alternatifler Yerine Better i18n?

Canlı Örnek

Tam olarak bu kurulumu kullanan açık kaynak Hydrogen demo mağazamıza göz atın:

• Demo mağaza: Hydrogen 2026.1, React 19, Cloudflare Workers
• 10+ dil yapay zeka çevirisi ile yapılandırılmış
• Çift kaynaklı kalıp: Better i18n CDN + Shopify Storefront API

Başlarken

1. Ücretsiz kaydolun — kredi kartı gerekmez
2. @better-i18n/remix'i Hydrogen projenize yükleyin
3. Bu rehberi izleyin — yerel ayar yönlendirmesi + çevirileri bağlayın
4. Yapay zeka ile çevirin — anahtarlarınızı ekleyin
5. Yayınlayın — mağazanız artık çok dilli

Yardım mı lazım? Geliştirici belgelerimize göz atın.

Bu rehber, @better-i18n/remix v0.5+ ile Shopify Hydrogen 2026.1+ sürümüne dayanmaktadır.