feat(compiler): add useLocale hook and setLocale/getLocale functions

[cherkanovart]

Summary

• Add useLocale() hook for reactive locale access in React components
• Add setLocale() function for changing locale from anywhere (event handlers, callbacks, etc.)
• Add getLocale() function for non-reactive locale access
• Add Next.js version compatibility warning when using with unsupported versions (< 15)
• Update README documentation with React Client API section

New API

import { useLocale, setLocale } from "@lingo.dev/compiler/react";

function LanguageSwitcher() {
  const locale = useLocale();  // reactive hook

  return (
    <select value={locale} onChange={(e) => setLocale(e.target.value)}>
      <option value="en">English</option>
      <option value="es">Español</option>
    </select>
  );
}

Test plan

• Unit tests for locale utilities (5 tests passing)
• TypeScript type check passing
• Build successful

Closes #1696

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation

  • Added React client API docs with usage examples for the new hook and LocaleSwitcher component; updated locale management guidance.

• API Updates

  • Moved React integration from beta to stable package imports.
  • Renamed and clarified the primary translation hook and updated the translation context surface (removed an old request method; added registration support).

• New Features

  • Client-side locale get/set utilities exposed for easier locale management.

[coderabbitai]

Caution

Review failed

The pull request is closed.

📝 Walkthrough

Walkthrough

Updated React Client API documentation for the new-compiler package: renamed useTranslationContext() → useLingoContext(), replaced cookie-based locale helpers with getLocale()/setLocale(), adjusted translation context surface (requestTranslation → registerHashes), and switched examples from beta to non-beta imports. (Docs only.)

Changes

Cohort / File(s)	Summary
React Client README packages/new-compiler/README.md	Added React Client API doc section describing useLingoContext() and LocaleSwitcher with usage examples.
React-specific README packages/new-compiler/src/react/README.md	Updated examples and API references: renamed useTranslationContext() → useLingoContext(), removed getLocaleFromCookies() in favor of getLocale()/setLocale(), changed context surface (requestTranslation → registerHashes), and switched imports from @lingo.dev/compiler-beta/react to @lingo.dev/compiler/react.
Changeset / Changelog .changeset/docs-locale-api.md	Added documentation changeset noting locale management updates via useLingoContext (docs-only).

Sequence Diagram(s)

(omitted — changes are documentation and API-surface examples only)

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• feat(compiler): add useLocale hook and setLocale/getLocale functions #1964 — Modifies React client locale API and README; strongly related to the rename/export of locale hooks and addition of getLocale/setLocale.

Suggested reviewers

• vrcprl
• sumitsaurabh927

Poem

🐰 I hopped through docs to make things clear,

useLingoContext now lends an ear,
locales set and gotten with delight,
beta imports flipped to shining white,
a little rabbit cheers tonight 🥕✨

🚥 Pre-merge checks | ✅ 1 | ❌ 4

❌ Failed checks (3 warnings, 1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	⚠️ Warning	The title mentions adding useLocale hook and setLocale/getLocale functions, but the raw_summary shows the API was actually renamed from useTranslationContext() to useLingoContext(), not useLocale; this creates a discrepancy between the title and actual changes.	Update the title to accurately reflect the actual API changes: use 'useLingoContext' instead of 'useLocale', or clarify which API functions are actually being added/renamed in this PR.
Description check	⚠️ Warning	The description references 'useLocale()' hook but the actual changes rename useTranslationContext() to useLingoContext(); the description examples and API signature do not match the actual implementation described in raw_summary.	Update the PR description to accurately reflect the actual API changes: replace useLocale() references with useLingoContext(), and ensure code examples match the implemented API surface.
Docstring Coverage	⚠️ Warning	Docstring coverage is 57.14% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Linked Issues check	❓ Inconclusive	The PR addresses #1696's missing exports issue by renaming/updating public API exports (useTranslationContext→useLingoContext, removing requestTranslation, adding registerHashes, adding setLocale/getLocale), but the title and description incorrectly reference 'useLocale' instead of actual 'useLingoContext', creating confusion about whether requirements are met.	Clarify whether useLingoContext is the correct final API (as per raw_summary changes) or if useLocale should exist; ensure PR description and title match the actual implementation to confirm #1696's API export requirements are satisfied.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Out of Scope Changes check	✅ Passed	The PR includes comprehensive documentation updates (README sections), API renames/additions (useLingoContext, setLocale, getLocale, registerHashes), and changeset file, all scoped to #1696's requirements for fixing missing exports and locale management.

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

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix/compiler-locale-exports-and-version-warning

---

_{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/new-compiler/src/react/README.md`:
- Around line 101-104: Update the README text in the `useLingoContext()` section
to hyphenate "locale-switching" for grammar consistency by changing the sentence
to read "Use this for custom locale-switching components." so the
`useLingoContext()` description contains the corrected phrase.

🧹 Nitpick comments (1)

packages/new-compiler/README.md (1)

339-346: Document the full client API surface for parity.

This section omits registerHashes (listed in the react README) and does not mention the standalone getLocale() / setLocale() helpers described in the PR objectives. Consider adding them here to keep the docs consistent.