next-translations

Thanks to this package you will be able to add to your website written in NextJS to download/manage translations on your website! Thanks to this package you will be able to build a very efficient website that will have generated pages WITH nested translations!. Powerful package also for STATIC and SERVER SIDE RENDERING sites in NextJS! Works without i18n!

install translations

1npm i next-translations

translations.config.js - you need to add this config file to your project

Parameter	Type	Default	Description
defaultLocale	string	'en'	Required. The default language on your site
locales	string[]	['en']	Required. All available languages on your website.
sitesForLoggedUser	string[]	[]	All paths available ONLY for the active session
sitedForLoggedAndNotLoggedUser	string[]	[]	All paths available for the all sessions
redirectForLoggedUser	string	'/'	Redirects the user when on a route for non-logged in users
redirectForNotLoggedUser	string	'/'	Redirects the user when in the route for logged in users
errorPagePath	string	'/404'	Showing if we have a custom link to the error page so that unnecessary redirects are not made
outputFolderTranslations	string	'/public/locales'	The path to your translations. NOTE: If you download translations using next-translations, they will be saved to the given address. For the site to work properly, they must be in the /public folder.
defaultLocaleWithMultirouting	boolean	undefined	The language to be excluded from multi routing. For example, we want /index.js to have the language from defaultLocale prop, then it should be substituted into this variable. Other languages (if any) will be available in /pages/[locale]
constNamespaces	string[]	['common']	These are all the namespaces we use throughout the project so as not to define them on every page.
componentNameToReplaced	string	'TComponent'	The name of the component in translations that will be captured and replaced in tComponent.
namespacesToFetch	string[]	['common']	All the namespaces you want to fetch during link Fetch Translations
linkFetchTranslations	(version: string, language: string, namespace: string) => string	undefined	A function to download our translations from the api. It is called every time it wants to load a given translation in a given language and namespace. The function returns single values that we entered in the fields: locales, namespaces. To return, we need to return a link to our api, e.g. return https://your-api-to-download-translations/${version}/${language}/${namespace} Note: if you add NEXT_PUBLIC_NEXT_TRANSLATIONS_APP_ENV to your .env file then you can access the version of the page, e.g.: dev, int, prd etc..

configuration

Attention! To avoid a translation error when building a page, add getTranslationsProps to each page! If you don't have these pages, you may get messages about no translation!

• /404
• /500
• /offline

example translations in /public/locales/en/common.json

1{
2  "section":{
3    "title": "Example title in your site!"
4  }
5}

/pages/_app.tsx for STATIC SITES and SERVER SIDE RENDERING

1import { initializeTranslations } from "next-translations/hooks";
2import { InitializeRedirectsTranslations, validLink } from "next-translations/redirects";
3import type { AppProps } from "next/app";
4import { useEffect } from "react";
5import { useRouter } from "next/router";
6
7export default function App({ Component, pageProps }: AppProps) {
8
9  // add this line
10  initializeTranslations(pageProps?.translations);
11
12  // add this lint if you want to use redirects: sitesForLoggedUser.
13  // You can add this in user context for example.
14  InitializeRedirectsTranslations({
15    isLoggedUser: true, // true or false for STATIC PAGES. Attention! if isLoggedUser is undefined then no redirects are performed!
16    isLoggedUser: pageProps?.isLoggedUser || false, // for SERVER SIDE RENDERING pages. Attention! if isLoggedUser is undefined then no redirects are performed!
17    enable: true, // default is true. Checks if routing can be done on the page. If it's false, it doesn't do routing.
18    withQuery: true, // default is true. Listens for query during redirects
19    withHash: true, // default is true. Listens for hash during redirects
20  });
21
22  //example
23  InitializeRedirectsTranslations({
24    isLoggedUser: !!user,
25    enable: user !== undefined,
26    withQuery: true,
27    withHash: false,
28  });
29
30  //checking routes and return valid route
31  useEffect(() => {
32    if (!router.isReady) {
33      return;
34    }
35
36    let queryValue = "";
37    if (window.location.search.length > 0) {
38      const splitQuery = window.location.search.split("?");
39      const getQueryValue = splitQuery.at(1);
40      if (getQueryValue) {
41        queryValue = getQueryValue;
42      }
43    }
44
45    let hashValue = "";
46    if (window.location.hash.length > 0) {
47      const splitHash = window.location.hash.split("#");
48      const getHashValue = splitHash.at(1);
49      if (getHashValue) {
50        hashValue = getHashValue;
51      }
52    }
53
54    // works in the same way as page redirects. If the user does not have access to a given subpage, he will return a link to the subpage to which he has based on the config
55    const result = validLink({
56      isLoggedUser: false, // checking if the user is logged in
57      locale: "en", // the locale we want to change to. If is undefined, the locale is selected based on the currently used one
58      path: "/user", // path where we want to generate the link. If is undefined, the locale is selected based on the currently used one
59      router: router, // need to add router from nextjs
60      query: queryValue, // query to your link.
61      hash: hashValue, // hash to your link
62    });
63  }, [router, user]);
64
65  return (
66    <main>
67        <Component {...pageProps} />
68    </main>
69  );
70}

/pages/yourPath.tsx - for STATIC SITES

Note: if you don't have defaultLocaleWithMultirouting defined, then you MUST keep content in /pages/[locale]/yourPath.tsx, otherwise you will only have the language that was set as defaultLocale!

1import { getTranslationsProps } from "next-translations";
2import { useTranslation } from "next-translations/hooks";
3import { GetStaticProps } from "next";
4
5function Home() {
6  const { t, pageTranslations } = useTranslation("common"); // enter the given namespace that you use in the given section
7  const { t, pageTranslations } = useTranslation("common:section"); // if you want you can also refer to namespace, along with nested elements - 1 example
8  const { t, pageTranslations } = useTranslation("common.section"); // if you want you can also refer to namespace, along with nested elements - 2 example
9
10  // t -> thanks to this function, you can download a given text/object/array at your discretion - just like you have downloaded/added in translations
11
12  // pageTranslations -> all translations that are available on this subpage
13
14  return (
15    <div>
16      t("section.title") // downloading translation - without nested elements
17      t("title") // downloading translation - if you using nested elements
18    </div>
19  );
20}
21
22export const getStaticProps: GetStaticProps = async ctx => {
23  const translationsProps = await getTranslationsProps(ctx, ["common"]); // add here all translations in string[] that you use on this subpage
24
25  // you have access to:
26  // ctx.locale - current locale
27  // ctx.locales - all locales
28  // ctx.defaultLocale - default locale
29
30  return {
31    props: {
32      ...translationsProps,
33    },
34  };
35}
36
37export default Home;
38

/pages/yourPath.tsx - for SERVER SIDE RENDERING

Note: if you don't have defaultLocaleWithMultirouting defined, then you MUST keep content in /pages/[locale]/yourPath.tsx, otherwise you will only have the language that was set as defaultLocale!

1import { getTranslationsPropsServer } from "next-translations/server";
2import { useTranslation } from "next-translations/hooks";
3import { GetServerSideProps } from "next";
4
5function Home() {
6  const { t, pageTranslations } = useTranslation("common"); // enter the given namespace that you use in the given section
7  const { t, pageTranslations } = useTranslation("common:section"); // if you want you can also refer to namespace, along with nested elements - 1 example
8  const { t, pageTranslations } = useTranslation("common.section"); // if you want you can also refer to namespace, along with nested elements - 2 example
9
10  // t -> thanks to this function, you can download a given text/object/array at your discretion - just like you have downloaded/added in translations
11
12  // pageTranslations -> all translations that are available on this subpage
13
14  return (
15    <div>
16      t("section.title") // downloading translation - without nested elements
17      t("title") // downloading translation - if you using nested elements
18    </div>
19  );
20}
21
22
23export const getServerSideProps: GetServerSideProps = async ctx => {
24  let translatesProps = null;
25  const translationsNamespaces = [namespaces.account];
26
27  if (process.env.NODE_ENV === "development") {
28    translatesProps = await getTranslationsProps(ctx, translationsNamespaces);  // add here all translations in string[] that you use on this subpage
29  } else {
30    translatesProps = await getTranslationsPropsServer(  // add here all translations in string[] that you use on this subpage
31      ctx,
32      translationsNamespaces,
33    );
34  }
35
36  // you have access to:
37  // ctx.locale - current locale
38  // ctx.locales - all locales
39  // ctx.defaultLocale - default locale
40
41  return {
42    props: {
43      ...translatesProps,
44      isLoggedUser: true, // or false, add this prop if you want to use redirects: sitesForLoggedUser
45    },
46  };
47};
48
49export default Home;
50

/pages/[locale]/yourPath.tsx - for STATIC SITES

1import { getTranslationsProps, getStaticPaths, getPaths } from "next-translations"; // add getStaticPaths only if you using: export { getStaticPaths }, if you using getStaticPaths from next - dont add this import!
2import { useTranslation } from "next-translations/hooks";
3import { GetStaticProps, GetStaticPaths } from "next";
4
5function Home() {
6  const { t, pageTranslations } = useTranslation("common"); // enter the given namespace that you use in the given section
7  const { t, pageTranslations } = useTranslation("common:section"); // if you want you can also refer to namespace, along with nested elements - 1 example
8  const { t, pageTranslations } = useTranslation("common.section"); // if you want you can also refer to namespace, along with nested elements - 2 example
9
10  // t -> thanks to this function, you can download a given text/object/array at your discretion - just like you have downloaded/added in translations
11
12  // pageTranslations -> all translations that are available on this subpage
13
14  return (
15    <div>
16      t("section.title") // downloading translation - without nested elements
17      t("title") // downloading translation - if you using nested elements
18    </div>
19  );
20}
21
22export const getStaticProps: GetStaticProps = async ctx => {
23  const translationsProps = await getTranslationsProps(ctx, ["common"]); // add here all translations in string[] that you use on this subpage
24
25  // you have access to:
26  // ctx.locale - current locale
27  // ctx.locales - all locales
28  // ctx.defaultLocale - default locale
29
30  return {
31    props: {
32      ...translationsProps,
33    },
34  };
35}
36
37
38export { getStaticPaths }; // IMPORTANT ADD THIS LINE TO ENABLE MULTI ROUTING
39
40
41//ALTERNATIVE with Nextjs getStaticPaths - if you using this, don't impoty getStaticPaths from next-translations
42
43export const getStaticPaths: GetStaticPaths = async () => { // IMPORTANT ADD THIS LINE TO ENABLE MULTI ROUTING (alternative)
44  return {
45    fallback: false,
46    paths: getPaths(),
47  };
48}
49
50export default Home;
51

/pages/[locale]/yourPath.tsx - for SERVER SIDE RENDERING

Attention! You manage the site's languages via slug! eg: /en/home - page with en language, /pl/home - page with pl language

1import { getTranslationsPropsServer } from "next-translations/server";
2import { useTranslation } from "next-translations/hooks";
3import { GetServerSideProps } from "next";
4
5function Home() {
6  const { t, pageTranslations } = useTranslation("common"); // enter the given namespace that you use in the given section
7  const { t, pageTranslations } = useTranslation("common", true); // translations without log errors
8  const { t, pageTranslations } = useTranslation("common:section"); // if you want you can also refer to namespace, along with nested elements - 1 example
9  const { t, pageTranslations } = useTranslation("common.section"); // if you want you can also refer to namespace, along with nested elements - 2 example
10
11  // t -> thanks to this function, you can download a given text/object/array at your discretion - just like you have downloaded/added in translations
12
13  // pageTranslations -> all translations that are available on this subpage
14
15  return (
16    <div>
17      t("section.title") // downloading translation - without nested elements
18      t("title") // downloading translation - if you using nested elements
19    </div>
20  );
21}
22
23export const getServerSideProps: GetServerSideProps = async ctx => {
24  let translatesProps = null;
25  const translationsNamespaces = [namespaces.account];
26
27  if (process.env.NODE_ENV === "development") {
28    translatesProps = await getTranslationsProps(ctx, translationsNamespaces); // add here all translations in string[] that you use on this subpage
29  } else {
30    translatesProps = await getTranslationsPropsServer( // add here all translations in string[] that you use on this subpage
31      ctx,
32      translationsNamespaces,
33    );
34  }
35
36  // you have access to:
37  // ctx.locale - current locale
38  // ctx.locales - all locales
39  // ctx.defaultLocale - default locale
40
41  return {
42    props: {
43      ...translatesProps,
44      isLoggedUser: true, // or false, add this prop if you want to use redirects: sitesForLoggedUser
45    },
46  };
47};
48
49export default Home;
50

useTranslation - all functions

1const { t, tString, tNumber, tArray, tObject, tComponent, pageTranslations } = useTranslation("common"); // enter the given namespace that you use in the given section
2const { t, pageTranslations } = useTranslation("common:section"); // if you want you can also refer to namespace, along with nested elements - 1 example
3const { t, pageTranslations } = useTranslation("common.section"); // if you want you can also refer to namespace, along with nested elements - 2 example
4
5pageTranslations // all translations that are available on this subpage
6
7t("section.text1"); // if there is a translation, it returns it as any, if not, it returns undefined
8
9tString("section.text2"); // if there is a translation and it has a string type, it returns it as string, if it doesn't find it, or it has the wrong type, it returns undefined.
10
11tNumber("section.text3"); // if there is a translation and it has a number type, it returns it as number, if it doesn't find it, or it has the wrong type, it returns undefined.
12
13tArray("section.text4"); // if there is a translation and it has a any[] type, it returns it as any[], if it doesn't find it, or it has the wrong type, it returns undefined.
14
15tObject("section.text5"); // if there is a translation and it has a object type, it returns it as object, if it doesn't find it, or it has the wrong type, it returns undefined.
16
17
18//if there is a translation and it has type string, if it doesn't find it or it has wrong type it returns undefined. If it contains <TComponent> value </TComponent> or <TComponent/>, you can create your own component based on the values returned from the callback. **Note** the text inside <TComponent> must be separated by a space between <TComponent> and </TComponent>!!!!! Example of correct implementation:
19{
20  "title": "example paragraph <TComponent> xxxx sad </TComponent> paragraph"
21}
22tComponent(
23  "section.textLink",
24  ({ textBefore, textComponent, textAfter, text }) => { // value from callback to create your own component. text is returned when it doesn't find a TComponent inside the text
25    return (
26      <div>
27        <p>{textBefore}</p>
28        <Link href="/">{textComponent}</Link>
29        <p>{textAfter}</p>
30      </div>
31    );
32  },
33);
34

Avaible types

1// import type {T_t, T_tString, T_tNumber, T_tArray, T_tObject, T_tComponent} from "next-translations/hooks"
2
3- T_t
4- T_tString
5- T_tNumber
6- T_tArray
7- T_tObject
8- T_tComponent

package.json

1"scripts": {
2    "getTranslations": "node node_modules/next-translations/getTranslations", // script to fetch all translations from your api **linkFetchTranslations**
3    "dev": "npm run getTranslations && next dev",
4    "build": "npm run getTranslations && next build",
5}