Skip to main content

Language Translation for the UI

Overview​

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.

Before you start​

This feature is only applicable to React apps that use the prebuilt UI.

Using translation strings​

1. Provide translation strings​

You can provide translations for each segment displayed in the user interfaces.

Important
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: [
      // ...
    ],
});

2. Load 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: " :)",
  }
});

3. Change the current language​

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

import SuperTokens from "supertokens-auth-react";

SuperTokens.changeLanguage("hu");

Using an internationalization library​

You can integrate SuperTokens with your internationalization library of choice. You can check out an example using i18next in the GitHub repository. 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 only re-renders and updates the displayed strings after calling either of the above functions. You can 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, it checks the default language store and uses the translation from there. The raw translation key displays if it's also missing from the default store. For example, this can happen for custom error messages returned by the backend API.

Save language preferences​

The system stores the chosen language in a cookie, allowing it to restore the language the next time the page loads. You can customize the domain of this cookie through the currentLanguageCookieScope option. This can be useful if you are running the 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 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>
    );
};