feat(compiler): useLingoLocale, setLingoLocale (#1134)

Author: mathio

.changeset/plenty-tools-move.md

@@ -0,0 +1,6 @@
+---
+"@lingo.dev/_react": minor
+"lingo.dev": minor
+---
+
+useLingoLocale, setLingoLocale

demo/next-app/src/components/hero-subtitle.tsx

@@ -6,7 +6,8 @@ export async function HeroSubtitle() {
     <p className="text-lg sm:text-xl text-gray-600 mb-10 max-w-xl mx-auto leading-relaxed">
       Localize your React app in every language in minutes.
       <br />
-      Scale to millions from day one.
+      Scale to millions from day one
+      <sup title="supports many popular frameworks">*</sup>.
     </p>
   );
 }

demo/next-app/src/lingo/dictionary.js

@@ -5,17 +5,31 @@ export default {
       entries: {
         "0/declaration/body/0/argument": {
           content: {
-            ar: "قم بتوطين تطبيق React الخاص بك بكل لغة في دقائق.<element:br></element:br> قم بالتوسع إلى الملايين من اليوم الأول.",
-            de: "Lokalisieren Sie Ihre React-App in jeder Sprache in Minuten.<element:br></element:br> Skalieren Sie von Anfang an auf Millionen.",
-            en: "Localize your React app in every language in minutes.<element:br></element:br> Scale to millions from day one.",
-            es: "Localiza tu aplicación React en cualquier idioma en minutos.<element:br></element:br> Escala a millones desde el primer día.",
-            fr: "Localisez votre application React dans toutes les langues en quelques minutes.<element:br></element:br> Évoluez vers des millions dès le premier jour.",
-            ja: "数分でReactアプリをすべての言語にローカライズします。<element:br></element:br> 最初の日から数百万にスケールします。",
-            ko: "몇 분 만에 React 앱을 모든 언어로 로컬라이즈하세요.<element:br></element:br> 첫날부터 수백만 사용자에게 확장할 수 있습니다.",
-            ru: "Локализуйте ваше приложение React на любом языке за считанные минуты.<element:br></element:br> Масштабируйте до миллионов с первого дня.",
-            zh: "在几分钟内将您的React应用本地化为任何语言。<element:br></element:br> 从第一天开始扩展到数百万用户。",
+            ar: "قم بترجمة تطبيق React الخاص بك إلى كل لغة في دقائق.<element:br></element:br> توسع إلى الملايين من اليوم الأول<element:sup>*</element:sup>.",
+            de: "Lokalisieren Sie Ihre React-App in jeder Sprache in wenigen Minuten.<element:br></element:br> Skalieren Sie vom ersten Tag an auf Millionen<element:sup>*</element:sup>.",
+            en: "Localize your React app in every language in minutes.<element:br></element:br> Scale to millions from day one<element:sup>*</element:sup>.",
+            es: "Localiza tu aplicación React en todos los idiomas en minutos.<element:br></element:br> Escala a millones desde el primer día<element:sup>*</element:sup>.",
+            fr: "Localisez votre application React dans toutes les langues en quelques minutes.<element:br></element:br> Adaptez-vous à des millions d'utilisateurs dès le premier jour<element:sup>*</element:sup>.",
+            ja: "数分でReactアプリをあらゆる言語にローカライズ。<element:br></element:br> 初日から数百万規模に対応<element:sup>*</element:sup>。",
+            ko: "몇 분 안에 React 앱을 모든 언어로 현지화하세요.<element:br></element:br> 첫날부터 수백만 명으로 확장하세요<element:sup>*</element:sup>.",
+            ru: "Локализуйте своё React-приложение на любой язык за считанные минуты.<element:br></element:br> Масштабируйтесь до миллионов с первого дня<element:sup>*</element:sup>.",
+            zh: "在几分钟内将您的 React 应用程序本地化为多种语言。<element:br></element:br> 从第一天起就支持扩展到数百万用户<element:sup>*</element:sup>。",
           },
-          hash: "2b8865d21f308426a4da45852b27004d",
+          hash: "75cc719ebad12413e5fa788174d4d4ec",
+        },
+        "0/declaration/body/0/argument/3-title": {
+          content: {
+            ar: "يدعم العديد من أطر العمل الشائعة",
+            de: "unterstützt viele beliebte Frameworks",
+            en: "supports many popular frameworks",
+            es: "soporta muchos frameworks populares",
+            fr: "prend en charge de nombreux frameworks populaires",
+            ja: "多くの人気フレームワークをサポート",
+            ko: "다양한 인기 프레임워크 지원",
+            ru: "поддерживает многие популярные фреймворки",
+            zh: "支持多种流行框架",
+          },
+          hash: "ce9b34049534ad201aef501f2a224a9d",
         },
       },
     },

demo/next-app/src/lingo/meta.json

@@ -5,11 +5,19 @@
       "scopes": {
         "0/declaration/body/0/argument": {
           "type": "element",
-          "hash": "2b8865d21f308426a4da45852b27004d",
+          "hash": "75cc719ebad12413e5fa788174d4d4ec",
           "context": "",
           "skip": false,
           "overrides": {},
-          "content": "Localize your React app in every language in minutes.<element:br></element:br> Scale to millions from day one."
+          "content": "Localize your React app in every language in minutes.<element:br></element:br> Scale to millions from day one<element:sup>*</element:sup>."
+        },
+        "0/declaration/body/0/argument/3-title": {
+          "type": "attribute",
+          "hash": "ce9b34049534ad201aef501f2a224a9d",
+          "context": "",
+          "skip": false,
+          "overrides": {},
+          "content": "supports many popular frameworks"
         }
       }
     }

packages/react/src/client/index.ts

@@ -4,3 +4,4 @@ export * from "./provider";
 export * from "./component";
 export * from "./locale-switcher";
 export * from "./attribute-component";
+export * from "./locale";

packages/react/src/client/locale.spec.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import { useLingoLocale, setLingoLocale } from "./locale";
+
+// Mock the utils module
+vi.mock("./utils", async (orig) => {
+  const actual = await orig();
+  return {
+    ...(actual as any),
+    getLocaleFromCookies: vi.fn(() => "en"),
+    setLocaleInCookies: vi.fn(),
+  };
+});
+
+import { getLocaleFromCookies, setLocaleInCookies } from "./utils";
+
+// Mock window.location.reload
+const mockReload = vi.fn();
+Object.defineProperty(window, "location", {
+  value: { ...window.location, reload: mockReload },
+  writable: true,
+});
+
+describe("useLingoLocale", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("returns the locale from cookies", () => {
+    (getLocaleFromCookies as any).mockReturnValue("es");
+    const { result } = renderHook(() => useLingoLocale());
+
+    expect(result.current).toBe("es");
+    expect(getLocaleFromCookies).toHaveBeenCalled();
+  });
+
+  it("returns null when no locale is set", () => {
+    (getLocaleFromCookies as any).mockReturnValue(null);
+    const { result } = renderHook(() => useLingoLocale());
+
+    expect(result.current).toBe(null);
+  });
+});
+
+describe("setLingoLocale", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockReload.mockClear();
+  });
+
+  it("sets locale in cookies and reloads page for valid locale", () => {
+    act(() => {
+      setLingoLocale("es");
+    });
+
+    expect(setLocaleInCookies).toHaveBeenCalledWith("es");
+    expect(mockReload).toHaveBeenCalled();
+  });
+
+  it("accepts various locales", () => {
+    const validLocales = [
+      "en",
+      "es",
+      "fr",
+      "de",
+      "en-US",
+      "es-ES",
+      "fr-CA",
+      "de-DE",
+    ];
+
+    validLocales.forEach((locale) => {
+      expect(() => {
+        act(() => {
+          setLingoLocale(locale);
+        });
+      }).not.toThrow();
+
+      expect(setLocaleInCookies).toHaveBeenCalledWith(locale);
+    });
+  });
+});

packages/react/src/client/locale.ts

@@ -0,0 +1,50 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { getLocaleFromCookies, setLocaleInCookies } from "./utils";
+
+/**
+ * Gets the current locale used by the Lingo compiler.
+ *
+ * @returns The current locale code, or `null` if no locale is set.
+ */
+export function useLingoLocale(): string | null {
+  const [locale, setLocale] = useState<string | null>(null);
+  useEffect(() => {
+    setLocale(getLocaleFromCookies());
+  }, []);
+  return locale;
+}
+
+/**
+ * Sets the current locale used by the Lingo compiler.
+ *
+ * **Note:** This function triggers a full page reload to ensure all components
+ * are re-rendered with the new locale. This is necessary because locale changes
+ * affect the entire application state.
+ *
+ * @param locale - The locale code to set. Must be a valid locale code (e.g., "en", "es", "fr-CA").
+
+ *
+ * @example Set the current locale
+ * ```tsx
+ * import { setLingoLocale } from "lingo.dev/react/client";
+ *
+ * export function LanguageSwitcher() {
+ *   const handleChange = (event: React.ChangeEvent<HTMLSelectElement>) => {
+ *     setLingoLocale(event.target.value);
+ *   };
+ *
+ *   return (
+ *     <select onChange={handleChange}>
+ *       <option value="en">English</option>
+ *       <option value="es">Spanish</option>
+ *     </select>
+ *   );
+ * }
+ * ```
+ */
+export function setLingoLocale(locale: string) {
+  setLocaleInCookies(locale);
+  window.location.reload();
+}

packages/react/src/rsc/component.tsx

@@ -15,6 +15,10 @@ export async function LingoComponent(props: LingoComponentProps) {
   const { $as, $fileKey, $entryKey, $loadDictionary, ...rest } = props;
   const dictionary = await loadDictionaryFromRequest($loadDictionary);
 
+  if ($as.name === "LingoAttributeComponent") {
+    rest.$loadDictionary = $loadDictionary;
+  }
+
   return (
     <LingoCoreComponent
       {...rest}