Translate Clerk components
A multilingual application needs sign-in and account-management UI in a supported language.
Clerk · Pipe
localization
Clerk localization lets you replace text in prebuilt Clerk components with predefined or custom language resources. Install @clerk/localizations, import a locale, and pass it through the integration's localization option.
How it works
Clerk localization replaces text in Clerk's prebuilt components with predefined or custom strings. Install the localizations package, import the locale resource, and provide it through the localization prop on the appropriate Clerk integration or provider.
Syntax
<ClerkProvider localization={locale}>...</ClerkProvider>Parameters
| Name | Type | Description |
|---|---|---|
localization | LocalizationResource | Localization resource containing translated or overridden Clerk component strings. |
Key points
- Localization can replace component strings, allowing translation or brand-specific wording.
- Use the package's ready-made locale resources instead of defining every translation manually.
- Add the localization package to the application before importing locale resources.
- The locale resource is supplied through Clerk's
localizationproperty. - Integrations that use appearance accept localization as a nested appearance option.
- Custom localization files use a shortened language-region naming convention.
Common mistakes
- Localization does not translate the hosted Clerk Account Portal.
- Portal pages stay English even when application components use a localization.
Example: Apply a predefined localization
import { ClerkProvider } from '@clerk/nextjs'
import { frFR } from '@clerk/localizations'
export default function RootLayout({ children }: { children: React.ReactNode }) {
return <ClerkProvider localization={frFR}>{children}</ClerkProvider>
}Installs and applies the predefined French localization to Clerk components through the provider.
When to use it
Adapt component wording
A product wants Clerk UI labels to match its terminology or tone.
Create a custom localization
A required language is not included in the predefined package resources.
Interview questions
QHow do you enable a predefined Clerk localization?
Install @clerk/localizations, import the locale resource, and pass it to the localization prop. With React integrations, the resource is commonly supplied through <ClerkProvider>.
Follow-up: How would you customize wording that is not covered by a predefined locale? Use a custom localization resource that overrides the relevant component strings.
QHow are predefined locale exports named?
The package exports locale resources using a name formed by removing the hyphen from the language-region code. For example, French for France uses the frFR export.
Follow-up: How should a Canadian French resource be named when contributing one? Use the abbreviated language-region form, such as fr-CA.ts.
QWhat parts of Clerk does localization affect?
Localization changes text rendered by Clerk components in the application. It does not change text in the hosted Clerk Account Portal, which remains English.
Follow-up: What should be localized separately if users also interact with the portal? Provide translations through the application's own content or other supported portal customization mechanisms.
Related
@clerk/localizationsClerkProviderappearancelocalizationLocalizationResourcecustom localization