Hata Mesajları için Dil Desteği

Sağlayıcılar hata mesajlarını kendi ifadeleri ve dilleriyle, çoğu zaman teknik terimlerle yazar ("Do not honour", "Invalid merchant"). localizedErrors plugin'i başarısız sonuçların errorMessage alanını, normalize hata koduna göre seçilen, müşteriye yönelik bir mesajla değiştirir. İngilizce, Türkçe, Almanca, Rusça ve Arapça mesajlar dahildir.

Yerleşik diller: İ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 Henüz yayınlanmadı.

Kurulum

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

const payment = betterPayment({
  providers: { iyzico: iyzico({ /* ... */ }) },
  plugins: [localizedErrors({ locale: '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.

Seçenekler

Kendi ifadeleriniz ve ek diller

localizedErrors({
  locale: 'tr',
  messages: {
    tr: { INSUFFICIENT_FUNDS: 'Bakiyeniz yetersiz, lütfen başka bir kart deneyin.' },
    es: {
      INSUFFICIENT_FUNDS: 'Fondos insuficientes. Intente con otra tarjeta.',
      CARD_DECLINED: 'Su banco rechazó el pago.',
    },
  },
});

Bir dilde eksik olan kod fallbackLocale diline düşer. Mesajı olmayan bir locale ConfigurationError fırlatır.

HTTP handler'da isteğe göre

HTTP handler her yanıtı kendi isteğine göre çevirir; varsayılan olarak Accept-Language başlığından: tr-TR,tr;q=0.9 Türkçe alır, desteklenmeyen bir dil locale dilini alır. Bir Idempotency-Key için tekrar gönderilen yanıtlar da yeni isteğe göre çevrilir. Dili başka bir yolla seçmek için bir fonksiyon verin ya da algılamayı kapatın:

// Language from a query parameter: /api/pay/iyzico/payment?lang=tr
localizedErrors({
  detectLocale: (request) => new URL(request.url, 'http://localhost').searchParams.get('lang') ?? undefined,
});

// Always Turkish
localizedErrors({ locale: 'tr', detectLocale: false });

Handler'ın kendi hata yanıtları (404, 403, geçersiz gövde) geliştiriciler içindir ve İngilizce kalır.

Kodunuzda

Kodda çağırdığınız işlemler locale 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
payment.errors.locales;                         // ['en', 'tr', ...]

Diğer plugin'lerin hata kodları

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

plugins: [
  blockList({ bins: ['400000'] }), // declares BLOCKED_BIN in $ERROR_CODES
  localizedErrors({
    locale: 'tr',
    messages: { tr: { BLOCKED_BIN: 'Bu kart kullanılamaz.' } },
  }),
],

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

better-payment'e dil eklemek

Yerleşik mesajlar packages/better-payment/src/plugins/localized-errors/ 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 localized-errors/index.ts içindeki errorMessages nesnesine ekleyin.
3. Bir pull request açın. Mevcut test her dilde her kodun mesajı olduğunu kontrol eder.