Skip to main content

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.

Alias

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.

useTranslations​

The useTranslations hook is used to render messages in the current locale.

Alias

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);
ParamTypeRequiredDescription
namespaceNamespace-Access messages in a given namespace
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.

Alias

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);
ParamTypeRequiredDescription
routeStaticRouteYesA static route for which to construct the href for, i.e. /dashboard
localeLocale-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);
ParamTypeRequiredDescription
routeDynamicRouteYesA dynamic route for which to construct the href for, i.e. /blog/[user]
paramsRouteParams<R>YesThe params for the dynamic segments of the route, i.e. { user: "Jon1VK" }
localeLocale-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);
OptionTypeRequiredDescription
pathnameRouteYesA route for which to construct the href for, i.e. /blog/[user]
paramsRouteParams<Route>*The params for the dynamic segments of the route, i.e. { user: "Jon1VK" }
localeLocale-In which locale the href should be constructed. Uses current locale by default.
queryRecord<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.

LanguageSwitcher
"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.

Recommendation

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: