Skip to main content

Language Translation for the UI

You can translate the UI using two main methods:

  1. You can override all displayed translation strings by providing translated versions for different languages (and even change the default English version).
  2. You can provide a translation function to integrate supertokens with your preferred internationalization library.

Translation strings#

Providing translation strings#

You can provide translations for each segment displayed in our UIs.

important
  • You can find the auth page header / footer UI keys here.
  • You can find the third party login UI keys here.
import React from "react";
import SuperTokens from "supertokens-auth-react";

SuperTokens.init({
    languageTranslations: { // This object contains all translation related options
        translations: { // These are the displayed translation strings for each language
          // The property names define the language code of the translations
          en: {
            // Here each key is a translation key and the value is the string that will be displayed
            // Setting the value to undefined will either display the translation from the default language or the translation key
            BRANDING_POWERED_BY_START: "We ❤️ ",
            // If you added a custom label or placeholder you can also provide translation for them if necessary
            // You can also use these to provide translations for your component overrides
            MY_CUSTOM_LABEL: "Age",
          },
          hu: {
            BRANDING_POWERED_BY_START: "Sok szeretettel: ",
            // This key is associated with an empty string by default, but you can override these as well.
            BRANDING_POWERED_BY_END: " 😊",
          }
        },
        /* 
         * This optional property sets the default and fallback language. 
         * It can be any string that will be used to fetch translations from the above object.
         * Defaults to "en"
         */
        defaultLanguage: "hu", 
    },
    appInfo: {
        appName: "...",
        apiDomain: "...",
        websiteDomain: "...",
    },
    recipeList: [
      // ...
    ],
});

Loading translations#

After initialization, you can provide additional translation data by calling the SuperTokens.loadTranslation. This can be useful if you are loading them asynchronously.

import SuperTokens from "supertokens-auth-react";

// This method takes an object as a parameter, which is structured the same as above.
// This will be merged into the existing definitions, so any properties missing here won't remove them from the already loaded translations
SuperTokens.loadTranslation({
  en: {
    BRANDING_POWERED_BY_END: " :)",
  }
});

Changing the current language#

You can update which translations store is displayed by calling the SuperTokens.changeLanguage.

import SuperTokens from "supertokens-auth-react";

SuperTokens.changeLanguage("hu");

Using an internationalization library#

You can easily integrate SuperTokens with your internationalization library of choice. You can check out an example using i18next here. To do this you need to do two things:

  1. Provide the translation function in SuperTokens.init
import React from "react";
import SuperTokens from "supertokens-auth-react";

SuperTokens.init({
    languageTranslations: {
        translationFunc: (key: string) => {
          // The string returned by this function will be displayed
          return key + "!";
        },
    },
    appInfo: {
        appName: "...",
        apiDomain: "...",
        websiteDomain: "...",
    },
    recipeList: [
      // ...
    ],
});
  1. Call SuperTokens.changeLanguage or SuperTokens.loadTranslation to re-render the translated UI

This is necessary, because the SDK will only re-render and update the displayed strings after either of the above functions are called. You can easily do this in event handlers, when updating the language choice or while adding new translation data.

Partial translations#

If the SDK can't find a segment in the current language's translation store, we will check the default language store and use the translation from there. The raw translation key is displayed if it's also missing from the default store. For example, this can happen for custom error messages returned by the backend API.

Saving language preferences#

The currently chosen language is stored in a cookie, this way it can be restored the next time the page loads. The domain of this cookie can be customized through the currentLanguageCookieScope option. This can be useful if you are running our SDK in multiple applications and want to share the language choice between sub-domains.

import React from "react";
import SuperTokens from "supertokens-auth-react";

SuperTokens.init({
    languageTranslations: {
        currentLanguageCookieScope: ".example.com",
    },
    appInfo: {
        appName: "...",
        apiDomain: "...",
        websiteDomain: "...",
    },
    recipeList: [
      // ...
    ],
});

Translations in component overrides#

The SDK also exports the useTranslation React hook you can use while overriding components. It returns a function that takes a translation segment key and returns it translated to the currently selected language. For more information on what translation keys you should use and the exact syntax, please see the original source code of the component you are overriding.

import React from "react";
import { useTranslation } from "supertokens-auth-react";

export const HeaderOverride = () => {
    const t = useTranslation();

    return (
        <div>
            <img src="octocat.jpg" />
            {t("MY_TRANSLATION_KEY") /* You can use your own custom translation keys as well as the default ones */}
        </div>
    );
};
Looking for older versions of the documentation?
Which UI do you use?
Custom UI
Pre built UI