README
next-multilingual">
next-multilingual
is an opinionated end-to-end solution for Next.js applications that requires multiple languages.
Check out our demo app!
Installation 💻
npm install next-multilingual
What's in it for me? 🤔
- The enforcement of i18n best practices across your entire application.
- Modular messages (also known as "localized strings") that work just like CSS modules (no more monolithic files).
- A powerful
useMessages
hook that supports ICU MessageFormat and JSX injection out of the box. - The ability to use localized URLs (e.g.,
/en-us/contact-us
for U.S. English and/fr-ca/nous-joindre
for Canadian French). - All page URLs will use locale prefixes (related to this discussion).
- Can easily be configured with smart language detection that dynamically renders the homepage, without using redirections.
- Automatically generate canonical and alternate links optimized for SEO.
Before we start 💎
next-multilingual
has put a lot of effort into adding TSDoc to all its APIs. Please check directly in your IDE if you are unsure how to use certain APIs provided in our examples.
Also, having an opinion on "best practices" is not an easy task. This is why we documented our design decisions in a special document that can be consulted here. If you feel that some of our APIs don't offer what you would expect, make sure to consult this document before opening an issue.
Getting Started 💨
For those who prefer to jump right into the action, look in the example
directory for an end-to-end implementation of next-multilingual
. For the rest, the section below will provide a complete, step by step, configuration guide.
Step by step configuration ⚙️
Configure Next.js
There are many options to configure in Next.js to achieve our goals. next-multilingual
mostly cares about:
- Your unique application identifier: this will be used to ensure that your messages (localized strings) have unique identifiers.
- Your locales: we only support BCP47 language tags that contain both a country and language code.
We offer two APIs to simplify this step:
getConfig
(simple config)
〰️ This function will generate a Next.js config that will meet most use cases. getConfig
takes the following arguments:
applicationId
— The unique application identifier that will be used as a messages key prefix.locales
— The actual desired locales of the multilingual application. The first locale will be the default locale. Only BCP 47 language tags following thelanguage
-country
format are accepted. For more details on why, refer to the design decisions document.options
(optional) — Options part of a Next.js configuration object.
getConfig
will return a Next.js configuration object.
To use it, simply add the following code in your application's next.config.js
:
const { getConfig } = require('next-multilingual/config');
const config = getConfig('exampleApp', ['en-US', 'fr-CA'], {
poweredByHeader: false,
});
module.exports = config;
Not all configuration options are not supported by getConfig
. If you ever happen to use one, an error message will point you directly to the next section: advanced config.
Config
(advanced config)
〰️ If you have more advanced needs, you can use the Config
object directly and insert the configuration required by next-multilingual
directly in an existing next.config.js
. The arguments of Config
are almost identical to getConfig
(minus the options
) - check in your IDE (TSDoc) for details. Here is an example of how it can be used:
const { Config } = require('next-multilingual/config');
const config = new Config('exampleApp', ['en-US', 'fr-CA']);
module.exports = {
i18n: {
locales: config.getUrlLocalePrefixes(),
defaultLocale: config.getDefaultUrlLocalePrefix(),
localeDetection: false,
},
poweredByHeader: false,
/* This is required since Next.js 11.1.3-canary.69 until we support ESM. */
experimental: {
esmExternals: false,
},
webpack(config, { isServer }) {
if (isServer) {
config.resolve.alias['next-multilingual/link