feat(shared,localizations): Add `flatLocalization` utility #7659

alexcarpenter · 2026-01-23T16:14:49Z

Description

A utility function that converts flattened localization objects (with dot-notation keys) to nested LocalizationResource objects for use with Clerk's localization prop.

Installation

import { flatLocalization } from '@clerk/localizations/utils';

Usage

Convert flattened localization keys to nested objects:

import { flatLocalization } from '@clerk/localizations/utils';

const flattened = {
  formFieldLabel__emailAddress: 'Email address',
  'unstable__errors.passwordComplexity.maximumLength': 'Password is too long',
  'unstable__errors.passwordComplexity.minimumLength': 'Password is too short',
};

const nested = flatLocalization(flattened);
// Result:
// {
//   formFieldLabel__emailAddress: 'Email address',
//   unstable__errors: {
//     passwordComplexity: {
//       maximumLength: 'Password is too long',
//       minimumLength: 'Password is too short',
//     },
//   },
// }

Use with Clerk components:

import { ClerkProvider } from '@clerk/nextjs';
import { flatLocalization } from '@clerk/localizations/utils';

const localization = flatLocalization({
  'formFieldLabel__emailAddress': 'Email address',
  'unstable__errors.passwordComplexity.maximumLength': 'Password is too long',
});

export default function App() {
  return (
    <ClerkProvider localization={localization}>
      {/* Your app */}
    </ClerkProvider>
  );
}

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

Summary by CodeRabbit

New Features
- Added support for flattened (dot‑separated) localization keys and a utility to convert them into nested localization objects; new utility is publicly available.
Tests
- Added comprehensive runtime and type-level tests covering behavior, validation, edge cases, and type correctness.
Chores
- Test configuration, test script, and test tooling added; build setup adjusted to include localization utilities; exports updated to expose the new utilities.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

changeset-bot · 2026-01-23T16:14:53Z

🦋 Changeset detected

Latest commit: 66b9d1c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 20 packages

Name	Type
@clerk/localizations	Patch
@clerk/shared	Patch
@clerk/react	Patch
@clerk/ui	Patch
@clerk/agent-toolkit	Patch
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/chrome-extension	Patch
@clerk/clerk-js	Patch
@clerk/expo-passkeys	Patch
@clerk/expo	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/msw	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/vue	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2026-01-23T16:14:55Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jan 23, 2026 7:22pm

pkg-pr-new · 2026-01-23T16:22:33Z

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@7659

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@7659

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@7659

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@7659

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@7659

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@7659

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@7659

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@7659

@clerk/express

npm i https://pkg.pr.new/@clerk/express@7659

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@7659

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@7659

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@7659

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@7659

@clerk/react

npm i https://pkg.pr.new/@clerk/react@7659

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@7659

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@7659

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@7659

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@7659

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@7659

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@7659

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@7659

commit: 66b9d1c

coderabbitai · 2026-01-23T16:24:01Z

📝 Walkthrough

Walkthrough

Adds support for flattened localization objects and conversion utilities. Introduces the FlattenedLocalizationResource type and new shared utils: unflattenObject and validateLocalizationFormat. Adds flatLocalization and re-exports it from packages/localizations/src/utils. Includes comprehensive runtime and type tests for flatLocalization, a vitest.config.mts and tsconfig.test.json for tests, a package.json test script, vitest devDependencies, expands tsup entry points to include src/utils, and exposes a public exports entry for "./utils" in packages/localizations/package.json.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title accurately summarizes the main change: adding a flatLocalization utility function across the shared and localizations packages.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

alexcarpenter · 2026-01-23T18:06:33Z

!snapshot

clerk-cookie · 2026-01-23T18:08:43Z

Hey @alexcarpenter - the snapshot version command generated the following package versions:

Package	Version
@clerk/agent-toolkit	0.2.9-snapshot.v20260123180714
@clerk/astro	3.0.0-snapshot.v20260123180714
@clerk/backend	3.0.0-snapshot.v20260123180714
@clerk/chrome-extension	3.0.0-snapshot.v20260123180714
@clerk/clerk-js	6.0.0-snapshot.v20260123180714
@clerk/dev-cli	1.0.0-snapshot.v20260123180714
@clerk/expo	3.0.0-snapshot.v20260123180714
@clerk/expo-passkeys	1.0.0-snapshot.v20260123180714
@clerk/express	2.0.0-snapshot.v20260123180714
@clerk/fastify	2.6.9-snapshot.v20260123180714
@clerk/localizations	4.0.0-snapshot.v20260123180714
@clerk/msw	0.0.1-snapshot.v20260123180714
@clerk/nextjs	7.0.0-snapshot.v20260123180714
@clerk/nuxt	2.0.0-snapshot.v20260123180714
@clerk/react	6.0.0-snapshot.v20260123180714
@clerk/react-router	3.0.0-snapshot.v20260123180714
@clerk/shared	4.0.0-snapshot.v20260123180714
@clerk/tanstack-react-start	1.0.0-snapshot.v20260123180714
@clerk/testing	2.0.0-snapshot.v20260123180714
@clerk/ui	1.0.0-snapshot.v20260123180714
@clerk/upgrade	2.0.0-snapshot.v20260123180714
@clerk/vue	2.0.0-snapshot.v20260123180714

Tip: Use the snippet copy button below to quickly install the required packages.
@clerk/agent-toolkit

npm i @clerk/agent-toolkit@0.2.9-snapshot.v20260123180714 --save-exact

@clerk/astro

npm i @clerk/astro@3.0.0-snapshot.v20260123180714 --save-exact

@clerk/backend

npm i @clerk/backend@3.0.0-snapshot.v20260123180714 --save-exact

@clerk/chrome-extension

npm i @clerk/chrome-extension@3.0.0-snapshot.v20260123180714 --save-exact

@clerk/clerk-js

npm i @clerk/clerk-js@6.0.0-snapshot.v20260123180714 --save-exact

@clerk/dev-cli

npm i @clerk/dev-cli@1.0.0-snapshot.v20260123180714 --save-exact

@clerk/expo

npm i @clerk/expo@3.0.0-snapshot.v20260123180714 --save-exact

@clerk/expo-passkeys

npm i @clerk/expo-passkeys@1.0.0-snapshot.v20260123180714 --save-exact

@clerk/express

npm i @clerk/express@2.0.0-snapshot.v20260123180714 --save-exact

@clerk/fastify

npm i @clerk/fastify@2.6.9-snapshot.v20260123180714 --save-exact

@clerk/localizations

npm i @clerk/localizations@4.0.0-snapshot.v20260123180714 --save-exact

@clerk/msw

npm i @clerk/msw@0.0.1-snapshot.v20260123180714 --save-exact

@clerk/nextjs

npm i @clerk/nextjs@7.0.0-snapshot.v20260123180714 --save-exact

@clerk/nuxt

npm i @clerk/nuxt@2.0.0-snapshot.v20260123180714 --save-exact

@clerk/react

npm i @clerk/react@6.0.0-snapshot.v20260123180714 --save-exact

@clerk/react-router

npm i @clerk/react-router@3.0.0-snapshot.v20260123180714 --save-exact

@clerk/shared

npm i @clerk/shared@4.0.0-snapshot.v20260123180714 --save-exact

@clerk/tanstack-react-start

npm i @clerk/tanstack-react-start@1.0.0-snapshot.v20260123180714 --save-exact

@clerk/testing

npm i @clerk/testing@2.0.0-snapshot.v20260123180714 --save-exact

@clerk/ui

npm i @clerk/ui@1.0.0-snapshot.v20260123180714 --save-exact

@clerk/upgrade

npm i @clerk/upgrade@2.0.0-snapshot.v20260123180714 --save-exact

@clerk/vue

npm i @clerk/vue@2.0.0-snapshot.v20260123180714 --save-exact

alexcarpenter · 2026-01-23T18:39:10Z

!snapshot

clerk-cookie · 2026-01-23T18:41:23Z

Hey @alexcarpenter - the snapshot version command generated the following package versions:

Package	Version
@clerk/agent-toolkit	0.2.9-snapshot.v20260123183947
@clerk/astro	3.0.0-snapshot.v20260123183947
@clerk/backend	3.0.0-snapshot.v20260123183947
@clerk/chrome-extension	3.0.0-snapshot.v20260123183947
@clerk/clerk-js	6.0.0-snapshot.v20260123183947
@clerk/dev-cli	1.0.0-snapshot.v20260123183947
@clerk/expo	3.0.0-snapshot.v20260123183947
@clerk/expo-passkeys	1.0.0-snapshot.v20260123183947
@clerk/express	2.0.0-snapshot.v20260123183947
@clerk/fastify	2.6.9-snapshot.v20260123183947
@clerk/localizations	4.0.0-snapshot.v20260123183947
@clerk/msw	0.0.1-snapshot.v20260123183947
@clerk/nextjs	7.0.0-snapshot.v20260123183947
@clerk/nuxt	2.0.0-snapshot.v20260123183947
@clerk/react	6.0.0-snapshot.v20260123183947
@clerk/react-router	3.0.0-snapshot.v20260123183947
@clerk/shared	4.0.0-snapshot.v20260123183947
@clerk/tanstack-react-start	1.0.0-snapshot.v20260123183947
@clerk/testing	2.0.0-snapshot.v20260123183947
@clerk/ui	1.0.0-snapshot.v20260123183947
@clerk/upgrade	2.0.0-snapshot.v20260123183947
@clerk/vue	2.0.0-snapshot.v20260123183947

Tip: Use the snippet copy button below to quickly install the required packages.
@clerk/agent-toolkit

npm i @clerk/agent-toolkit@0.2.9-snapshot.v20260123183947 --save-exact

@clerk/astro

npm i @clerk/astro@3.0.0-snapshot.v20260123183947 --save-exact

@clerk/backend

npm i @clerk/backend@3.0.0-snapshot.v20260123183947 --save-exact

@clerk/chrome-extension

npm i @clerk/chrome-extension@3.0.0-snapshot.v20260123183947 --save-exact

@clerk/clerk-js

npm i @clerk/clerk-js@6.0.0-snapshot.v20260123183947 --save-exact

@clerk/dev-cli

npm i @clerk/dev-cli@1.0.0-snapshot.v20260123183947 --save-exact

@clerk/expo

npm i @clerk/expo@3.0.0-snapshot.v20260123183947 --save-exact

@clerk/expo-passkeys

npm i @clerk/expo-passkeys@1.0.0-snapshot.v20260123183947 --save-exact

@clerk/express

npm i @clerk/express@2.0.0-snapshot.v20260123183947 --save-exact

@clerk/fastify

npm i @clerk/fastify@2.6.9-snapshot.v20260123183947 --save-exact

@clerk/localizations

npm i @clerk/localizations@4.0.0-snapshot.v20260123183947 --save-exact

@clerk/msw

npm i @clerk/msw@0.0.1-snapshot.v20260123183947 --save-exact

@clerk/nextjs

npm i @clerk/nextjs@7.0.0-snapshot.v20260123183947 --save-exact

@clerk/nuxt

npm i @clerk/nuxt@2.0.0-snapshot.v20260123183947 --save-exact

@clerk/react

npm i @clerk/react@6.0.0-snapshot.v20260123183947 --save-exact

@clerk/react-router

npm i @clerk/react-router@3.0.0-snapshot.v20260123183947 --save-exact

@clerk/shared

npm i @clerk/shared@4.0.0-snapshot.v20260123183947 --save-exact

@clerk/tanstack-react-start

npm i @clerk/tanstack-react-start@1.0.0-snapshot.v20260123183947 --save-exact

@clerk/testing

npm i @clerk/testing@2.0.0-snapshot.v20260123183947 --save-exact

@clerk/ui

npm i @clerk/ui@1.0.0-snapshot.v20260123183947 --save-exact

@clerk/upgrade

npm i @clerk/upgrade@2.0.0-snapshot.v20260123183947 --save-exact

@clerk/vue

npm i @clerk/vue@2.0.0-snapshot.v20260123183947 --save-exact

alexcarpenter added 3 commits January 23, 2026 10:56

init

6fb2301

simplify

70914a7

make type safe

cb6321d

github-actions bot added localizations core-3 labels Jan 23, 2026

fix build

1ea2999

vercel bot deployed to Preview January 23, 2026 16:19 View deployment

Update flatLocalization.type.spec.ts

5ee270d

vercel bot deployed to Preview January 23, 2026 16:25 View deployment

sort

313d485

vercel bot deployed to Preview January 23, 2026 16:35 View deployment

add utils export

716efc1

vercel bot deployed to Preview January 23, 2026 18:33 View deployment

add changeset

66b9d1c

vercel bot deployed to Preview January 23, 2026 19:22 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(shared,localizations): Add `flatLocalization` utility #7659

feat(shared,localizations): Add `flatLocalization` utility #7659

Uh oh!

alexcarpenter commented Jan 23, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

changeset-bot bot commented Jan 23, 2026 •

edited

Loading

Uh oh!

vercel bot commented Jan 23, 2026 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Jan 23, 2026 •

edited

Loading

Uh oh!

coderabbitai bot commented Jan 23, 2026 •

edited

Loading

Walkthrough

Uh oh!

alexcarpenter commented Jan 23, 2026

Uh oh!

clerk-cookie commented Jan 23, 2026

Uh oh!

alexcarpenter commented Jan 23, 2026

Uh oh!

clerk-cookie commented Jan 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

feat(shared,localizations): Add flatLocalization utility #7659

Are you sure you want to change the base?

feat(shared,localizations): Add flatLocalization utility #7659

Uh oh!

Conversation

alexcarpenter commented Jan 23, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Installation

Usage

Checklist

Type of change

Summary by CodeRabbit

Uh oh!

changeset-bot bot commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel bot commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new bot commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai bot commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Uh oh!

alexcarpenter commented Jan 23, 2026

Uh oh!

clerk-cookie commented Jan 23, 2026

Uh oh!

alexcarpenter commented Jan 23, 2026

Uh oh!

clerk-cookie commented Jan 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

feat(shared,localizations): Add `flatLocalization` utility #7659

feat(shared,localizations): Add `flatLocalization` utility #7659

alexcarpenter commented Jan 23, 2026 •

edited by coderabbitai bot

Loading

changeset-bot bot commented Jan 23, 2026 •

edited

Loading

vercel bot commented Jan 23, 2026 •

edited

Loading

pkg-pr-new bot commented Jan 23, 2026 •

edited

Loading

coderabbitai bot commented Jan 23, 2026 •

edited

Loading