chore(repo): Improve main & localizations README

.changeset/big-socks-perform.md

@@ -0,0 +1,5 @@
+---
+"@clerk/localizations": patch
+---
+
+Improve README by adding instructions on how to add/edit localizations

README.md

@@ -7,10 +7,16 @@
   </a>
   <br />
 </p>
+<h1 align="center">
+  Official Clerk JavaScript SDKs
+</h1>
+<p align="center">
+  <strong>
+    Clerk helps developers build user management. We provide streamlined user experiences for your users to sign up, sign in, and manage their profile.
+  </strong>
+</p>
 
-# Official Clerk JavaScript SDKs
-
-This repository contains all the Clerk JavaScript SDKs under the `@clerk/` namespace. Visit [https://clerk.com](https://clerk.com) to signup for an account.
+This repository contains all the Clerk JavaScript SDKs under the `@clerk` namespace. Visit [clerk.com](https://clerk.com) to signup for an account.
 
 [![chat on Discord](https://img.shields.io/discord/856971667393609759.svg?logo=discord)](https://clerk.com/discord)
 [![documentation](https://img.shields.io/badge/documentation-clerk-green.svg)](https://clerk.com/docs)
@@ -24,53 +30,41 @@ Would you like to work on Open Source software and help maintain this repository
 
 ---
 
-## Documentation and Usage
+## 🚀 Get Started with Clerk
 
-For how to get started with Clerk, you can refer to the official [documentation page](https://clerk.com/docs).
+1. [Sign up for an account](https://dashboard.clerk.com/sign-up?utm_source=github&utm_medium=clerk_js_repo_readme)
+1. Create an application in your Clerk dashboard
+1. Spin up a new codebase with one of the [quickstart guides](https://clerk.com/docs/quickstarts/overview?utm_source=github&utm_medium=clerk_js_repo_readme)
 
-For JavaScript environments/platforms that Clerk supports, there should be a specific package corresponding to the respective technology.
+This repository contains the SDKs for environment/platforms that Clerk supports. For example, if you want to use Clerk with Node.js you can install:
 
 ```sh
 npm install @clerk/clerk-sdk-node
 # or
 yarn add @clerk/clerk-sdk-node
+# or
+pnpm add @clerk/clerk-sdk-node
 ```
 
-## Packages
+## 🎓 Learning Clerk
 
-For package specific details on installation, architecture and usage usage, you can refer to the package's README file.
+Clerk's full documentation is available at [clerk.com/docs](https://clerk.com/docs?utm_source=github&utm_medium=clerk_js_repo_readme).
 
-- [`@clerk/backend`](./packages/backend): Functionalities regarded as "core" for Clerk to operate with. _Authentication resolution, API Resources etc._
-- [`@clerk/clerk-expo`](./packages/expo) Clerk package for the Expo universal app framework.
-- [`@clerk/clerk-js`](./packages/clerk-js): Core JavaScript implementation used by Clerk in the browser.
-- [`@clerk/clerk-react`](./packages/react) Clerk package for React applications.
-- [`@clerk/clerk-sdk-node`](./packages/sdk-node): SDK for native Node.js environment and frameworks.
-- [`@clerk/fastify`](./packages/fastify): Clerk package for Fastify.
-- [`@clerk/chrome-extension`](./packages/chrome-extension): Clerk package for Chrome extensions.
-- [`@clerk/nextjs`](./packages/nextjs): Clerk package for Next.js.
-- [`@clerk/remix`](./packages/remix): Clerk package for Remix.
-- [`@clerk/types`](./packages/types) Main TypeScript typings for Clerk libraries.
-- ...
+- **We recommend starting with the [Quickstart guides](https://clerk.com/docs/quickstarts/overview).** It'll enable you to quickly add Clerk to your application. If you're starting a new project and are not sure what to pick, use [Next.js](https://nextjs.org/docs/getting-started/installation) and [@clerk/nextjs](https://clerk.com/docs/quickstarts/nextjs).
+- **To learn more about Clerk's components and features, checkout the rest of the [Clerk documentation](https://clerk.com/docs?utm_source=github&utm_medium=clerk_js_repo_readme).** You'll be able to e.g. browse the [component reference](https://clerk.com/docs/components/overview?utm_source=github&utm_medium=clerk_js_repo_readme) page.
 
-Additionally there are packages which act as shared utilities or building blocks.
+## 🚢 Release Notes
 
-## Setup
+Curious what we shipped recently? You can browse the [GitHub Releases](https://github.com/clerkinc/javascript/releases) page or look at the individual `CHANGELOG.md` files inside each package (e.g. [`clerk-js CHANGELOG`](https://github.com/clerkinc/javascript/blob/main/packages/clerk-js/CHANGELOG.md)).
 
-- Clone the repository.
-- `npm install`.
-- `npm run build`.
+## 🤝 How to Contribute
 
-\* See the [docs folder](./docs) for additional repository documentation.
+We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/clerkinc/javascript/blob/main/docs/CONTRIBUTING.md). We'd love to have you as part of the Clerk community!
 
-## Cleanup
+It'll show you how to make changes to the SDKs, open pull requests, or submitting issues. If you want to add or edit localizations (e.g. how a button text is translated to your language), you can check out the [`localizations` README](./packages/localizations/README.md).
 
-To clean existing builds and installed dependencies of the monorepo and setup again, run `npm run nuke`.
+## 📝 License
 
-## How to add a new localization key
+This project is licensed under the **MIT license**.
 
-- Add the key types to the types [package](./packages/types/src/localization.ts).
-- Add the corresponding localization values for every supported language in the [localizations package](./packages/localizations/)
-- Replace the plain string (if there is one) with the localization value like so:  
-  `<Text>Role</Text>`  
-  becomes  
-  `<Text localizationKey={localizationKeys('formFieldLabel__role')} />`
+See [LICENSE](https://github.com/clerkinc/javascript/blob/main/LICENCE.md) for more information.

docs/CONTRIBUTING.md

@@ -18,6 +18,7 @@ Please note we have a [code of conduct](https://github.com/clerkinc/javascript/b
     - [What is the difference between a commit message, a PR description and a changeset description?](#what-is-the-difference-between-a-commit-message-a-pr-description-and-a-changeset-description)
     - [Notes on Pull Requests](#notes-on-pull-requests)
   - [Issues and feature requests](#issues-and-feature-requests)
+  - [Localizations](#localizations)
   - [Publishing packages](#publishing-packages)
   - [License](#license)
 
@@ -35,6 +36,16 @@ The current monorepo setup is based on:
 - [GitHub Actions](https://docs.github.com/en/actions), used for quality checks and automated release orchestration.
 - [Yalc](https://github.com/wclr/yalc), used for to publish packages locally and test them in other local projects.
 
+All packages of the monorepo are inside [packages](../packages). For package specific details on installation, architecture and usage, you can refer to the package's README file.
+
+- [`@clerk/backend`](../packages/backend): Functionalities regarded as "core" for Clerk to operate with. _Authentication resolution, API Resources etc._
+- [`@clerk/clerk-js`](../packages/clerk-js): Core JavaScript implementation used by Clerk in the browser.
+- [`@clerk/clerk-react`](../packages/react) Clerk package for React applications.
+- [`@clerk/types`](../packages/types): Main TypeScript typings for Clerk libraries.
+- Browse [packages](../packages) to see more
+
+Additionally there are packages which act as shared utilities or building blocks.
+
 ### Prerequisites
 
 Have a node version installed that is equal or higher than the one defined in `.nvmrc`
@@ -154,6 +165,10 @@ Issues that have the label `needs-triage` have been seen by our team and are que
 
 If you are a paying Clerk customer looking for support, please reach out directly to our support team by heading to https://www.clerk.com, clicking the chat bubble in the bottom right corner, and selecting "contact support".
 
+## Localizations
+
+If you want to add or edit localizations (e.g. how a button text is translated to your language), you can check out the [`localizations` README](../packages/localizations/README.md).
+
 ## Publishing packages
 
 _Note: Only core maintainers can publish packages._

packages/localizations/README.md

@@ -30,7 +30,9 @@
 
 ## Overview
 
-`@clerk/localizations` contains localized strings for applications using Clerk.
+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` 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](#contributing).
 
 ## Getting Started
 
@@ -52,22 +54,43 @@ npm run build
 
 ## Usage
 
+`@clerk/localizations` contains predefined localizations you can use:
+
 ```javascript
-import { ClerkProvider } from '@clerk/nextjs';
+import React from 'react';
+import { ClerkProvider } from '@clerk/clerk-react';
 import { frFR } from '@clerk/localizations';
 
-function MyApp({ Component, pageProps }) {
+function App() {
+  return (
+    <ClerkProvider localization={frFR}>
+      <div>Hello from clerk</div>
+    </ClerkProvider>
+  );
+}
+
+export default App;
+```
+
+You can also provide your own localization:
+
+```javascript
+import React from 'react';
+import { ClerkProvider } from '@clerk/clerk-react';
+
+const localization = {
+  socialButtonsBlockButton: 'Sign In with {{provider|titleize}}',
+};
+
+function App() {
   return (
-    <ClerkProvider
-      localization={frFR}
-      {...pageProps}
-    >
-      <Component {...pageProps} />
+    <ClerkProvider localization={localization}>
+      <div>Hello from clerk</div>
     </ClerkProvider>
   );
 }
 
-export default MyApp;
+export default App;
 ```
 
 ## Support
@@ -82,6 +105,50 @@ You can get in touch with us in any of the following ways:
 
 We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/clerkinc/javascript/blob/main/docs/CONTRIBUTING.md).
 
+### Adding a new localization key
+
+1. Open the [`types/src/localization.ts`](https://github.com/clerkinc/javascript/blob/main/packages/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.
+
+1. Run `npm build` to compile `types` with your new key
+
+1. Open the [`localizations/src/en-US.ts`](https://github.com/clerkinc/javascript/blob/main/packages/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.
+
+1. Use the new localization key inside the component. There are two ways:
+
+   - The string is inside a component like `<Text>`:
+
+     ```diff
+     - <Text>Role</Text>
+     + <Text localizationKey={localizationKeys('formFieldLabel__role')} />
+     ```
+
+   - The string is used in a function call:
+
+     ```diff
+     + 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`](https://github.com/clerkinc/javascript/blob/main/packages/localizations/src/en-US.ts) file and search for the text you want to update.
+
+1. 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](https://en.wikipedia.org/wiki/IETF_language_tag) format
+
+1. 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.