Shopify Tema Çeviri Anahtarları: Tam Mekanik Rehberi

Shopify tema çeviri anahtarları, bir JSON locale dosyası girişini Liquid çıkışına t filtresinin aracılığıyla bağlayan nokta-notasyonlu tanımlayıcılardır. Alıcı dili değiştirdiğinde, Shopify anahtarı etkin locale dosyasına karşı çözer ve doğru dizgiyi otomatik olarak gösterir. Bu tek mekanizma, bir temaya eklediğiniz her UI etiketi, sepet iletisi, bölüm ayarı ve özel kod parçasını kapsar.

Temel çıkarımlar

• Her çeviriye uygun dize locales/*.json içinde yaşar; Liquid t filtesi çalışma zamanında bunu çözer.
• İki dosya türü vardır: .json mağaza ziyaretçileri için, .schema.json tema editörü için.
• Şema etiketleri t filtesi değil, t: önekini kullanır.
• Sınır değerler: locale dosya başına 3.400 anahtar, değer başına 1.000 karakter.
• .liquid dosyalarında sabit kodlanmış metin, Translate & Adapt dahil olmak üzere hiçbir çeviri uygulaması tarafından görülmez.

Dosya sistemi nasıl düzenlenmiştir

Her Shopify temasının mağaza ön yüzü arayüzünü destekleyen JSON dosyalarını içeren bir /locales dizini vardır. Yetkili kaynak dosya en.default.json olup, ja.json, fr.json ve de.json gibi eş dosyalar dil başına çevirileri taşır.

Bu dizinde iki ayrı dosya türü yaşar: .json dosyaları ziyaretçilerin gördüğünü belirlerken, .schema.json dosyaları yalnızca tema editörünü ilgilendirir.

Adlandırma IETF BCP 47 kuralını izler:

• en.default.json - kaynak dil, her zaman gerekli
• ja.json - Japonca (tüm bölgeler)
• en-GB.json - İngilizce (İngiltere bölgesel varyasyonu)
• fr-CA.json - Fransızca (Kanada bölgesel varyasyonu)

default işaretleyicisi Shopify'a hangi dosyanın yetkili olduğunu söyler. Geri dönüş yukarıdan aşağıya doğru çalışır: ja.json içinde bir anahtar eksikse, Shopify bir hata fırlatmak yerine en.default.json dosyasından değeri sessizce gösterir, bu geliştirme sırasında yararlı olup üretimde sessiz bir UX başarısızlığıdır.

Mağaza ön yüzü anahtarları ve t filtesi

Tema düzenler, şablonlar, kod parçaları ve Liquid varlıkları sabit kodlanmış metin dizgileri yerine Liquid t filtesi ile çevirilere referans verir; bu, etkin dil için locale dosyasından uygun çevrilmiş dizgiyi döndürür.

Anahtar yapısı category.group.description şeklini izler:

{{ 'products.product.add_to_cart' | t }}
{{ 'cart.general.title' | t }}
{{ 'general.404.title' | t }}

Liquid'de çeviri anahtarlarına referans verirken, bunların tek tırnak içinde sarılması gerekir.

İlgili JSON girişi basittir:

// locales/en.default.json
{
  "products": {
    "product": {
      "add_to_cart": "Add to cart"
    }
  }
}

Japonca için:

// locales/ja.json
{
  "products": {
    "product": {
      "add_to_cart": "カートに追加"
    }
  }
}

Enterpolasyon ve çoğullaştırma

t filtesini kullanırken, çevirileri enterpolasyon ve çoğullaştırabileceği gibi, herhangi bir tarihi ve saati yerelleştirebilirsiniz.

Enterpolasyon adlandırılmış bir değişkeni iletir:

{{ 'cart.item_count' | t: count: cart.item_count }}

// en.default.json
{
  "cart": {
    "item_count": {
      "one": "{{ count }} item",
      "other": "{{ count }} items"
    }
  }
}

Unicode Konsorsiyumu'nun CLDR tarafından tanımlanan aşağıdaki çoğullaştırma anahtarları desteklenir: few, many, one, other, two ve zero. Japonca dilbilgisi olarak çoğullaştırılmaz, bu nedenle bir ja.json çoğullaştırma grubu yalnızca other gerektirir. Bu, çok dilli mağazalarda CI başarısızlıklarının gerçek bir kaynağıdır: varsayılan locale'de uygun bir çoğullaştırma nesnesi olan bir grup, her locale dosyasında nesne olarak kalmalı, düz bir dizgiye çökmemelidir.

Şema anahtarları ve t: öneki

Şema ad alanı ayrıdır. Bir {% schema %} bloğunun içinde, label, info, name ve default için dizgi değerleri Liquid filtresi yerine t: önekini kullanır:

{% schema %}
{
  "name": "t:sections.hero.name",
  "settings": [
    {
      "type": "text",
      "id": "heading",
      "label": "t:sections.hero.settings.heading.label",
      "default": "t:sections.hero.settings.heading.default"
    }
  ]
}
{% endschema %}

Etiket ve varsayılan metin değerlerini şema JSON'ına sabit kodlamak yerine, t: önekini kullanarak çeviri anahtarlarına referans verebilirsiniz. Bu, her dil için şema tanımlarını çoğaltmadan ayarlar etiketlerinizi çeviriye uygun hale getirir.

Birçok bölüm içinde sabit kodlanmış İngilizce etiketler içeren bir temaya çeviri anahtarlarını geri takma, bir pahalı öğleden sonradır. Ödüller temanızın Almanca, Fransızca ve Japonca tüccarlarına hiçbir şema düzenlemesi olmadan sevk edilmesidir.

Eşleşen giriş en.default.json değil locales/en.default.schema.json içinde yaşar. İki ad alanını karıştırmak, tema editöründe ham t:sections.hero.name değişmezlerinin görünmesini sağlayan yaygın bir hatadır.

Yaygın şema hatası

Sık karşılaşılan bir hata, etiket değerleri olarak doğrudan dile özel nesneler sağlamaktır, örneğin "label": {"en": "Example Setting", "fr": "Paramètre Exemple"}. Theme Check bunu işaretler çünkü label ve name gibi şema alanları nesne değil, dizgi olmalıdır.

Büyük temalarda karşılaşacağınız sınır değerler

Locale dosyaları için çeviri anahtarları konusunda bir sınır vardır. Maksimum değer, tek bir locale dosyada 3.400 çevirip her çeviri değeri 1.000 karakteri aşamaz.

Yönettiğim 10.000+ SKU katalogunda, bölüm sayısı kabaca 60 karmaşık bölümün ötesine geçtiğinde bu tavanı en.default.schema.json içinde vurduk. Düzeltme, kaldırılan bölümlerden eski anahtarlar için denetim yapmak olup, bunu 3.400 anahtarın altına geri getirdi ve hiçbir şey aktif olmaktan kaybedilmedi. shopify-theme-locale-validator gibi bir araç bu kullanılmayan anahtarları otomatik olarak ortaya çıkarabilir.

Sahip olamayacağınız Shopify tarafından yönetilen anahtarlar

Shopify, kasa, sistem iletileri ve müşteri hesapları için kendi çevirilerini sağlar. Bu çevrilmiş dizgiler, locale dosyalarınızın dışında, ayrılmış shopify ve customer_accounts üst düzey anahtarları altında depolanır.

Bu çevirilerden birini geçersiz kılmak için, mağaza ön yüzü locale dosyasına anahtarını ekleyin. Örneğin, Fransızca kasa ödeme düğmesi etiketini geçersiz kılmak için, locales/fr.json içinde shopify.checkout.general.pay_now_button_label altında anahtarı ekleyin.

İşte bir Japonca mağaza Shopify varsayılanı "Siparişi Yerleştir" dizgesini brand'e özgü kopyayla nasıl geçersiz kıldığı, kasa kaynağına dokunmaksızın.

Translate & Adapt API katmanı

Tema locale dosyaları statik UI dizgilerini işler. Dinamik içerik (ürün başlıkları, açıklamalar, sayfa içeriği, metafield değerleri) ayrı bir mekanizmadan geçer: translationsRegister GraphQL mutasyonu.

Mutasyon, bir kaynağın çeviriye uygun içeriği için çevirileri oluşturur veya günceller. Her çeviri, kaynağın çeviriye uygun içeriğinden bir digest değeri gerektirir.

Şubat 2026 itibariyle, translationsRegister GraphQL API'sini kullanarak, kaynak tutamaçları için çevirileri kaydetme sırasına girebilir, tüccarlar için yerelleştirilmiş çevrimiçi mağaza URL'leri oluşturabilirsiniz. Bu, URL slugunun SEO için önemli olduğu Japonca mağazalar için anlamlı bir katkıdır.

API aynı zamanda metafield'ları kapsar: metafield çevirileri GraphQL Admin API'si aracılığıyla kullanılabilir ve birini kaydetmek için translationsRegister mutasyonunu metafield'ın kaynak kimliği ve bir içerik digest'i ile kullanırsınız.

İki katman bilinçli olarak ayrıdır:

Sabit kodlanmış metin sorunu

Liquid'de sabit kodlanmış bir dize, çeviriye uygun bir kaynak değildir. Düzeltme, locale dosyaları, anahtarlar ve t filtesidir. Bu, özel bir bölüm veya kod parçasının Translate & Adapt'ta görülmememesinin en sık sebebidir.

Düzeltme, dize başına tek seferlik işlemdir:

1. Anahtarı ve varsayılan değeri en.default.json öğesine ekleyin.
2. .liquid dosyasındaki sabit kodlanmış metni {{ 'your.key' | t }} ile değiştirin.
3. Çevrilmiş değeri her etkin locale dosyasında aynı anahtarın altına ekleyin.
4. Translate & Adapt uygulamasında anahtarın artık çeviriye uygun kaynak olarak görünüp görülmediğini doğrulayın.

Sessizce ne kırılır

Bunlar görsel QA'yı geçip canlı çok dilli mağazalarda kırılmadır:

• Eksik çoğullaştırma other formu. Zorunlu other formundan yoksun bir çoğullaştırma grubu, çevrilmiş bir dize {{ count }} veya {{ product_title }} yer tutucu sessizce bırakıldı, kopya yapıştırılmış JSON anahtarı kendisini sessizce üstüne yazıp, Liquid'de | t referansı asla tanımlanmayan bir anahtarı işaret ediyor.
• Çoğaltılmış JSON anahtarları. JSON ayrıştırıcıları önceki değerleri sessizce atar, bu nedenle aynı nesnede iki kez tanımlanan "placeholder", çalışma zamanına bağlı olarak öngörülemeyen çıkış verir.
• Yeniden adlandırılmış bölümlerden eski anahtarlar. ja.json içinde mevcut ancak en.default.json içinde yok olan anahtarlar Theme Check uyarısı üretiyor ancak çalışma zamanı hatası yok, zaman içinde çeviri yayılmasına neden oluyor.
• Şema içinde t filtesi kullanma. t filtesi Liquid dosyaları içindir. {% schema %} içinde, t: önekli dizgiyi kullanın. Filtre formunu kullanmak filtre çıkışını sessizce bir değişmez etiket dizgisi olarak gösterecek.

Sonucu doğrulama

Çok dilli bir temayı üretimine göndermeden önce bu denetim listesini kullanın:

• Yerel olarak shopify theme check çalıştırın; sıfır hata katı bir gerekliliktir, bir öneri değildir.
• Her etkin locale için, Dil Editörü'nü açın (Çevrimiçi Mağaza > Temalar > Dilleri Düzenle) ve hiçbir t:sections.* değişmezinin herhangi bir bölüm sekmesinde ham dizgi olarak görünmediğini doğrulayın.
• Translate & Adapt uygulamasında, eklediğiniz bir anahtarı arayın; görünürse, bağlantı tamamlanmıştır.
• Mağaza ön yüzü dilini önizleme çubuğundan değiştirin ve en az bir enterpolasyon dizgisini (bir sepet sayısı) ve bir çoğullaştırılan dizgiyi spot kontrol edin.
• Anahtar sayılarını denetleyin: cat locales/en.default.schema.json | python3 -c "import sys,json; d=json.load(sys.stdin); print(sum(1 for _ in str(d).split()))" kaba bir yaklaşımdır; uygun sayı 3.400 anahtar sınırını tavan olarak kullanır.

Otomatikleştirilmiş anahtar denetimleri için, Shopify locale dosyaları hakkında sözlük girdisini görerek mağaza ön yüzü ve şema ad alanlarının nasıl etkileşim kurduğunun açıklanmasını okuyun.

Özet

Shopify temalarında çeviri anahtarı sistemi iki ad alandır (mağaza ön yüzü JSON, şema JSON), bir Liquid filtesidir (t), bir şema önekidir (t:), dinamik içerik için bir GraphQL mutasyonudur (translationsRegister) ve iki sınır değerdir (3.400 anahtar, 1.000 karakter). Temadaki her çok dilli sorun bu beş bileşenden birinin yanlış yapılandırılmış olmasından kaynaklanır. Bağlantıyı bir kez doğru şekilde yapmak, Dil Editörü, Translate & Adapt ve herhangi bir üçüncü taraf çeviri uygulaması tümünün daha fazla kod değişikliği olmaksızın aynı gerçek kaynağı görmesi anlamına gelir.

Bu işi dışarıya vermek isteyen mağazalar için Lintel gibi stüdyolar Shopify tema geliştirme hizmeti veriyor.