DEV Community: Jan Amann

🌐 learn.next-intl.dev is live!

Jan Amann — Tue, 12 Aug 2025 09:36:00 +0000

🎥 10 chapters · 42 lessons · 5+ hours of 4K video
💻 All code, recaps & resources included

When I started working on this last December, I thought creating this course would take maybe two or three months. But i18n is a rabbit hole. With all the research and content production, it took me eight months to get it right. But even more so, I'm incredibly excited to finally reveal the course in its entirety!

Here’s a little preview of the course platform:

The course avoids oversimplified examples and instead is built around a real-world project—starting from a single, hardcoded language, taking it all the way to a fully internationalized app, ready for new countries and markets.

Have a look at learn.next-intl.dev!

Reliable date formatting in Next.js

Jan Amann — Mon, 07 Oct 2024 17:23:00 +0000

Let's take a look at the following component:

import {formatDistance} from 'date-fns';

type Props = {
  published: Date;
};

export default function BlogPostPublishedDate({published}: Props) {
  const now = new Date();

  // ... is this ok? 🤔
  return <p>{formatDistance(published, now, {addSuffix: true})}</p>;
}

A quick local test of this component renders the expected result:

1 hour ago

So, should we push this to production?

Hmm, wait—something feels a bit off here. Let's take a closer look together.

Environment differences

Since this component neither uses any interactive features of React like useState, nor does it read from server-side data sources, it can be considered a shared component. This means that depending on where the component is being imported from, it may render as either a Server Component or a Client Component.

Let's consider where the component renders in either case:

Type	Server	Client
Server Component	✅
Client Component	✅	✅

Now the good news is that if we render this component as a Server Component, there's only one environment to consider: the server. The final markup is generated there, and this is what the user will see.

When it comes to Client Components, the situation is a bit more complex. Since the server and the client likely have a different local time when the component is rendered, we can already anticipate that this component may render inconsistently depending on the environment.

There's some interesting nuance here as well: Since our component qualifies as a shared component, it can run in either environment. Even if the developer originally intended the component to run as a Server Component, it may silently switch to a Client Component if it gets imported into a Client Component in the future—leading to the additional rendering environment to consider.

Hydration mismatches

Let's take a closer look at what happens when BlogPostPublishedDate renders as a Client Component.

In this case, the value for now will always differ between the server and client, due to the latency between these two environments. Depending on factors like caching, the difference may be even significant.

// Server: "1 hour ago"
formatDistance(published, now, {addSuffix: true})}

// Client: "8 days ago"
formatDistance(published, now, {addSuffix: true})}

React is not particularly happy when it encounters such a situation:

Text content does not match server-rendered HTML

We'll likely get better error reporting for this type of error in Next.js 15 (yay!), but the error still won't vanish by itself—or at least not yet. Interestingly, there's a discussion about React patching the Date object in the future, which could potentially help to mitigate this issue.

// Detect dark theme var iframe = document.getElementById('tweet-1785691330988986587-955'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1785691330988986587&theme=dark" }

This is however not the case currently, and there's a also bit more to it—so let's move on for now.

Purity

The crucial part of the component is here:

const now = new Date();

If you've been using React for a while, you may be familiar with the necessity of components being pure.

Quoting from the React docs, we can keep a component pure by considering these two aspects:

It minds its own business: It does not change any objects or variables that existed before it was called.
Same inputs, same output: Given the same inputs, a pure function should always return the same result.

Since the component is reading from the constantly changing new Date() constructor during rendering, it violates the principle of "same inputs, same output". React components require functional purity to ensure consistent output when being re-rendered (which can happen at any time and often without the user explicitly asking the UI to update).

But is this true for all components? In fact, with the introduction of Server Components, there's a new type of component in town that doesn't have the restriction of "same inputs, same output". Server Components can for instance fetch data, making their output reliant on the state of an external system. This is fine, because Server Components only generate an output once—on the server.

So what does this mean for our component?

Leveraging Server Components

Right, you may have guessed it: We can move the creation of the now variable to a Server Component and pass it down as a prop.

import BlogPostPublishedDate from './BlogPostPublishedDate';

export default function BlogPostPage() {
  // ✅ Is only called on the server
  const now = new Date();

  const published = ...;

  return <BlogPostPublishedDate now={now} published={published} />;
}

Pages in Next.js render as Server Components by default, so if we don't see a 'use client' directive in this file, we can be sure that the now variable is only created on the server side.

The now prop that we're passing to BlogPostPublishedDate is an instance of Date that can naturally be serialized by React. This means that we can pick it up in our component—both when executing on the server, as well as on the client.

It's worth mentioning that the published date will now update based on the caching rules of the page, therefore if your page renders statically, you might want to consider introducing a revalidate interval.

There's an argument that you might even want to render an updated date on the client side—however, this approach comes with trade-offs. Since the final render now depends on your app's hydration, this can lead to a noticable "flicker" or layout shift as the content updates, affecting core web vitals like Largest Contentful Paint (LCP) and Cumulative Layout Shift (CLS). Due to this, getting the initial render on the server side right might still be preferable.

Are we done yet?

What time is it?

What if we have more components that rely on the current time? We could instantiate the now variable in each component that needs it, but if you consider that even during a single render pass there can be timing differences, this might result in inconsistencies if you're working with dates that require precision.

An option to ensure that a single now value is used across all components that render as part of a single request is to use the cache() function from React:

import {cache} from 'react';

// The first component that calls `getNow()` will
// trigger the creation of the `Date` instance.
const getNow = cache(() => new Date());

export default getNow;

… and use it in our page component:

import getNow from './getNow';

export default function BlogPostPage() {
  // ✅ Will be consistent for the current request,
  // regardless of the timing of different calls
  const now = getNow();
  // ...
}

Now, the first component to call getNow() will trigger the creation of the Date instance. The instance is now bound to the request and will be reused across all subsequent calls to getNow().

Well, are we done now?

Where are we?

We've carefully ensured that our app is free of hydration mismatches and have established consistent time handling across all components. But what happens if we decide one day that we don't want to render a relative time like "2 days ago", but a specific date like "Sep 25, 2024"?

import {format} from 'date-fns';

type Props = {
  published: Date;
};

export default function BlogPostPublishedDate({published}: Props) {
  // `now` is no longer needed? 🤔
  return <p>{format(published, 'MMM d, yyyy')}</p>;
}

A quick local test shows that everything seems fine, so let's push this to production.

Text content does not match server-rendered HTML

Back to square one.

What's happening here? While our local test worked fine, we're suddenly getting an error in production.

The reason for this is: Time zones.

Handling time zones

While we, as performance-oriented developers, try to serve our app from a location that's close to the user, we can't expect that the server and the client share the same time zone. This means that the call to format can lead to different results on the server and the client.

In our case, this can lead to different dates being displayed. Even more intricate: Only at certain times of the day, where the time zone difference is significant enough between the two environments.

A bug like this can involve quite some detective work. I've learned this first hand, having written more than one lengthy pull request description, containing fixes for such issues in apps I've worked on.

To fix our new bug, the solution is similar to the one we've used for the now variable: We can create a timeZone variable in a Server Component and use that as the source of truth.

export default function BlogPostPage() {
  // ...

  // Use the time zone of the server
  const timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;

  return <BlogPostPublishedDate timeZone={timeZone} published={published} />;
}

To incorporate this into our date formatting, we can use the date-fns-tz package, which wraps date-fns and adds support for formatting dates in a given time zone.

import {format} from 'date-fns-tz';

type Props = {
  published: Date;
  timeZone: string;
};

export default function BlogPostPublishedDate({published, timeZone}: Props) {
  return <p>{format(published, timeZone, 'MMM d, yyyy')}</p>;
}

Sticking to a single time zone for your app is definitely the easiest solution here. However, in case you'd like to format dates in the user's time zone, a reasonable approach might require having the time zone available on the server side so that it can be used in server-only code.

As browsers don't include the time zone of the user in an HTTP request, one way to get an approximation of the user's time zone is to use geographical information from the user's IP address. In case you're running your app on Vercel, the x-vercel-ip-timezone request header can be used as a convenient way to retrieve this value. However, it's important to note that this is only an approximation, so letting the user choose their time zone explicitly might still be sensible.

Localized date formatting

So far, we've assumed that our app will be used by American English users, with dates being formatted like:

Sep 25, 2024

Our situation gets interesting again, once we consider that the date format is not universal. In Great Britain, for instance, the same date might be formatted as "19 Sept 2024", with the day and month being swapped.

In case we want to localize our app to another language, or even support multiple languages, we now need to consider the locale of the user. Simply put, a locale represents the language of the user, optionally combined with additional information like the region (e.g. en-GB represents English as spoken in Great Britain).

To address this new requirement, you might already have a hunch where this is going.

Ensuring consistent date formatting across the server and client requires that we'll create a locale variable in a Server Component and pass it down to relevant components. This can in turn be used by a library like date-fns-tz to format the date accordingly.

import {format} from 'date-fns-tz';

type Props = {
  published: Date;
  timeZone: string;
  locale: string;
};

export default function BlogPostPublishedDate({
  published,
  timeZone,
  locale
}: Props) {
  return <p>{format(published, timeZone, 'MMM d, yyyy', {locale})}</p>;
}

It's important to pass the locale to all formatting calls now, as this can differ by environment—just like the timeZone and our value for now from earlier.

Can `next-intl` help?

The main problem we've addressed in this post revolves around hydration mismatches that occur when formatting dates across the server and client in Next.js applications. To avoid these errors, we need to ensure that three key environment properties are shared across the entire app:

now: A single, shared timestamp representing the current time
timeZone: Geographical location of the user, affecting date offsets
locale: Language and regional settings for localization

next-intl is a package that provides internationalization (i18n) support for Next.js applications, including the ability to format dates consistently across the server and client.

next-intl uses a centralized i18n/request.ts module that allows to provide request-specific environment configuration like now, timeZone and the locale of the user.

import {getRequestConfig} from 'next-intl/server';

export default getRequestConfig(async () => ({
  // (defaults to the current time)
  now: new Date(),

  // (defaults to the server's time zone)
  timeZone: 'Europe/Berlin',

  // (requires an explicit preference)
  locale: 'en'

  // ...
}));

Note that, as the name of getRequestConfig implies, the configuration object can be created per request, allowing for dynamic configuration based on a given user's preferences.

This can now be used to format dates in components—at any point of the server-client spectrum:

import {useFormatter} from 'next-intl';

type Props = {
  published: Date;
};

export default function BlogPostPublishedDate({published}: Props) {
  // ✅ Works in any environment
  const format = useFormatter();

  // "Sep 25, 2024"
  format.dateTime(published);

  // "8 days ago"
  format.relativeTime(published);
}

Behind the scenes, i18n/request.ts is consulted by all server-only code, typically Server Components, but also Server Actions or Route Handlers. In turn, a component called NextIntlClientProvider, commonly placed in the root layout of your app, inherits this configuration and makes it available to all client-side code.

As a result, formatting functions like format.dateTime(…) can seamlessly access the necessary configuration in any environment. This configuration is then passed to native JavaScript APIs like Intl.DateTimeFormat to achieve correct and consistent formatting.

Related resources

While the main focus of this post was on date formatting, there are a few related resources that I can recommend if you're interested in digging deeper into the topic:

Internationalization (i18n) in Next.js 13 with React Server Components

Jan Amann — Wed, 12 Apr 2023 08:32:00 +0000

With the introduction of Next.js 13 and the beta release of the App Router, React Server Components became publicly available. This new paradigm allows components that don’t require React’s interactive features such as useState and useEffect to remain server-side only.

One area that benefits from this new capability is internationalization.
Traditionally, internationalization requires a tradeoff in performance, as loading translations results in larger client-side bundles and using message parsers impacts the client runtime performance of your app.

The promise of React Server Components is that we can have our cake and eat it too. If internationalization is implemented entirely on the server side, we can achieve new levels of performance for our apps, leaving the client side for interactive features. But how can we work with this paradigm when we need interactively-controlled states that should be reflected in internationalized messages?

In this article, we’ll explore a multilingual app that displays street photography images from Unsplash. We’ll use next-intl to implement all our internationalization needs in React Server Components and we’ll look at a technique for introducing interactivity with a minimalistic client-side footprint.

Interactive demo

Fetching photos from Unsplash

A key benefit of Server Components is the ability to fetch data directly from inside components via async/await. We can use this to fetch the photos from Unsplash in our page component.

But first, we need to create our API client based on the official Unsplash SDK.

import {createApi} from 'unsplash-js';

export default createApi({
  accessKey: process.env.UNSPLASH_ACCESS_KEY
});

Once we have our Unsplash API client, we can use it in our page component.

import {OrderBy} from 'unsplash-js';
import UnsplashApiClient from './UnsplashApiClient';

export default async function Index() {
  const topicSlug = 'street-photography';

  const [topicRequest, photosRequest] = await Promise.all([
    UnsplashApiClient.topics.get({topicIdOrSlug: topicSlug}),
    UnsplashApiClient.topics.getPhotos({
      topicIdOrSlug: topicSlug,
      perPage: 4
    })
  ]);

  return (
    <PhotoViewer
      coverPhoto={topicRequest.response.cover_photo}
      photos={photosRequest.response.results}
    />
  );
}

Note: We use Promise.all to invoke both requests that we need to make in parallel. This way we avoid a request waterfall.

At this point, our app renders a simple photo grid.

The app currently uses hard-coded English labels and the dates of the photos are displayed as timestamps—not very user-friendly (yet).

Adding internationalization with `next-intl`

In addition to English, we’d like our app to be available in Spanish. Support for Server Components is currently in beta for next-intl, so we can use the installation instructions for the latest beta to set up our app for internationalization.

Formatting dates

Aside from adding a second language, we’ve already found that the app doesn’t adapt well to English users because the dates should be formatted. To achieve a good user experience, we’d like to tell the user the relative time when the photo was uploaded (e.g. “8 days ago”).

Once next-intl is set up, we can fix the formatting by using the format.relativeTime function in the component that renders each photo.

import {useFormatter} from 'next-intl';

export default function PhotoGridItem({photo}) {
  const format = useFormatter();
  const updatedAt = new Date(photo.updated_at);

  return (
    <a href={photo.links.html}>
        {/* ... */}
        <p>{format.relativeTime(updatedAt)}</p>
      </div>
    </a>
  );
}

Now the date when a photo has been updated is easier to read.

Hint: In a traditional React app that renders on both the server and client side, it can be quite a challenge to ensure that the displayed relative date is in sync across the server and client. Since these are different environments and may be in different time zones, you need to configure a mechanism to transfer the server time to the client side. By performing the formatting only on the server side, we don’t have to worry about this problem in the first place.

¡Hola! 👋 Translating our app to Spanish

Next, we can replace the static labels in the header with localized messages. These labels are passed as props from the PhotoViewer component, so this is our chance to introduce dynamic labels via the useTranslations hook.

import {useTranslations} from 'next-intl';

export default function PhotoViewer(/* ... */) {
  const t = useTranslations('PhotoViewer');

  return (
    <>
      <Header
        title={t('title')}
        description={t('description')}
      />
      {/* ... */}
    </>
  );
}

For each internationalized label we add, we need to make sure that there is an appropriate entry set up for all languages.

// en.json
{
  "PhotoViewer": {
    "title": "Street photography",
    "description": "Street photography captures real-life moments and human interactions in public places. It is a way to tell visual stories and freeze fleeting moments of time, turning the ordinary into the extraordinary."
  }
}

// es.json
{
  "PhotoViewer": {
    "title": "Street photography",
    "description": "La fotografía callejera capta momentos de la vida real y interacciones humanas en lugares públicos. Es una forma de contar historias visuales y congelar momentos fugaces del tiempo, convirtiendo lo ordinario en lo extraordinario."
  }
}

Tip: next-intl provides a TypeScript integration that helps you ensure that you’re only referencing valid message keys.

Once this is done, we can visit the Spanish version of the app at /es.

So far, so good!

Adding interactivity: Dynamic ordering of photos

By default, the Unsplash API returns the most popular photos. We want the user to be able to change the order to show the most recent photos first.

Here, the question arises whether we should resort to client-side data fetching so that we can implement this feature with useState. However, that would require us to move all of our components to the client side, resulting in an increased bundle size.

Do we have an alternative? Yes. And it’s a capability that has been around on the web for ages: search parameters (sometimes referred to as query parameters). What makes search parameters a great option for our use case is that they can be read on the server side.

So let’s modify our page component to receive searchParams via props.

export default async function Index({searchParams}) {
  const orderBy = searchParams.orderBy || OrderBy.POPULAR;

  const [/* ... */, photosRequest] = await Promise.all([
    /* ... */,
    UnsplashApiClient.topics.getPhotos({orderBy, /* ... */})
  ]);

After this change, the user can navigate to /?orderBy=latest to change the order of the displayed photos.

To make it easy for the user to change the value of the search parameter, we’d like to render an interactive select element from within a component.

We can mark the component with 'use client'; to attach an event handler and process change events from the select element. Nevertheless, we would like to keep the internationalization concerns on the server side to reduce the size of the client bundle.

Let’s have a look at the required markup for our select element.

<select>
  <option value=“popular”>Popular</option>
  <option value="latest">Latest</option>
</select>

We can split this markup into two parts:

Render the select element with an interactive Client Component.
Render the internationalized option elements with a Server Component and pass them as children to the select element.

Let’s implement the select element for the client side.

'use client';

import {useRouter} from 'next-intl/client';

export default function OrderBySelect({orderBy, children}) {
  const router = useRouter();

  function onChange(event) {
    // The `useRouter` hook from `next-intl` automatically
    // considers a potential locale prefix of the pathname.
    router.replace('/?orderBy=' + event.target.value);
  }

  return (
    <select defaultValue={orderBy} onChange={onChange}>
      {children}
    </select>
  );
}

Now, let’s use our component in PhotoViewer and provide the localized option elements as children.

import {useTranslations} from 'next-intl';
import OrderBySelect from './OrderBySelect';

export default function PhotoViewer({orderBy, /* ... */}) {
  const t = useTranslations('PhotoViewer');

  return (
    <>
      {/* ... */}
      <OrderBySelect orderBy={orderBy}>
        <option value="popular">{t('orderBy.popular')}</option>
        <option value="latest">{t('orderBy.latest')}</option>
      </OrderBySelect>
    </>
  );
}

With this pattern, the markup for the option elements is now generated on the server side and passed to the OrderBySelect, which handles the change event on the client side.

Tip: Since we have to wait for the updated markup to be generated on the server side when the order is changed, we may want to show the user a loading state. React 18 introduced the useTransition hook which is integrated with Server Components. This allows us to disable the select element while waiting for a response from the server.

import {useRouter} from 'next-intl/client';
import {useTransition} from 'react';

export default function OrderBySelect({orderBy, children}) {
  const [isTransitioning, startTransition] = useTransition();
  const router = useRouter();

  function onChange(event) {
    startTransition(() => {
      router.replace('/?orderBy=' + event.target.value);
    });
  }

  return (
    <select disabled={isTransitioning} /* ... */>
      {children}
    </select>
  );
}

Adding more interactivity: Page controls

The same pattern that we’ve explored for changing the order can be applied to page controls by introducing a page search parameter.

Note that languages have different rules for handling decimal and thousand separators. Furthermore, languages have different forms of pluralization: While English only makes a grammatical distinction between one and zero/many elements, for example Croatian has a separate form for “few” elements.

next-intl uses the ICU syntax which makes it possible to express these language subtleties.

// en.json
{
  "Pagination": {
    "info": "Page {page, number} of {totalPages, number} ({totalElements, plural, =1 {one result} other {# results}} in total)",
    // ...
  }
}

This time we don’t need to mark a component with 'use client';. Instead, we can implement this with regular anchor tags.

import {ArrowLeftIcon, ArrowRightIcon} from '@heroicons/react/24/solid';
import {Link, useTranslations} from 'next-intl';

export default function Pagination({pageInfo, orderBy}) {
  const t = useTranslations('Pagination');
  const totalPages = Math.ceil(pageInfo.totalElements / pageInfo.size);

  function getHref(page) {
    return {
      // Since we're using `Link` from next-intl, a potential locale
      // prefix of the pathname is automatically considered.
      pathname: '/',
      // Keep a potentially existing `orderBy` parameter. 
      query: {orderBy, page}
    };
  }

  return (
    <>
      {pageInfo.page > 1 && (
        <Link aria-label={t('prev')} href={getHref(pageInfo.page - 1)}>
          <ArrowLeftIcon />
        </Link>
      )}
      <p>{t('info', {...pageInfo, totalPages})}</p>
      {pageInfo.page < totalPages && (
        <Link aria-label={t('prev')} href={getHref(pageInfo.page + 1)}>
          <ArrowRightIcon />
        </Link>
      )}
    </>
  );
}

Conclusion

Server Components are a great match for internationalization

Internationalization is an important part of the user experience, whether you support multiple languages or you want to get the subtleties of a single language right. A library like next-intl can help with both cases.

Implementing internationalization in Next.js apps has historically come with a performance tradeoff, but with Server Components this is no longer the case. However, it might take some time to explore and learn patterns that will help you keep your internationalization concerns on the server side.

In our street photography viewer app, we only needed to move a single component to the client side: OrderBySelect.

Another aspect to consider is that you might want to consider implementing loading states since the network latency introduces a delay before your users see the result of their actions.

Search parameters are a great alternative to `useState`

Search parameters are a great way to implement interactive features in Next.js apps, as they help to reduce the bundle size of the client side.

Apart from performance, there are other benefits of using search parameters:

URLs with search parameters can be shared while preserving the application state.
Bookmarks preserve the state as well.
You can optionally integrate with the browser history, enabling undoing state changes via the back button.

Note however that there are also tradeoffs to consider:

Search parameter values are strings, so you may need to serialize and deserialize data types.
The URL is part of the user interface, so using many search parameters may affect readability.

You can have a look at the complete code of the example on GitHub.

Many thanks to Delba de Oliveira from Vercel for providing feedback for this article!

Cover photo by NASA on Unsplash