docs: reference docs for Lingo.dev Compiler (#1048)

* docs: reference docs for Lingo.dev Compiler

* docs: update LocaleSwitcher docs

* docs: improve

* docs: improve

* chore: remove rules

* docs: removoe

* docs: updates

* docs: updates

* docs: fix error

* docs: clarify stubs

* docs: minor tweak

* fix: code examples

* docs: fix React Router examples

* docs: add init examples

---------

Co-authored-by: Max Prilutskiy <[email protected]>

Author: davidturnbull

packages/compiler/src/index.ts

@@ -156,6 +156,28 @@ const unplugin = createUnplugin<Partial<typeof defaultParams> | undefined>(
 );
 
 export default {
+  /**
+   * Initializes Lingo.dev Compiler for Next.js (App Router).
+   *
+   * @param compilerParams - The compiler parameters.
+   *
+   * @returns The Next.js configuration.
+   *
+   * @example Configuration for Next.js's default template
+   * ```ts
+   * import lingoCompiler from "lingo.dev/compiler";
+   * import type { NextConfig } from "next";
+   *
+   * const nextConfig: NextConfig = {
+   *   /* config options here *\/
+   * };
+   *
+   * export default lingoCompiler.next({
+   *   sourceRoot: "app",
+   *   models: "lingo.dev",
+   * })(nextConfig);
+   * ```
+   */
   next:
     (
       compilerParams?: Partial<typeof defaultParams> & {
@@ -250,6 +272,51 @@ export default {
 
       return nextConfig;
     },
+  /**
+   * Initializes Lingo.dev Compiler for Vite.
+   *
+   * @param compilerParams - The compiler parameters.
+   *
+   * @returns The Vite configuration.
+   *
+   * @example Configuration for Vite's "react-ts" template
+   * ```ts
+   * import { defineConfig, type UserConfig } from "vite";
+   * import react from "@vitejs/plugin-react";
+   * import lingoCompiler from "lingo.dev/compiler";
+   *
+   * // https://vite.dev/config/
+   * const viteConfig: UserConfig = {
+   *   plugins: [react()],
+   * };
+   *
+   * export default defineConfig(() =>
+   *   lingoCompiler.vite({
+   *     models: "lingo.dev",
+   *   })(viteConfig)
+   * );
+   * ```
+   *
+   * @example Configuration for React Router's default template
+   * ```ts
+   * import { reactRouter } from "@react-router/dev/vite";
+   * import tailwindcss from "@tailwindcss/vite";
+   * import lingoCompiler from "lingo.dev/compiler";
+   * import { defineConfig, type UserConfig } from "vite";
+   * import tsconfigPaths from "vite-tsconfig-paths";
+   *
+   * const viteConfig: UserConfig = {
+   *   plugins: [tailwindcss(), reactRouter(), tsconfigPaths()],
+   * };
+   *
+   * export default defineConfig(() =>
+   *   lingoCompiler.vite({
+   *     sourceRoot: "app",
+   *     models: "lingo.dev",
+   *   })(viteConfig)
+   * );
+   * ```
+   */
   vite: (compilerParams?: Partial<typeof defaultParams>) => (config: any) => {
     const mergedParams = _.merge(
       {},

packages/react/src/client/loader.ts

@@ -1,3 +1,32 @@
+/**
+ * A placeholder function for loading dictionaries that contain localized content.
+ *
+ * This function:
+ *
+ * - Should be used in client-side rendered applications (e.g., Vite-based apps)
+ * - Should be passed into the `LingoProviderWrapper` component
+ * - Is transformed into functional code by Lingo.dev Compiler
+ *
+ * @param locale - The locale to load the dictionary for.
+ *
+ * @returns Promise that resolves to the dictionary object containing localized content.
+ *
+ * @example Use in a Vite application
+ * ```tsx
+ * import React from "react";
+ * import ReactDOM from "react-dom/client";
+ * import { LingoProviderWrapper, loadDictionary } from "lingo.dev/react/client";
+ * import { App } from "./App.tsx";
+ *
+ * ReactDOM.createRoot(document.getElementById("root")!).render(
+ *   <React.StrictMode>
+ *     <LingoProviderWrapper loadDictionary={(locale) => loadDictionary(locale)}>
+ *       <App />
+ *     </LingoProviderWrapper>
+ *   </React.StrictMode>,
+ * );
+ * ```
+ */
 export const loadDictionary = async (locale: string): Promise<any> => {
   return {};
 };

packages/react/src/client/locale-switcher.tsx

@@ -3,11 +3,46 @@
 import { useState, useEffect } from "react";
 import { getLocaleFromCookies, setLocaleInCookies } from "./utils";
 
+/**
+ * The props for the `LocaleSwitcher` component.
+ */
 export type LocaleSwitcherProps = {
-  className?: string;
+  /**
+   * An array of locale codes to display in the dropdown.
+   *
+   * This should contain both the source and target locales.
+   */
   locales: string[];
+  /**
+   * A custom class name for the dropddown's `select` element.
+   */
+  className?: string;
 };
 
+/**
+ * An unstyled dropdown for switching between locales.
+ *
+ * This component:
+ *
+ * - Only works in environments that support cookies
+ * - Gets and sets the current locale from the `"lingo-locale"` cookie
+ * - Triggers a full page reload when the locale is changed
+ *
+ * @example Creating a locale switcher
+ * ```tsx
+ * import { LocaleSwitcher } from "lingo.dev/react/client";
+ *
+ * export function App() {
+ *   return (
+ *     <header>
+ *       <nav>
+ *         <LocaleSwitcher locales={["en", "es"]} />
+ *       </nav>
+ *     </header>
+ *   );
+ * }
+ * ```
+ */
 export function LocaleSwitcher(props: LocaleSwitcherProps) {
   const { locales } = props;
   const [locale, setLocale] = useState<string>("");

packages/react/src/client/provider.tsx

@@ -4,11 +4,79 @@ import { useEffect, useState } from "react";
 import { LingoContext } from "./context";
 import { getLocaleFromCookies } from "./utils";
 
+/**
+ * The props for the `LingoProvider` component.
+ */
 export type LingoProviderProps<D> = {
+  /**
+   * The dictionary object that contains localized content.
+   */
   dictionary: D;
+  /**
+   * The child components containing localizable content.
+   */
   children: React.ReactNode;
 };
 
+/**
+ * A context provider that makes localized content from a preloaded dictionary available to its descendants.
+ *
+ * This component:
+ *
+ * - Should be placed at the top of the component tree
+ * - Should be used in client-side applications that preload data from the server (e.g., React Router apps)
+ *
+ * @template D - The type of the dictionary object.
+ * @throws {Error} When no dictionary is provided.
+ *
+ * @example Use in a React Router application
+ * ```tsx
+ * import { LingoProvider } from "lingo.dev/react/client";
+ * import { loadDictionary } from "lingo.dev/react/react-router";
+ * import {
+ *   Links,
+ *   Meta,
+ *   Outlet,
+ *   Scripts,
+ *   ScrollRestoration,
+ *   useLoaderData,
+ *   type LoaderFunctionArgs,
+ * } from "react-router";
+ * import "./app.css";
+ *
+ * export const loader = async ({ request }: LoaderFunctionArgs) => {
+ *   return {
+ *     lingoDictionary: await loadDictionary(request),
+ *   };
+ * };
+ *
+ * export function Layout({ children }: { children: React.ReactNode }) {
+ *   const { lingoDictionary } = useLoaderData<typeof loader>();
+ *
+ *   return (
+ *     <LingoProvider dictionary={lingoDictionary}>
+ *       <html lang="en">
+ *         <head>
+ *           <meta charSet="utf-8" />
+ *           <meta name="viewport" content="width=device-width, initial-scale=1" />
+ *           <Meta />
+ *           <Links />
+ *         </head>
+ *         <body>
+ *           {children}
+ *           <ScrollRestoration />
+ *           <Scripts />
+ *         </body>
+ *       </html>
+ *     </LingoProvider>
+ *   );
+ * }
+ *
+ * export default function App() {
+ *   return <Outlet />;
+ * }
+ * ```
+ */
 export function LingoProvider<D>(props: LingoProviderProps<D>) {
   // TODO: handle case when no dictionary is provided - throw suspense? return null / other fallback?
   if (!props.dictionary) {
@@ -23,11 +91,51 @@ export function LingoProvider<D>(props: LingoProviderProps<D>) {
   );
 }
 
+/**
+ * The props for the `LingoProviderWrapper` component.
+ */
 export type LingoProviderWrapperProps<D> = {
+  /**
+   * A callback function that loads the dictionary for the current locale.
+   *
+   * @param locale - The locale code to load the dictionary for.
+   *
+   * @returns The dictionary object containing localized content.
+   */
   loadDictionary: (locale: string) => Promise<D>;
+  /**
+   * The child components containing localizable content.
+   */
   children: React.ReactNode;
 };
 
+/**
+ * A context provider that loads the dictionary for the current locale and makes localized content available to its descendants.
+ *
+ * This component:
+ *
+ * - Should be placed at the top of the component tree
+ * - Should be used in purely client-side rendered applications (e.g., Vite-based apps)
+ *
+ * @template D - The type of the dictionary object containing localized content.
+ *
+ * @example Use in a Vite application
+ * ```tsx file="src/main.tsx"
+ * import { LingoProviderWrapper, loadDictionary } from "lingo.dev/react/client";
+ * import { StrictMode } from 'react'
+ * import { createRoot } from 'react-dom/client'
+ * import './index.css'
+ * import App from './App.tsx'
+ *
+ * createRoot(document.getElementById('root')!).render(
+ *   <StrictMode>
+ *     <LingoProviderWrapper loadDictionary={(locale) => loadDictionary(locale)}>
+ *       <App />
+ *     </LingoProviderWrapper>
+ *   </StrictMode>,
+ * );
+ * ```
+ */
 export function LingoProviderWrapper<D>(props: LingoProviderWrapperProps<D>) {
   const [dictionary, setDictionary] = useState<D | null>(null);
 

packages/react/src/client/utils.ts

@@ -3,12 +3,53 @@
 import { LOCALE_COOKIE_NAME, DEFAULT_LOCALE } from "../core";
 import Cookies from "js-cookie";
 
+/**
+ * Gets the current locale from the `"lingo-locale"` cookie.
+ *
+ * Defaults to `"en"` if:
+ *
+ * - Running in an environment that doesn't support cookies
+ * - No `"lingo-locale"` cookie is found
+ *
+ * @returns The current locale code, or `"en"` as a fallback.
+ *
+ * @example Get the current locale
+ * ```tsx
+ * import { getLocaleFromCookies } from "lingo.dev/react/client";
+ *
+ * export function App() {
+ *   const currentLocale = getLocaleFromCookies();
+ *   return <div>Current locale: {currentLocale}</div>;
+ * }
+ * ```
+ */
 export function getLocaleFromCookies(): string {
   if (typeof document === "undefined") return DEFAULT_LOCALE;
 
   return Cookies.get(LOCALE_COOKIE_NAME) || DEFAULT_LOCALE;
 }
 
+/**
+ * Sets the current locale in the `"lingo-locale"` cookie.
+ *
+ * Does nothing in environments that don't support cookies.
+ *
+ * @param locale - The locale code to store in the `"lingo-locale"` cookie.
+ *
+ * @example Set the current locale
+ * ```tsx
+ * import { setLocaleInCookies } from "lingo.dev/react/client";
+ *
+ * export function LanguageButton() {
+ *   const handleClick = () => {
+ *     setLocaleInCookies("es");
+ *     window.location.reload();
+ *   };
+ *
+ *   return <button onClick={handleClick}>Switch to Spanish</button>;
+ * }
+ * ```
+ */
 export function setLocaleInCookies(locale: string): void {
   if (typeof document === "undefined") return;
 

packages/react/src/core/const.ts

@@ -1,3 +1,14 @@
+/**
+ * The default locale.
+ */
 export const DEFAULT_LOCALE = "en";
+
+/**
+ * The name of the cookie that stores the current locale.
+ */
 export const LOCALE_COOKIE_NAME = "lingo-locale";
+
+/**
+ * The name of the header that stores the current locale.
+ */
 export const LOCALE_HEADER_NAME = "x-lingo-locale";