first commit

docs/localization/i18n/react-i18n/src/hooks/use-translate/use-translate.md

@@ -0,0 +1,96 @@
+# useTranslate
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+`useTranslate(namespace?)` is the terse alias of `useTranslation`. It
+returns just the bound translator function — useful when the consumer
+only needs to render translated text and does not care about the
+`{ ready, i18n }` extras. The hook composes `useTranslation` directly,
+so all of Suspense, the error-boundary cause-chain on namespace-load
+failure, and the production no-Provider identity fallback flow through
+unchanged.
+
+The intended use case is leaf components that only stamp out text. For
+anything that needs to read the underlying `I18nInstance`, observe the
+`ready` flag, or branch on the current locale, prefer `useTranslation`.
+
+## Features
+
+- Returns the bound `t(key, options?)` function from `useTranslation`.
+- Optional namespace prefix forwarded to `useTranslation(namespace)`.
+- Inherits Suspense + error-boundary behaviour from `useTranslation`.
+- Inherits the production no-Provider identity-translator soft-fail.
+- Zero extra allocations beyond the underlying `useTranslation` call.
+
+## Usage: Basic Example
+
+```tsx
+import { useTranslate, TranslationProvider } from "@suaveplan/react-i18n";
+import { createI18n } from "@suaveplan/i18n/plugin";
+
+function Greeting() {
+    const t = useTranslate();
+    return <span>{t("hello")}</span>;
+}
+
+const i18n = createI18n({
+    defaultLocale: "en-GB",
+    messages: { "en-GB": { hello: "Hi there" } },
+});
+
+export function App() {
+    return (
+        <TranslationProvider i18n={i18n}>
+            <Greeting />
+        </TranslationProvider>
+    );
+}
+```
+
+## Usage: Advanced Example
+
+The terse form composes naturally with namespace prefixes and the full
+options bag — the returned function is identical to the one
+`useTranslation(namespace).t` returns, so anything that translator
+supports also works here. The pattern below shows interpolation, plural
+selection through the catalog's `count` shorthand, and a default-value
+fallback when a key is absent.
+
+```tsx
+import { useTranslate } from "@suaveplan/react-i18n";
+
+export function CartSummary(props: { readonly itemCount: number }) {
+    const t = useTranslate("cart");
+    return (
+        <output>
+            {t("summary", { count: props.itemCount })}
+            {" — "}
+            {t("subtotal", {
+                values: { amount: 12.5 },
+                defaultValue: "Subtotal pending",
+            })}
+        </output>
+    );
+}
+```
+
+## API Reference
+
+### `useTranslate(namespace?: string): UseTranslationT`
+
+- **Parameters**:
+  - `namespace?` — optional namespace passed straight through to `useTranslation`.
+- **Returns**: the bound translator `(key: string, options?: UseTranslationOptions) => string`.
+- **Throws**:
+  - **Promise** under Suspense semantics when the namespace must be loaded.
+  - **`ReactI18nError(REACT_I18N.NAMESPACE_LOAD_FAILED)`** when the preload Promise rejects.
+  - **`ReactI18nError(REACT_I18N.NO_PROVIDER)`** outside a `<TranslationProvider>` in development.
+
+## Implementation Notes
+
+- The hook is intentionally a one-line composition (`useTranslation(namespace).t`). Keeping the body tiny means future changes to Suspense / no-Provider semantics in `useTranslation` propagate automatically.
+- The function reference returned is the SAME `t` function `useTranslation` returns — destructuring `useTranslation(ns).t === useTranslate(ns)` for the same render. This keeps the single-function form interchangeable with the triple-return form when refactoring between the two.
+- Prefer `useTranslation` when the consumer needs `ready` or wants to check `i18n` for advanced operations like switching the active locale or subscribing to bus events.