> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paysight.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Localization

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

# Localization

<Info>
  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.
</Info>

## Supported Locales

<Tabs>
  <Tab title="All Locales">
    <CardGroup cols={3}>
      <Card title="English (US)" icon="flag-usa">
        `en-US`
      </Card>

      <Card title="English (UK)" icon="flag">
        `en-GB`
      </Card>

      <Card title="German" icon="flag">
        `de-DE`
      </Card>

      <Card title="Spanish" icon="flag">
        `es-ES`
      </Card>

      <Card title="French" icon="flag">
        `fr-FR`
      </Card>

      <Card title="Italian" icon="flag">
        `it-IT`
      </Card>

      <Card title="Polish" icon="flag">
        `pl-PL`
      </Card>

      <Card title="Portuguese" icon="flag">
        `pt-PT`
      </Card>

      <Card title="Romanian" icon="flag">
        `ro-RO`
      </Card>

      <Card title="Russian" icon="flag">
        `ru-RU`
      </Card>

      <Card title="Turkish" icon="flag">
        `tr-TR`
      </Card>

      <Card title="Finnish" icon="flag">
        `fi-FI`
      </Card>

      <Card title="Norwegian" icon="flag">
        `no-NO`
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="Table View">
    | 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         |
  </Tab>
</Tabs>

## Setting the Locale

<Tabs>
  <Tab title="During Initialization">
    You can set the locale when initializing the widget:

    ```javascript theme={null}
    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)
      }
    });
    ```

    <Info>
      If no locale is specified, the widget defaults to `en-US`.
    </Info>
  </Tab>

  <Tab title="Update After Initialization">
    You can update the locale after the widget has been initialized:

    ```javascript theme={null}
    widget.update({
      locale: 'de-DE' // German (Germany)
    });
    ```

    <Warning>
      Changing the locale will immediately update all text in the widget. Consider when this might impact user experience.
    </Warning>
  </Tab>
</Tabs>

## Localization Effects

<AccordionGroup>
  <Accordion title="UI Text" defaultOpen icon="font">
    All text elements in the widget interface are automatically translated based on the selected locale, including:

    <Note>
      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".
    </Note>

    * Field labels and placeholders
    * Error and validation messages
    * Button text
    * Section headers
    * Helper text
  </Accordion>

  <Accordion title="Date Formats" icon="calendar">
    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   |

    <Info>
      Expiration date input is automatically formatted according to the locale's conventions.
    </Info>
  </Accordion>

  <Accordion title="Number Formats" icon="hashtag">
    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 € |

    <Info>
      The widget automatically formats currency displays based on the locale and currency settings.
    </Info>
  </Accordion>

  <Accordion title="Validation Messages" icon="circle-check">
    Validation error messages are translated to match the selected locale:

    ```javascript theme={null}
    // English (US)
    "This field is required."

    // German
    "Dieses Feld ist erforderlich."

    // French
    "Ce champ est obligatoire."
    ```

    <Info>
      All validation messages are professionally translated to maintain consistency and clarity.
    </Info>
  </Accordion>
</AccordionGroup>

## Custom Button Text

<CodeGroup>
  ```javascript Custom Button Text theme={null}
  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'
  }
  });
  ```

  ```javascript Locale-Specific Button theme={null}
  // 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)
    }
  });
  ```
</CodeGroup>

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

## Localization Best Practices

<Steps>
  <Step title="Default to Browser Locale">
    Consider detecting the user's browser locale and setting the widget locale accordingly:

    ```javascript theme={null}
    // 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';
    };
    ```
  </Step>

  <Step title="Provide Language Selection">
    Give users the ability to choose their preferred language:

    <Note>
      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.
    </Note>

    ```javascript theme={null}
    // 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);
    });
    ```
  </Step>

  <Step title="Test with RTL Languages">
    If you plan to support right-to-left languages in the future, test your integration with RTL layout.

    <Warning>
      While the widget doesn't currently support RTL languages like Arabic or Hebrew, proper container styling can help prepare for future support.
    </Warning>
  </Step>

  <Step title="Ensure Consistent Experience">
    Make sure the rest of your application is localized to match the widget locale for a consistent user experience.

    <Info>
      A consistent localized experience across your entire checkout flow improves user trust and conversion rates.
    </Info>
  </Step>
</Steps>

## Complete Implementation Example

<Accordion title="Dynamic Locale Selection Implementation">
  ```javascript theme={null}
  // 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);
    });
  }
  ```
</Accordion>

## Next Steps

<CardGroup cols={3}>
  <Card title="Styling Guide" icon="palette" href="/widget-sdk/guides/styling">
    Learn how to customize the widget appearance to match your brand.
  </Card>

  <Card title="Events Guide" icon="bolt" href="/widget-sdk/guides/events">
    Understand how to handle widget events for a complete integration.
  </Card>

  <Card title="Technical Reference" icon="book" href="/widget-sdk/technical-reference">
    View the complete API documentation for advanced usage.
  </Card>
</CardGroup>