Localization

Auth Studio 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.

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

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.

Add Languages

In the Admin Console, open Auth Studio -> Localization
Click Add Language and select one of the available predefined languages, such as English, Spanish, French, Swedish, Arabic, or Chinese
Add the language to your template and update the translation values in the editor for each required component
Ensure all required strings are reviewed for every enabled flow before publishing

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.

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