You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -17,6 +18,23 @@ While `next-i18next` uses [i18next](https://www.i18next.com/) and [react-i18next
17
18
18
19
A live demo is [available here](http://next-i18next.com/). This demo app is the [simple example](./examples/simple/) - nothing more, nothing less.
19
20
21
+
## Why next-i18next?
22
+
23
+
Easy to set up, easy to use: setup only takes a few steps, and configuration is simple.
24
+
25
+
No other requirements: `next-i18next` simplifies internationalisation for your [NextJs](https://nextjs.org/) app without extra dependencies.
26
+
27
+
Production ready: `next-i18next` supports passing translations and configuration options into pages as props with SSG/SSR support.
28
+
29
+
## How does it work?
30
+
31
+
Your `next-i18next.config.js` file will provide configuration for `next-i18next`.
32
+
After configuration, `appWithTranslation` allows us to use the `t` (translate) function in our components via hooks.
33
+
34
+
Then we add `serverSideTranslation` to [getStaticProps](https://nextjs.org/docs/basic-features/data-fetching#getstaticprops-static-generation) or [getServerSideProps](https://nextjs.org/docs/basic-features/data-fetching#getserversideprops-server-side-rendering) (depending on your case) in our page-level components.
35
+
36
+
Now our NextJs app is fully translatable!
37
+
20
38
## Setup
21
39
22
40
### 1. Installation
@@ -30,6 +48,7 @@ You need to also have `react` and `next` installed.
30
48
### 2. Translation content
31
49
32
50
By default, `next-i18next` expects your translations to be organised as such:
51
+
33
52
```
34
53
.
35
54
└── public
@@ -46,7 +65,7 @@ If you want to structure your translations/namespaces in a custom way, you will
46
65
47
66
### 3. Project setup
48
67
49
-
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](https://nextjs.org/docs/advanced-features/i18n-routing).
68
+
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](https://nextjs.org/docs/advanced-features/i18n-routing).
50
69
51
70
This tells `next-i18next` what your `defaultLocale` and other locales are, so that it can preload translations on the server:
52
71
@@ -58,19 +77,19 @@ module.exports = {
58
77
defaultLocale:'en',
59
78
locales: ['en', 'de'],
60
79
},
61
-
}
80
+
};
62
81
```
63
82
64
83
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:
The `appWithTranslation` HOC is primarily responsible for adding a `I18nextProvider`.
109
+
The `appWithTranslation` HOC is primarily responsible for adding a [`I18nextProvider`](https://react.i18next.com/latest/i18nextprovider).
91
110
92
111
#### serverSideTranslations
93
112
94
113
This is an async function that you need to include on your page-level components, via either [`getStaticProps`](https://nextjs.org/docs/basic-features/data-fetching#getstaticprops-static-generation) or [`getServerSideProps`](https://nextjs.org/docs/basic-features/data-fetching#getserversideprops-server-side-rendering) (depending on your use case):
Note that `serverSideTranslations` must be imported from `next-i18next/serverSideTranslations` – this is a separate module that contains NodeJs-specific code.
@@ -114,47 +136,43 @@ The `serverSideTranslations` HOC is primarily responsible for passing translatio
114
136
This is the hook which you'll actually use to do the translation itself. The `useTranslation` hook [comes from `react-i18next`](https://react.i18next.com/latest/usetranslation-hook), but can be imported from `next-i18next` directly:
115
137
116
138
```tsx
117
-
import { useTranslation } from'next-i18next'
139
+
import { useTranslation } from'next-i18next';
118
140
119
141
exportconst Footer = () => {
120
-
121
-
const { t } =useTranslation('footer')
142
+
const { t } =useTranslation('footer');
122
143
123
144
return (
124
145
<footer>
125
-
<p>
126
-
{t('description')}
127
-
</p>
146
+
<p>{t('description')}</p>
128
147
</footer>
129
-
)
130
-
}
148
+
);
149
+
};
131
150
```
132
151
133
152
### 4. Declaring namespace dependencies
134
153
135
154
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.
136
155
137
-
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](./examples/simple/pages/index.js).
156
+
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](./examples/simple/pages/index.js). Passing in an empty array of required namespaces will send no namespaces.
138
157
139
158
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.
140
159
141
160
### 5. Advanced configuration
142
161
143
-
144
162
#### Passing other config options
145
163
146
164
If you need to modify more advanced configuration options, you can pass them via `next-i18next.config.js`. For example:
147
165
148
166
```js
149
-
constpath=require('path')
167
+
constpath=require('path');
150
168
151
169
module.exports= {
152
170
i18n: {
153
171
defaultLocale:'en',
154
172
locales: ['en', 'de'],
155
173
},
156
-
localePath:path.resolve('./my/custom/path')
157
-
}
174
+
localePath:path.resolve('./my/custom/path'),
175
+
};
158
176
```
159
177
160
178
#### Unserialisable configs
@@ -171,42 +189,52 @@ Reason: `function` cannot be serialized as JSON. Please only return JSON seriali
171
189
To fix this, you'll need to set `config.serializeConfig` to `false`, and manually pass your config into `appWithTranslation`:
All other [i18next options](https://www.i18next.com/overview/configuration-options) can be passed in as well.
207
229
230
+
## Migration to v8
231
+
232
+
To migrate from previous versions to the version 8, check out the [v8-migration guide](https://github.com/isaachinman/next-i18next/tree/master/docs/v8-migration.md)
233
+
208
234
## Notes
235
+
209
236
For Docker deployment, note that if you use the `Dockerfile` from [Next.js docs](https://nextjs.org/docs/deployment#docker-image) do not forget to copy `next.config.js` and `next-i18next.config.js` into the Docker image.
Please read the [full documentation](https://github.com/isaachinman/next-i18next/blob/master/README.md), before migrating from previous versions to v8.
4
+
5
+
This is a guide which will cover most use cases to migrate from v7 to v8.
6
+
We advise migrating as soon as possible, as new versions of NextJs won't be compatible with the v7 of this package `next-i18next`.
7
+
8
+
## What is new?
9
+
10
+
This package, `next-i18next`, has changed a lot because it now is _not_ providing internationalised routing anymore, as [NextJs has first class support for it.](https://nextjs.org/docs/advanced-features/i18n-routing)
11
+
12
+
Before the translation functionality was initialised on a global level, in `_app.js`. Now, you must use a new method, called `serverSideTranslations` on *each* page in your `pages` directory.
13
+
14
+
The object `i18n` which was imported directly from `i18n.js` in `next-i18next@<8` suppored only client-side-rendering. Now in the v8 the `i18n` object also supports server-side rendering. So you can use the `i18n.language` for server-side rendered elements.
15
+
16
+
## What is the same?
17
+
18
+
1.`appWithTranslation` still wraps the App in `_app.js`
19
+
2.`withTranslation` works the same way
20
+
3.`useTranslation` works the same way
21
+
4. The [translation content structure](https://github.com/isaachinman/next-i18next/blob/master/README.md#2-translation-content) remains the same
22
+
23
+
24
+
## What is different?
25
+
26
+
1.`getInitialProps` is not supported anymore, using `serverSideTranslations` is mandatory for all pages.
27
+
If you require `getInitialProps` keep using the last `7.x` version.
28
+
29
+
## Step By Step Migration Guide
30
+
31
+
1. Remove `i18n.js` and add `next-i18next.config.js` as described in [the docs](https://github.com/isaachinman/next-i18next#3-project-setup) to your `next.config.js` file
32
+
2. Replace `import { appWithTranslation } from 'i18n'` with `import { appWithTranslation } from 'next-i18next'`
33
+
3. Replace all instances of `import { withTranslation } from 'i18n` to `import { withTranslation } from 'next-i18next'`
34
+
4. Replace all instances of `import { useTranslation } from 'i18n` to `import { useTranslation } from 'next-i18next'`
35
+
5. Add to `getServerSideProps` or `getStaticProps` in the return as props`...(await serverSideTranslations(locale, [<YOUR_NAMESPACES>]))` in every single page where you have translations. Note that if you have a component in `_app` that needs translations, you will have to do this for _all_ pages. Follow [the docs.](https://github.com/isaachinman/next-i18next#serversidetranslations)
36
+
6. Remove `namespacesRequired: ['common'],` in `_app.js` (not used anymore)
37
+
7. To change language imperatively, you can now do: `router.push(router.asPath, undefined, { locale: <YOUR_LOCALE>, });`
38
+
39
+
## Optional
40
+
41
+
1. Add to the custom 404 page the `...(await serverSideTranslations(locale, [<YOUR_NAMESPACES>])),` as a return in props in `getStaticProps` so the 404 page works with translations as well
42
+
2. Add to the custom 500 page the `...(await serverSideTranslations(locale, [<YOUR_NAMESPACES>])),` as a return in props in `getStaticProps` so the 500 page works with translations as well
43
+
3. Add set cookie `NEXT_LOCALE` for language recognition. More about that in [the NextJs docs](https://nextjs.org/docs/advanced-features/i18n-routing#leveraging-the-next_locale-cookie)
44
+
4. Adjust the Jest test settings to mock `withTranslation`,`useTranslation`, and `t()` or/and `i18n` in props.
45
+
46
+
More info in the [full documentation](https://github.com/isaachinman/next-i18next/blob/master/README.md), or in the [next.js documentation.](https://nextjs.org/docs/advanced-features/i18n-routing)
0 commit comments