Neoteric Plumbing Mishap

    next-i18next
    TypeScript icon, indicating that this package has built-in type declarations

    11.0.0 • Public • Published

    next-i18next

    npm version CircleCI Package Quality

    The easiest way to translate your NextJs apps.

    If you are using next-i18next in production, please consider sponsoring the package with any amount you think appropriate.

    What is this?

    Although NextJs provides internationalised routing directly, it does not handle any management of translation content, or the actual translation functionality itself. All NextJs does is keep your locales and URLs in sync.

    To complement this, next-i18next provides the remaining functionality – management of translation content, and components/hooks to translate your React components – while fully supporting SSG/SSR, multiple namespaces, codesplitting, etc.

    While next-i18next uses i18next and react-i18next under the hood, users of next-i18next simply need to include their translation content as JSON files and don't have to worry about much else.

    A live demo is available here. This demo app is the simple example - nothing more, nothing less.

    Why next-i18next?

    Easy to set up, easy to use: setup only takes a few steps, and configuration is simple.

    No other requirements: next-i18next simplifies internationalisation for your NextJs app without extra dependencies.

    Production ready: next-i18next supports passing translations and configuration options into pages as props with SSG/SSR support.

    How does it work?

    Your next-i18next.config.js file will provide configuration for next-i18next. After configuration, appWithTranslation allows us to use the t (translate) function in our components via hooks.

    Then we add serverSideTranslation to getStaticProps or getServerSideProps (depending on your case) in our page-level components.

    Now our NextJs app is fully translatable!

    Setup

    1. Installation

    yarn add next-i18next

    You need to also have react and next installed.

    2. Translation content

    By default, next-i18next expects your translations to be organised as such:

    .
    └── public
        └── locales
            ├── en
            |   └── common.json
            └── de
                └── common.json
    

    This structure can also be seen in the simple example.

    If you want to structure your translations/namespaces in a custom way, you will need to pass modified localePath and localeStructure values into the initialisation config.

    3. Project setup

    First, create a next-i18next.config.js file in the root of your project. The syntax for the nested i18n object comes from NextJs directly.

    This tells next-i18next what your defaultLocale and other locales are, so that it can preload translations on the server:

    next-i18next.config.js

    module.exports = {
      i18n: {
        defaultLocale: 'en',
        locales: ['en', 'de'],
      },
    };

    Now, create or modify your next.config.js file, by passing the i18n object into your next.config.js file, to enable localised URL routing:

    next.config.js

    const { i18n } = require('./next-i18next.config');
    
    module.exports = {
      i18n,
    };

    There are three functions that next-i18next exports, which you will need to use to translate your project:

    appWithTranslation

    This is a HOC which wraps your _app:

    import { appWithTranslation } from 'next-i18next';
    
    const MyApp = ({ Component, pageProps }) => <Component {...pageProps} />;
    
    export default appWithTranslation(MyApp);

    The appWithTranslation HOC is primarily responsible for adding a I18nextProvider.

    serverSideTranslations

    This is an async function that you need to include on your page-level components, via either getStaticProps or getServerSideProps (depending on your use case):

    import { serverSideTranslations } from 'next-i18next/serverSideTranslations';
    
    export async function getStaticProps({ locale }) {
      return {
        props: {
          ...(await serverSideTranslations(locale, ['common', 'footer'])),
          // Will be passed to the page component as props
        },
      };
    }

    Note that serverSideTranslations must be imported from next-i18next/serverSideTranslations – this is a separate module that contains NodeJs-specific code.

    Also, note that serverSideTranslations is not compatible with getInitialProps, as it only can execute in a server environment, whereas getInitialProps is called on the client side when navigating between pages.

    The serverSideTranslations HOC is primarily responsible for passing translations and configuration options into pages, as props – you need to add it to any page that has translations.

    useTranslation

    This is the hook which you'll actually use to do the translation itself. The useTranslation hook comes from react-i18next, but can be imported from next-i18next directly:

    import { useTranslation } from 'next-i18next';
    
    export const Footer = () => {
      const { t } = useTranslation('footer');
    
      return (
        <footer>
          <p>{t('description')}</p>
        </footer>
      );
    };

    4. Declaring namespace dependencies

    By default, next-i18next will send all your namespaces down to the client on each initial request. This can be an appropriate approach for smaller apps with less content, but a lot of apps will benefit from splitting namespaces based on route.

    To do that, you can pass an array of required namespaces for each page into serverSideTranslations. You can see this approach in examples/simple/pages/index.js. Passing in an empty array of required namespaces will send no namespaces.

    Note: useTranslation provides namespaces to the component that you use it in. However, serverSideTranslations provides the total available namespaces to the entire React tree and belongs on the page level. Both are required.

    5. Advanced configuration

    Passing other config options

    If you need to modify more advanced configuration options, you can pass them via next-i18next.config.js. For example:

    const path = require('path');
    
    module.exports = {
      i18n: {
        defaultLocale: 'en',
        locales: ['en', 'de'],
      },
      localePath: path.resolve('./my/custom/path'),
    };

    Unserialisable configs

    Some i18next plugins (which you can pass into config.use) are unserialisable, as they contain functions and other JavaScript primitives.

    You may run into this if your use case is more advanced. You'll see NextJs throw an error like:

    Error: Error serializing `._nextI18Next.userConfig.use[0].process` returned from `getStaticProps` in "/my-page".
    Reason: `function` cannot be serialized as JSON. Please only return JSON serializable data types.
    

    To fix this, you'll need to set config.serializeConfig to false, and manually pass your config into appWithTranslation:

    import { appWithTranslation } from 'next-i18next';
    import nextI18NextConfig from '../next-i18next.config.js';
    
    const MyApp = ({ Component, pageProps }) => <Component {...pageProps} />;
    
    export default appWithTranslation(MyApp, nextI18NextConfig);
    import { serverSideTranslations } from 'next-i18next/serverSideTranslations';
    
    import nextI18NextConfig from '../next-i18next.config.js';
    
    export const getStaticProps = async ({ locale }) => ({
      props: {
        ...(await serverSideTranslations(
          locale,
          ['common', 'footer'],
          nextI18NextConfig
        )),
      },
    });

    Client side loading of translations via HTTP

    Since v11.0.0 next-i18next also provides support for client side loading of translations.

    More information about that can be found here.

    Reloading Resources in Development

    Because resources are loaded once when the server is started, any changes made to your translation JSON files in development will not be loaded until the server is restarted.

    In production this does not tend to be an issue, but in development you may want to see updates to your translation JSON files without having to restart your development server each time. To do this, set the reloadOnPrerender config option to true.

    This option will reload your translations whenever serverSideTranslations is called (in getStaticProps or getServerSideProps). If you are using serverSideTranslations in getServerSideProps, it is recommended to disable reloadOnPrerender in production environments as to avoid reloading resources on each server call.

    Options

    Key Default value Note
    defaultNS 'common'
    localePath './public/locales' Can be a function, see note below.
    localeExtension 'json' Ignored if localePath is a function.
    localeStructure '{{lng}}/{{ns}}' Ignored if localePath is a function.
    reloadOnPrerender false
    serializeConfig true
    strictMode true
    use (for plugins) []

    localePath as a function is of the form (locale: string, namespace: string, missing: boolean) => string returning the entire path including filename and extension. When missing is true, return the path for the addPath option of i18next-fs-backend, when false, return the path for the loadPath option. More info at the i18next-fs-backend repo.

    All other i18next options and react-i18next options can be passed in as well.

    Loading Namespaces Dynamically Client Side

    In some use cases, you might want to load a translation file dynamically without having to use serverSideTranslations. This can be especially useful for lazy-loaded components that you don't want slowing down pages.

    This can easily be done by using addResourceBundle:

    import { i18n } from 'next-i18next'
    
    const Component = () => {
      const { locale } = useRouter()
    
      useEffect(() => {
        i18n.addResourceBundle(locale, '<namespace name>')
      }, [])
    }

    Custom interpolation prefix/suffix

    By default, i18next uses {{ as prefix and }} as suffix for interpolation. If you want/need to override these interpolation settings, you must also specify an alternative localeStructure setting that matches your custom prefix and suffix.

    For example, if you want to use { and } the config would look like this:

    {
      i18n: {
        defaultLocale: 'en',
        locales: ['en', 'nl'],
      },
      interpolation: {
        prefix: '{',
        suffix: '}',
      },
      localeStructure: '{lng}/{ns}',
    }

    Migration to v8

    To migrate from previous versions to the version 8, check out the v8-migration guide

    Notes

    Vercel and Netlify

    Some serverless PaaS may not be able to locate the path of your translations and require additional configuration. If you have filesystem issues using serverSideTranslations, set config.localePath to use path.resolve. An example can be found here.

    Docker

    For Docker deployment, note that if you use the Dockerfile from Next.js docs do not forget to copy next.config.js and next-i18next.config.js into the Docker image.

    COPY --from=builder /app/next.config.js ./next.config.js
    COPY --from=builder /app/next-i18next.config.js ./next-i18next.config.js
    

    Asynchronous i18next backends

    If you choose to use an i18next backend different to the built-in i18next-fs-backend, you will need to ensure the translation resources are loaded before you call the t function. Since React suspense is not yet supported for SSR, this can be solved in 2 different ways:

    1) Preload the namespaces:

    Set the ns option, like in this example. Doing this will ensure all translation resources are loaded on initialization.

    2) Check the ready flag:

    If you cannot or do not want to provide the ns array, calls to the t function will cause namespaces to be loaded on the fly. This means you'll need to handle the "not ready" state by checking ready === true or props.tReady === true. Not doing so will result in rendering your translations before they loaded, which will cause "save missing" be called despite the translations actually existing (just yet not loaded). This can be done with the useTranslation hook or the withTranslation HOC.

    Contributors

    Thanks goes to these wonderful people (emoji key):

    Rob Capellini
    Rob Capellini

    💻 ⚠️
    Alexander Kachkaev
    Alexander Kachkaev

    📢 💬 🤔 💻 ⚠️
    Mathias Wøbbe
    Mathias Wøbbe

    💻 🤔 ⚠️
    Lucas Feliciano
    Lucas Feliciano

    🤔 👀
    Ryan Leung
    Ryan Leung

    💻
    Nathan Friemel
    Nathan Friemel

    💻 📖 💡 🤔

    This project follows the all-contributors specification. Contributions of any kind welcome!

    Sponsors

    Install

    npm i next-i18next

    DownloadsWeekly Downloads

    201,229

    Version

    11.0.0

    License

    MIT

    Unpacked Size

    110 kB

    Total Files

    41

    Last publish

    Collaborators

    • isaachinman