A modern localisation solution for Next.js, featuring Full TypeScript support, SSR support, easy setup & configuration, included middleware, global dictionaries & dictionary inheritance. This is a very early version; Next Loc will improve and evolve in the future.
Install Next Loc globally:
npm install -g next-loc
Next Loc requires the following packages to be installed in your project directory:
chalk
chalk-konsole
string-replace-utils
accept-language
smob
-
lz-string
(can be changed, see below)
Configure Next Loc in your project:
npx next-loc@latest
Flag | Alternative | Description |
---|---|---|
--default |
-d |
Use the default configuration. |
--default-dir |
-dd |
Use the default destination directory (src/locale ). |
Made a mistake during configuration? Just run the command again to overwrite the existing configuration!
Next, import the generated middleware into your middleware.ts
or middleware.js
file. Refer to the Next.js docs for more information. Here is an example implementation:
import { localeMiddleware } from "./path/to/middleware";
export const middleware = (request: NextRequest, _event: NextFetchEvent) => {
return localeMiddleware(request, _event);
};
export const config = {
matcher: "/((?!api|_next/static|_next/image|favicon.ico).*)",
};
Create a directory for each locale (with the same name), following the format described by the dictionaryPath
option in the config.ts
file.
Create a JSON file for each namespace (with the same name) within each locale directory, following the format described by the dictionaryPath
option in the config.ts
file.
For example, using the default configuration, the following dictionary files should be created:
src/locale/dictionary/en-GB/common.json
Move all routes into a [locale]
directory, which allows the current locale to be determined using the URL params. See the Next.js docs for more information.
Wrap your app inside the <LocaleContextProvider>
component at your app root, which allows you to access the current locale and dictionary in client components via the use of the useLocaleContext()
hook. See the context documentation for more information.
- During SSR, the dictionary can be omitted as it is imported automatically within the
translate
function. - If no dictionary is provided during client-side-rendering, an empty dictionary will be used, thus all translations will not be found.
- If no locale is provided, the default locale will be used.
-
key
refers to the full dot notation path to the translation. For example,"common.greetings.welcome"
, would be found at thewelcome
key, within thegreetings
object, within the JSON object in thecommon.json
file.
// Usage with SSR
import { dictionary } from "./path/to/compileDictionary";
// Get locale from URL params
const str = translate("common.greetings.welcome", dictionary, locale);
// Usage with client components
const { dictionary, locale } = useLocaleContext();
const str = translate("common.greetings.welcome", dictionary, locale);
See the context documentation for more information.
- Returns a translate function
- Default locale in the returned function is set to the value of
locale
here - The
key
is appended to the value ofnamespace
here (.
is added automatically) - If a dictionary is provided, it will be used by default in the returned function
- All parameters can be overriden by passing them in the returned function (except from
key
which is always appended to thenamespace
here)
- Default locale in the returned function is set to the value of
- During SSR, the dictionary can be omitted as it is imported automatically within the
translate
function. - If no dictionary is provided during client-side-rendering, an empty dictionary will be used, thus all translations will not be found.
- If no locale is provided, the default locale will be used.
// Usage with SSR
const t = genT(locale, "common.greetings");
const str = t("welcome");
// Usage with client components
const t = genT(locale, "common.greetings", dictionary);
const str = t("welcome");
useAutoGenT
is a React Hook provided by Next Loc, which acts as a shorthand for genT(locale, namespace, dictionary)
. It can be used in client components to prevent having to call useLocaleContext()
to get the dictionary and locale. Instead, the locale and dictionary are retrieved from context within the hook itself.
⚠️ Translations are not strings by default, but actually instances of aLocalisedString
class, which is a direct copy of theReplaceable
class from string-replace-utils. This simply provides some useful methods for replacing substrings. You can change this behaviour by modifying the return value of thegetTranslation
function AND the return value in the catch block inside thetranslate
function. To replace substrings with React components, it is recommended to use react-string-replace (this may be integrated in a future release).
Next Loc includes a locale context provider to make it easier to access the locale and dictionary in client components. The recommended usage is to set the context at the app root.
import { dictionary } from "./path/to/compileDictionary";
export default function RootLayout({
children,
params: { locale },
}: Readonly<{ children: React.ReactNode }> & NextLocTypes.LocaleParam) {
return (
<html lang={locale}>
<body>
<LocaleContextProvider {...{ locale, dictionary }}>
{children}
</LocaleContextProvider>
<LocaleLogProvider />
</body>
</html>
);
}
Use useLocaleContext()
to access the locale and dictionary in client components.
const { locale, dictionary } = useLocaleContext();
Next Loc also includes a context provider for the translate
function. This allows you to create a translate function using genT
, then pass it to the <TranslationContextProvider />
component, then use useTranslationContext()
to access the translate function in client components.
// Using SSR
export const Component = () => {
const t = genT(locale, "common.greetings");
return (
<TranslationContextProvider translator={t}>
<ChildComponent />
</TranslationContextProvider>
);
};
// Child (client) component
export const ChildComponent = () => {
const { translator: t } = useTranslationContext();
return <p>{t("welcome")}</p>;
};
Next Loc makes some checks to ensure that localisation will function as expected (these can be inspected in internal/checks.ts
). To enable these checks, add the <LocaleLogProvider />
component at the app root.
These checks cover:
- Checking that all supported locales satisfy the
localePattern
specified in theconfig.ts
file - Checking that the default locale is included as a supported locale
Next Loc generates a configuration file, config.ts
within the destination directory. This file can be freely modified to suit your needs. This is the default configuration that is generated with the default options during setup:
{
supportedLocales: ["en-GB"],
supportedNamespaces: ["common"],
globalNamespaces: [],
defaultLocale: "en-GB",
defaultNamespace: "common",
cookieName: "hl",
localePattern: /[a-z]{2}-[A-Z]{2}/,
dictionaryPath: "src/locale/dictionary/{locale}/{namespace}.json",
inherits: {},
ignoreMiddleware: [
"/static",
"/api",
"/_next",
"favicon.ico",
"robots.txt",
"sitemap.xml",
],
suppress: {
missingDictionary: false,
localeSatisfiesPattern: false,
defaultLocaleIsSupported: false,
},
optOutCompression: false,
}
supportedLocales
A string array, containing the locales supported by your application.
supportedNamespaces
A string array, containing the namespaces supported by your application. Each namespace corresponds to an indiviual JSON file located inside each dictionary directory.
globalNamespaces
A string array, containing the namespaces found in the GLOBAL
directory, available for all locales.
defaultLocale
The default locale, used when no cookie is set, and the request URL contains no supported locale.
defaultNamespace
The namespace used for finding localisations when no namespace is provided to the translator function.
cookieName
The name of the cookie used to store the selected locale in the user's browser.
localePattern
The pattern for supported locales. This is used when the request URL does not contain a supported locale, to determine if the user is trying to access a valid, but not supported locale. For example, using the default configuration, the URL /de-DE/page
would be redirected to en-GB/page
, because de-DE
satisfies the localePattern
. Whereas the URL something/page
would be redirected to en-GB/something/page
, because something
does not satisfy the localePattern
.
dictionaryPath
The path to the JSON dictionary files. This should include {locale}
and {namespace}
to point to the correct files for each locale and namespace during dictionary compilation. See Using Non-JSON Dictionaries below for more information.
inherits
Declare dictionary inheritance, in the format { {locale}: {other locales}[], ... }
. See inheritance below for more information.
ignoreMiddleware
An array of paths for which the middleware will return an unmodified response. This is useful for ignoring static files which should not differ based on locale, such as /favicon.ico
. Middleware execution can be prevented via the config
object within middleware.ts
, as referenced by the Next.js docs. Paths in ignoreMiddleware
will NOT prevent middleware from being executed.
suppress
Allows you to suppress certain errors.
-
missingDictionary
: Iftrue
, no errors will be shown when a dictionary is missing. If an array containing locales is provided, only errors for those locales will be suppressed. -
localeSatisfiesPattern
: Iftrue
, no errors will be shown when a locale does not satisfy thelocalePattern
specified in theconfig.ts
file. -
defaultLocaleIsSupported
: Iftrue
, no error will be shown when the default locale is not included as a supported locale.
optOutCompression
If true
, Next Loc will not compress the dictionary object. See the section on compression below for more information.
Next Loc provides a property in the config object, inherits
, which allows locales to inherit translations from other locales. This is useful for implementing locales for different cultures within the same language. For example, if your site has the locale en-GB
, but you also want to support the locale en-US
, instead of copying every file from the en-GB
directory, you can simply add the following to the config.ts
file:
inherits: {
"en-US": ["en-GB"]
}
This means that every localisation from en-GB
is inherited by en-US
. From here, you can add unique translations to en-US
as normal, and they will overwrite the translations inherited from en-GB
. To prevent errors due to missing dictionary files for en-US
, make sure to set suppress.missingDictionary
to true
, or include en-US
in its array.
Next Loc also provides support for global dictionaries. A global dictionary is, in essence, "inherited" by ALL locales. To use global dictionaries, create a GLOBAL
directory in the same directory as the normal locales. Within this GLOBAL
directory, create a JSON file for each member of globalNamespaces
in config.ts
. Translations located in global dictionaries are accessed in the same way as regular localisations. For example, if there is a file GLOBAL/metadata.json
, its translations can be accessed as follows.
//...
<p>{translate("metadata.site.title", locale, dictionary)}</p>
//...
Dictionaries are compiled in the following order:
- Global dictionaries
- Inherited dictionaries (overwrite global dictionaries)
- Inherited locales are compiled in the order in which they are listed in
inherits
property
- Inherited locales are compiled in the order in which they are listed in
- Regular dictionaries
For example, if en-US
inherits from ["en-GB", "en-CA"]
, and the application makes use of global dictionaries, the global dictionaries will be compiled first, then merged with the inherited dictionaries, first en-GB
, then en-CA
, any conflicts being overwritten by the inherited dictionaries in the order of their declaration (en-CA
overwrites conflicts with en-GB
), then the regular dictionaries for en-US
will be compiled last, any conflicts being overwritten by the regular dictionaries.
Next Loc includes support for compressing the dictionary object. The default and recommended compression method is achieved via the use of lz-string. To change the compression (and decompression) functions, modify the compressFunction
and decompressFunction
functions exported from internal/compression.ts
. For small sites with a small amount of text, or a small number of locales, you should consider opting out of compression to improve performance.
Next Loc currently does not have out-of-the-box support for non-JSON dictionaries. You may be able to achieve this functionality by doing the following:
- Modify the
dictionaryPath
option in the configuration file, to use the necessary file extension. - Modify the
compileDictionary
function ininternal/compileDictionary.ts
,- Change
JSON.parse(fileContents)
to a custom function - The function must parse the format of your dictionary file, and return a JSON object
- Change