{"_id":"@charamza/next-translate","name":"@charamza/next-translate","dist-tags":{"latest":"1.4.0"},"versions":{"1.4.0":{"name":"@charamza/next-translate","version":"1.4.0","description":"Tiny and powerful i18n tools (Next plugin + API) to translate your Next.js pages.","license":"MIT","keywords":["react","preact","i18n","nextjs","next.js","next","plugin","translate","translation","internationalization","locale","locales","globalization"],"repository":{"type":"git","url":"https://github.com/vinissimus/next-translate.git"},"author":{"name":"Aral Roca Gòmez","email":"contact@aralroca.com"},"main":"./lib/cjs/index.js","module":"./lib/esm/index.js","types":"./index.d.ts","scripts":{"build":"yarn clean && cross-env NODE_ENV=production && yarn tsc","clean":"yarn clean:build && yarn clean:examples","clean:build":"rm -rf lib plugin appWith* Dynamic* I18n* index _context loadNa* setLang* Trans* useT* withT* getP* getC* *.d.ts getT transC* wrapT* types formatElements","clean:examples":"rm -rf examples/**/.next && rm -rf examples/**/node_modules && rm -rf examples/**/yarn.lock","example":"yarn example:complex","example:basic":"yarn build && cd examples/basic && yarn && yarn dev","example:complex":"yarn build && cd examples/complex && yarn && yarn dev","example:without-loader":"yarn build && cd examples/without-loader && yarn && yarn dev","format":"pretty-quick","husky":"pretty-quick --staged && yarn test","prepare":"husky install","prepublish":"yarn test && yarn build","test":"cross-env NODE_ENV=test jest --env=jsdom","test:coverage":"cross-env NODE_ENV=test jest --env=jsdom --coverage","test:watch":"cross-env NODE_ENV=test jest --env=jsdom --watch","tsc":"tsc -p tsconfig.json && tsc -p tsconfig-cjs.json && node build-packages.js"},"devDependencies":{"@babel/cli":"7.16.0","@babel/core":"7.16.0","@babel/preset-env":"7.16.4","@babel/preset-typescript":"7.16.0","@testing-library/react":"12.1.2","@types/node":"16.11.7","@types/react":"17.0.35","@types/react-dom":"17.0.11","@types/webpack":"5.28.0","babel-jest":"27.3.1","babel-plugin-transform-es2015-modules-commonjs":"6.26.2","babel-preset-minify":"0.5.1","cross-env":"7.0.3","express":"4.17.1","husky":"7.0.4","jest":"27.3.1","next":"12.0.4","prettier":"2.4.1","pretty-quick":"3.1.2","react":"17.0.2","react-dom":"17.0.2","supertest":"6.1.6","typescript":"4.5.2"},"peerDependencies":{"next":">= 10.0.0","react":">= 16.8.0"},"prettier":{"trailingComma":"es5","tabWidth":2,"semi":false,"singleQuote":true},"jest":{"roots":["/__tests__","/src"],"testPathIgnorePatterns":["/node_modules/",".utils.js"],"transform":{"^.+\\.(j|t)sx?$":"babel-jest"}},"licenseText":"The MIT License\n\nMIT License\n\nCopyright (c) 2021 Aral Roca Gomez\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n","_id":"@charamza/next-translate@1.4.0","dist":{"shasum":"fd76fdeb8a50ab9580338ca556d9d36245fc7bce","integrity":"sha512-IGCaWjX6+N6yrIlBJX19fRxa+7aL2IcpAo276WUcuw6GmxEWbFQ/ES0/+y0KNP3SX3mJqY62zQ8s/y7DhwnI+A==","tarball":"https://registry.npmjs.org/@charamza/next-translate/-/next-translate-1.4.0.tgz","fileCount":294,"unpackedSize":406692,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIFa5FWSIPKHbg5+hzOuO17IG6hNcivN+IQm1aUepk2lQAiEAvksL0/iwTurqeRD5itMfDnQVSs/Zgm/pUB1NfKrIvQA="}],"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v4.10.10\r\nComment: https://openpgpjs.org\r\n\r\nwsFzBAEBCAAGBQJiaFI5ACEJED1NWxICdlZqFiEECWMYAoorWMhJKdjhPU1b\r\nEgJ2VmqIuRAAktycVsrbQcdmd00iDm34NUkgeXop8WmhkneZyvAaubD3mMxX\r\nFXUTNk7GAc1sOOxTcifyuL4RW1z4uKIdXgPQ0GLc2Po8mCehDdcHBREv7Xul\r\nC8BYDnyGztjNfMnMjWCPoyVjMQ5KliUl1lm22UFBGbR9lVteWjGenXRVkG9+\r\nSloEX72Viz4RgwcpW0Ht0FMmNJaNgrQOU/Yz65SHx3sm0Jh05dIce64/Vro6\r\na4WBTx27+S/ERasJAOeT6y/Ekj7jIvr4tsCezH0l/yjKZmjt7KXSPAdSR1jJ\r\nv8n9VRYlZhtx9fUMaCtDNWS33PN0nX7ldvVTykvB7zzb/PgAJ6e3ihVn7R28\r\nbI6C2IoAkOdh3BqlSl7+283QLcmKJFuRZAqi2VBzpbpORefWI4uzX6/+YxDg\r\nMo+0iBFWydTF7LEfrqAeJmvO7pL1DMo0MRO+FFckfc5GXuP00VN1QDyKDGhj\r\nsntzZdoMPh7C6ni9V/Tk3F/TgIXNGR1TwWvVH/UGPTDd3cY5A+8dbrefuPXD\r\nNu4si70ry2ToCuH4MKYQ51ZKGO1sSe4A7jVs8ezNrgTnqH6yW5tsGykjK0kv\r\nFAXKyqEvrLbnX7Tu0/d/yfZaIPMYw9k+xE+8j+EmkCqmA7ppd+SUgFBzXMXr\r\nchn8CScnmaO4U+a7K8kpjkQBCgA14Uva5yE=\r\n=iXeS\r\n-----END PGP SIGNATURE-----\r\n"},"_npmUser":{"name":"charamza","email":"jenda60@gmail.com"},"directories":{},"maintainers":[{"name":"charamza","email":"jenda60@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/next-translate_1.4.0_1651003961453_0.5224691745429983"},"_hasShrinkwrap":false}},"time":{"created":"2022-04-26T20:12:41.398Z","1.4.0":"2022-04-26T20:12:41.655Z","modified":"2022-04-26T20:12:41.842Z"},"maintainers":[{"name":"charamza","email":"jenda60@gmail.com"}],"description":"Tiny and powerful i18n tools (Next plugin + API) to translate your Next.js pages.","keywords":["react","preact","i18n","nextjs","next.js","next","plugin","translate","translation","internationalization","locale","locales","globalization"],"repository":{"type":"git","url":"https://github.com/vinissimus/next-translate.git"},"author":{"name":"Aral Roca Gòmez","email":"contact@aralroca.com"},"license":"MIT","readme":"

\n \"next-translate\"\n

\n\n

\n Easy i18n for Next.js +10\n

\n

\n Next plugin + i18n API\n

\n\n
\n\n[![npm version](https://badge.fury.io/js/next-translate.svg)](https://badge.fury.io/js/next-translate)\n[![PRs Welcome][badge-prwelcome]][prwelcome]\n\n\n\n\"follow\n\n
\n\n- [1. About next-translate](#1-about-next-translate)\n - [How are translations loaded?](#how-are-translations-loaded)\n- [2. Getting started](#2-getting-started)\n - [Install](#install)\n - [Add next-translate plugin](#add-next-translate-plugin)\n - [Add i18n.js config file](#add-i18njs-config-file)\n - [Create your namespaces files](#create-your-namespaces-files)\n - [Use translations in your pages](#use-translations-in-your-pages)\n- [3. Configuration](#3-configuration)\n- [4. API](#4-api)\n - [useTranslation](#usetranslation)\n - [withTranslation](#withtranslation)\n - [Trans Component](#trans-component)\n - [DynamicNamespaces](#dynamicnamespaces)\n - [getT](#gett)\n - [I18nProvider](#i18nprovider)\n - [appWithI18n](#appwithi18n)\n - [loadNamespaces](#loadnamespaces)\n- [5. Plurals](#5-plurals)\n- [6. Use HTML inside the translation](#6-use-html-inside-the-translation)\n- [7. Nested translations](#7-nested-translations)\n- [8. Fallbacks](#8-fallbacks)\n- [9. Formatter](#9-formatter)\n- [10. How to change the language](#10-how-to-change-the-language)\n- [11. How to save the user-defined language](#11-how-to-save-the-user-defined-language)\n- [12. How to use multi-language in a page](#12-how-to-use-multi-language-in-a-page)\n- [13. How to use next-translate in a mono-repo](#13-how-to-use-next-translate-in-a-mono-repo)\n- [14. Demos](#14-demos)\n - [Demo from Next.js](#demo-from-nextjs)\n - [Basic demo](#basic-demo)\n - [Complex demo](#complex-demo)\n - [Without the webpack loader demo](#without-the-webpack-loader-demo)\n- [Contributors ✨](#contributors-)\n\n

\n \"Translations\n

\n\n## 1. About next-translate\n\nThe main goal of this library is to keep the translations as simple as possible in a Next.js environment.\n\nNext-translate has two parts: **Next.js plugin** + **i18n API**.\n\n**Features** ✨\n\n- 🚀 ・ Works well with automatic page optimization.\n- 🦄 ・ Easy to use and configure.\n- 🌍 ・ Basic i18n support: interpolation, plurals, useTranslation hook, Trans component...\n- 🈂️ ・ It loads only the necessary translations _(for page and for locale)_.\n- 📦 ・ Tiny (~1kb) and tree shakable. No dependencies.\n\n

\n \"Bundle\n

\n\n### How are translations loaded?\n\nIn the configuration file, you specify each page that namespaces needs:\n\n**i18n.json**\n\n```js\n{\n \"pages\": {\n \"*\": [\"common\"],\n \"/\": [\"home\"],\n \"/cart\": [\"cart\"],\n \"/content/[slug]\": [\"content\"],\n \"rgx:^/account\": [\"account\"]\n }\n // rest of config here...\n}\n```\n\n_[Read here](#create-your-namespaces-files) about how to add the namespaces JSON files._\n\nNext-translate ensures that each page only has its namespaces with the current language. So if we have 100 locales, only 1 will be loaded.\n\nIn order to do this we use a **webpack loader** that loads the necessary translation files inside the Next.js methods (**getStaticProps**, **getServerSideProps** or **getInitialProps**). If you have one of these methods already on your page, the webpack loader will use your own method, but the defaults it will use are:\n\n- **`getStaticProps`**. This is the **default method used on most pages**, unless it is a page specified in the next two points. This is for performance, so the calculations are done in build time instead of request time.\n- **`getServerSideProps`**. This is the **default method for dynamic pages** like `[slug].js` or `[...catchall].js`. This is because for these pages it is necessary to define the `getStaticPaths` and there is no knowledge of how the slugs should be for each locale. Likewise, how is it by default, only that you write the getStaticPaths then it will already use the getStaticProps to load the translations.\n- **`getInitialProps`**. This is the **default method for these pages that use a HoC**. This is in order to avoid conflicts because HoC could overwrite a `getInitialProps`.\n\nThis **whole process is transparent**, so in your pages you can directly consume the `useTranslate` hook to use the namespaces, and you don't need to do anything else.\n\nIf for some reason you use a `getInitialProps` in your `_app.js` file, then the translations will only be loaded into your `getInitialProps` from `_app.js`. We recommend that for optimization reasons you don't use this approach unless it is absolutely necessary.\n\n## 2. Getting started\n\n### Install\n\n- `yarn add next-translate`\n\n### Add next-translate plugin\n\nIn your **next.config.js** file:\n\n```js\nconst nextTranslate = require('next-translate')\n\nmodule.exports = nextTranslate()\n```\n\nOr if you already have **next.config.js** file and want to keep the changes in it, pass the config object to the `nextTranslate()`. For example for webpack you could do it like this:\n\n```js\nconst nextTranslate = require('next-translate')\n\nmodule.exports = nextTranslate({\n webpack: (config, { isServer, webpack }) => {\n return config;\n }\n})\n```\n\n### Add i18n.js config file\n\nAdd a configuration file `i18n.json` _(or `i18n.js` with `module.exports`)_ in the root of the project. Each page should have its namespaces. Take a look at it in the [config](#3-configuration) section for more details.\n\n```json\n{\n \"locales\": [\"en\", \"ca\", \"es\"],\n \"defaultLocale\": \"en\",\n \"pages\": {\n \"*\": [\"common\"],\n \"/\": [\"home\", \"example\"],\n \"/about\": [\"about\"]\n }\n}\n```\nIn the configuration file you can use both the configuration that we [specified here](#3-configuration) and the own [features about internationalization of Next.js 10](https://nextjs.org/docs/advanced-features/i18n-routing).\n\n\n### Create your namespaces files\n\nBy default the namespaces are specified on the **/locales** root directory in this way:\n\n**/locales**\n\n```bash\n.\n├── ca\n│   ├── common.json\n│   └── home.json\n├── en\n│   ├── common.json\n│   └── home.json\n└── es\n ├── common.json\n └── home.json\n```\n\nEach filename matches the namespace specified on the `pages` config property, while each file content should be similar to this:\n\n```json\n{\n \"title\": \"Hello world\",\n \"variable-example\": \"Using a variable {{count}}\"\n}\n```\n\nHowever, you can use another destination to save your namespaces files using [loadLocaleFrom](#3-configuration) configuration property:\n\n**i18n.js**\n\n```js\n{\n // ...rest of config\n \"loadLocaleFrom\": (lang, ns) =>\n // You can use a dynamic import, fetch, whatever. You should\n // return a Promise with the JSON file.\n import(`./myTranslationsFiles/${lang}/${ns}.json`).then((m) => m.default),\n}\n```\n\n### Use translations in your pages\n\nThen, use the translations in the page and its components:\n\n**pages/example.js**\n\n```jsx\nimport useTranslation from 'next-translate/useTranslation'\n\nexport default function ExamplePage() {\n const { t, lang } = useTranslation('common')\n const example = t('variable-example', { count: 42 })\n\n return
{example}
//
Using a variable 42
\n}\n```\n\nYou can consume the translations directly on your pages, you don't have to worry about loading the namespaces files manually on each page. The [next-translate plugin](#add-next-translate-plugin) loads only the namespaces that the page needs and only with the current language.\n\n## 3. Configuration\n\nIn the configuration file you can use both the configuration that we specified here and the own [features about internationalization of Next.js 10](https://nextjs.org/docs/advanced-features/i18n-routing).\n\n| Option | Description | Type | Default |\n| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- | ------------------------------------------------------------------------------- |\n| `defaultLocale` | ISO of the default locale (\"en\" as default). | `string` | `\"en\"` |\n| `locales` | An array with all the languages to use in the project. | `string[]` | `[]` |\n| `loadLocaleFrom` | Change the way you load the namespaces. | `function` that returns a `Promise` with the `JSON`. | By default is loading the namespaces from **locales** root directory. |\n| `pages` | An object that defines the namespaces used in each page. Example of object: `{\"/\": [\"home\", \"example\"]}`. To add namespaces to all pages you should use the key `\"*\"`, ex: `{\"*\": [\"common\"]}`. It's also possible to use regex using `rgx:` on front: `{\"rgx:/form$\": [\"form\"]}`. You can also use a function instead of an array, to provide some namespaces depending on some rules, ex: `{ \"/\": ({ req, query }) => query.type === 'example' ? ['example'] : []}` | `Object` | `{}` |\n| `logger` | Function to log the **missing keys** in development and production. If you are using `i18n.json` as config file you should change it to `i18n.js`. | `function` | By default the logger is a function doing a `console.warn` only in development. | |\n| `loggerEnvironment` | String to define if the logger should run in the browser, in node or both | `\"node\"` | `\"browser\"` | `\"both\"` | `\"browser\"` | |\n| `logBuild` | Each page has a log indicating: namespaces, current language and method used to load the namespaces. With this you can disable it. | `Boolean` | `true` |\n| `loader` | If you wish to disable the webpack loader and manually load the namespaces on each page, we give you the opportunity to do so by disabling this option. | `Boolean` | `true` |\n| `interpolation` | Change the delimeter that is used for interpolation. | `{prefix: string; suffix: string, formatter: function }` | `{prefix: '{{', suffix: '}}'}`\n| `keySeparator` | Change the separator that is used for nested keys. Set to `false` to disable keys nesting in JSON translation files. Can be useful if you want to use natural text as keys. | `string` | `false` | `'.'`\n| `nsSeparator` | char to split namespace from key. You should set it to `false` if you want to use natural text as keys. | `string` | `false` | `':'`\n| `defaultNS` | default namespace used if not passed to `useTranslation` or in the translation key. | `string` | `undefined`\n| `staticsHoc` | The HOCs we have in our API ([appWithI18n](#appwithi18n)), do not use [hoist-non-react-statics](https://github.com/mridgway/hoist-non-react-statics) in order not to include more kb than necessary _(static values different than getInitialProps in the pages are rarely used)_. If you have any conflict with statics, you can add hoist-non-react-statics (or any other alternative) here. [See an example](docs/hoist-non-react-statics.md). | `Function` | `null`\n| `extensionsRgx` | Change the regex used by the webpack loader to find Next.js pages. | `Regex` | `/\\.(tsx\\|ts\\|js\\|mjs\\|jsx)$/`\n| `revalidate` | If you want to have a default revalidate on each page we give you the opportunity to do so by passing a number to revalidate. You can still define getStaticProps on a page with a different revalidate amount and override this default override. | `Number` | If you don't define it, by default the pages will have no revalidate.\n| `pagesInDir` | If you run `next ./my-app` to change where your pages are, you can here define `my-app/pages` so that next-translate can guess where they are. | `String` | If you don't define it, by default the pages will be searched for in the classic places like `pages` and `src/pages`.\n| `localesToIgnore` | Indicate these locales to ignore when you are prefixing the default locale using a middleware (in Next +12, [learn how to do it](https://nextjs.org/docs/advanced-features/i18n-routing#prefixing-the-default-locale)) | `Array` | `['default']`\n\n## 4. API\n\n### useTranslation\n\n**Size**: ~150b 📦\n\nThis hook is the recommended way to use translations in your pages / components.\n\n- **Input**: string - defaultNamespace (optional)\n- **Output**: Object { t: Function, lang: string }\n\nExample:\n\n```jsx\nimport React from 'react'\nimport useTranslation from 'next-translate/useTranslation'\n\nexport default function Description() {\n const { t, lang } = useTranslation('ns1') // default namespace (optional)\n const title = t('title')\n const titleFromOtherNamespace = t('ns2:title')\n const description = t`description` // also works as template string\n const example = t('ns2:example', { count: 3 }) // and with query params\n const exampleDefault = t('ns:example', { count: 3 }, { default: \"The count is: {{count}}.\" }) // and with default translation\n\n return (\n <>\n

{title}

\n

{description}

\n

{example}

\n <>\n )\n}\n```\n\nThe `t` function:\n\n- **Input**:\n - **i18nKey**: string (namespace:key)\n - **query**: Object _(optional)_ (example: { name: 'Leonard' })\n - **options**: Object _(optional)_\n - **fallback**: string | string[] - fallback if i18nKey doesn't exist. [See more](#8-fallbacks).\n - **returnObjects**: boolean - Get part of the JSON with all the translations. [See more](#7-nested-translations).\n - **default**: string - Default translation for the key. If fallback keys are used, it will be used only after exhausting all the fallbacks.\n - **ns**: string - Namespace to use when none is embded in the `i18nKey`.\n- **Output**: string\n\n### withTranslation\n\n**Size**: ~560b 📦\n\nIt's an alternative to `useTranslation` hook, but in a HOC for these components that are no-functional. _(Not recommended, it's better to use the `useTranslation` hook.)_.\n\nThe `withTranslation` HOC returns a Component with an extra prop named `i18n` (Object { t: Function, lang: string }).\n\nExample:\n\n```jsx\nimport React from 'react'\nimport withTranslation from 'next-translate/withTranslation'\n\nclass Description extends React.Component {\n render() {\n const { t, lang } = this.props.i18n\n const description = t('common:description')\n\n return

{description}

\n }\n}\n\nexport default withTranslation(NoFunctionalComponent)\n```\n\nSimilar to `useTranslation(\"common\")` you can call `withTranslation` with the second parameter defining a default namespace to use:\n\n```\nexport default withTranslation(NoFunctionalComponent, \"common\")\n```\n\n### Trans Component\n\n**Size**: ~1.4kb 📦\n\nSometimes we need to do some translations with HTML inside the text (bolds, links, etc), the `Trans` component is exactly what you need for this. We recommend to use this component only in this case, for other cases we highly recommend the usage of `useTranslation` hook instead.\n\nExample:\n\n```jsx\n// The defined dictionary entry is like:\n// \"example\": \"<0>The number is <1>{{count}}\",\n, ]}\n values={{ count: 42 }}\n/>\n```\n\nOr using `components` prop as a object:\n\n```jsx\n// The defined dictionary entry is like:\n// \"example\": \"The number is {{count}}\",\n,\n b: ,\n }}\n values={{ count: 42 }}\n defaultTrans=\"The number is {{count}}\"\n/>\n```\n\n- **Props**:\n - `i18nKey` - string - key of i18n entry (namespace:key)\n - `components` - Array | Object - In case of Array each index corresponds to the defined tag `<0>`/`<1>`. In case of object each key corresponds to the defined tag ``.\n - `values` - Object - query params\n - `fallback` - string | string[] - Optional. Fallback i18nKey if the i18nKey doesn't match.\n - `defaultTrans` - string - Default translation for the key. If fallback keys are used, it will be used only after exhausting all the fallbacks.\n - `ns` - Namespace to use when none is embedded in `i18nKey`\n\nIn cases where we require the functionality of the `Trans` component, but need a **string** to be interpolated, rather than the output of the `t(props.i18nKey)` function, there is also a `TransText` component, which takes a `text` prop instead of `i18nKey`.\n\n- **Props**:\n - `text` - string - The string which (optionally) contains tags requiring interpolation\n - `components` - Array | Object - This behaves exactly the same as `Trans` (see above).\n\nThis is especially useful when mapping over the output of a `t()` with `returnObjects: true`:\n```jsx\n// The defined dictionary entry is like:\n// \"content-list\": [\"List of things\", \"with tags\"]\nconst contentList = t('someNamespace:content-list', {}, { returnObjects: true });\n\n{contentList.map((listItem: string) => (\n ,\n em: ,\n }}\n />\n)}\n\n```\n\n### DynamicNamespaces\n\n**Size**: ~1.5kb 📦\n\nThe `DynamicNamespaces` component is useful to load dynamic namespaces, for example, in modals.\n\nExample:\n\n```jsx\nimport React from 'react'\nimport Trans from 'next-translate/Trans'\nimport DynamicNamespaces from 'next-translate/DynamicNamespaces'\n\nexport default function ExampleWithDynamicNamespace() {\n return (\n \n {/* ALSO IS POSSIBLE TO USE NAMESPACES FROM THE PAGE */}\n

\n \n

\n\n {/* USING DYNAMIC NAMESPACE */}\n \n \n )\n}\n```\n\nRemember that `['dynamic']` namespace should **not** be listed on `pages` configuration:\n\n```js\n pages: {\n '/my-page': ['common'], // only common namespace\n }\n```\n\n- **Props**:\n - `namespaces` - string[] - list of dynamic namespaces to download - **Required**.\n - `fallback`- ReactNode - Fallback to display meanwhile the namespaces are loading. - **Optional**.\n - `dynamic` - function - By default it uses the [loadLocaleFrom](#3-configuration) in the configuration to load the namespaces, but you can specify another destination. - **Optional**.\n\n### getT\n\n**Size**: ~1.3kb 📦\n\nAsynchronous function to load the `t` function outside components / pages. It works on both server-side and client-side.\n\nUnlike the useTranslation hook, we can use here any namespace, it doesn't have to be a namespace defined in the \"pages\" configuration. It downloads the namespace indicated as a parameter on runtime.\n\nExample inside `getStaticProps`:\n\n```js\nimport getT from 'next-translate/getT'\n// ...\nexport async function getStaticProps({ locale }) {\n const t = await getT(locale, 'common')\n const title = t('title')\n return { props: { title } }\n}\n```\n\nExample inside API Route:\n\n```js\nimport getT from 'next-translate/getT'\n\nexport default async function handler(req, res) {\n const t = await getT(req.query.__nextLocale, 'common')\n const title = t('title')\n\n res.statusCode = 200\n res.setHeader('Content-Type', 'application/json')\n res.end(JSON.stringify({ title }))\n}\n```\n\n### I18nProvider\n\n**Size**: ~3kb 📦\n\nThe `I18nProvider` is a context provider internally used by next-translate to provide the current **lang** and the page **namespaces**. **SO MAYBE YOU'LL NEVER NEED THIS**.\n\nHowever, it's exposed to the API because it can be useful in some cases. For example, to use multi-language translations in a page.\n\nThe `I18nProvider` is accumulating the namespaces, so you can rename the new ones in order to keep the old ones.\n\n```jsx\nimport React from 'react'\nimport I18nProvider from 'next-translate/I18nProvider'\nimport useTranslation from 'next-translate/useTranslation'\n\n// Import English common.json\nimport commonEN from '../../locales/en/common.json'\n\nfunction PageContent() {\n const { t, lang } = useTranslation()\n\n console.log(lang) // -> current language\n\n return (\n
\n

{t('common:example') /* Current language */}

\n

{t('commonEN:example') /* Force English */}

\n
\n )\n}\n\nexport default function Page() {\n const { lang } = useTranslation()\n\n return (\n \n \n \n )\n}\n```\n\n### appWithI18n\n\n**Size**: ~3.7kb 📦\n\nThe `appWithI18n` is internally used by next-translate. **SO MAYBE YOU'LL NEVER NEED THIS**. However, we expose it in the API in case you disable the webpack [loader](#3-configuration) option and decide to load the namespaces manually.\n\nIf you wish not to use the webpack loader, then you should put this in your `_app.js` file (and create the `_app.js` file if you don't have it).\n\nExample:\n\n`_app.js`\n\n```jsx\nimport appWithI18n from 'next-translate/appWithI18n'\nimport i18nConfig from '../i18n'\n\nfunction MyApp({ Component, pageProps }) {\n return \n}\n\n// Wraping your _app.js\nexport default appWithI18n(MyApp, {\n ...i18nConfig,\n // Set to false if you want to load all the namespaces on _app.js getInitialProps\n skipInitialProps: true,\n})\n```\n\nIf `skipInitialProps=true`, then you should also use the [loadNamespaces](#loadnamespaces) helper to manually load the namespaces on each page.\n\n\n### loadNamespaces\n\n**Size**: ~1.9kb 📦\n\nThe `loadNamespaces` is internally used by next-translate. **SO MAYBE YOU'LL NEVER NEED THIS**. However, we expose it in the API in case you disable the webpack [loader](#3-configuration) option and decide to load the namespaces manually.\n\nTo load the namespaces, you must return in your pages the props that the helper provides.\n\n```js\nimport loadNamespaces from 'next-translate/loadNamespaces'\n\nexport function getStaticProps({ locale }) {\n return {\n props: {\n ...(await loadNamespaces({ locale, pathname: '/about' })),\n }\n }\n}\n```\n🚨 To work well, it is necessary that your `_app.js` will be wrapped with the [appWithI18n](#appwithi18n). Also, the `loadLocaleFrom` configuration property is **mandatory** to define it.\n\n## 5. Plurals\n\nWe support 6 plural forms (taken from [CLDR Plurals](http://cldr.unicode.org/index/cldr-spec/plural-rules) page) by adding to the key this suffix (or nesting it under the key with no `_` prefix):\n\n- `_zero`\n- `_one` (singular)\n- `_two` (dual)\n- `_few` (paucal)\n- `_many` (also used for fractions if they have a separate class)\n- `_other` (required—general plural form—also used if the language only has a single form)\n\n_See more info about plurals [here](https://unicode-org.github.io/cldr-staging/charts/37/supplemental/language_plural_rules.html#sl)_.\n\nOnly the last one, **`_other`**, is required because it’s the only common plural form used in all locales.\n\nAll other plural forms depends on locale. For example English has only two: `_one` and `_other` (1 cat vs. 2 cats). Some languages have more, like Russian and Arabic.\n\nIn addition, we also support **an exact match** by specifying the number (`_0`, `_999`) and this works for all locales. Here is an example:\n\nCode:\n\n```js\n// **Note**: Only works if the name of the variable is {{count}}.\nt('cart-message', { count })\n```\n\nNamespace:\n\n```js\n{\n \"cart-message_0\": \"The cart is empty\", // when count === 0\n \"cart-message_one\": \"The cart has only {{count}} product\", // singular\n \"cart-message_other\": \"The cart has {{count}} products\", // plural\n \"cart-message_999\": \"The cart is full\", // when count === 999\n}\n```\n\nor\n\n```js\n{\n \"cart-message\": {\n \"0\": \"The cart is empty\", // when count === 0\n \"one\": \"The cart has only {{count}} product\", // singular\n \"other\": \"The cart has {{count}} products\", // plural\n \"999\": \"The cart is full\", // when count === 999\n }\n}\n```\n\n> Intl.PluralRules API is **only available for modern browsers**, if you want to use it in legacy browsers you should add a [polyfill](https://github.com/eemeli/intl-pluralrules).\n\n\n## 6. Use HTML inside the translation\n\nYou can define HTML inside the translation this way:\n\n```json\n{\n \"example-with-html\": \"<0>This is an example <1>using HTML inside the translation\"\n}\n```\n\nExample:\n\n```jsx\nimport Trans from 'next-translate/Trans'\n// ...\nconst Component = (props) =>

\n// ...\n, ]}\n/>\n```\n\nRendered result:\n\n```html\n

This is an example using HTML inside the translation

\n```\n\nEach index of `components` array corresponds with `` of the definition.\n\nIn the `components` array, it's not necessary to pass the children of each element. Children will be calculated.\n\n## 7. Nested translations\n\nIn the namespace, it's possible to define nested keys like this:\n\n```json\n{\n \"nested-example\": {\n \"very-nested\": {\n \"nested\": \"Nested example!\"\n }\n }\n}\n```\n\nIn order to use it, you should use \".\" as id separator:\n\n```js\nt`namespace:nested-example.very-nested.nested`\n```\n\nAlso is possible to use as array:\n\n```json\n{\n \"array-example\": [\n { \"example\": \"Example {{count}}\" },\n { \"another-example\": \"Another example {{count}}\" }\n ]\n}\n```\n\nAnd get all the array translations with the option `returnObjects`:\n\n```js\nt('namespace:array-example', { count: 1 }, { returnObjects: true })\n/*\n[\n { \"example\": \"Example 1\" },\n { \"another-example\": \"Another example 1\" }\n]\n*/\n```\n\n### 8. Fallbacks\n\nIf no translation exists you can define fallbacks (`string|string[]`) to search for other translations:\n\n```js\nconst { t } = useTranslation()\nconst textOrFallback = t(\n 'ns:text',\n { count: 1 },\n {\n fallback: 'ns:fallback',\n }\n)\n```\n\nList of fallbacks:\n\n```js\nconst { t } = useTranslation()\nconst textOrFallback = t(\n 'ns:text',\n { count: 42 },\n {\n fallback: ['ns:fallback1', 'ns:fallback2'],\n }\n)\n```\n\nIn Trans Component:\n\n```jsx\n, ]}\n values={{ count: 42 }}\n fallback={['ns:fallback1', 'ns:fallback2']} // or string with just 1 fallback\n/>\n```\n\n## 9. Formatter\n\nYou can format params using the `interpolation.formatter` config function.\n\nin `i18n.js`:\n\n```js\nconst formatters = {\n es: new Intl.NumberFormat(\"es-ES\"),\n en: new Intl.NumberFormat(\"en-EN\"),\n}\n\nreturn {\n // ...\n interpolation: {\n format: (value, format, lang) => {\n if(format === 'number') return formatters[lang].format(value)\n return value\n }\n }\n}\n```\n\nIn English namespace:\n\n```json\n{\n \"example\": \"The number is {{count, number}}\"\n}\n```\n\nIn Spanish namespace:\n\n```json\n{\n \"example\": \"El número es {{count, number}}\"\n}\n```\n\nUsing:\n\n```js\nt('example', { count: 33.5 })\n```\n\nReturns:\n\n- In English: `The number is 33.5`\n- In Spanish: `El número es 33,5`\n\n## 10. How to change the language\n\nIn order to change the current language you can use the [Next.js navigation](https://nextjs.org/docs/advanced-features/i18n-routing) (Link and Router) passing the `locale` prop.\n\nAn example of a possible `ChangeLanguage` component using the `useRouter` hook from `Next.js`:\n\n```js\nimport React from 'react'\nimport Link from 'next/link'\nimport useTranslation from 'next-translate/useTranslation'\nimport i18nConfig from '../i18n.json'\n\nconst { locales } = i18nConfig\n\nexport default function ChangeLanguage() {\n const { t, lang } = useTranslation()\n\n return locales.map((lng) => {\n if (lng === lang) return null\n\n return (\n \n {t(`layout:language-name-${lng}`)}\n \n )\n })\n}\n```\n\nYou could also use `setLanguage` to change the language while keeping the same page.\n\n```js\nimport React from 'react'\nimport setLanguage from 'next-translate/setLanguage'\n\nexport default function ChangeLanguage() {\n return (\n \n )\n}\n```\n\nAnother way of accessing the `locales` list to change the language is using the `Next.js router`. The `locales` list can be accessed using the [Next.js useRouter hook](https://nextjs.org/docs/api-reference/next/router#userouter).\n\n## 11. How to save the user-defined language\n\nYou can set a cookie named `NEXT_LOCALE` with the user-defined language as value, this way a locale can be forced.\n\nExample of hook:\n\n```js\nimport { useRouter } from 'next/router'\n\n// ...\n\nfunction usePersistLocaleCookie() {\n const { locale, defaultLocale } = useRouter()\n\n useEffect(persistLocaleCookie, [locale, defaultLocale])\n function persistLocaleCookie() {\n if(locale !== defaultLocale) {\n const date = new Date()\n const expireMs = 100 * 24 * 60 * 60 * 1000 // 100 days\n date.setTime(date.getTime() + expireMs)\n document.cookie = `NEXT_LOCALE=${locale};expires=${date.toUTCString()};path=/`\n }\n }\n}\n```\n\n## 12. How to use multi-language in a page\n\nIn some cases, when the page is in the current language, you may want to do some exceptions displaying some text in another language.\n\nIn this case, you can achieve this by using the `I18nProvider`.\n\nLearn how to do it [here](#i18nprovider).\n\n## 13. How to use next-translate in a mono-repo\n\nNext-translate uses by default the current working directory of the Node.js process (`process.cwd()`).\n\nIf you want to change it you can use :\n- the `NEXT_TRANSLATE_PATH` environment variable. It supports both relative and absolute path\n- the native NodeJS function `process.chdir(PATH_TO_NEXT_TRANSLATE)` to move the `process.cwd()`\n\n## 14. Demos\n\n### Demo from Next.js\n\nThere is a demo of `next-translate` on the Next.js repo:\n\n- https://github.com/vercel/next.js/tree/master/examples/with-next-translate\n\nTo use it:\n\n```bash\nnpx create-next-app --example with-next-translate with-next-translate-app\n# or\nyarn create next-app --example with-next-translate with-next-translate-app\n```\n\n### Basic demo\n\nThis demo is in this repository:\n\n- `git clone git@github.com:vinissimus/next-translate.git`\n- `cd next-translate`\n- `yarn && yarn example:basic`\n\n### Complex demo\n\nSimilar than the basic demo but with some extras: TypeScript, Webpack 5, MDX, with _app.js on top, pages located on src/pages folder, loading locales from src/translations with a different structure.\n\nThis demo is in this repository:\n\n- `git clone git@github.com:vinissimus/next-translate.git`\n- `cd next-translate`\n- `yarn && yarn example:complex`\n\n### Without the webpack loader demo\n\nSimilar than the basic example but loading the page namespaces manually deactivating the webpack loader in the i18n.json config file.\n\n> We do not recommend that it be used in this way. However we give the opportunity for anyone to do so if they are not comfortable with our webpack loader.\n\nThis demo is in this repository:\n\n- `git clone git@github.com:vinissimus/next-translate.git`\n- `cd next-translate`\n- `yarn && yarn example:without-loader`\n\n[badge-prwelcome]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square\n[prwelcome]: http://makeapullrequest.com\n[spectrum]: https://spectrum.chat/next-translate\n\n## Contributors ✨\n\nThanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\"\"/
Aral Roca Gomez
🚧 💻		\"\"/
Vincent Ducorps
💻		\"\"/
Björn Rave
💻		\"\"/
Justin
💻		\"\"/
Pol
🚇		\"\"/
Ademílson F. Tonato
💻		\"\"/
Faul
💻
\"\"/
bickmaev5
💻		\"\"/
Pierre Grimaud
📖		\"\"/
Roman Minchyn
📖 💻		\"\"/
Egor
💻		\"\"/
Darren
💻		\"\"/
Giovanni Giordano
💻		\"\"/
Eugene
💻
\"\"/
Andrew Chung
💻		\"\"/
Thanh Minh
💻		\"\"/
crouton
💻		\"\"/
Patrick
📖		\"\"/
Vantroy
💻		\"\"/
Joey
💻		\"\"/
gurkerl83
💻
\"\"/
Teemu Perämäki
📖		\"\"/
Luis Serrano
📖		\"\"/
j-schumann
💻		\"\"/
Andre Hsu
💻		\"\"/
slevy85
💻		\"\"/
Bernd Artmüller
💻		\"\"/
Rihards Ščeredins
💻
\"\"/
n4n5
📖		\"\"/
Rubén Moya
💻		\"\"/
Tom Esterez
💻		\"\"/
Dan Needham
💻 ⚠️ 📖		\"\"/
Bruno Antunes
💻		\"\"/
Kaan Atakan
💻		\"\"/
Romain
💻
\"\"/
Arnau Jiménez
💻		\"\"/
Edwin Veldhuizen
💻
\n\n\n\n\n\n\nThis project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!\n","readmeFilename":"README.md"}