next-translate 0.19 release – adapting the i18n routing from Next.js 10

Next 10 is already here, and with it, next-translate 0.19 🎉

Although it’s a minor one, this release has BREAKING CHANGES. However, we’ve tried to implement backward compatibility to almost all changes so the migration should be easy.

If you look at the console there will be several console.warn telling you what to do. Also, below is a guide on how to migrate.

The goal of this release is to make a step towards version 1.0.0.

If you have any doubt/problem about the migration, please create an issue on GitHub and I’ll try my best to answer them.

Also, if you want to leave your feedback of this release you can write me on twitter.

BREAKING CHANGES

CHANGES

  • feat(builder): ignore test files in builder #283 (by @dnepro)

How to migrate from 0.18 to 0.19

Prerequisites

As a prerequisite, it is necessary to have version >= 10.0.0 of Next.js.

I recommend these readings before the migration:

1. Rename allLanguages and defaultLanguage

You should rename:

  • allLanguages -> locales
  • defaultLanguage -> defaultLocale

Although the old names are still supported, you’ll end up receiving a warning because we are going to deprecate them in next releases.

2. Add the i18n routing config to next.config.js

Since i18n routing is now handled by the Next.js core, we must pass it to the next.config.js file:

const { locales, defaultLocale } = require('./i18n.json')

module.exports = {
  i18n: { locales, defaultLocale },
}

3. Use Next.js Link and Router

No need to use the next-translate Link and Router anymore. We can use the original Next.js, replacing lang with locale:

old way:

import Link from 'next-translate/Link'

export default function Example() {
  return (
    <Link href="/" lang="es">
      <a>Change language to Spanish</a>
    </Link>
  )
}

new way:

import Link from 'next/link'

export default function Example() {
  return (
    <Link href="/" locale="es">
      <a>Change language to Spanish</a>
    </Link>
  )
}

Although the old Link and Route are still supported, you’ll end up receiving a warning because we are going to remove them in next releases.

4. Get the locale inside getServerSideProps, getStaticProps

Next.js now adds the locale in the context.

Instead of:

export function getStaticProps({ lang }) {
  return {
    props: something(lang)
  }
}

do:

export function getStaticProps({ locale }) {
  return {
    props: something(locale)
  }
}

4. Use Router.locale instead of clientSideLang

Instead of

import clientSideLang from 'next-translate/clientSideLang'
// ...
const lang = clientSideLang()

do:

import Router from 'next/router'
// ...
const lang = Router.locale

Although the old clientSideLang is still supported, you’ll end up receiving a warning because we are going to remove it in next releases.

5. Remove documentLang, now is handled automatically by Next.js

Instead of:

import Document, { Html, Head, Main, NextScript } from 'next/document'	
import documentLang from 'next-translate/documentLang'	

export default class MyDocument extends Document {	
  render() {	
    return (	
      <Html lang={documentLang(this.props)}>	
        <Head />	
        <body>	
          <Main />	
          <NextScript />	
        </body>	
      </Html>	
    )	
  }	
}

do:

import Document, { Html, Head, Main, NextScript } from 'next/document'	

export default class MyDocument extends Document {	
  render() {	
    return (	
      <Html>	
        <Head />	
        <body>	
          <Main />	
          <NextScript />	
        </body>	
      </Html>	
    )	
  }	
}

(Or remove the _document.js if you don’t have anything like this example)

Although the old documentLang is still supported, you’ll end up receiving a warning because we are going to remove it in next releases.

6. Remove the I18nMiddleware in case to use a custom server

If instead of using the “build step” you’re using the other alternative, by using i18nMiddleware and the appWithI18n wrapper, remember that now the i18nMiddleware is no longer necessary.

7. defaultLangRedirect config is no longer supported

Now if you need redirects you can:

  • Add the necessary redirects directly in the Next.js configuration.

8. ignoreRoutes config is no longer supported

Because the i18n routing isn’t a workaround anymore, it is now correctly handled without the need of this property. 😊

9. fixAs and fixHref are no longer supported

These helpers were initially for internal use of the library and were exposed here for a very concrete and punctual use case. As now the navigation is done by Next.js, we cannot maintain these helpers because they no longer give the same result as how it was internally handled before. Besides, the as in Next 10 is no longer necessary, now you can write directly in the href.

If you still want to use them, they are small helpers that you can integrate into your codebase. But they are no longer part of the next-translate API.

That’s all

Author: admin