i18n

Sağlayıcılar hata mesajlarını kendi ifadeleri ve dilleriyle, çoğu zaman teknik terimlerle yazar ("Do not honour", "Invalid merchant"). i18n plugin'i başarısız sonuçların errorMessage alanını, normalize hata koduna göre seçilen, müşterinin dilinde bir mesajla değiştirir. Better Auth'un i18n plugin'i gibi çalışır: İngilizce yerleşiktir, desteklediğiniz dilleri siz eklersiniz ve her isteğin dili seçtiğiniz stratejilerle algılanır.

Yerleşik çeviriler: İngilizce ve Türkçe 0.5.0 sürümünde eklendi, Almanca 0.5.1 sürümünde eklendi, Rusça 0.5.2 sürümünde eklendi ve Arapça 0.7.0 sürümünde eklendi.

KurulumCopy Anchor Link

import { betterPayment, iyzico } from 'better-payment';
import { i18n, locales } from 'better-payment/plugins';

const payment = betterPayment({
  providers: { iyzico: iyzico({ /* ... */ }) },
  plugins: [
    i18n({
      translations: { tr: locales.tr, de: locales.de },
      defaultLocale: 'tr',
    }),
  ],
});

const result = await payment.createPayment(request);
result.code;            // 'INSUFFICIENT_FUNDS'
result.errorMessage;    // 'Kartınızın bakiyesi veya limiti yetersiz. Başka bir kart deneyin.'
result.providerMessage; // the provider's own message, for your logs

Yalnızca code alanı olan sonuçlar değişir: başarısız sonuçlar ve NETWORK_ERROR ile gelen pending sonuçlar. Sağlayıcının metni loglarınız ve destek ekibiniz için providerMessage alanında kalır.

ÇevirilerCopy Anchor Link

translations her dili, hata koduna göre mesajlarıyla eşler. İngilizce yerleşiktir, yalnızca diğer dilleri eklersiniz. Yerleşik diller locales içindedir: en, tr, de, ru ve ar.

import { i18n, locales, type TranslationDictionary } from 'better-payment/plugins';

// All built-in languages
i18n({ translations: locales });

// Some of them, with your own wording for one message
i18n({
  translations: {
    tr: { ...locales.tr, INSUFFICIENT_FUNDS: 'Bakiyeniz yetersiz, lütfen başka bir kart deneyin.' },
    de: locales.de,
  },
});

// A language of your own
const es: TranslationDictionary = {
  INSUFFICIENT_FUNDS: 'Fondos insuficientes. Intente con otra tarjeta.',
  CARD_DECLINED: 'Su banco rechazó el pago.',
};
i18n({ translations: { es }, defaultLocale: 'es' });

Bir dilde eksik olan kod İngilizce mesajda kalır. Çevirisi olmayan bir defaultLocale ConfigurationError fırlatır.

SeçeneklerCopy Anchor Link

Dil algılamaCopy Anchor Link

HTTP handler her yanıtı kendi isteğine göre çevirir. detection içindeki stratejiler sırayla çalışır ve desteklenen ilk dil kazanır; hiçbiri bulamazsa yanıt defaultLocale dilinde olur.

• header: q değerleriyle birlikte Accept-Language başlığı. Bölge, diline düşer: tr-TR Türkçe alır.
• cookie: adı localeCookie olan çerez.
• callback: istekle çağrılan getLocale.

i18n({
  translations: locales,
  detection: ['cookie', 'header'],
  localeCookie: 'lang',
});

// Language from a query parameter: /api/pay/iyzico/payment?lang=tr
i18n({
  translations: locales,
  detection: ['callback'],
  getLocale: (request) => new URL(request.url, 'http://localhost').searchParams.get('lang'),
});

// Always Turkish
i18n({ translations: { tr: locales.tr }, defaultLocale: 'tr', detection: [] });

Bir Idempotency-Key için tekrar gönderilen yanıtlar da yeni isteğe göre çevrilir. Handler'ın kendi hata yanıtları (404, 403, geçersiz gövde) geliştiriciler içindir ve İngilizce kalır.

KodunuzdaCopy Anchor Link

Kodda çağırdığınız işlemler defaultLocale dilini kullanır. Başka bir dil için ya da plugin hook'ları olmadan çalışan sağlayıcıya özel metotların (iyzico ödeme formu, abonelikler) sonuçları için payment.errors kullanın:

payment.errors.message('EXPIRED_CARD', 'en');   // "Check your card's expiry date."
payment.errors.translate(checkoutResult, 'tr'); // the result, with errorMessage in Turkish
await payment.errors.detectLocale(request);     // 'tr', by the detection strategies
payment.errors.locales;                         // ['en', 'tr', 'de']

Diğer plugin'lerin hata kodlarıCopy Anchor Link

Diğer plugin'lerin $ERROR_CODES içinde tanımladığı kodlar da çevrilir. Plugin'in kendi mesajı varsayılandır; çevirileri translations içinde ekleyin:

plugins: [
  blockList({ bins: ['400000'] }), // declares BLOCKED_BIN in $ERROR_CODES
  i18n({
    translations: { tr: { ...locales.tr, BLOCKED_BIN: 'Bu kart kullanılamaz.' } },
    defaultLocale: 'tr',
  }),
],

Önce plugin'in kodu (errorCode içinde), sonra normalize code aranır.

localizedErrors'tan geçişCopy Anchor Link

localizedErrors, errorMessages, LocalizedErrorsOptions ve ErrorMessageDictionary çalışmaya devam eder ve kullanımdan kaldırılmıştır. localizedErrors tüm yerleşik dilleri içeriyordu; i18n ile desteklediğiniz dilleri listeleyin ya da hepsi için locales verin.

Better Payment'e dil eklemekCopy Anchor Link

Yerleşik çeviriler packages/better-payment/src/plugins/i18n/locales/ altında, her dil için bir dosyada ve Record<PaymentErrorCode, string> tipindedir: bir kodu eksik olan dosya derlenmez.

1. en.ts dosyasını dilin adıyla (fr.ts) kopyalayın ve mesajları çevirin. Mesajları müşteriye yönelik, o dilde doğal okunan ifadelerle ve teknik ayrıntısız yazın. Paket boyutu kontrolüne sığdırmak için kısaltmayın; yeni dil sınırı aşarsa bunu pull request'te belirtin.
2. Dili locales/index.ts içinden dışa aktarın.
3. Bir pull request açın. Mevcut test her dilde her kodun mesajı olduğunu kontrol eder.