Hooks
NextGlobeGen provides multiple hooks that help you with the internationalization requirements of the application. Most of the hooks work interchangeably in Client and Server Components but some can be used only in Client Components.
Client & Server Components
These hooks work on both Server and Client Components. The developer does not need to know if a component will be used in a client or server context when building components with these hooks.
useLocale
The useLocale hook returns the current locale.
An alias getLocale is also available for async server components and generateMetadata function.
import { useLocale } from "next-globe-gen";
import { ReactNode } from "react";
export default function RootLayout({ children }: { children: ReactNode }) {
const locale = useLocale();
return (
<html lang={locale}>
<body>{children}</body>
</html>
);
}
Parameters
useLocale does not take any parameters.
Returns
useLocale returns the current locale.
useSchema
The useSchema hook returns the routing schema containing all routes, locales, and configuration.
An alias getSchema is also available for async server components and generateMetadata function.
import { useSchema } from "next-globe-gen";
export default function LanguageSwitcher() {
const schema = useSchema();
return (
<nav>
<ul>
{schema.locales.map((locale) => (
<li key={locale}>
<a href={`/${locale}`}>{locale.toUpperCase()}</a>
</li>
))}
</ul>
</nav>
);
}
Parameters
useSchema does not take any parameters.
Returns
useSchema returns the routing schema object with the following properties:
| Property | Type | Description |
|---|---|---|
locales | string[] | Array of all supported locale codes |
defaultLocale | string | The default locale |
unPrefixedLocales | string[] | Locales that don't require URL prefixes |
routes | Record<string, Record<string, string>> | Mapping of routes to their localized versions |
domains | DomainConfig[] | undefined | Domain-based routing configuration (if enabled) |
formats | Partial<Formats> | undefined | Custom date/time/number format configurations |
useTranslations
The useTranslations hook is used to render messages in the current locale.
An alias getTranslations is also available for async server components and generateMetadata function.
import { useTranslations } from "next-globe-gen";
export default function HomePage() {
const t = useTranslations("home");
return (
<section>
<h1>{t("title")}</h1>
<p>{t("description", { name: "NextGlobeGen" })}</p>
</section>
);
}
Parameters
useTranslations(namespace?: Namespace);
| Param | Type | Required | Description |
|---|---|---|---|
namespace | Namespace | - | Access messages in a given namespace |
Namespace of some deeply nested messages object is it's full object dot notation syntax as a string, possibly prefixed with a filename namespace. (i.e. filename.deeply.nested.object)
Returns
useTranslations returns a t function.
useHref
If you need to construct a localized href of a route, you can use the useHref hook. This hook is used under the hood in other components and functions, such as the Link component.
An alias getHref is also available for async server components and generateMetadata function.
Parameters
useHref has three overloads when calling it.
1. With a static route
useHref<R extends StaticRoute>(route: R, locale?: Locale);
| Param | Type | Required | Description |
|---|---|---|---|
route | StaticRoute | Yes | A static route for which to construct the href for, i.e. /dashboard |
locale | Locale | - | In which locale the href should be constructed. Uses current locale by default. |
2. With a dynamic route
useHref<R extends DynamicRoute>(route: R, params: RouteParams<R>, locale?: Locale);
| Param | Type | Required | Description |
|---|---|---|---|
route | DynamicRoute | Yes | A dynamic route for which to construct the href for, i.e. /blog/[user] |
params | RouteParams<R> | Yes | The params for the dynamic segments of the route, i.e. { user: "Jon1VK" } |
locale | Locale | - | In which locale the href should be constructed. Uses current locale by default. |
3. With an options object
useHref<R extends HrefOptions<Route>>({ pathname, params, locale, query }: R);
| Option | Type | Required | Description |
|---|---|---|---|
pathname | Route | Yes | A route for which to construct the href for, i.e. /blog/[user] |
params | RouteParams<Route> | * | The params for the dynamic segments of the route, i.e. { user: "Jon1VK" } |
locale | Locale | - | In which locale the href should be constructed. Uses current locale by default. |
query | Record<string, string> | - | URL search params that should be included in the href |
* params option is required only if the given pathname has dynamic segments.
Returns
useHref returns the localized version of the given route.
Client Components
These hooks are restricted to Client Components as they depend on Next.js hooks that are functional only within Client Components.
useRoute
The useRoute hook returns the current route of the page. It can be used to create a generic language switcher component.
"use client";
import { Link, useRoute, type RouteParams } from "next-globe-gen";
import { useParams } from "next/navigation";
export default function LanguageSwitcher() {
const route = useRoute();
const params = useParams<RouteParams<typeof route>>();
return (
<nav>
<ul>
<li>
<Link href={route} params={params} locale="en">
In English
</Link>
</li>
<li>
<Link href={route} params={params} locale="fi">
Suomeksi
</Link>
</li>
</ul>
</nav>
);
}
Parameters
useRoute does not take any parameters.
Returns
useRoute returns the current route of the page.
useRouter
The useRouter hook extends the Next.js useRouter hook to allow programmatic navigations to localized pathnames in Client Components.
Use the <Link> component for navigation unless you have a specific requirement for using useRouter.
"use client";
import { useRouter } from "next-globe-gen";
export default function Page() {
const router = useRouter();
return <button onClick={() => router.push("/dashboard")}>Dashboard</button>;
}
Parameters
useRouter does not take any parameters.
Returns
useRouter returns a router instance. See Next.js useRouter docs what each function is made for. Check the useHref section what values should be given in the HrefOptions object.
/* 1. With static route */
router.push<R extends StaticRoute>(route: R, opts?: { locale?: Locale, scroll?: boolean })
router.replace<R extends StaticRoute>(route: R, opts?: { locale?: Locale, scroll?: boolean })
router.prefetch<R extends StaticRoute>(route: R, opts?: { locale?: Locale, kind?: string })
/* 2. With dynamic route */
router.push<R extends DynamicRoute>(route: R, opts: { params: RouteParams<R>, locale?: Locale, scroll?: boolean })
router.replace<R extends DynamicRoute>(route: R, opts: { params: RouteParams<R>, locale?: Locale, scroll?: boolean })
router.prefetch<R extends DynamicRoute>(route: R, opts: { params: RouteParams<R>, locale?: Locale, kind?: string })
/* 3. With route options object */
router.push<R extends HrefOptions<Route>>(route: R, opts?: { scroll?: boolean })
router.replace<R extends HrefOptions<Route>>(route: R, opts?: { scroll?: boolean })
router.prefetch<R extends HrefOptions<Route>>(route: R, opts?: { kind?: string })
/* Calls forwarded to Next.js router instance */
router.refresh()
router.back()
router.forward()
Async Server Components
Since ESLint has a rule which disallows calling hooks in async server components and generateMetadata function, the package also exports get-prefixed aliases which can be used instead.
These aliases are included: