next-translate

<img src="images/logo.svg" width="300" alt="next-translate" /> Easy i18n for Next.js +10 Next plugin + i18n API <div align="center">

npm [![PRs Welcome][badge-prwelcome]][prwelcome] <a href="https://github.com/aralroca/next-translate/actions?query=workflow%3ACI" alt="Tests status"> <img src="https://github.com/aralroca/next-translate/workflows/CI/badge.svg" /></a> <a href="https://twitter.com/intent/follow?screen_name=aralroca"> <img src="https://img.shields.io/twitter/follow/aralroca?style=social&logo=x" alt="follow on Twitter"></a>

</div>

1. About next-translate
- How are translations loaded?
2. Getting started
3. Configuration
4. API
5. Plurals
6. Use HTML inside the translation
7. Nested translations
8. Fallbacks
9. Formatter
10. How to change the language
11. How to save the user-defined language
12. How to use multi-language in a page
13. How to use next-translate in a mono-repo
14. Use Next 13 app directory
15. Demos
Contributors ✨

1. About next-translate

The main goal of this library is to keep the translations as simple as possible in a Next.js environment.

Next-translate has two parts: Next.js plugin + i18n API.

Features ✨

🚀 ・ Automatic page optimization (pages dir).
🏝️ ・ React 18 server/client pages/components (app dir).
🦄 ・ Easy to use and configure.
🌍 ・ Basic i18n support: interpolation, plurals, useTranslation hook, Trans component...
🈂️ ・ It loads only the necessary translations (for page and for locale).
📦 ・ Tiny (~1kb) and tree shakable. No dependencies.

How are translations loaded?

In the configuration file, you specify each page that namespaces needs:

i18n.json

{
  "pages": {
    "*": ["common"],
    "/": ["home"],
    "/cart": ["cart"],
    "/content/[slug]": ["content"],
    "rgx:^/account": ["account"]
  }
  // rest of config here...
}

Read here about how to add the namespaces JSON files.

Next-translate ensures that each page only has its namespaces with the current language. So if we have 100 locales, only 1 will be loaded.

In order to do this we use a webpack loader that loads the necessary translation files inside the Next.js methods (getStaticProps, getServerSideProps or getInitialProps). If you have one of these methods already on your page, the webpack loader will use your own method, but the defaults it will use are:

getStaticProps. This is the default method used on most pages, unless it is a page specified in the next two points. This is for performance, so the calculations are done in build time instead of request time.
getServerSideProps. This is the default method for dynamic pages like [slug].js or [...catchall].js. This is because for these pages it is necessary to define the getStaticPaths and there is no knowledge of how the slugs should be for each locale. Likewise, how is it by default, only that you write the getStaticPaths then it will already use the getStaticProps to load the translations.
getInitialProps. This is the default method for these pages that use a HoC. This is in order to avoid conflicts because HoC could overwrite a getInitialProps.

This whole process is transparent, so in your pages you can directly consume the useTranslation hook to use the namespaces, and you don't need to do anything else.

If for some reason you use a getInitialProps in your _app.js file, then the translations will only be loaded into your getInitialProps from _app.js. We recommend that for optimization reasons you don't use this approach unless it is absolutely necessary.

2. Getting started

Install

yarn add next-translate

Add next-translate plugin

The next-translate-plugin is a tool that allows developers to efficiently handle translations on a page-by-page basis during the build process. It is distinct from the next-translate package, which allows developers to access the translations in the code where it is needed. The plugin works by parsing all pages, searching for the translations and rewriting the page file adding the translations to it. This makes the plugin a more efficient and flexible solution for handling translations within a Next.js application. It is recommended to install the plugin as a devDependency.

yarn add next-translate-plugin -D

In your next.config.js file:

const nextTranslate = require('next-translate-plugin')

module.exports = nextTranslate()

Or if you already have next.config.js file and want to keep the changes in it, pass the config object to the nextTranslate(). For example for webpack you could do it like this:

const nextTranslate = require('next-translate-plugin')

module.exports = nextTranslate({
  webpack: (config, { isServer, webpack }) => {
    return config;
  }
})

Add i18n.js config file

Add a configuration file i18n.json (or i18n.js with module.exports) in the root of the project. Each page should have its namespaces. Take a look at it in the config section for more details.

{
  "locales": ["en", "ca", "es"],
  "defaultLocale": "en",
  "pages": {
    "*": ["common"],
    "/": ["home", "example"],
    "/about": ["about"]
  }
}

In the configuration file you can use both the configuration that we specified here and the own features about internationalization of Next.js 10.

Create your namespaces files

By default the namespaces are specified on the /locales root directory in this way:

/locales

.
├── ca
│   ├── common.json
│   └── home.json
├── en
│   ├── common.json
│   └── home.json
└── es
    ├── common.json
    └── home.json

Each filename matches the namespace specified on the pages config property, while each file content should be similar to this:

{
  "title": "Hello world",
  "variable-example": "Using a variable {{count}}"
}

However, you can use another destination to save your namespaces files using loadLocaleFrom configuration property:

i18n.js

{
  // ...rest of config
  "loadLocaleFrom": (lang, ns) =>
    // You can use a dynamic import, fetch, whatever. You should
    // return a Promise with the JSON file.
    import(`./myTranslationsFiles/${lang}/${ns}.json`).then((m) => m.default),
}

Use translations in your pages

Then, use the translations in the page and its components:

pages/example.js

import useTranslation from 'next-translate/useTranslation'

export default function ExamplePage() {
  const { t, lang } = useTranslation('common')
  const example = t('variable-example', { count: 42 })

  return <div>{example}</div> // <div>Using a variable 42</div>
}

You can consume the translations directly on your pages, you don't have to worry about loading the namespaces files manually on each page. The next-translate plugin loads only the namespaces that the page needs and only with the current language.

3. Configuration

In the configuration file you can use both the configuration that we specified here and the own features about internationalization of Next.js 10.

Option	Description	Type	Default
`defaultLocale`	ISO of the default locale ("en" as default).	`string`	`"en"`
`locales`	An array with all the languages to use in the project.	`string[]`	`[]`
`loadLocaleFrom`	Change the way you load the namespaces.	`function` that returns a `Promise` with the `JSON`.	By default is loading the namespaces from locales root directory.
`pages`	An object that defines the namespaces used in each page. Example of object: `{"/": ["home", "example"]}`. To add namespaces to all pages you should use the key `""`, ex: `{"": ["common"]}`. It's also possible to use regex using `rgx:` on front: `{"rgx:/form$": ["form"]}`. You can also use a function instead of an array, to provide some namespaces depending on some rules, ex: `{ "/": ({ req, query }) => query.type === 'example' ? ['example'] : []}`	`Object<string[] or function>`	`{}`
`logger`	Function to log the missing keys in development and production. If you are using `i18n.json` as config file you should change it to `i18n.js`.	`function`	By default the logger is a function doing a `console.warn` only in development.
`loggerEnvironment`	String to define if the logger should run in the browser, in node or both	`"node"` \| `"browser"` \| `"both"`	`"browser"`
`logBuild`	Each page has a log indicating: namespaces, current language and method used to load the namespaces. With this you can disable it.	`Boolean`	`true`
`loader`	If you wish to disable the webpack loader and manually load the namespaces on each page, we give you the opportunity to do so by disabling this option.	`Boolean`	`true`
`interpolation`	Change the delimiter that is used for interpolation.	`{prefix: string; suffix: string, formatter: function }`	`{prefix: '{{', suffix: '}}'}`
`keySeparator`	Change the separator that is used for nested keys. Set to `false` to disable keys nesting in JSON translation files. Can be useful if you want to use natural text as keys.	`string` \| `false`	`'.'`
`nsSeparator`	char to split namespace from key. You should set it to `false` if you want to use natural text as keys.	`string` \| `false`	`':'`
`defaultNS`	default namespace used if not passed to `useTranslation` or in the translation key.	`string`	`undefined`
`staticsHoc`	The HOCs we have in our API (appWithI18n), do not use hoist-non-react-statics in order not to include more kb than necessary (static values different than getInitialProps in the pages are rarely used). If you have any conflict with statics, you can add hoist-non-react-statics (or any other alternative) here. See an example.	`Function`	`null`
`extensionsRgx`	Change the regex used by the webpack loader to find Next.js pages.	`Regex`	`/\.(tsx\|ts\|js\|mjs\|jsx)$/`
`revalidate`	If you want to have a default revalidate on each page we give you the opportunity to do so by passing a number to revalidate. You can still define getStaticProps on a page with a different revalidate amount and override this default override.	`Number`	If you don't define it, by default the pages will have no revalidate.
`pagesInDir`	If you run `next ./my-app` to change where your pages are, you can here define `my-app/pages` so that next-translate can guess where they are.	`String`	If you don't define it, by default the pages will be searched for in the classic places like `pages` and `src/pages`.
`localesToIgnore`	Indicate these locales to ignore when you are prefixing the default locale using a middleware (in Next +12, learn how to do it)	`Array<string>`	`['default']`
`allowEmptyStrings`	Change how translated empty strings should be handled. If omitted or passed as true, it returns an empty string. If passed as false, returns the key name itself (including ns).	`Boolean`	`true`

4. API

useTranslation

Size: ~150b 📦

This hook is the recommended way to use translations in your pages / components.

Input: string - defaultNamespace (optional)
Output: Object { t: Function, lang: string }

Example:

import React from 'react'
import useTranslation from 'next-translate/useTranslation'

export default function Description() {
  const { t, lang } = useTranslation('ns1') // default namespace (optional)
  const title = t('title')
  const titleFromOtherNamespace = t('ns2:title')
  const description = t`description` // also works as template string
  const example = t('ns2:example', { count: 3 }) // and with query params
  const exampleDefault = t('ns:example', { count: 3 }, { default: "The count is: {{count}}." }) // and with default translation

  return (
    <>
      <h1>{title}</h1>
      <p>{description}</p>
      <p>{example}</p>
    <>
  )
}

The t function:

Input:
- i18nKey: string (namespace:key)
- query: Object (optional) (example: { name: 'Leonard' })
- options: Object (optional)
  - fallback: string | string[] - fallback if i18nKey doesn't exist. See more.
  - returnObjects: boolean - Get part of the JSON with all the translations. See more.
  - default: string - Default translation for the key. If fallback keys are used, it will be used only after exhausting all the fallbacks.
  - ns: string - Namespace to use when none is embded in the i18nKey.
Output: string