Localization

Learn how to localize the Paysight Widget for different languages and regions

Localization

The Paysight Widget supports multiple languages and regions through its comprehensive localization system. This guide explains how to configure and use these features to create a localized payment experience for your global customers.

Supported Locales

All Locales

English (US)

en-US

English (UK)

en-GB

German

de-DE

Spanish

es-ES

French

fr-FR

Italian

it-IT

Polish

pl-PL

Portuguese

pt-PT

Romanian

ro-RO

Russian

ru-RU

Turkish

tr-TR

Finnish

fi-FI

Norwegian

no-NO

Setting the Locale

During Initialization

You can set the locale when initializing the widget:

const widget = PaysightSDK.createWidget({
  targetId: 'payment-form',
  config: {
    // Required fields
    productId: 1234,
    sessionId: 'session_xyz',
    amount: 14.99,
    environment: 'production',
    
    // Set the locale
    locale: 'fr-FR', // French (France)
  }
});

If no locale is specified, the widget defaults to en-US.

Localization Effects

UI Text

All text elements in the widget interface are automatically translated based on the selected locale, including:

When the locale is changed, all UI elements adapt automatically, including field labels, placeholder text, error messages, and button text. For example, in French, “Card Number” becomes “Numéro de Carte” and “Pay Now” becomes “Payer Maintenant”.

• Field labels and placeholders
• Error and validation messages
• Button text
• Section headers
• Helper text

Date Formats

Date formats are automatically adjusted based on the locale:

Locale	Date Format	Example
en-US	MM/YY	12/25
en-GB	MM/YY	12/25
de-DE	MM/JJ	12/25
fr-FR	MM/AA	12/25

Expiration date input is automatically formatted according to the locale’s conventions.

Number Formats

Currency and number formats follow locale-specific conventions:

Locale	Currency Format	Example
en-US	$X,XXX.XX	$1,234.56
en-GB	£X,XXX.XX	£1,234.56
de-DE	X.XXX,XX €	1.234,56 €
fr-FR	X XXX,XX €	1 234,56 €

The widget automatically formats currency displays based on the locale and currency settings.

Validation Messages

Validation error messages are translated to match the selected locale:

// English (US)
"This field is required."

// German
"Dieses Feld ist erforderlich."

// French
"Ce champ est obligatoire."

All validation messages are professionally translated to maintain consistency and clarity.

Custom Button Text

Custom Button Text

const widget = PaysightSDK.createWidget({
targetId: 'payment-form',
config: {
  // Required fields
  productId: 1234,
  sessionId: 'session_xyz',
  amount: 14.99,
  environment: 'production',
  
  // Set the locale
  locale: 'fr-FR',
  
  // Override the button text
  buttonText: 'Complete Purchase'
}
});

The buttonText property overrides the default localized button text, allowing you to customize the call-to-action regardless of the selected locale.

Localization Best Practices

1. Default to Browser Locale

   Consider detecting the user’s browser locale and setting the widget locale accordingly:

   // Get browser locale or default to en-US
   const getBrowserLocale = () => {
     const browserLocale = navigator.language;
     const supportedLocales = [
       'en-US', 'en-GB', 'de-DE', 'es-ES', 'fr-FR', 
       'it-IT', 'pl-PL', 'pt-PT', 'ro-RO', 'ru-RU', 
       'tr-TR', 'fi-FI', 'no-NO'
     ];
     
     // Check if browser locale is supported
     if (supportedLocales.includes(browserLocale)) {
       return browserLocale;
     }
     
     // Check if language part is supported (e.g., 'de' from 'de-CH')
     const languagePart = browserLocale.split('-')[0];
     const matchingLocale = supportedLocales.find(locale => 
       locale.startsWith(languagePart + '-')
     );
     
     return matchingLocale || 'en-US';
   };
   

2. Provide Language Selection

   Give users the ability to choose their preferred language:

   A well-designed language selector typically appears as a dropdown menu with language names in their native script, often accompanied by country/region flags. When users select a language, the widget interface updates immediately to reflect the new locale.

   // Example of a language selector implementation
   const languageSelector = document.getElementById('language-selector');
   
   languageSelector.addEventListener('change', (event) => {
     const newLocale = event.target.value;
     
     // Update the widget locale
     widget.updateConfig({
       locale: newLocale
     });
     
     // Optionally, save the user's preference
     localStorage.setItem('preferred-locale', newLocale);
   });
   

3. Test with RTL Languages

   If you plan to support right-to-left languages in the future, test your integration with RTL layout.

   While the widget doesn’t currently support RTL languages like Arabic or Hebrew, proper container styling can help prepare for future support.

4. Ensure Consistent Experience

   Make sure the rest of your application is localized to match the widget locale for a consistent user experience.

   A consistent localized experience across your entire checkout flow improves user trust and conversion rates.

Complete Implementation Example

Dynamic Locale Selection Implementation

// Get browser locale or default to en-US
const getBrowserLocale = () => {
  const browserLocale = navigator.language;
  const supportedLocales = [
    'en-US', 'en-GB', 'de-DE', 'es-ES', 'fr-FR', 
    'it-IT', 'pl-PL', 'pt-PT', 'ro-RO', 'ru-RU', 
    'tr-TR', 'fi-FI', 'no-NO'
  ];
  
  // Check if browser locale is supported
  if (supportedLocales.includes(browserLocale)) {
    return browserLocale;
  }
  
  // Check if language part is supported (e.g., 'de' from 'de-CH')
  const languagePart = browserLocale.split('-')[0];
  const matchingLocale = supportedLocales.find(locale => 
    locale.startsWith(languagePart + '-')
  );
  
  return matchingLocale || 'en-US';
};

// Initialize widget with detected locale
const widget = PaysightSDK.createWidget({
  targetId: 'payment-form',
  config: {
    // Required fields
    productId: 1234,
    sessionId: 'session_xyz',
    amount: 14.99,
    environment: 'production',
    
    // Set locale based on browser
    locale: getBrowserLocale()
  }
});

// Setup language selector
const languageSelector = document.getElementById('language-selector');
if (languageSelector) {
  // Set initial value
  languageSelector.value = getBrowserLocale();
  
  // Handle language changes
  languageSelector.addEventListener('change', (e) => {
    const selectedLocale = e.target.value;
    widget.update({ locale: selectedLocale });
    
    // Optional: Update page content language
    document.documentElement.lang = selectedLocale.split('-')[0];
    
    // Optional: Store preference for future visits
    localStorage.setItem('preferredLocale', selectedLocale);
  });
}

Next Steps

Styling Guide

Learn how to customize the widget appearance to match your brand.

Events Guide

Understand how to handle widget events for a complete integration.

Technical Reference

View the complete API documentation for advanced usage.