feat(shared,ui): Add support for flattened localization usage

[alexcarpenter]

Description

Adds support for a flattened localization object format alongside the existing nested format, allowing users to use dot-notation keys (e.g., "signIn.start.title") instead of nested objects.

Usage

Nested format (existing):

<ClerkProvider
  localization={{
    signIn: {
      start: { title: "Welcome back" }
    }
  }}
/>

Flattened format (new):

<ClerkProvider
  localization={{
    "signIn.start.title": "Welcome back",
    "signIn.start.subtitle": "Please sign in"
  }}
/>

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

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

Summary by CodeRabbit

• New Features

  • Localization now accepts both nested and flattened dot-notation formats (e.g., "button.submit": "Click me") and normalizes/validates inputs for consistent merging.

• Library

  • Utility functions for detecting, validating, and converting flattened/localized objects are now publicly available via the utils bundle.

• Tests

  • Added comprehensive tests covering flattened vs nested detection, validation, and unflattening behaviors.

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

[vercel]

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 2:25pm

[changeset-bot]

⚠️ No Changeset found

Latest commit: bb0a850

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[coderabbitai]

📝 Walkthrough

Walkthrough

The change adds support for nested and flattened dot-notation localization inputs. New types (LocalizationPath, FlattenedLocalizationResource, LocalizationInput) were added. Utilities isFlattenedObject, isNestedObject, validateLocalizationFormat, and unflattenObject were implemented and exported. ClerkOptions.localization type was changed from LocalizationResource to LocalizationInput. parseLocalization now validates input format, unflattens flattened inputs, and merges normalized localization into the base resource. Tests for the new types and utilities were added.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main feature: adding support for flattened localization usage across the shared and ui packages.
Docstring Coverage	✅ Passed	Docstring coverage is 85.71% which is sufficient. The required threshold is 80.00%.

_{✏️ 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.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@packages/shared/src/utils/unflattenObject.ts`:
- Around line 39-49: The unflattening loop currently assumes intermediate keys
are objects and will crash or overwrite when input contains conflicting keys
(e.g., "a":"x" and "a.b":"y"); update the logic inside the Object.entries loop
(the code using variables key, parts, current) to validate conflicts before
mutating: at each iteration when accessing current[part], if current[part]
exists and is not an object (typeof !== 'object' or is null) throw a descriptive
Error naming the conflicting path (e.g., the joined parts up to i) and the
original flat key; additionally, before assigning to current[parts[parts.length
- 1]] check if an existing value is an object while you're about to set a
non-object (or vice versa) and throw a similarly descriptive Error to avoid
clobbering nested structures.

[pkg-pr-new]

Open in StackBlitz

@clerk/agent-toolkit

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

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: bb0a850