next.js: i18n with static sites

#webdev #nextjs #javascript

Version 3.x.x exclusively supports Next.js' app directory architecture. The 2.x.x branch continues to support the page directory, please.

Recently, I had a client who wanted a fast single-page application (SPA) with an outstanding lighthouse score and multiple languages hosted on a cheap shared hosting solution only accessible by FTP ... and of course, they wanted it to be built with react.js.

Based on the initial requirements and the following discussion, we decided to have a local build step to generate static files and transfer them to the web server.

Given their limited expertise and specific requirements, I suggested a static site generator with a custom headless setup for their content. The client was happy with the proposed architecture. I was looking into the possibility of using next.js and the two major requirements: a static page served by Apache and internationalisation (i18n).

True static files

Next.js provides a true out-of-the-box static sites generator. The next export command generates a fully optimised static HTML file set. This export can thus be served without any dependencies by any web server. There is no need to run node.js, etc - a regular Nginx or Apache installation is sufficient.

internationalization (i18n)

Next.js also provides amazing out-of-the-box support for internationalized (i18n) routing and a decent ecosystem for i18n-solutions

The i18n routing support complements existing i18n library solutions like react-intl, react-i18next, linguine, rosetta, next-intl and others by streamlining the routes and locale parsing.

That sounds nice, and being a fan of react-i18next, I looked into next-i18next and was quite happy to see that they support Static Generation (SSG).

To complement this, next-i18next (....) fully supports SSG/SSR, multiple namespaces, code splitting, etc.
Production ready: next-i18next supports passing translations and configuration options into pages as props with SSG/SSR support.
https://github.com/isaachinman/next-i18next/

Upon closer inspection, I figured they only support Static Generation (SSG) with next start, not next export. (About the differences, read my article The two and a half + one flavors of next.js's pre-rendering).

next start spins up the next.js web server and requires node.js - which was a problem for the hosting solutions.

I needed an export which would run on a basic nginx.

From the next.js documentation:

Note that Internationalized Routing does not integrate with the next export as the next export does not leverage the Next.js routing layer. Hybrid Next.js applications that do not use next export are fully supported.
https://nextjs.org/docs/advanced-features/i18n-routing#how-does-this-work-with-static-generation

Creating a custom i18n solution for true SSG support

Well, we're just going to create our custom i18n solution.

Let's collect the requirements:

The custom solution must:

have full support for next export

The custom solution should:

load the translation files from a folder with minimal configuration
provide a hook with the same interface as react-i18next
provide a stateful hook for the current language
set/retrieve the selected language to/from the search parameters so we can share a localised link
fallback to the default language if no search parameter is present
set the search parameter on internal links and preserve existing search parameters
provide a sample component for selecting the language