Translation

The Translation API provides localized text strings for customer-facing messages in Norce Checkout. Adapters use translations for error messages, payment instructions, shipping descriptions, and other text displayed to end customers during checkout.

How Translations Work

When an adapter needs to display a message to a customer, it retrieves the appropriate translation from the Translation API using a translation key and the order's culture (locale). The API returns the localized string for that culture, with fallback to a default language if no translation exists for the requested culture.

Translations are organized by:

Key: A unique identifier for the text string (e.g., payment.error.declined)
Culture: The locale code (e.g., sv-SE, en-US, nb-NO)
Value: The translated text for that culture

Translation Keys

Translation keys follow a hierarchical naming convention that indicates the context and purpose of the text:

Key Pattern	Description	Example
`payment.error.*`	Payment-related error messages	`payment.error.declined`
`payment.status.*`	Payment status descriptions	`payment.status.pending`
`shipping.label.*`	Shipping option labels	`shipping.label.express`
`checkout.message.*`	General checkout messages	`checkout.message.processing`
`validation.error.*`	Validation error messages	`validation.error.invalid_email`

Common Translation Keys

Here are commonly used translation keys and their typical values:

Payment Messages

Key	English (en-US)	Swedish (sv-SE)
`payment.error.declined`	Your payment was declined. Please try another payment method.	Din betalning avvisades. Försök med en annan betalningsmetod.
`payment.error.timeout`	The payment request timed out. Please try again.	Betalningsförfrågan tog för lång tid. Försök igen.
`payment.status.pending`	Payment is being processed	Betalningen behandlas
`payment.status.authorized`	Payment authorized	Betalning auktoriserad

Checkout Messages

Key	English (en-US)	Swedish (sv-SE)
`checkout.message.processing`	Processing your order...	Behandlar din beställning...
`checkout.message.complete`	Thank you for your order!	Tack för din beställning!
`checkout.error.cart_changed`	Your cart has been updated. Please review before continuing.	Din varukorg har uppdaterats. Granska innan du fortsätter.

Using the Translation API

Retrieve a translation:

GET /api/v0/checkout/translations/{key}?culture=sv-SE
X-Merchant: your-merchant
Authorization: Bearer your-token

Response:

{
  "key": "payment.error.declined",
  "culture": "sv-SE",
  "value": "Din betalning avvisades. Försök med en annan betalningsmetod."
}

List all translations for a culture:

GET /api/v0/checkout/translations?culture=sv-SE
X-Merchant: your-merchant
Authorization: Bearer your-token

Custom Translations

You can override default translations or add custom translations for your checkout implementation. This is useful for:

Customizing messaging to match your brand voice
Adding translations for additional languages
Providing context-specific messages for your business

Create or update a translation:

PUT /api/v0/checkout/translations
X-Merchant: your-merchant
Authorization: Bearer your-token
Content-Type: application/json

{
  "key": "checkout.message.complete",
  "culture": "sv-SE",
  "value": "Tack för ditt köp hos ExampleStore!"
}

Adapter Integration

Adapters retrieve translations when constructing customer-facing responses. For example, when a payment is declined, the payment adapter fetches the appropriate error message:

// Example adapter code
var errorMessage = await translationService.GetTranslation(
    "payment.error.declined", 
    order.Culture
);

return new PaymentResult 
{ 
    Success = false, 
    Message = errorMessage 
};

Supported Cultures

Norce Checkout supports translations for common Nordic and European locales:

sv-SE - Swedish (Sweden)
nb-NO - Norwegian Bokmål (Norway)
da-DK - Danish (Denmark)
fi-FI - Finnish (Finland)
en-US - English (United States)
en-GB - English (United Kingdom)
de-DE - German (Germany)

Additional cultures can be configured based on your market requirements.

Fallback Behavior

When a translation is not available for the requested culture, the Translation API follows this fallback order:

Exact culture match (e.g., sv-SE)
Language match (e.g., sv)
Default culture (typically en-US)

This ensures customers always see a message, even if a specific translation is missing.