Auth Studio V3 supports multiple languages so your users see content in a language they understand. This guide explains how language is detected, how to override it, and how to implement localization programmatically using the V3JS SDK.

Localization

JS Libraries V3 Quick Start

If your implementation uses JS Libraries V3 with LoginRadiusSDK, configure localization through raasoption.localizationConfig.

Start with One Key

const localization = {
  login: {
    title: "Connexion",
  },
};

raasoption.localizationConfig = localization;

Add More Keys (Optional)

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

raasoption.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." }
  ],
  ...
};

raasoption.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." },
  ],
};

raasoption.localizationConfig = localization;

Full Key Reference

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

Example reference path:

v3/localization/en.json

How to use the reference files

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

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

What Localization Does

Detects the browser's preferred language automatically
Allows you to force a language with a query parameter
Enables per-component text customization across Auth, Profile, and Workflow
Supports programmatic localization via commonOptions.localization when using V3JS directly

How Language Is Chosen

By default, Auth Studio uses the browser's language settings. You can use JavaScript with the V3JS SDK to override the language options and create a customized experience.

Important: If browser localization is enabled (localization = true in commonOptions), template-level localization takes priority and will auto-switch based on browser settings. In this case, localizationObject passed in commonOptions will not be honored.

Programmatic Localization

When using V3JS directly, you can implement localization in two ways:

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 commonOptions = {
  apiKey: "your-api-key",
  localization: localization,
};

const LRObject = new LoginRadiusV3(commonOptions);
LRObject.init();

Dynamic Localization (Based on 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 = LRObject.util.parseQueryString(
    window.location.search.substring(1),
  );
  const lang = params.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 localization = await getLocalizationFromUrl();

  const commonOptions = {
    apiKey: "your-api-key",
    localization: localization,
  };

  const LRObject = new LoginRadiusV3(commonOptions);
  LRObject.init();
})();

Note: The page must reload when 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;
});

Browser Localization vs Programmatic Localization

Browser Localization Enabled

If localization = true is passed in commonOptions:

Template-level localization takes priority
Language auto-switches based on browser settings
localizationObject in commonOptions will not be honored

Browser Localization Disabled

If browser localization is turned off:

localizationObject passed in commonOptions will be merged with default template translations
Only specified fields are overridden; others use default English content

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

const commonOptions = {
  apiKey: "your-api-key",
  localization: localizationObject, // Merging with default template
};

const LRObject = new LoginRadiusV3(commonOptions);
LRObject.init();

Text Customization

Customize titles, button labels, descriptions, and input labels per component.

Components include: Login, Passwordless, OTP, Social, Footer, and more
Edit text per language and component directly in the Admin Console
Preview changes and verify layout before publishing

Using Auth Studio Templates

Go to Admin Console > Auth Studio > Templates
Edit text directly in the editor
Create one template per language
No localization object needed when using templates

Validation and error messages: localized using hooks

Email & SMS Localization

Use language-specific template names for emails and SMS:

const params = LRObject.util.parseQueryString(
  window.location.search.substring(1),
);

const commonOptions = {
  verificationEmailTemplate:
    params.language === "french"
      ? "email-verification-fr"
      : "verification-default",
  smsTemplateWelcome:
    params.language === "french" ? "welcome-sms-fr" : "welcome-default",
};

Template	Option
Verification Email	`verificationEmailTemplate`
Reset Password	`resetPasswordEmailTemplate`
Welcome Email	`welcomeEmailTemplate`
Welcome SMS	`smsTemplateWelcome`

Google reCAPTCHA Language

Set the reCAPTCHA language based on your localization:

const params = LRObject.util.parseQueryString(
  window.location.search.substring(1),
);
commonOptions.v2RecaptchaLanguage = params.language === "french" ? "fr" : "en";

See the full list of reCAPTCHA language codes.

Localization Object Schema

The localization object supports customization for all major components:

Authentication Components

login — Login form
registration — Registration form
passkey-registration — Passkey registration

Password Management

forgotpassword — Forgot password form
reset-password-by-token — Reset password via token
reset-password-by-email-otp — Reset password via email OTP
reset-password-by-phone-otp — Reset password via phone OTP

MFA Flows

mfa-selector — MFA method selector
mfa-passkey — Passkey MFA
email-otp — Email OTP verification
sms-otp — SMS OTP verification
authenticator-login — Authenticator app login
authenticator-setup — Authenticator app setup

Passwordless Flows

passwordless-login — Passwordless login initiation
verify-passwordless-login-email — Email link verification
verify-passwordless-login-email-otp — Email OTP verification
verify-passwordless-login-sms-otp — SMS OTP verification

PIN Flows

set-pin — Set PIN
pin-authentication — PIN authentication
forgot-pin — Forgot PIN
reset-pin-by-reset-token — Reset PIN via token
reset-pin-by-otp — Reset PIN via OTP

Verification

verify-email-otp — Email OTP verification
verify-email-link — Email link verification
verify-sms-otp — SMS OTP verification

consent-form — Consent form
privacy-policy — Privacy policy

Account States

account-blocked — Account blocked message
account-suspended — Account suspended message
account-locked — Account locked message
account-restricted — Account restricted message

Profile Components

profile — Profile overview
email-profile — Email management
personal-details-profile — Personal details
providers-profile — Connected providers

Each component supports fields like title, description, buttonText, emailLabel, passwordLabel, and component-specific fields. See the full schema reference for complete field lists.

Add Languages

In the Admin Console, open Auth Studio -> Localization
Click Add Language, choose a language code, and provide translations
Ensure all required strings are covered for each enabled component

RTL and Layout

If you support right-to-left languages (like Arabic), verify spacing, alignment, and component mirroring. Keep styles flexible and avoid assumptions about text length.

Accessibility

Provide sufficient contrast for text in all themes
Maintain readable font sizes and spacing
Ensure keyboard navigation and screen reader support work across languages

Testing

Switch between target languages on desktop and mobile
Validate error messages, email templates, and SMS content
Confirm date, time, currency, and number formats per locale
Verify that browser localization and programmatic localization work as expected

Localization

On this page