Çoklu Dil (i18n) ✓ Canlı

Desteklenen diller

Kodlar BCP-47 / ISO 639-1 küçük harftir ve panelin dil kodu uzayıyla birebir aynıdır. Listede olmayan bir anahtar (örn. fr) sessizce düşürülür — kayıt reddedilmez, o anahtar saklanmaz. Panel bu dördü dışında bir dilde açıksa metin kırılmaz; aşağıdaki fallback zinciri devreye girer.

Fallback zinciri

Bir dil haritasından gösterilecek metin her yerde aynı sırayla seçilir (panel, portal, çalışma zamanı ve veritabanı aynı zinciri uygular):

1. İstenen dil dolu mu? → map[locale]
2. Taban dil dolu mu? → map["tr"]
3. Yukarıdaki tablo sırasında (tr, en, de, ru) ilk dolu değer — deterministiktir, JSON anahtar sırasına bağlı değildir
4. Hiçbiri yoksa → boş metin ("")

SDK aynı zinciri resolveLocalized() ile hazır verir (@restomenum/plugin-sdk):

import { resolveLocalized } from '@restomenum/plugin-sdk';

const title = { tr: 'Kurye Entegrasyonu', en: 'Courier Integration' };

resolveLocalized(title, 'en');             // 'Courier Integration'
resolveLocalized(title, 'de');             // 'Kurye Entegrasyonu'  ← tr'ye düşer (de çevirisi yok)
resolveLocalized(title, 'fr');             // 'Kurye Entegrasyonu'  ← desteklenmeyen dil de tr'ye düşer
resolveLocalized({ en: 'Only EN' }, 'de'); // 'Only EN'             ← tr yoksa LOCALES sırasındaki ilk dolu

Kendi Custom UI sayfanda kullanıcının dilini App Bridge getContext verir:

// iframe Custom UI: kullanıcının dilini App Bridge getContext verir
// → { serverId, pluginId, locale, refId }
const ctx = await bridge('getContext');
const label = resolveLocalized(page.title, ctx.locale);

Mağaza listelemesi — ad & açıklama

Marketplace kartındaki ad ve açıklama dil dil girilir. Bu alanlar eklentinin kendisine aittir (manifest'e değil, sürüme iliştirilen mağaza bilgisi önerisi olarak gider) ve sürüm onaylanıp yayınlanınca marketplace'e uygulanır — anında değişmez (Versiyonlama).

{
  "display_name_i18n": {
    "tr": "Kurye Entegrasyonu",
    "en": "Courier Integration",
    "de": "Kurier-Integration"
  },
  "description_i18n": {
    "tr": "Paketleri kuryeye otomatik aktarır.",
    "en": "Automatically dispatches packets to your courier."
  }
}

Manifest metinleri de aynı konvansiyon

Çoklu dil yeni bir mekanizma değildir — manifest'te zaten kullanılıyor. Aynı dil haritası şekli şu alanlarda geçerlidir:

• nav[].label — sol menü öğesinin adı
• pages[].title — Custom UI sayfa başlığı
• buttons[].label ve buttons[].confirm — aksiyon butonu metinleri
• forms[].title, forms[].fields[].label, forms[].submitLabel — declarative form metinleri

"nav": [
  {
    "slot": "sidebar.main",
    "pageId": "dashboard",
    "label": { "tr": "Kurye Paneli", "en": "Courier Panel" }
  }
],
"pages": [
  {
    "id": "dashboard",
    "title": { "tr": "Kurye Paneli", "en": "Courier Panel" },
    "customUiOrigin": "https://acme.example.com"
  }
]

Portal editöründen girme

Hem mağaza metinleri (ad/açıklama) hem de manifest etiketleri — menü öğesi, aksiyon butonu, sayfa başlığı, form metinleri — dil sekmeli alanlardır. Sekmede çeviri varsa dolu, yoksa soluk bir nokta görünür; karakter sayacı seçili dilin değerini sayar.

1. Yeni eklenti: Eklenti adı ve Açıklama alanlarında dil sekmesine tıkla, çeviriyi yaz. tr sekmesi boşken kaydedemezsin.
2. Mevcut eklentinin metnini değiştirme: sürüm düzenleme ekranındaki Mağaza Bilgileri kartını doldur. Boş bıraktığın alan "değişiklik yok" demektir, mevcut metin korunur.
3. Manifest etiketleri: aynı ekrandaki Menü Öğeleri, Aksiyon Butonları, Custom UI Sayfaları ve Declarative Formlar kartlarında etiket/başlık alanlarının üstündeki dil kodlarına (TR / EN / DE / RU) tıklayıp çeviriyi yaz. Burada taban dil zorunlu değildir; boş bıraktığın dil için dolu olan ilk dile düşülür.
4. Sürümü incelemeye gönder. Öneri, sürüm onaylanıp yayınlanınca marketplace'e uygulanır.

MCP ile (AI ajanı)

MCP sunucusu aynı alanları araç parametresi olarak verir. Dil anahtarları katalogdan türetilir; get_catalog çıktısındaki locales bloğu desteklenen dilleri, taban dili, fallback zincirini ve uzunluk sınırlarını döner — ajan önce onu okur.

# MCP aracı — sürüme çok dilli mağaza bilgisi önerisi ekler
set_listing({
  version_id: "…",
  display_name_i18n: { tr: "Kurye Entegrasyonu", en: "Courier Integration" },
  description_i18n:  { tr: "Paketleri kuryeye otomatik aktarır.", en: "Automatically dispatches packets to your courier." }
})

# Yeni eklenti oluştururken de aynı şekilde:
create_plugin({
  name: "Kurye Entegrasyonu",
  slug: "kurye-entegrasyonu",
  name_i18n: { tr: "Kurye Entegrasyonu", en: "Courier Integration" }
})

Manifest tarafında da aynı harita geçerlidir: set_nav (label), set_buttons (label, confirm), set_pages (title) ve set_forms (title, submitLabel, fields[].label/help/placeholder, options[].label) dil dil değer alır. Şemalar katalogdan türediği için desteklenmeyen bir dil anahtarı araç çağrısında reddedilir.

En iyi pratikler

• Önce taban dili doldur. tr her zaman dolu olsun; çeviriler onun üstüne gelir. Böylece hiçbir tenant boş başlık görmez.
• Yarım çeviri bırakabilirsin. Yalnız en hazırsa onu ekle; eksik diller zincirle otomatik doldurulur. Bekleyip hepsini birden yayınlamak zorunda değilsin.
• Makine çevirisine güvenme. Marketplace kartı satış metnidir; bozuk çeviri eklentinin güvenilirliğini düşürür. Emin değilsen o dili boş bırak — fallback daha iyi görünür.
• Uzunluğu en uzun dile göre planla. Almanca/Rusça çeviriler Türkçeden belirgin uzayabilir; ad için 3–60 karakter sınırı her dilde ayrı kontrol edilir.
• Marka adını çevirme. Eklenti adında ürün/marka kısmını sabit tut, yalnız açıklayıcı eki çevir (Acme Kurye → Acme Courier).
• Kendi listeni türetme. Kod tarafında desteklenen dilleri SDK'nın LOCALES sabitinden import et; elle ['tr','en'] yazarsan yeni bir dil eklendiğinde sessizce geride kalırsın.

İlgili

• Manifest Referansı — etiket alanlarının tam şeması
• @restomenum/plugin-sdk — resolveLocalized, LOCALES, LocalizedText
• AI ile yönet (MCP) — set_listing / create_plugin
• Yayına Alma — mağaza metni değişikliği inceleme akışı