Localization prop (experimental)
This feature is currently experimental and may not behave as expected. If you encounter any issues, please reach out to support(opens in a new tab) with as much detail as possible.
Clerk offers the ability to override the strings for all of the elements in each of the Clerk Components. This allows you to provide localization for your users or change the wording to suit your brand.
@clerk/localizations
The @clerk/localizations
package contains predefined localizations for the Clerk Components. Clerk currently supports:
- ar-SA
- cs-CZ
- da-DK
- de-DE
- el-GR
- en-US (default)
- es-ES
- fr-FR
- he-IL
- it-IT
- ja-JP
- ko-KR
- nb-NO
- nl-NL
- pl-PL
- pt-BR
- pt-PT
- ru-RU
- sk-SK
- sv-SE
- tr-TR
- uk-UA
- vi-VN
- zh-CN
- zh-TW
Usage
To get started, install the @clerk/localizations
package.
terminalnpm install @clerk/localizations
terminalyarn add @clerk/localizations
terminalpnpm add @clerk/localizations
Once the @clerk/localizations
package is installed, you can import the localizations you need by removing the "-" from the locale. In this example, the fr-FR locale is imported as frFR
. The imported localization is then passed to the localization
prop on the <ClerkProvider>
.
_app.tsximport { ClerkProvider } from "@clerk/nextjs"; // fr-FR locale is imported as frFR import { frFR } from "@clerk/localizations"; import type { AppProps } from "next/app"; function MyApp({ Component, pageProps }: AppProps) { return ( // Add the localization prop to the ClerkProvider <ClerkProvider localization={frFR} {...pageProps}> <Component {...pageProps} /> </ClerkProvider> ); } export default MyApp;
Adding or updating a localization
Our localizations are customer-sourced and we encourage customers to add or update localizations. To do so, follow these steps:
- Fork the https://github.com/clerk/javascript/(opens in a new tab) repo.
- Clone it locally to edit it.
- Review our Contributing(opens in a new tab) guide.
- If you are updating an existing localization locate the file in
packages/localizations/src
- If you are adding a new language, copy the
en-US.ts
file and name it according to your language. The naming is the abbreviated language-region. For example, for French in Canada, it would befr-CA.ts.
- Go through the file and edit the entries.
- If you are adding a new localization, add the language to the
packages/localizations/src/index.ts
file. - Commit your changes to git and push them to your fork. Create a Pull Request(opens in a new tab) from your fork to Clerk's repo against the
main
branch. We will review and either approve or ask for updates.
Custom localizations
You can also provide your own localizations for the Clerk Components. This is useful if you want to provide limited or quick localization for a language that Clerk doesn't currently support or if you want to change the wording to suit your brand.
Usage
_app.tsximport { ClerkProvider } from "@clerk/nextjs"; import type { AppProps } from "next/app"; const localization = { socialButtonsBlockButton: "Sign In with {{provider|titleize}}", }; function MyApp({ Component, pageProps }: AppProps) { return ( <ClerkProvider localization={localization} {...pageProps}> <Component {...pageProps} /> </ClerkProvider> ); } export default MyApp;
To find the key for your translation (like the socialButtonsBlockButton
from the code example below), open up our English localization file(opens in a new tab). Search the file for the term that you want to customize.
For example, if you want to change the 'to continue to' string from the <SignIn />
and <SignUp />
components, you would search for 'to continue to'. You will find several instances of this. Some of those are in the the following signUp
object:
signUp: { start: { title: 'Create your account', subtitle: 'to continue to {{applicationName}}', actionText: 'Have an account?', actionLink: 'Sign in', }, emailLink: { title: 'Verify your email', subtitle: 'to continue to {{applicationName}}', formTitle: 'Verification link', formSubtitle: 'Use the verification link sent to your email address', resendButton: "Didn't receive a link? Resend", verified: { title: 'Successfully signed up', }, loading: { title: 'Signing up...', }, verifiedSwitchTab: { title: 'Successfully verified email', subtitle: 'Return to the newly opened tab to continue', subtitleNewTab: 'Return to previous tab to continue', }, }, emailCode: { title: 'Verify your email', subtitle: 'to continue to {{applicationName}}', formTitle: 'Verification code', formSubtitle: 'Enter the verification code sent to your email address', resendButton: "Didn't receive a code? Resend", }, phoneCode: { title: 'Verify your phone', subtitle: 'to continue to {{applicationName}}', formTitle: 'Verification code', formSubtitle: 'Enter the verification code sent to your phone number', resendButton: "Didn't receive a code? Resend", }, continue: { title: 'Fill in missing fields', subtitle: 'to continue to {{applicationName}}', actionText: 'Have an account?', actionLink: 'Sign in', }, },
If you want to customize multiple entries from the <SignUp />
component, the procedure would resemble the following:
const localization = { signUp: { start: { subtitle: 'to access {{applicationName}}', }, emailCode: { subtitle: 'to access {{applicationName}}' } } };
Last updated on January 8, 2024