@clerk/localizations

Changelog · Report a Bug · Request a Feature · Get help

Getting Started

When using Clerk's components you can override the strings for all of the elements. This allows you to provide localization for your users or change the wording to suit your brand.

@clerk/localizations contains localized strings for applications using Clerk. If you found a typo, inaccuracies, or want to contribute a new language, please submit a PR and follow the contributing guide.

[!WARNING] Clerk officially only maintains the en-US (English - United States) locale. All other language translations provided within this package are community contributions.

Installation

The fastest way to get started with @clerk/localizations is by following the localization reference documentation.

Usage

Furthermore, you can learn how to update a localization or use a custom one.

Support

You can get in touch with us in any of the following ways:

• Join our official community Discord server
• On our support page

Contributing

We're open to all community contributions! If you'd like to contribute in any way, please read our contribution guidelines and code of conduct.

Adding a new localization key

1. Open the types/src/localization.ts file to add a new key to the _LocalizationResource type.

   Naming things is hard, so try these things first: Has the component that should contain the new key already other localizations? If yes, see how they are named and if you could follow that pattern. For example, the <SignIn /> component has keys with signIn.start.title, then I'd make sense to follow the signIn. pattern. If you're not sure, take your best guess and the maintainers will comment on the PR!

   An exception to that are any errors that might be returned from the Frontend API. They need to go into the unstable__errors object inside each localization.

2. Run npm build to compile types with your new key

3. Open the localizations/src/en-US.ts file and add your new key to the object. en-US is the default language. If you feel comfortable adding your message in another language than English, feel free to also edit other files.

4. Use the new localization key inside the component. There are two ways:

   • The string is inside a component like <Text>:

     - <Text>Role</Text>
     + <Text localizationKey={localizationKeys('formFieldLabel__role')} />

   • The string is used in a function call:

     + const { t } = useLocalizations();
     
     - card.setError('Some Error')
     + card.setError(t(localizationKeys('some_error')))

   You'll need to import localizationKeys and useLocalizations when using them.

Updating a localization key

1. Open the localizations/src/en-US.ts file and search for the text you want to update.

2. Update the text inside en-US. If possible, also update other languages.

Adding a new localization language

1. Create a new file that follows the IETF language tag format

2. Copy the contents of the en-US.ts file and translate all keys where necessary. Empty strings can stay empty. You don't need to translate things word by word, adjust where necessary as long as the same meaning is conveyed.

Security

@clerk/localizations follows good practices of security, but 100% security cannot be assured.

@clerk/localizations is provided "as is" without any warranty. Use at your own risk.

For more information and to report security issues, please refer to our security documentation.

License

This project is licensed under the MIT license.

See LICENSE for more information.