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
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:
- Next.js docs about i18n: https://nextjs.org/docs/advanced-features/i18n-routing
- README of this repo, because it's updated: https://github.com/vinissimus/next-translate/blob/0.19.0/README.md
1. Rename allLanguages and defaultLanguage
You should rename:
allLanguages->localesdefaultLanguage->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)
}
}For getStaticPaths you should provide all the slugs for each locale, so you are receiving the locales:
export function getStaticPaths({ locales }) {
// ...
}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.localeAlthough the old
clientSideLangis 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
documentLangis 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.