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
Table View

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

Locale Code	Language	Region
`en-US`	English	United States
`en-GB`	English	United Kingdom
`de-DE`	German	Germany
`es-ES`	Spanish	Spain
`fr-FR`	French	France
`it-IT`	Italian	Italy
`pl-PL`	Polish	Poland
`pt-PT`	Portuguese	Portugal
`ro-RO`	Romanian	Romania
`ru-RU`	Russian	Russia
`tr-TR`	Turkish	Turkey
`fi-FI`	Finnish	Finland
`no-NO`	Norwegian	Norway

Setting the Locale

During Initialization
Update After 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.

You can update the locale after the widget has been initialized:

widget.update({
  locale: 'de-DE' // German (Germany)
});

Changing the locale will immediately update all text in the widget. Consider when this might impact user experience.

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

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'
}
});

// Function to get button text based on locale
const getButtonTextForLocale = (locale) => {
  const buttonTextMap = {
    'en-US': 'Pay Now',
    'en-GB': 'Pay Now',
    'de-DE': 'Jetzt bezahlen',
    'fr-FR': 'Payer maintenant',
    'es-ES': 'Pagar ahora'
  };
  
  return buttonTextMap[locale] || buttonTextMap['en-US'];
};

// Use in widget configuration
const widget = PaySightSDK.createWidget({
  targetId: 'payment-form',
  config: {
    productId: 1234,
    sessionId: 'session_xyz',
    amount: 14.99,
    environment: 'production',
    locale: userLocale,
    buttonText: getButtonTextForLocale(userLocale)
  }
});

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

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';
};

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);
});

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.

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.

Widget SDK

Integration Guides

Widget SDK Reference

Examples

Localization

Localization

Supported Locales

English (US)

English (UK)

German

Spanish

French

Italian

Polish

Portuguese

Romanian

Russian

Turkish

Finnish

Norwegian

Setting the Locale

Localization Effects

Custom Button Text

Localization Best Practices

Complete Implementation Example

Next Steps

Styling Guide

Events Guide

Technical Reference

​Localization

​Supported Locales

English (US)

English (UK)

German

Spanish

French

Italian

Polish

Portuguese

Romanian

Russian

Turkish

Finnish

Norwegian

​Setting the Locale

​Localization Effects

​Custom Button Text

​Localization Best Practices

​Complete Implementation Example

​Next Steps

Styling Guide

Events Guide

Technical Reference

Localization

Supported Locales

Setting the Locale

Localization Effects

Custom Button Text

Localization Best Practices

Complete Implementation Example

Next Steps