useTranslate

(no submodules)

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

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.

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.

3.6 KiB Raw Blame History