Kigo Locale Configuration

Overview

The Kigo Locale Configuration System enables SDK-hosted sites and white-label implementations to customize the terminology used throughout the user experience. Each label supports singular and plural variations, providing flexibility for partner-specific branding.

The configuration is defined under the locale key within the SDK context and is useful for partners looking to adjust copy without changing the core functionality or structure of the application.

📘

Labels vs. language

locale customizes individual terms (e.g. "reward" vs. "perk"). The display language of the SDK is set separately with i18n.locale (supported values: 'en', 'fr-CA').

Priority & Structure

Locale settings are resolved per label and per form (singular / plural).

Configuration Priority

1. Hosted site override via locale in context
2. SDK default values (fallbacks)

The SDK defaults for offerLabel, revealLabel, claimLabel, and promoCodeLabel are translated into the active i18n.locale language. Values you pass in locale are used as-is in every language, so if you support multiple languages, update your locale values when the language changes.

Locale Context Structure

export type LocaleLabel = {
  singular?: string;
  plural?: string;
};

export type ExtendedLocaleLabel = LocaleLabel & {
  // When true, includes the user's name with the label (e.g. "John's Wallet")
  includeName?: boolean;
  // Already-localized prefix shown before the wallet label, including its trailing space (e.g. "your ")
  walletPrefix?: string;
};

export type BaseLocale = {
  programNameLabel?: LocaleLabel;
  walletLabel?: ExtendedLocaleLabel;
  rewardLabel?: LocaleLabel;
  offerLabel?: LocaleLabel;
  cashBackLabel?: LocaleLabel;
  promotionLabel?: LocaleLabel;
  claimLabel?: LocaleLabel;
  revealLabel?: LocaleLabel;
  cardLabel?: LocaleLabel;
  promoCodeLabel?: LocaleLabel;
  merchantProductLabel?: LocaleLabel;
  receiptLabel?: LocaleLabel;
  locationLabel?: LocaleLabel;
  successLabel?: LocaleLabel;
  lightningDealLabel?: LocaleLabel;
};

All labels and both forms are optional, and values must be strings. Each form falls back to the SDK default independently: if you set only singular, the default plural is still used.

Available Labels

Example Configuration

const locale = {
  programNameLabel: { singular: "Rewards Plus", plural: "Rewards Plus" },
  walletLabel: { singular: "My Perks", plural: "My Perks", includeName: false },
  rewardLabel: { singular: "perk", plural: "perks" },
  offerLabel: { singular: "deal", plural: "deals" },
  claimLabel: { singular: "redeem", plural: "redeem" },
  cashBackLabel: { singular: "Cash Back", plural: "Cash Back" },
  locationLabel: { singular: "location", plural: "locations" },
  lightningDealLabel: { singular: "Flash Sale", plural: "Flash Sales" }
};

Integration with SDK Context

You can integrate locale overrides directly into the SDK initialization. setContext performs a deep merge, so you only need to pass the labels you want to change:

window.Kigo.setContext({
  locale: {
    rewardLabel: { singular: "reward", plural: "rewards" },
    walletLabel: { singular: "Wallet", plural: "Wallets" },
    // Add any other overrides as needed
  }
});

To switch the SDK language and keep your labels in sync:

window.Kigo.setContext({
  i18n: { locale: "fr-CA" },
  locale: {
    walletLabel: { singular: "Portefeuille", plural: "Portefeuilles" }
  }
});

Best Practices

1. Brand Alignment

• Use terms that are aligned with your partner or brand's language style.
• For example, replace reward with perk, or offer with deal.

2. Consistent Grammar

• Define both singular and plural so neither form falls back to the SDK default.
• Keep grammar rules consistent throughout the interface.

3. Localization Testing

• Test on multiple screen sizes to confirm layout is preserved.
• Ensure labels aren’t truncated or overflowing UI elements.

Troubleshooting

Common Issues

1. Label not updating:
   Confirm your locale overrides are present in the SDK context and spelled correctly.

2. Unexpected plural text:
   If a plural value is not set, the SDK default plural is used (not your singular value). Set both forms.

3. Label not translated after a language change:
   Values passed in locale are not translated by the SDK. Pass updated labels together with i18n.locale when the language changes.

4. Not reflecting changes:
   Ensure cache is cleared and SDK is using the latest context payload.

Summary

The locale configuration system provides partners and hosted sites with flexibility to personalize terminology for their users. This improves UX clarity, supports localization efforts, and helps align with brand guidelines—all without modifying core SDK logic.