--- title: Language Translation for the UI description: Translate your UI by providing custom translation strings or integrating with an internationalization library. sidebar: order: 70 --- ## 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 :::warning 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. :::info[Important] - You can find the auth page header / footer UI keys in the [GitHub repository](https://github.com/supertokens/supertokens-auth-react/blob/master/lib/ts/translation/translations.ts). - You can find the `emailpassword` login UI keys in the [GitHub repository](https://github.com/supertokens/supertokens-auth-react/blob/master/lib/ts/recipe/emailpassword/components/themes/translations.ts). ::: ```tsx 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: [ // ... ], }); ``` ```tsx check=false reason="pre-built UI globals are provided by the host framework" // this goes in the auth route config of your frontend app (once the pre-built UI script has been loaded) supertokensUIInit({ 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. ```tsx 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: " :)", }, }); ``` ```tsx check=false reason="pre-built UI globals are provided by the host framework" // 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 supertokensUI.loadTranslation({ en: { BRANDING_POWERED_BY_END: " :)", }, }); ``` ### 3. Change the current language You can update which translations store displays by calling the `SuperTokens.changeLanguage`. ```tsx import SuperTokens from "supertokens-auth-react"; SuperTokens.changeLanguage("hu"); ``` ```tsx check=false reason="pre-built UI globals are provided by the host framework" supertokensUI.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](https://github.com/supertokens/supertokens-auth-react/blob/master/examples/with-i18next/src/App.js). To do this you need to do two things: 1. Provide the translation function in `SuperTokens.init` ```tsx 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: [ // ... ], }); ``` ```tsx check=false reason="pre-built UI globals are provided by the host framework" // this goes in the auth route config of your frontend app (once the pre-built UI script has been loaded) supertokensUIInit({ languageTranslations: { translationFunc: (key: string) => { // The string returned by this function will be displayed return key + "!"; }, }, appInfo: { appName: "...", apiDomain: "...", websiteDomain: "...", }, recipeList: [ // ... ], }); ``` 2. 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. ```tsx import React from "react"; import SuperTokens from "supertokens-auth-react"; SuperTokens.init({ languageTranslations: { currentLanguageCookieScope: ".example.com", }, appInfo: { appName: "...", apiDomain: "...", websiteDomain: "...", }, recipeList: [ // ... ], }); ``` ```tsx check=false reason="pre-built UI globals are provided by the host framework" // this goes in the auth route config of your frontend app (once the pre-built UI script has been loaded) supertokensUIInit({ 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. :::info[Caution] Not applicable for non react apps. ::: ```tsx import React from "react"; import { useTranslation } from "supertokens-auth-react"; export const HeaderOverride = () => { const t = useTranslation(); return (
{t("MY_TRANSLATION_KEY") /* You can use your own custom translation keys as well as the default ones */}
); }; ```