# 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.