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 $15-99 ö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 şu tipleri tanımlar: PRODUCT, PRODUCT_VARIANT, COLLECTION, BLOG, ARTICLE, PAGE, SHOP, THEME, METAFIELD, LINK, FILTER. 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 Shopify Markets'ta hedef dil için aktif bir locale. Shopify'ın temel yapısına yeniyseniz önce Shopify Nedir içeriğimizi okumanızı öneririz.
1. Shopify Custom App Oluşturma
Shopify Admin'den Settings > Apps and sales channels > Develop apps yolunu izleyin. Yeni bir uygulama oluşturun. Admin API Configuration bölümünde ş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ı yükleyin ve Admin API access token'ı kopyalayı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 ücretsiz hesap açın. Ücretsiz plan ayda 500.000 karaktere kadar çeviri yapmanıza izin verir. Orta ölçekli bir Shopify mağazası için bu limit genellikle tek seferlik tam çeviriyi karşılar; sonraki aylarda yalnızca yeni eklenen içerikler çevrildiğinden tüketim düşer. Hesap panelinden API key'inizi alın.
3. Shopify Markets'ta Locale Aktivasyonu
Shopify Admin'den Settings > Markets bölümüne gidin. Hedef dilinizi (örneğin Almanca için de) ilgili market'e ekleyin. Locale eklenmeden translationsRegister mutation'ı hata döner.
Kritik Not: Shopify, aynı anda en fazla 20 locale destekler. Temel plandaki mağazalar ek dil için Shopify Markets'ın ücretli özelliğini aktifleştirmek zorunda kalabilir. Shopify Plus müşterileri bu kısıtla karşılaşmaz.
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ığı", "<p>Ürün açıklaması <strong>kalın metin</strong></p>"],
"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": "<p>Produktbeschreibung auf Deutsch</p>",
"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-createdEndpoint şu akışı işler:
- Webhook payload'ından product.id'yi al
- translatableResources query'siyle ürünün çevrilebilir içeriklerini çek
- DeepL API'ye gönder
- translationsRegister ile Shopify'a yaz
- İş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ı kelime sayısına değil, sayfa görüntülemesine göre ölçeklenir. Aylık 200.000 sayfa görüntülemesi olan bir mağaza için Business planı yılda $2.388 tutar. Aynı mağazada DeepL Pro + tek seferlik geliştirme maliyeti ilk yılda genellikle daha düşük, ikinci yıldan itibaren belirgin olarak avantajlıdır.
Weglot ve Langify gibi uygulamalar tema koduna JavaScript enjekte ederek çalışır. Bu yöntem Core Web Vitals metriklerini, özellikle LCP ve TBT'yi olumsuz etkiler. DeepL API entegrasyonu ise çevirileri Shopify'ın kendi veri tabanına yazar; tema koduna dokunulmaz.
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 ücretsiz limiti aşmaz
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'in aylık 500.000 karakterlik ücretsiz limitini çok az aşar. Koleksiyon, sayfa ve blog içerikleri hariç tutulduğunda büyük bölümü ücretsiz limite sığar. Sayfalar ve blog içerikleri dahil edildiğinde Pro plan gerekebilir.
Gözlem 3: Uygulama kullanıcılarının yüzde kırkı çevirilerin "kaybolduğunu" düşünür; aslında locale silinmiştir
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. Uygulama çevirileri kendi veri tabanında tutar 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; locale silinip yeniden eklendiğinde içerikler geri gelir.
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 API'nin ücretsiz katmanı ayda 500.000 karaktere kadar çeviriyi karşılar. Ücret ödemeniz gereken tek durum DeepL'in ücretsiz limitini aşmaktır; bu durumda DeepL Pro planı aylık yaklaşık 25 dolardan başlar.
translationsRegister mutation'ı kaç dili destekler?
Shopify, Translations API üzerinden 20'ye kadar locale destekler. 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 ölçülebilir olarak daha yüksektir. DeepL'in 2023 kalite karşılaştırma raporu, Türkçe dil çiftlerinde %85 kullanıcı tercih oranını belgeliyor.
Shopify Markets olmadan bu entegrasyon çalışır mı?
Hayır. translationsRegister mutation'ının locale parametresi, Shopify Markets'ta aktif bir locale'a karşılık gelmelidir. Locale aktifleştirilmeden yapılan kayıt LOCALE_NOT_ENABLED hatası döndürür. Shopify Markets'ı açmak için Admin'den Settings > Markets > Add market yolunu izleyin.
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.
