@better-i18n/use-intl 0.4.0 → 0.4.1

package/README.md

@@ -20,7 +20,50 @@ bun add @better-i18n/use-intl use-intl
 
 ## Quick Start
 
-### Client-Side (CSR)
+### Vite App (Recommended — Zero Config)
+
+Pair with [`@better-i18n/vite`](https://www.npmjs.com/package/@better-i18n/vite) for the best experience — zero FOUC, automatic locale detection, no props needed:
+
+```bash
+npm install @better-i18n/vite @better-i18n/use-intl use-intl
+```
+
+```ts
+// vite.config.ts
+import { betterI18n } from "@better-i18n/vite";
+
+export default defineConfig({
+  plugins: [
+    betterI18n({ project: "acme/dashboard", localeCookie: "locale" }),
+    react(),
+  ],
+});
+```
+
+```tsx
+// App.tsx — no project/locale/messages props needed
+import { BetterI18nProvider, useTranslations, LocaleDropdown } from "@better-i18n/use-intl";
+
+function App() {
+  return (
+    <BetterI18nProvider>
+      <LocaleDropdown />
+      <HomePage />
+    </BetterI18nProvider>
+  );
+}
+
+function HomePage() {
+  const t = useTranslations("home");
+  return <h1>{t("title")}</h1>;
+}
+```
+
+The Vite plugin injects project, locale, messages, languages, and cookie config into the HTML — the provider reads it all automatically.
+
+### Client-Side (Manual Config)
+
+Without the Vite plugin, pass `project` and `locale` as props:
 
 ```tsx
 import { BetterI18nProvider, useTranslations } from '@better-i18n/use-intl'
@@ -215,13 +258,109 @@ function LanguageSwitcher() {
 }
 ```
 
-## TanStack Start Full Example
+## Router Integration
+
+### TanStack Router
+
+Detected automatically. `useLocaleRouter()` uses TanStack Router's `router.navigate()` for SPA navigation — no extra setup needed.
+
+See our [TanStack Start guide](https://docs.better-i18n.com/frameworks/tanstack-start) for a complete example with locale middleware, URL-based locale detection, SEO-friendly routing, and hydration without mismatches.
+
+### React Router (`react-router-dom`)
+
+The provider's built-in URL update uses `history.replaceState`, which doesn't notify React Router. Add a `LocaleSync` component to bridge locale state with the router:
+
+```tsx
+import { useEffect } from "react";
+import { BrowserRouter, Routes, Route, useNavigate, useLocation } from "react-router-dom";
+import { BetterI18nProvider, useLocale } from "@better-i18n/use-intl";
+
+// Syncs locale state → URL using react-router-dom's navigate
+function LocaleSync() {
+  const { locale } = useLocale();
+  const navigate = useNavigate();
+  const location = useLocation();
+
+  useEffect(() => {
+    const segments = location.pathname.split("/").filter(Boolean);
+    const first = segments[0];
+    if (first && /^[a-z]{2}$/i.test(first) && first !== locale) {
+      segments[0] = locale;
+      navigate("/" + segments.join("/"), { replace: true });
+    }
+  }, [locale, location.pathname, navigate]);
+
+  return null;
+}
+
+export default function App() {
+  return (
+    <BrowserRouter>
+      <BetterI18nProvider>
+        <LocaleSync />
+        <Routes>
+          <Route path="/:locale" element={<HomePage />} />
+        </Routes>
+      </BetterI18nProvider>
+    </BrowserRouter>
+  );
+}
+```
+
+### No Router (Plain SPA)
+
+Works out of the box. On locale switch, the provider calls `history.replaceState` to update the URL prefix automatically.
+
+## Locale Prefix Strategy
+
+Control how locale codes appear in URLs via the `localePrefix` prop:
+
+```tsx
+<BetterI18nProvider localePrefix="always">
+```
+
+| Strategy | Default Locale | Other Locales | Best For |
+|----------|---------------|---------------|----------|
+| `"as-needed"` (default) | `/about` (no prefix) | `/tr/about` | SEO — default locale has clean URLs |
+| `"always"` | `/en/about` | `/tr/about` | Apps with `/:locale` route pattern |
+
+**`"as-needed"`** — Default locale has no URL prefix. Non-default locales get a prefix. Best for SEO because your primary language has clean URLs.
+
+**`"always"`** — Every locale gets a prefix, including the default. Use this when your router has a `/:locale` parameter in every route (e.g., TanStack Router's `$locale/` layout routes or React Router's `/:locale/*` pattern).
+
+## Components
+
+### `<LocaleDropdown />`
+
+Pre-built, styled locale switcher with flags, keyboard navigation, and dark mode support.
+
+```tsx
+import { LocaleDropdown } from "@better-i18n/use-intl";
+
+// Zero config — styled mode
+<LocaleDropdown />
+
+// Unstyled mode for full custom styling via data attributes
+<LocaleDropdown variant="unstyled" className="my-dropdown" />
+
+// Custom placement
+<LocaleDropdown placement="top" />
+```
+
+Customizable via CSS custom properties:
+
+| Property | Controls |
+|----------|----------|
+| `--better-locale-text` | Text color |
+| `--better-locale-menu-bg` | Menu background |
+| `--better-locale-border` | Border color |
+| `--better-locale-hover-bg` | Hover state |
+| `--better-locale-trigger-bg` | Trigger background |
+| `--better-locale-accent` | Checkmark/accent color |
+
+## Documentation
 
-See our [TanStack Start guide](/docs/react/tanstack-start) for a complete example with:
-- Locale middleware
-- URL-based locale detection
-- SEO-friendly routing
-- Hydration without mismatches
+Full documentation at [docs.better-i18n.com/frameworks/vite](https://docs.better-i18n.com/frameworks/vite)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-i18n/use-intl",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Better i18n integration for use-intl (React, TanStack Start)",
   "license": "MIT",
   "repository": {
@@ -62,7 +62,7 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@better-i18n/core": "^0.3.0",
+    "@better-i18n/core": "^0.4.0",
     "@floating-ui/react": "^0.27.19"
   },
   "peerDependencies": {