loading
Preparing LoginRadius developer resources
Mission: Help enterprises accelerate digital transformation with our fully-managed Customer IAM technology.
Skip to main content

Localization

Localize the LoginRadius Frontend SDK's form UI by passing a localizationConfig object in your SDK options. The SDK ships with built-in English defaults; any values you provide override the matching defaults, so you only need to supply the strings you want to change.

localizationConfig covers the text rendered by the SDK's prebuilt components:

  • Form UI text — titles, descriptions, labels, placeholders, and buttons across every flow (login, registration, MFA, passwordless, profile, etc.)
  • Error messages — via mapErrorMessages (by error code)
  • Validation messages — via mapValidationMessages (by validation rule)
  • Workflow field labels and placeholders — via workflows

For the complete localization key set, use the reference files in the LoginRadius hosted-page-themes repository.

note

If localizationConfig is passed in your SDK options, automatic browser-based localization is disabled — your config takes full control.

When to use

Use programmatic localization when any of the following apply:

  • Your site is single-language but in a language other than English.
  • You support a fixed set of languages and want full control over copy and validation messages.
  • You need to override specific keys (for example, a custom button label) while keeping the rest of the SDK's defaults.
  • Your application allows users to switch languages at runtime via a toggle or URL parameter.

When you only need the SDK to follow the browser's language and you are satisfied with default translations, you can omit localizationConfig and let browser-based localization handle it.

Prerequisites

Before configuring localization, make sure you have:

Configuration

Localization is configured through options at SDK initialization. Two modes are available and they are mutually exclusive:

  • Browser-based localization — enabled by default when localizationConfig is not provided. The SDK detects the browser's preferred language and applies the matching built-in translation.
  • Programmatic localization — enabled by passing localizationConfig. The SDK uses your provided keys and falls back to the English defaults for anything you do not override. Browser detection is suppressed in this mode.
note

If browser localization is enabled (localization = true in options) it takes priority and auto-switches based on browser settings. In that case, localizationObject passed in options is not honored.

What you can localize

The localization object has four primary surfaces. Override only the keys you need; everything else falls back to defaults.

SurfaceKeyPurpose
Component UI text<componentName>Titles, labels, placeholders, button text per component
Validation messagesmapValidationMessagesPer-rule validation error messages
API error messagesmapErrorMessagesPer-API-code error messages
Workflow textworkflowsIdentity Orchestration workflow field labels and prompts

Quick start

Provide localizationConfig when you instantiate the SDK. Include only the keys you want to override — every other string falls back to the SDK's built-in English copy.

Basic example

Pass a localizationConfig object with the strings you want to translate. The example below overrides the login screen's title, field labels, button, and the forgot-password link.

const localization = {
  login: {
    title: "Connexion",
    emailLabel: "Courriel",
    passwordLabel: "Mot de passe",
    buttonText: "Se connecter",
    forgotPassword: "Mot de passe oublié ?",
  },
};

const LRObject = new LoginRadiusSDK({
  apiKey: "<YOUR_API_KEY>",
  localizationConfig: localization,
});

Validation rule messages

These rule names are fixed. You can customize the message text for each rule.

const localization = {
  // other localization keys...
  mapValidationMessages: [
    { rule: "required", message: "The %s field is required." },
    {
      rule: "valid_email",
      message: "The %s field must be a valid email address.",
    },
    {
      rule: "min_length",
      message: "The %s field must be at least %s characters in length.",
    },
    {
      rule: "max_length",
      message: "The %s field must not exceed %s characters in length.",
    },
    { rule: "matches", message: "The %s field does not match the %s field." },
  ],
};

const LRObject = new LoginRadiusSDK({
  apiKey: "<YOUR_API_KEY>",
  localizationConfig: localization,
});

API error code messages

These codes depend on what the API returns. Add or update codes based on your API responses for customizing error messages.

const localization = {
  // other localization keys...
  mapErrorMessages: [
    { code: 966, message: "Email ID is not properly entered, please check." },
    { code: 938, message: "The user's account does not exist." },
  ],
};

const LRObject = new LoginRadiusSDK({
  apiKey: "<YOUR_API_KEY>",
  localizationConfig: localization,
});

How to use the reference files

The steps below refer to the localization reference files in the hosted-page-themes repository:

  1. Open the language folder you need under v3/localization, such as en, ar, etc.
  2. Use the component entries inside en.json, ar.json, etc., based on the specific use case.
  3. Copy the required keys into your localization object and keep only the values you want to override.
  4. Repeat the same structure for other languages so the component keys stay consistent across locales.

Programmatic localization

When using the JavaScript SDK directly, you can implement localization in two ways: ship a single fixed language, or load language data dynamically based on a URL parameter.

Static localization

Use when language is fixed (for example, a French-only site).

const localization = {
  login: {
    title: "Connexion",
    emailLabel: "Courriel",
    passwordLabel: "Mot de passe",
    submitButton: "Se connecter",
    forgotPasswordLink: "Mot de passe oublié ?",
  },
  registration: {
    title: "Inscription",
    emailLabel: "Courriel",
    passwordLabel: "Mot de passe",
    submitButton: "S'inscrire",
  },
};

const LRObject = new LoginRadiusSDK({
  apiKey: "<YOUR_API_KEY>",
  localizationConfig: localization,
});

Dynamic localization (URL parameter)

Use when users switch languages via toggle or link.

Step 1: Create JSON files

Create locale files like locales/french.json:

{
  "login": {
    "title": "Connexion",
    "emailLabel": "Courriel",
    "submitButton": "Se connecter"
  },
  "registration": {
    "title": "Inscription",
    "submitButton": "S'inscrire"
  }
}

Step 2: Detect language from URL and initialize

async function getLocalizationFromUrl() {
  const params = new URLSearchParams(window.location.search);
  const lang = params.get("language");

  if (!lang) return {}; // Use English defaults

  const fileMap = {
    french: "french.json",
    chinese: "chinese.json",
    spanish: "spanish.json",
  };

  const file = fileMap[lang];
  if (!file) return {};

  try {
    const response = await fetch(`locales/${file}`);
    return await response.json();
  } catch (e) {
    console.warn("Localization file not found:", file);
    return {};
  }
}

(async () => {
  const localizationConfig = await getLocalizationFromUrl();

  const LRObject = new LoginRadiusSDK({
    apiKey: "<YOUR_API_KEY>",
    localizationConfig,
  });
})();
note

The page must reload when the language changes.

Language toggle implementation

Add a language selector to your page:

<select id="lang_toggle">
  <option value="">English</option>
  <option value="?language=french">Français</option>
  <option value="?language=chinese">中文</option>
  <option value="?language=spanish">Español</option>
</select>
document.getElementById("lang_toggle").addEventListener("change", function () {
  window.location.search = this.value;
});

Mode precedence

The SDK resolves browser-based and programmatic localization through a single rule. Browser localization wins whenever localization: true is set in options. Otherwise, the SDK reads from localizationConfig and falls back to its English defaults for any key you omit.

options (localization)localizationConfigRuntime behavior
trueyesBrowser localization wins. localizationConfig is ignored.
truenoBrowser localization wins. Built-in translations render.
falseyeslocalizationConfig merges with English defaults, key by key.
falsenoEnglish defaults render unchanged.

The SDK applies overrides one key at a time. Each value you supply replaces the matching default, and any key you omit renders in English. The example below translates the login and registration titles only — labels, placeholders, button text, and validation messages remain in English.

const localization = {
  login: {
    title: "customTitle", // Custom title for login
  },
  registration: {
    title: "custom register title", // Custom title for registration
  },
};

const LRObject = new LoginRadiusSDK({
  apiKey: "<YOUR_API_KEY>",
  localizationConfig: localization, // Merging with default template
});
note

To force programmatic localization while keeping localization: true elsewhere in your configuration, pass disableLocalization: true in options. The SDK then honors localizationConfig and skips browser detection.

Email and SMS localization

Use language-specific template names for emails and SMS. The template names themselves are configured in the LoginRadius Dashboard; the SDK picks the right one at runtime.

const params = new URLSearchParams(window.location.search);
const isFrench = params.get("language") === "french";

const LRObject = new LoginRadiusSDK({
  apiKey: "<YOUR_API_KEY>",
  verificationEmailTemplate: isFrench
    ? "email-verification-fr"
    : "verification-default",
  smsTemplateWelcome: isFrench ? "welcome-sms-fr" : "welcome-default",
});
TemplateOption
Verification emailverificationEmailTemplate
Reset passwordresetPasswordEmailTemplate
Welcome emailwelcomeEmailTemplate
Welcome SMSsmsTemplateWelcome

Google reCAPTCHA language

Set the reCAPTCHA language so the challenge UI matches the rest of the localized form:

const params = new URLSearchParams(window.location.search);

const LRObject = new LoginRadiusSDK({
  apiKey: "<YOUR_API_KEY>",
  captchaLanguage: params.get("language") === "french" ? "fr" : "en",
});

See the full list of reCAPTCHA language codes.

Best practices

Localization is more than translation — these practices keep the experience accessible and testable across locales:

  • Provide sufficient contrast for text in all themes so translated copy stays legible.
  • Maintain readable font sizes and spacing — some target languages expand text length significantly (German, French) or shrink it (CJK).
  • Ensure keyboard navigation and screen reader support work across languages; non-Latin scripts can change focus order if styles are not tested.
  • Keep template keys consistent across locales — copy en.json to each new locale rather than authoring from scratch.
  • Default to graceful fallback — leave keys unset rather than translating them poorly. The SDK will fall back to English defaults.
  • Localize end-to-end — UI strings, validation messages, error codes, email and SMS templates, and the reCAPTCHA widget should all share the same language for any given user.

Troubleshooting

SymptomLikely causeResolution
localizationConfig is ignored, UI stays in EnglishBrowser localization is enabled and takes prioritySet the SDK to disable browser localization (or pass disableLocalization: true) and re-initialize
Some keys still appear in EnglishYour localizationConfig is missing some keys, so the SDK falls back to the English defaults for those entriesOpen the reference <locale>.json in the hosted-page-themes repository, identify the keys that are not present in your localizationConfig, and add them with the correct translations.
Language switch does not take effectPage was not reloaded after switchingTrigger a full reload on language change (the SDK reads localizationConfig only at init)
Validation messages are in the wrong languagemapValidationMessages not provided for that localeAdd mapValidationMessages entries for every validation rule used by your forms
CAPTCHA challenge shows in the wrong languagecaptchaLanguage is not set in optionsSet captchaLanguage to the same BCP 47 code as the UI locale (e.g., fr, de, pt-BR)

Options

localizationConfig, disableLocalization, captchaLanguage, and template options.

Customization

Style the SDK UI while preserving localized copy.

JavaScript SDK overview

Concepts, components, and runtime for the LoginRadius JavaScript SDK.

React SDK overview

Provider, hooks, and JSX components for the LoginRadius React SDK.

Hosted-page-themes localization

Reference translations for LoginRadius hosted-page themes.