When initialising the st.js library, you can translate the default text values of:
- Messages appearing inside of the notification div (st-notification-frame)
- Card Components labels
- Card "Pay" button
- Card Components validation labels
Advantages:
- Provide alternative wording to the default phrases to better reflect your brand’s voice.
- Translate text into languages we don’t currently accept as a supported locale (as described on this page).
Unmodified Card Components
Translating the text
During the initialisation of the st.js library, you can update the default text using the translations property. The translation property expects a dictionary, where each key represents the default text to override. For each key specified in the translations object, you will need to provide a custom text value.
<html>
<head>
</head>
<body>
<div id="st-notification-frame"></div>
<form id="st-form" action="https://www.example.com" method="POST">
<div id="st-card-number" class="st-card-number"></div>
<div id="st-expiration-date" class="st-expiration-date"></div>
<div id="st-security-code" class="st-security-code"></div>
<button type="submit" id="st-form__submit" class="st-form__submit">
Pay securely
</button>
</form>
<script src="<CDN_DOMAIN>"></script>
<script>
(function() {
var st = SecureTrading({
jwt: 'INSERT YOUR JWT HERE',
translations:{'An error occurred': 'INSERT YOUR CUSTOM PHRASE HERE'},
});
st.Components();
})();
</script>
</body>
</html>
Replace <CDN_DOMAIN> with a supported domain. Click here for a full list.
Here is the full list of phrases for which custom text can be specified:
Important: These are case sensitive.
- Notification div messages:
- “A target element for the input field with id could not be found. Please check your configuration”
- “Amount and currency are not set”
- “An error occurred”
- “Decline”
- “Form is not valid”
- “Invalid field”
- “Invalid request”
- “Invalid response”
- “Merchant validation failure”
- “Method not implemented”
- “Payment has been cancelled”
- “Payment has been successfully processed”
- “Timeout”
- “You are not logged to Apple account”
Before and after – Customising the notification div messages
- Card Components labels:
- “Card number”
- “Expiration date”
- “Security code”
Before and after – Customising the labels
- Card "Pay" button:
- “Pay”
- “Processing”
Before and after – Customising the button
- Card Components validation labels:
- “Field is required”
- “Value is too short”
- “Value mismatch pattern”
Before and after – Customising the validation labels
Custom translations post initialisation of st.js library
After initialisation of the st.js library, the values assigned to translations can be overridden using the method updateTranslations(translations: object, replace = false): void
- The first argument accepts a translations object matching the specification provided to the initial config.
- The second argument replace is optional and defaults to false.
- When false, the updateTranslations method retains the original translations object during initialisation and modifies the messages and label keys specified in the new object.
- When true, the updateTranslations method overrides the text translations provided in the original translations object.
Example Use Case
When initialising the st.js library, let’s suppose you’d like to translate the “Pay” button to include amount:
translations: {'Pay': 'Pay £15.99'}If at any point the total price changes (e.g. due to shipping fees), you will need to update the amount displayed on the “Pay” button by invoking updateTranslations method, like so:
st.updateTranslations({'Pay': 'Pay £18.99'}, replace = false);
By using replace=false, this ensures that only the “Pay” button translation is affected, and all other translations specified during initialisation are left unchanged.
The updateTranslations method as described in the example above can only ever update the amount displayed to the customer, not the actual transaction amount processed.
To update the amount charged to the customer, you will need to generate a newly- signed JWT on your server including the new amount and pass this as the first argument of the updateJWT method.
