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

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

- Add useLocale() hook for reactive locale access in components
- Add setLocale() function for changing locale from anywhere
- Add getLocale() function for non-reactive locale access
- Add Next.js version compatibility warning for < 15
- Update README documentation with React Client API section

Closes #1696

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

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

- Add useLocale() hook for reactive locale access in components
- Add setLocale() function for changing locale from anywhere
- Add getLocale() function for non-reactive locale access
- Update README documentation with React Client API section

Closes #1696

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* refactor(cli): update ensure-key-order tests to skip non-original keys

- Rename test to reflect new behavior of skipping keys not present in the original input.
- Adjust expected result to match the updated logic in the loader function.
- Remove unnecessary key reordering logic from the loader implementation.

* docs(compiler): document locale management with useLingoContext

- Update README with useLingoContext() usage for locale switching
- Remove unused useLocale/setLocale code in favor of useLingoContext()
- Users can use useLingoContext() to get { locale, setLocale }

Closes #1696

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* docs(react): correct wording in README for locale-switching components

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: cherkanovart

.changeset/docs-locale-api.md

@@ -0,0 +1,4 @@
+---
+---
+
+Update documentation for locale management using useLingoContext hook.

packages/new-compiler/README.md

@@ -330,6 +330,58 @@ LINGO_BUILD_MODE=cache-only npm run build
 2. **CI**: Generate real translations with `buildMode: "translate"` and real API keys
 3. **Production Build**: Use `buildMode: "cache-only"` (no API keys needed)
 
+## React Client API
+
+The compiler provides hooks and components for managing locale in your React components.
+
+### `useLingoContext()`
+
+Access the translation context to get the current locale and change it.
+
+**Returns:**
+- `locale` (string): Current locale code
+- `setLocale` (function): Change the locale
+- `translations` (object): Translation dictionary
+- `isLoading` (boolean): Whether translations are loading
+
+```tsx
+"use client";
+import { useLingoContext } from "@lingo.dev/compiler/react";
+
+export function LanguageSwitcher() {
+  const { locale, setLocale } = useLingoContext();
+
+  return (
+    <select value={locale} onChange={(e) => setLocale(e.target.value)}>
+      <option value="en">English</option>
+      <option value="es">Español</option>
+      <option value="de">Deutsch</option>
+    </select>
+  );
+}
+```
+
+### `LocaleSwitcher` Component
+
+A pre-built dropdown component for switching locales (no hooks needed):
+
+```tsx
+"use client";
+import { LocaleSwitcher } from "@lingo.dev/compiler/react";
+
+export function Header() {
+  return (
+    <LocaleSwitcher
+      locales={[
+        { code: "en", label: "English" },
+        { code: "es", label: "Español" },
+        { code: "de", label: "Deutsch" },
+      ]}
+    />
+  );
+}
+```
+
 ## Custom Locale Resolvers
 
 Customize how locales are detected and persisted by providing custom resolver files:

packages/new-compiler/src/react/README.md

@@ -19,7 +19,7 @@ Context provider that manages translations and locale switching for your entire
 
 ```tsx
 // app/layout.tsx
-import { LingoProvider } from "@lingo.dev/compiler-beta/react";
+import { LingoProvider } from "@lingo.dev/compiler/react";
 
 export default function RootLayout({ children }) {
   return (
@@ -52,7 +52,7 @@ A dropdown component for switching between locales.
 // Client Component with Next.js integration
 "use client";
 import { useRouter } from "next/navigation";
-import { LocaleSwitcher } from "@lingo.dev/compiler-beta/react";
+import { LocaleSwitcher } from "@lingo.dev/compiler/react";
 
 export function Header() {
   const router = useRouter();
@@ -84,7 +84,7 @@ Returns a translation function `t(hash)` for translating text in Client Componen
 
 ```tsx
 "use client";
-import { useTranslation } from "@lingo.dev/compiler-beta/react";
+import { useTranslation } from "@lingo.dev/compiler/react";
 
 export function Welcome() {
   const t = useTranslation();
@@ -98,37 +98,35 @@ export function Welcome() {
 }
 ```
 
-### `useTranslationContext()`
+### `useLingoContext()`
 
-Access the translation context directly.
+Access the full translation context directly. Use this for custom locale-switching components.
 
 **Returns:**
 
 - `locale` (string): Current locale
 - `setLocale` (function): Change locale
 - `translations` (object): Translation dictionary
-- `requestTranslation` (function): Request a translation
+- `registerHashes` (function): Register translation hashes
 - `isLoading` (boolean): Loading state
 
-## Utility Functions
-
-### `getLocaleFromCookies()`
-
-Get the current locale from cookies (client-side).
-
-**Parameters:**
-
-- `cookieName` (string, optional): Cookie name, default: 'locale'
-- `defaultLocale` (string, optional): Default if not found, default: 'en'
-
-**Returns:** Current locale string
-
 **Example:**
 
 ```tsx
-import { getLocaleFromCookies } from "@lingo.dev/compiler-beta/react";
+"use client";
+import { useLingoContext } from "@lingo.dev/compiler/react";
+
+export function LanguageSwitcher() {
+  const { locale, setLocale } = useLingoContext();
 
-const locale = getLocaleFromCookies(); // e.g., 'en'
+  return (
+    <select value={locale} onChange={(e) => setLocale(e.target.value)}>
+      <option value="en">English</option>
+      <option value="es">Español</option>
+      <option value="de">Deutsch</option>
+    </select>
+  );
+}
 ```
 
 ## How It Works
@@ -196,15 +194,15 @@ import type {
   LocaleConfig,
   TranslationFunction,
   TranslationContextType,
-} from "@lingo.dev/compiler-beta/react";
+} from "@lingo.dev/compiler/react";
 ```
 
 ## Testing
 
 When testing components that use translations:
 
 ```tsx
-import { LingoProvider } from "@lingo.dev/compiler-beta/react";
+import { LingoProvider } from "@lingo.dev/compiler/react";
 
 test("my component", () => {
   render(