{"body":[{"published":true,"publishedOn":"2020-06-15","lastModifiedOn":"","title":"i18n with Next.js and full SSG support","author":"BiscuiTech","excerpt":"Having a React app with localization in multiple languages is really, really hard. But is there a better way?","coverImage":{"coverUrl":"https://images.unsplash.com/photo-1508633069371-a735f885a1c7?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=600&q=80","url":"https://images.unsplash.com/photo-1508633069371-a735f885a1c7?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=600&q=80","accreditation":"Matthew Brodeur"},"canonicalLinks":["https://dev.to/biscuitech/i18n-with-next-js-and-full-ssg-support-2aih"],"source":"## The Issue\n\nIf you tried to look around for _simple_ i18n integrations of `next.js`, you'd soon realized that it just doesn't exist. The reference in the next.js example directory managed by Vercel (formely known as Zeit) points to an integration using a _custom server_. Although it's a nice display of next's different capabilities, we want to statically generate the html on the server - Server Side Generation. Using a custom server makes all serverless and static optimizations impossible.\n\nSo let's dive in using Next.js 9.3 Server-Side Generation (SSG) and 100% serverless.\nYou can also jump straight into code by heading into [this repo.](https://github.com/BiscuiTech/i18n-typescript-app)\n\n## The Setup\n\nFirst, create a folder to work with, then initialize your app with next's create app.\n\n```shell\nnpm init next-app --example with-typescript with-typescript-app\n```\n\nWe're using TypeScript in this example because it's a nicer approach when working with the `Locale` type. More on that soon.\n\n`cd` in the newly created folder and run `npm run dev`. You should have an app looking like this:\n\n\n\nNow that we have a barebones app up and running, let's dig into the meat of the subject. And for good mesure, move your files inside your src folder.\n\n### Translations Types & Config\n\nCreate a folder in /src called translations. In it, create a types.ts file.\n\n```typescript\n// ./src/translations/types.ts\nimport { locales } from \"./config\";\n\nexport type Locale = typeof locales[number];\n\nexport interface Translations {\n [key: string]: string;\n}\n\nexport type Strings = {\n [key in Locale]: Translations;\n};\n\nexport type Localization = {\n locale: Locale;\n translations: Translations;\n namespace: string;\n};\n\nexport function isLocale(tested: string): tested is Locale {\n return locales.some((locale) => locale === tested);\n}\n```\n\nThen, create a config.ts.\n\n```typescript\n// ./src/translations/config.ts\nexport const defaultLocale = \"en\" as const;\n\nexport const locales = [\"en\", \"fr\"] as const;\n\nexport const languageNames = {\n en: \"English\",\n fr: \"Français\",\n};\n```\n\nThose files are self explanatory, but quickly it goes like this:\n\n- config.ts serves as the constants used throughout the Context.\n- The types will help us populate the Context and the localizations instances correctly.\n\nLet's add those types to the global compiler:\n\n```typescript\n// ./next-env.d.ts\n/// \n/// \n/// \n```\n\nNext add a getInitialLocale.ts\n\n```typescript\n// ./src/translations/getInitialLocale.ts\nimport { defaultLocale } from \"./config\";\nimport { Locale, isLocale } from \"./types\";\n\nexport function getInitialLocale(): Locale {\n const localSetting = localStorage.getItem(\"locale\");\n if (localSetting && isLocale(localSetting)) {\n return localSetting;\n }\n\n const [browserSetting] = navigator.language.split(\"-\");\n if (isLocale(browserSetting)) {\n return browserSetting;\n }\n\n return defaultLocale;\n}\n```\n\nFinally, add your localized strings here:\n\n```typescript\n// ./src/translations/locales/index.ts\nimport en from \"./en\";\nimport fr from \"./fr\";\n\nexport default {\n fr,\n en,\n};\n\n//./src/translations/locales/en/index.ts\nimport common from \"./common\";\nimport home from \"./home\";\n\nexport default {\n common,\n home,\n};\n\n// ./src/translations/locales/en/home.ts\nconst home = {\n hello: \"Hello Next.js 👋\",\n};\n\nexport default home;\n\n// ./src/translations/locales/en/common.ts\nconst common = {\n navHome: \"Home\",\n navAbout: \"About\",\n navUsersList: \"Users List\",\n navUsersAPI: \"Users API\",\n};\n\nexport default common;\n```\n\nBefore proceeding, add those files in another language while keeping the same structure. If you're looking for a quick copy-paste, take these.\n\n### The Context\n\nNext up, we need to create a react context. This will server as the focal point of all the text strings the app will load on each page.\n\nInside your /src folder, create a context folder and a LanguageContext.tsx file.\n\n```tsx\n// ./src/context/LanguageContext.tsx\nimport React from \"react\";\nimport { useRouter } from \"next/router\";\nimport { useLocalStorage } from \"../hooks/useLocalStorage\";\nimport { isLocale, Localization, Locale } from \"../translations/types\";\nimport defaultStrings from \"../translations/locales/en\";\nimport locales from \"../translations/locales\";\n\n/**\n * Language Context\n */\n\ninterface ContextProps {\n readonly localization: Localization;\n readonly setLocale: (localization: Localization) => void;\n}\n\nexport const LanguageContext = React.createContext({\n localization: {\n locale: \"en\", // default lang\n translations: defaultStrings.common, // default translations TODO: what to do here?\n namespace: \"common\", // default namespace TODO: could we null this? 'common' might be misleading\n },\n setLocale: () => null,\n});\n\n/**\n * Language Context: Provider\n */\n\nexport const LanguageProvider: React.FC<{ localization: Localization }> = ({\n localization,\n children,\n}) => {\n const [localizationState, setLocalizationState] = React.useState({\n locale: localization?.locale,\n translations: localization?.translations,\n namespace: localization?.namespace,\n });\n const [getStoredLocale, setStoredLocale] = useLocalStorage(\"locale\");\n const { query } = useRouter();\n React.useEffect(() => {\n if (localizationState.locale !== getStoredLocale) {\n setStoredLocale(localizationState.locale);\n }\n }, [localizationState]);\n\n React.useEffect(() => {\n if (\n typeof query.lang === \"string\" &&\n isLocale(query.lang) &&\n localization?.locale !== query.lang\n ) {\n setLocalizationState({\n locale: localization?.locale,\n translations: localization?.translations,\n namespace: localization?.namespace,\n });\n }\n }, [query.lang, localizationState]);\n\n return (\n \n {children}\n \n );\n};\n\nexport const getLocalizationProps = (ctx, namespace) => {\n const lang: Locale = (ctx.params?.lang as Locale) || \"fr\";\n const locale: any = locales[lang];\n const strings: any = locale[namespace];\n const translations = {\n common: locales[lang].common,\n ...strings,\n };\n return {\n locale: ctx.params?.lang || \"en\",\n translations,\n namespace,\n };\n};\n```\n\n

\n Some of this will feel hard to understand at first, but let's keep going and\n you'll grasp everything eventually. I promise!\n

\n\nAlright, this is a big file. Let's break it down.\nThe context will hold an object called `localization` with the keys `locale`, `translations`and `namespace`.\n\n- `locale` is the active language of the site. As a default, we're using 'en' for english.\n\n- `translations` will hold all the text strings. As a default we're using the _common_ strings. Those will make sense later.\n\n- `namespace` will serve as the key to dynamically fetch text strings. As a default, we're using `common`.\n\n```tsx\nexport const LanguageProvider: React.FC<{ localization: Localiztion }> = ({\n localization,\n children,\n}) => {\n return (\n \n {children}\n \n );\n};\n```\n\nThis is the declaration and rendering portion. `React.FC` is the react's Type for Functional Component, to which we add `localization` as a type, previously created in our types.ts file. Next, let's add `useState`.\n\n```tsx\nexport const LanguageProvider: React.FC<{ localization: Localiztion }> = ({\n localization,\n children,\n}) => {\n const [localizationState, setLocalizationState] = React.useState({\n locale: localization?.locale,\n translations: localization?.translations,\n namespace: localization?.namespace,\n });\n return (\n \n {children}\n \n );\n};\n```\n\nHere we add the state to the context. We will play with this state throughout the app!\n\n```tsx\n// ./src/context/LanguageContext.tsx\nexport const LanguageProvider: React.FC<{ localization: Localization }> = ({\n localization,\n children,\n}) => {\n const [localizationState, setLocalizationState] = React.useState({\n locale: localization?.locale,\n translations: localization?.translations,\n namespace: localization?.namespace,\n });\n const [getStoredLocale, setStoredLocale] = useLocalStorage(\"locale\");\n const { query } = useRouter();\n React.useEffect(() => {\n if (localizationState.locale !== getStoredLocale) {\n setStoredLocale(localizationState.locale);\n }\n }, [localizationState]);\n\n React.useEffect(() => {\n if (\n typeof query.lang === \"string\" &&\n isLocale(query.lang) &&\n localization?.locale !== query.lang\n ) {\n setLocalizationState({\n locale: localization?.locale,\n translations: localization?.translations,\n namespace: localization?.namespace,\n });\n }\n }, [query.lang, localizationState]);\n\n return (\n \n {children}\n \n );\n};\n```\n\nAnd finally, we set and get a LocalStorage key of \"locale\". This will mainly serve as a lower level mechanism to know which locale the user is in. By setting a LocaleStorage, we can also write it to memory for future visits by our users.\n\nYou'll also note there's two useEffects. The first one syncs our LocaleStorage from our state each time the state mutates. The second one writes to state the localized strings and mutates every time it changes. It also checks for errors by making sure the query from `router` is in fact a supported language. Note: if it's not a supported language, it'll simply revert to `en`.\n\nBefore moving on, move all your pages that are not in /api in a new folder called [lang]. Next.js will then take the lang query prop and pass it along. Afterwards, create a new index.ts at the root of the pages folder.\n\n```tsx\nimport React from \"react\";\nimport Head from \"next/head\";\nimport { getInitialLocale } from \"../translations/getInitialLocale\";\n\nconst Index: React.FC = () => {\n React.useEffect(() => {\n window.location.replace(`/${getInitialLocale()}`);\n });\n\n return (\n \n \n \n );\n};\n\nexport default Index;\n```\n\n### The Hooks\n\nLast bit of setup is to add some hooks.\n\n```typescript\n// ..src/hooks/useLocalStorage.ts\nimport { useState } from \"react\";\n\nexport function useLocalStorage(key: string, initialValue: any = \"\") {\n // State to store our value\n // Pass initial state function to useState so logic is only executed once\n const [storedValue, setStoredValue] = useState(() => {\n try {\n // Get from local storage by key\n const item = window.localStorage.getItem(key);\n // Parse stored json or if none return initialValue\n return item ? JSON.parse(item) : initialValue;\n } catch (error) {\n // If error also return initialValue\n return initialValue;\n }\n });\n\n // Return a wrapped version of useState's setter function that ...\n // ... persists the new value to localStorage.\n const setValue = (value) => {\n try {\n // Allow value to be a function so we have same API as useState\n const valueToStore =\n value instanceof Function ? value(storedValue) : value;\n // Save state\n setStoredValue(valueToStore);\n // Save to local storage\n window.localStorage.setItem(key, JSON.stringify(valueToStore));\n } catch (error) {\n // A more advanced implementation would handle the error case\n console.log(error);\n }\n };\n\n return [storedValue, setValue];\n}\n```\n\nThis hook is simply to sync a key-value pair into local storage. It returns a setter (setValue) and getter (storedValue) function - much like any hook.\n\n```typescript\n// ..src/hooks/useTranslation.ts\nimport { useContext } from \"react\";\nimport { LanguageContext } from \"../context/LanguageContext\";\n\nexport default function useTranslation() {\n const { localization } = useContext(LanguageContext);\n function t(key: string) {\n if (!localization.translations[key]) {\n console.warn(\n `Translation '${key}' for locale '${localization.locale}' not found.`\n );\n }\n return localization.translations[key] || \"\";\n }\n\n return {\n t,\n locale: localization.locale,\n };\n}\n```\n\nThis one is the hook that will be used all throughout the application. It uses the context holding all the strings and returns them to be used. It also supports the namespace functinality.\n\n## getStaticPaths & getStaticProps\n\nSo, now we have all this setup, how in the hell do we get localized strings?!\n\nWell I'm glad you asked! We load it simply by calling a sort of API. And in Next.js, how do we call an API? On a per-page basis in `getStaticProps`!\n\n```tsx {4-9,14,23,26-33,35-42}\n// ./src/pages/index.tsx\nimport Link from \"next/link\";\nimport Layout from \"../../components/Layout\";\nimport { GetStaticPaths, GetStaticProps, NextPage } from \"next\";\nimport {\n getLocalizationProps,\n LanguageProvider,\n} from \"../../context/LanguageContext\";\nimport { Localization } from \"../../translations/types\";\n\nconst IndexPage: NextPage<{\n localization: Localization;\n}> = ({ localization }) => (\n \n \n

Hello Next.js 👋

\n \n About\n \n

\n \n \n);\n\nexport const getStaticProps: GetStaticProps = async (ctx) => {\n const localization = getLocalizationProps(ctx, \"home\");\n return {\n props: {\n localization,\n },\n };\n};\n\nexport const getStaticPaths: GetStaticPaths = async () => {\n return {\n paths: [\"en\", \"fr\"].map((lang) => ({ params: { lang } })),\n fallback: false,\n };\n};\n\nexport default IndexPage;\n```\n\nEasy as 1,2,3! As a side note, you also need to tell next.js to build all the pages of your locales. You can do that in getStaticPaths. You can read more on getStaticPaths here: [nextjs.org/docs](https://nextjs.org/docs/basic-features/data-fetching#getstaticpaths-static-generation)\n\nI highly suggest you inspect the repo of my website [here](https://github.com/BiscuiTech/BiscuiT). You'll get a better grip of how all the files work together.\n\nGetting back to our pages/index.ts, you'll notice we also modified the page function. We added the Provider and passed the translations objet down. This is the last setup needed. The following steps are simply how to call the hook to fetch the strings.\n\nSimple, isn't it? With this method, the only code actually modifying your app (besides the setup itself) is the page file.\n\n## useTranslate\n\nNow that we have the props ready to go, we simply need to use them inside our components. We're going to use the hook that fetches the translations props and make them available to us. If you understand how Context works, this is a piece of cake. Note that we need to move our rendering to a components because direct children cannot access the Context.\n\n```tsx {8,20,23}\n// ./src/pages/[lang]/index.tsx\nconst IndexPage: NextPage<{\n localization: Localization;\n}> = ({ localization }) => {\n return (\n \n \n \n \n \n );\n};\n\n// ./src/components/Home.tsx\nimport React from \"react\";\nimport useTranslation from \"../hooks/useTranslation\";\nimport Link from \"next/link\";\n\nconst Home = () => {\n const { t, locale } = useTranslation();\n return (\n <>\n

{t(\"header\")}

\n \n About\n \n

\n \n );\n};\n\nexport default Home;\n```\n\n## LocaleSwitcher\n\nEverything works and the correct strings render, but switching locale by manually punching the letters in url is tedious at best. We need to create a locale swticher component. It's really easy. Let's do it!\n\n```tsx\nimport React from \"react\";\nimport { useRouter } from \"next/router\";\nimport { locales } from \"../translations/config\";\nimport useTranslation from \"../hooks/useTranslation\";\n\nconst LocaleSwitcher: React.FC = () => {\n const router = useRouter();\n const handleLocaleChange = React.useCallback(\n (e: React.ChangeEvent) => {\n const targetLang = e.target.value;\n const regex = new RegExp(`^/(${locales.join(\"|\")})`);\n router.push(\n router.pathname,\n router.asPath.replace(regex, `/${targetLang}`)\n );\n },\n [router]\n );\n const { t, locale } = useTranslation();\n return (\n

\n \n {t(\"common\")[\"localeSwitcher\"]}\n \n \n

\n );\n};\n\nexport default LocaleSwitcher;\n```\n\nLet's also add the new string we used here to ours files in `translations/locales/[lang]/common.ts`\n\n```typescript {7}\n// ./src/translations/locales/en/common.ts\nconst common = {\n navHome: \"Home\",\n navAbout: \"About\",\n navUsersList: \"Users List\",\n navUsersAPI: \"Users API\",\n localeSwitcher: \"Language\",\n};\n\nexport default common;\n```\n\nAnd now we're finally done - for real! Feel free to add strings in your locales directory and replace the rest of the text in the app.\n\n> Special thanks to [Filip Wojciechowski](https://twitter.com/filipcodes) who initially came up with this idea without the static generations and namespace functionalities. You can find his blog [here](https://w11i.me/how-to-build-multilingual-website-in-next-js).\n\n## Looking forward\n\nOne caveat of this method is that your useTranslate hook needs to be called inside a component and not inside the page directly. You could simply move the ContextProvider up the chain and into your \\_app if you so desire.\n\nThere are talks of a native **next.js** i18n implementation, so the future of localized apps is looking bright! In the meantime, take a look at this PR: https://github.com/vercel/next.js/pull/14454\n","readingTime":"12 min read","slug":"i18n-ssg-nextjs-app"}]}

Articles

Tag along my adventure through JavaScript and the Web.

i18n with Next.js and full SSG support