DeepL API ile Shopify Mağazanızı Uygulama Olmadan Başka Bir Dile Çevirin

DeepL API ile Shopify mağazanızı uygulama olmadan çevirmek için içerikleri Shopify Translations API'den GraphQL ile çeker, DeepL'e gönderir ve çevirileri yine Translations API ile mağazaya yazarsınız. Bunun için bir custom app, çeviri izinleri, DeepL hesabı ve yayınlanmış bir hedef dil gerekir. Böylece Weglot veya Langify'a aylık abonelik ücreti (Shopify App Store'da Weglot için $17-87, Langify için $17.50-59.95) ödemeden çevirinin kontrolü sizde kalır.

Shopify Translations API, mağazanızdaki her içeriği (ürün başlıkları, açıklamalar, koleksiyon sayfaları, blog yazıları) doğrudan GraphQL üzerinden okuyup yazmanıza izin verir. DeepL API ise bu içerikleri profesyonel kalitede makine çevirisiyle dönüştürür. İki API'yi birleştirdiğinizde Weglot veya Langify'a aylık abonelik ücreti ödemeden aynı sonucu alır, çeviri üzerinde tam kontrolü elinizde tutarsınız

Bu rehber, Shopify mağazanızı DeepL ile başka bir dile çevirmek için gereken teknik adımları, GraphQL sorgularını ve otomasyon akışını kapsar. Herhangi bir uygulama yüklemeniz gerekmez.

Shopify Translations API Nedir ve DeepL ile Nasıl Çalışır?

Shopify Translations API, Admin GraphQL API'nin bir parçasıdır ve mağazanızdaki her "çevrilebilir kaynak" için çeviri kaydetmenizi, okumanızı ve silmenizi sağlar. DeepL API bu noktada bir ara katman görevi görür: Shopify'dan ham içeriği alır, DeepL'e gönderir, dönen çeviriyi Shopify'a geri yazar.

Shopify, çevrilebilir kaynak olarak başlıca şu tipleri tanımlar: PRODUCT, PRODUCT_OPTION, PRODUCT_OPTION_VALUE, COLLECTION, ARTICLE, BLOG, PAGE, SHOP, MENU, LINK, FILTER, METAOBJECT, ONLINE_STORE_THEME. Her kaynak için çevrilecek alanlar önceden belirlidir. Örneğin bir ürün için title, body_html, handle, meta_title, meta_description alanları çevrilebilirdir.

DeepL ise /v2/translate endpoint'i üzerinden çalışır. İstek gövdesinde kaynak dili, hedef dili ve çevrilecek metni gönderirsiniz; JSON yanıtında çevrilmiş metin döner. HTML içerikleri için tag_handling=html parametresini eklemek zorunludur; aksi takdirde <p>, <strong>, <br> gibi etiketler de çevirilmeye çalışılır ve bozulur.

Başlamadan Önce: Gereksinimler ve Ön Hazırlık

Bu entegrasyonu kurabilmek için dört şeye ihtiyacınız var: Shopify Custom App, doğru API izinleri, DeepL hesabı ve mağazada hedef dil için etkin (yayınlanmış) bir locale. Shopify'ın temel yapısına yeniyseniz önce Shopify Nedir içeriğimizi okumanızı öneririz.

1. Shopify Custom App Oluşturma

1 Ocak 2026'dan beri admin içinden yeni custom app oluşturulamıyor; uygulamayı Dev Dashboard (dev.shopify.com) üzerinden oluşturun. Uygulamanın erişim ayarlarında şu scope'ları açın:

• read_translations
• write_translations
• read_products (ürün içeriklerini çekmek için)
• read_content (sayfa ve blog içerikleri için)

Uygulamayı Dev Dashboard'dan mağazanıza kurun ve Admin API access token'ını alın. Bu token tüm API çağrılarında X-Shopify-Access-Token header'ı olarak kullanılacak.

2. DeepL API Key

‍DeepL API sayfasından hesap açın. Yeni hesaplar, tek seferlik 1 milyon karakterlik Developer planıyla açılır; daha fazlası için ücretli Growth planı gerekir. Orta ölçekli bir Shopify mağazası için bu kota genellikle tek seferlik tam çeviriyi karşılar; sonraki çevirilerde yalnızca yeni eklenen içerikler çevrildiğinden tüketim düşer. Hesap panelinden API key'inizi alın.

3. Hedef Dilin Eklenmesi ve Yayınlanması

Shopify Admin'den Settings > Languages bölümüne gidin. Hedef dilinizi (örneğin Almanca için de) ekleyin ve yayınlayın. Dil mağazada etkin olmadan translationsRegister mutation'ı hata döner. Ayrı bir market açmanız gerekmez; market'e özel çeviri isteğe bağlıdır.

Kritik Not: Basic, Grow ve Advanced planlarda en fazla 20, Plus'ta 30 dil yayınlanabilir.

Adım Adım Uygulama: DeepL + Shopify Çeviri Akışı

Entegrasyon dört aşamada tamamlanır: içerikleri Shopify'dan çekme, DeepL'e gönderme, çevirileri Shopify'a yazma ve webhook ile otomatik tetikleme.

1. Çevrilecek İçerikleri Shopify'dan Çekme

translatableResources query'si belirli bir kaynak tipindeki tüm çevrilebilir alanları döndürür. Aşağıdaki GraphQL sorgusu mağazanızdaki tüm ürünlerin çevrilebilir içeriklerini ve mevcut çevirilerini getirir:

query GetTranslatableProducts($after: String) {
  translatableResources(resourceType: PRODUCT, first: 50, after: $after) {
    edges {
      node {
        resourceId
        translatableContent {
          key
          value
          digest
          locale
        }
        translations(locale: "de") {
          key
          value
          outdatedAt
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

digest alanı kritik önem taşır. Her içerik bloğunun hash'ini temsil eder. translationsRegister mutation'ında bu değeri göndermek zorundasınız; Shopify böylece hangi orijinal içeriğin çevrildiğini doğrular. digest olmadan mutation hata döner.

pageInfo.hasNextPage true döndükçe after parametresine endCursor değerini vererek döngüyü sürdürün. 100'den fazla ürünü olan mağazalarda pagination zorunludur.

2. DeepL API'ye İçerik Gönderme

Shopify'dan gelen içerikleri DeepL'e göndermek için HTTP POST isteği kullanılır:

POST https://api-free.deepl.com/v2/translate
Authorization: DeepL-Auth-Key {API_KEY}
Content-Type: application/json

{
  "text": ["Ürün başlığı", "
Ürün açıklaması kalın metin
"],
  "source_lang": "TR",
  "target_lang": "DE",
  "tag_handling": "html"
}

Birden fazla metni tek istekte göndermek, hem API kotanızı hem de yanıt süresini optimize eder. DeepL, bir istekte en fazla 50 metin bloğu kabul eder.

Şunu göz önünde bulundurun: body_html alanı içinde Shopify'a özgü {{ variable }} Liquid ifadeleri varsa, bu ifadeleri çeviriye göndermeden önce placeholder ile değiştirin ve çeviri döndükten sonra geri yerleştirin. Aksi takdirde DeepL bu ifadeleri de çevirir ve Liquid bozulur.

3. Çevirileri Shopify'a Kaydetme

translationsRegister mutation'ı, DeepL'den dönen çevirileri Shopify'a yazar:

mutation RegisterTranslations($resourceId: ID!, $translations: [TranslationInput!]!) {
  translationsRegister(resourceId: $resourceId, translations: $translations) {
    userErrors {
      field
      message
    }
    translations {
      key
      value
      locale
    }
  }
}

Variables:

{
  "resourceId": "gid://shopify/Product/1234567890",
  "translations": [
    {
      "key": "title",
      "value": "Produkttitel auf Deutsch",
      "locale": "de",
      "translatableContentDigest": "abc123..."
    },
    {
      "key": "body_html",
      "value": "
Produktbeschreibung auf Deutsch
",
      "locale": "de",
      "translatableContentDigest": "def456..."
    }
  ]
}

userErrors alanını kontrol edin. BLANK_TRANSLATION_VALUE hatası alıyorsanız boş string göndermek yerine o alanı translations dizisinden çıkarın. INVALID_DIGEST hatası translatableContentDigest'in yanlış olduğunu gösterir; query'i tekrar çalıştırıp güncel digest'i alın.

4. Webhook ile Otomatik Çeviri Akışı

Manuel çeviri yerine yeni ürün eklendiğinde otomatik tetikleme kurabilirsiniz. Shopify'da products/create webhook'unu kendi sunucunuzdaki bir endpoint'e yönlendirin:

POST https://your-server.com/webhooks/product-created

Endpoint şu akışı işler:

1. Webhook payload'ından product.id'yi al
2. translatableResources query'siyle ürünün çevrilebilir içeriklerini çek
3. DeepL API'ye gönder
4. translationsRegister ile Shopify'a yaz
5. İşlemi logla

Shopify webhook'larını doğrulamayı unutmayın. Her webhook isteğinin header'ında X-Shopify-Hmac-Sha256 değeri gelir; bu değeri kendi secret key'inizle HMAC-SHA256 ile hesaplayıp karşılaştırmazsanız sahte isteklere açık kalırsınız.

İpucu: Çeviri işlemi asenkron çalıştırılmalı. Webhook yanıtı 5 saniyeden uzun sürerse Shopify yeniden deneme başlatır ve aynı ürün birden fazla kez çevrilir. Webhook gelir gelmez 200 OK döndürün, asıl işi bir job queue'ya (örneğin Redis + Bull veya AWS SQS) bırakın.

Uygulama vs. API: Weglot, Langify ve DeepL Karşılaştırması

Piyasadaki Shopify çeviri uygulamaları işi tek tıkla yapıyor gibi görünse de ölçeklendikçe maliyet ve kontrol sorunları ortaya çıkar.

Weglot'un fiyatlandırması esas olarak kelime ve dil sayısına göre belirlenir; planlarda aylık çeviri isteği sınırı da bulunur. Business planı ayda 29 € (50.000 çeviri isteği, 3 dil) iken aylık 200.000 çeviri isteği olan bir mağaza Pro planına (ayda 79 €) düşer. Aynı mağazada DeepL Growth + tek seferlik geliştirme maliyeti ilk yılda genellikle daha düşük, ikinci yıldan itibaren belirgin olarak avantajlıdır.

Weglot gibi uygulamalar tema koduna JavaScript enjekte ederek çalışır. Bu yöntem Core Web Vitals metriklerini, özellikle LCP ve TBT'yi olumsuz etkiler. Langify ise çevirileri Shopify'da saklar; JavaScript yalnız Custom Content çevirilerinde kullanılır. DeepL API entegrasyonu ise çevirileri Shopify'ın kendi veri tabanına yazar; tema koduna dokunulmaz. API entegrasyonu yerine Shopify'ın kendi ücretsiz Translate & Adapt uygulamasını tercih edecekseniz, kurulum adımlarını çok dilli mağaza kurulum rehberimizde ayrı ele aldık.

Hreflang ve Çok Dilli SEO: Shopify'ın Otomatik Yaptıkları ve Eksik Kaldıkları

Shopify, aktif locale'lar için <link rel="alternate" hreflang="..."> etiketlerini otomatik olarak <head> bölümüne ekler. Mağazanızda de locale aktifse Almanca ürün sayfaları https://sizinmagazaniz.com/de/products/urun-adi URL'inde yayınlanır ve Türkçe sayfada hreflang="de" etiketi otomatik görünür.

Shopify'ın Otomatik Eklediği Hreflang Tag'leri

Subdirectory yapısı (/de/, /fr/) Shopify'ın varsayılan davranışıdır ve Google'ın önerdiği yapıdır. Subdomain (de.example.com) veya ayrı domain (example.de) için harici bir DNS yapılandırması ve Shopify Markets'ta özel domain ataması gerekir.

Meta Title ve Description Çevirisi

Shopify Translations API, meta_title ve meta_description alanlarını da destekler. Bu alanları çevirmezseniz Almanca sayfada Türkçe meta etiketler görünür; Google bu durumda sayfayı hedef dilde yanlış kategorize eder.

translatableContent listesinde bu alanlar key: "meta_title" ve key: "meta_description" olarak gelir. Ürün çevirisiyle aynı translationsRegister mutation'ına dahil edin.

Handle Çevirisi ve SEO Uyarısı

Ürün handle'larını (URL slug) çevirmek mümkündür fakat dikkatli olunmalıdır. Handle değiştirilirse eski URL 404 döner. Shopify otomatik redirect oluşturmaz. Handle'ları değiştirmek yerine orijinal bırakmak, SEO açısından daha güvenlidir. Hedef dilde anlamlı URL istiyorsanız, redirect oluşturmayı ayrı bir adım olarak planlayın.

Shopify SEO konusundaki kapsamlı teknik rehber için Shopify SEO Optimizasyonu içeriğimizi inceleyin.

Nodus Works Sahasından 3 Kritik Gözlem

Gözlem 1: body_html alanındaki Liquid ifadeleri entegrasyonları çökertir

Shopify tema geliştiricileri zaman zaman ürün açıklamalarına {% if %} blokları veya {{ metafield }} ifadeleri gömer. Bu içerik doğrudan DeepL'e gönderildiğinde iki sonuç çıkar: ya Liquid ifadesi çevrilip bozulur, ya da DeepL ifadeyi görmezden gelip etrafındaki metni çevirir ve kayıt hatasız görünür. Ancak Shopify bu çeviriyi render ettiğinde Liquid bozuk işlendiği için sayfa boş veya hatalı görünür. Gönderim öncesinde {{ }} ve {% %} blokları için regex ile placeholder sistemi kurun.

Gözlem 2: 500 ürünlü bir mağazanın tam çevirisi Developer planının kotasına sığar

500 ürünlü tipik bir Türk e-ticaret mağazasında ortalama başlık 60 karakter, açıklama 800 karakter, meta alanlar 200 karakter olarak ölçtük. Ürün başına ortalama 1.060 karakter, toplam 530.000 karakter tutulur. Bu rakam, DeepL Developer planının tek seferlik 1 milyon karakterlik kotasına sığar. Sayfalar ve blog içerikleri dahil edildiğinde ya da kota bittikten sonraki çevirilerde ücretli Growth planı gerekebilir.

Gözlem 3: Uygulama kullanıcıları çoğu zaman çevirilerin "kaybolduğunu" düşünür; aslında dil pazardan kaldırılmıştır

Weglot veya Langify kullanan mağazalarda sık karşılaştığımız senaryo: geliştirici bir temayı güncellerken veya Shopify arka ofisinden bir ayarı değiştirirken kasıtsız olarak locale'ı Markets'tan kaldırır. Çeviriler yerinde durur (Weglot'ta uygulamanın kendi panelinde, Langify'da Shopify'da) ama Shopify artık o locale'ı göstermez. Kullanıcı panikler, destek bileti açar. DeepL API entegrasyonunda çeviriler Shopify'ın kendi translations sisteminde tutulur; dil yalnız bir pazardan kaldırıldıysa ya da yayından alındıysa çeviriler korunur ve dil yeniden eklendiğinde içerikler geri gelir. Dili Settings > Languages bölümünden tamamen silmek ise o dildeki bütün çevirileri kalıcı olarak siler; silmeden önce çevirileri dışa aktarın.

SSS

Shopify'da DeepL API kullanmak için yazılım bilmek şart mı?

Temel JavaScript veya Python bilgisi yeterlidir. Shopify GraphQL API'si standart HTTP istekleri üzerinden çalışır, özel bir SDK gerektirmez. Ancak webhook tabanlı otomasyon için bir sunucu (Node.js, Python Flask/FastAPI veya serverless bir fonksiyon) kurabilmeniz gerekir. Teknik altyapı kurmak istemiyorsanız bu entegrasyonu sizin için kurabilecek bir Shopify ajansıyla çalışmak, uzun vadede uygulama maliyetinden daha ekonomiktir.

Shopify Translations API ücretsiz mi?

Evet, Shopify Translations API tüm planlarda ücretsizdir. DeepL tarafında yeni hesaplar tek seferlik 1 milyon karakterlik Developer planıyla açılır. Ücret ödemeniz gereken tek durum bu kotayı aşmaktır; bu durumda DeepL'in ücretli Growth planına geçersiniz.

translationsRegister mutation'ı kaç dili destekler?

Basic, Grow ve Advanced planlarda en fazla 20, Plus'ta 30 dil yayınlanabilir. Desteklenen dillerin tam listesi Shopify'ın supportedLocales query'siyle çekilebilir. Türkçe (tr), Almanca (de), İngilizce (en), Arapça (ar), Fransızca (fr) dahil 60'ın üzerinde dil mevcuttur.

Çeviriler Shopify Admin'den manuel düzenlenebilir mi?

Evet. translationsRegister ile kaydedilen çeviriler, Shopify Admin'de Settings > Languages altında görünür ve oradan düzenlenebilir. Bu, DeepL'in otomatik çevirilerini manuel olarak iyileştirmek için kullanılabilir. Yapılan düzenleme sonraki webhook tetiklemesinde silinmez; ancak ürün güncellendiğinde digest değişeceğinden API yeniden yazma yaparsa düzenlemeniz üzerine yazılır. Bunu önlemek için webhook akışına "zaten çevrilmiş ve düzenlenmiş mi?" kontrolü ekleyin.

DeepL API Türkçeyi destekliyor mu?

Evet. DeepL, Türkçeyi 2022'den itibaren hem kaynak hem hedef dil olarak destekler. Türkçeden İngilizceye ve Almancaya çeviri kalitesi, Google Translate'e kıyasla özellikle e-ticaret metinlerinde daha yüksektir.

Shopify Markets olmadan bu entegrasyon çalışır mı?

Evet. translationsRegister mutation'ının locale parametresi, mağazada etkin bir dile karşılık gelmelidir; ayrı bir market açmak gerekmez. Dil etkinleştirilmeden yapılan kayıt LOCALE_NOT_ENABLED hatası döndürür. Dili eklemek için Admin'den Settings > Languages yolunu izleyip dili ekleyin ve yayınlayın; market'e özel çeviri isteğe bağlıdır.

Shopify mağazasını DeepL ile çevirmek ne kadar sürer?

500 ürünlük bir mağaza için başlangıç kurulumu 1-3 gün sürer: Custom App oluşturma, API entegrasyonunu yazma ve test etme dahil. Çeviri işleminin kendisi DeepL'in hızına göre değişir; 500 ürün için toplu çekim ve yazma işlemi genellikle 10-30 dakika içinde tamamlanır. Webhook tabanlı otomasyon kurulduktan sonra her yeni ürün eklenmesinde çeviri 1-2 dakika içinde otomatik gerçekleşir.

Shopify'da çeviri uygulaması yerine API kullanmak daha mı iyi?

Teknik altyapınız varsa ve 2 yıldan fazla süreyle çok dilli mağaza işletecekseniz API yolu daha avantajlıdır. Uygulama kullanmak kurulum süresini minimuma indirir ama ölçeklendikçe maliyet artar, sayfa hızına JavaScript yükü eklenir ve vendor bağımlılığı oluşur. Tek seferlik kurulum sonrası maliyet neredeyse sıfıra yaklaşır; bu yatırımı 6 ay içinde geri döner.

Shopify Translations API ile hangi içerikler çevrilebilir?

Ürün başlıkları, açıklamalar, koleksiyon sayfaları, blog yazıları, statik sayfalar, navigasyon linkleri, ürün varyant seçenekleri, metafieldler ve tema metin dizeleri çevrilebilir. Ürün görselleri, fiyatlar ve stok bilgileri çevri kapsamı dışındadır.

Sonuç

Shopify Translations API ile DeepL API'yi birleştirmek, mağazanıza tam kontrollü, düşük maliyetli ve performansa zarar vermeyen bir çeviri altyapısı kurar. Weglot veya Langify gibi uygulamaların aylık sabit maliyeti yerine yalnızca gerçekten harcadığınız karakter başına ödeme yaparsınız; çeviriler Shopify'ın kendi sisteminde yerel olarak saklanır.

Kritik teknik nokta: translatableContentDigest'i doğru yönetin, body_html içindeki Liquid ifadelerini placeholder ile koruyun ve webhook yanıtını asenkron yapılandırın.

Shopify mağazanızda bu entegrasyonu kurmak veya mevcut çeviri altyapınızı yeniden yapılandırmak için Shopify Entegrasyon Çözümleri sayfamızı inceleyin ya da doğrudan bizimle iletişime geçin.

Kargo ve ödeme entegrasyonlarını da aynı anda yapılandırmak isteyenler için Shopify ERP Entegrasyonu rehberimiz ilgili teknik altyapıyı kapsamaktadır.