32 | 
33 |
34 | {% set _divider = false %}
35 | {% if config.links.sidebar %}
36 | {% for linkTitle, link in config.links.sidebar %}
37 | {% set _divider = true %}
38 |
33 | 
\
26 | \
27 | &#xNAN;_Are you working on an open source project and are looking for a way to manage your translations? -_ [_locize_](https://locize.com) _loves the open-source philosophy and may be able to support you._
28 | {% endhint %}
29 |
30 | [Learn more about supported frameworks](overview/supported-frameworks.md)
31 |
32 | {% hint style="success" %}
33 | Check out [this video](https://youtu.be/37rcHVcQ6t0) and the corresponding [blog post](https://www.locize.com/blog/how-to-easily-add-i18n-to-your-software) about "Vite + React + TypeScript" with i18next.
34 |
35 | [
](https://youtu.be/37rcHVcQ6t0)
36 | {% endhint %}
37 |
38 | {% hint style="success" %}
39 | [Here](https://locize.com/blog/react-i18next/) you'll find a simple tutorial on how to best use [react-i18next](https://react.i18next.com/).\
40 | Some basics of i18next and some cool possibilities on how to optimize your localization workflow.[\
41 | ](https://locize.com/blog/react-i18next/)
42 | {% endhint %}
43 |
44 | {% hint style="success" %}
45 | Do you want to use i18next in [Vue.js](https://github.com/locize/locize-i18next-vue-example)? Check out [this tutorial blog post](https://locize.com/blog/i18next-vue/).
46 |
47 | [](https://locize.com/blog/i18next-vue/)
48 | {% endhint %}
49 |
50 | {% hint style="success" %}
51 | Did you know internationalization is also important on your app's backend? In [this tutorial blog post](https://locize.com/blog/how-does-server-side-internationalization-look-like/) you can check out how this works.[\
52 | ](https://locize.com/blog/how-does-server-side-internationalization-look-like/)[](https://locize.com/blog/how-does-server-side-internationalization-look-like/)
53 | {% endhint %}
54 |
55 | {% hint style="success" %}
56 | Are you still using i18next in [jQuery](https://github.com/i18next/jquery-i18next)? Check out [this tutorial blog post](https://www.locize.com/blog/jquery-i18next).
57 |
58 | [](https://www.locize.com/blog/jquery-i18next)
59 | {% endhint %}
60 |
61 | ## Complete solution
62 |
63 | Most frameworks leave it to you how translations are being loaded. You are responsible to detect the user language, to load the translations and push them into the framework.
64 |
65 | i18next takes care of these issues for you. We provide you with plugins to:
66 |
67 | * detect the user language
68 | * load the translations
69 | * optionally cache the translations
70 | * extension, by using post-processing - e.g. to enable sprintf support
71 |
72 | [Learn more about plugins and utilities](overview/plugins-and-utils.md)
73 |
74 | ## Flexibility
75 |
76 | i18next comes with strong defaults but it is flexible enough to fulfill custom needs.
77 |
78 | * Use moment.js over intl for date formatting?
79 | * Prefer different pre- and suffixes for interpolation?
80 | * Like gettext style keys better?
81 |
82 | i18next has you covered!
83 |
84 | [Learn more about options](overview/configuration-options.md)
85 |
86 | ## Scalability
87 |
88 | The framework was built with scalability in mind. For smaller projects, having a single file with all the translation might work, but for larger projects this approach quickly breaks down. i18next gives you the option to separate translations into multiple files and to load them on demand.
89 |
90 | [Learn more about namespaces](principles/namespaces.md)
91 |
92 | ## Ecosystem
93 |
94 | There are tons of modules built for and around i18next: from extracting translations from your code over bundling translations using webpack, to converting gettext, CSV and RESX to JSON.
95 |
96 | * [Learn more about plugins and utils](overview/plugins-and-utils.md)
97 | * [Learn more about frameworks supported](overview/supported-frameworks.md)
98 |
99 | ## [Localization as a service](https://locize.com)
100 |
101 | Through [locize.com](http://locize.com/?utm_source=i18next_com\&utm_medium=gitbook), i18next even provides its own translation management tool: localization as a service.
102 |
103 | {% embed url="https://www.youtube.com/watch?v=TFV_vhJs5DY" %}
104 |
105 | [Learn more about the enterprise offering](overview/for-enterprises.md)
106 |
107 | Imagine you run a successful online business, and you want to expand it to reach customers in different countries. You know that to succeed in those markets, your website or app needs to speak the language and understand the culture of each place.
108 |
109 | 1. **i18next**: Think of 'i18next' as a sophisticated language expert for your website or app. It's like hiring a team of translators and cultural experts who ensure that your online business is fluent in multiple languages. It helps adapt your content, menus, and messages to fit perfectly in each target market, making your business more appealing and user-friendly.
110 | 2. **locize**: Now, 'locize' is your efficient manager in charge of organizing and streamlining the translation process. It keeps all your language versions organized and ensures they're always accurate and up-to-date. So, if you want to introduce a new product or promotion, locize helps you do it seamlessly in all the languages you operate in, saving you time and resources.
111 |
112 | Together, 'i18next' and '[locize](https://locize.com)' empower your business to effortlessly reach international audiences. They help you speak the language of your customers, making your business more accessible, relatable, and successful in global markets.
113 |
--------------------------------------------------------------------------------
/SUMMARY.md:
--------------------------------------------------------------------------------
1 | # Table of contents
2 |
3 | * [Introduction](README.md)
4 |
5 | ## Overview
6 |
7 | * [Getting started](overview/getting-started.md)
8 | * [Comparison to others](overview/comparison-to-others.md)
9 | * [API](overview/api.md)
10 | * [Configuration Options](overview/configuration-options.md)
11 | * [Supported Frameworks](overview/supported-frameworks.md)
12 | * [Plugins and Utils](overview/plugins-and-utils.md)
13 | * [For Enterprises](overview/for-enterprises.md)
14 | * [First setup help](overview/first-setup-help.md)
15 | * [TypeScript](overview/typescript.md)
16 |
17 | ## Translation Function
18 |
19 | * [Essentials](translation-function/essentials.md)
20 | * [Interpolation](translation-function/interpolation.md)
21 | * [Formatting](translation-function/formatting.md)
22 | * [Plurals](translation-function/plurals.md)
23 | * [Nesting](translation-function/nesting.md)
24 | * [Context](translation-function/context.md)
25 | * [Objects and Arrays](translation-function/objects-and-arrays.md)
26 |
27 | ## Principles
28 |
29 | * [Best Practices](principles/best-practices.md)
30 | * [Translation Resolution](principles/translation-resolution.md)
31 | * [Namespaces](principles/namespaces.md)
32 | * [Fallback](principles/fallback.md)
33 | * [Plugins](principles/plugins.md)
34 |
35 | ## How to
36 |
37 | * [Add or Load Translations](how-to/add-or-load-translations.md)
38 | * [Extracting translations](how-to/extracting-translations.md)
39 | * [Caching](how-to/caching.md)
40 | * [Backend Fallback](how-to/backend-fallback.md)
41 | * [FAQ](how-to/faq.md)
42 |
43 | ## Misc
44 |
45 | * [JSON Format](misc/json-format.md)
46 | * [Creating own Plugins](misc/creating-own-plugins.md)
47 | * [Migration Guide](misc/migration-guide.md)
48 | * [The history of i18next](misc/the-history-of-i18next.md)
49 | * [Testimonials](misc/testimonials.md)
50 |
51 | ***
52 |
53 | * [🌐 localization as a service](https://locize.com)
54 | * [🎓 i18next crash course](https://youtu.be/SA\_9i4TtxLQ)
55 | * [💾 GitHub Repository](https://github.com/i18next/i18next)
56 |
--------------------------------------------------------------------------------
/_layouts/README.md:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/i18next/i18next-gitbook/6755a6155fe610a051076a1d86c520cde709b683/_layouts/README.md
--------------------------------------------------------------------------------
/_layouts/website/README.md:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/i18next/i18next-gitbook/6755a6155fe610a051076a1d86c520cde709b683/_layouts/website/README.md
--------------------------------------------------------------------------------
/_layouts/website/summary.html:
--------------------------------------------------------------------------------
1 | {% macro articles(_articles) %}
2 | {% for article in _articles %}
3 |
33 | 
](https://www.locize.com/blog/i18next-locize-ai-human)
155 | {% endhint %}
156 |
157 | #### [**locize**](https://locize.com) is the perfect translation management tool for your [**i18next**](https://www.i18next.com) project
158 |
159 | #### ➡️ [i18next](https://www.i18next.com/) + [locize](https://locize.com/) = [true continuous localization](https://locize.com/how-it-works.html#continouslocalization)
160 |
--------------------------------------------------------------------------------
/how-to/backend-fallback.md:
--------------------------------------------------------------------------------
1 | ---
2 | description: Do you want to define a fallback which uses local translations?
3 | ---
4 |
5 | # Backend Fallback
6 |
7 | ## Browser fallback with local / bundled translations
8 |
9 | With i18next you can configure a fallback backend to be used in the browser. It will try to load from your primary backend (in this case from your [http backend](https://github.com/i18next/i18next-http-backend)) and if the primary backend is not reachable or does not serve translations, your second backend (in this case [local or bundled](https://github.com/i18next/i18next-resources-to-backend) translations) will be used. This is all possible thanks to the [chained backend](https://github.com/i18next/i18next-chained-backend).
10 |
11 | ```javascript
12 | import i18next from "i18next";
13 | import ChainedBackend from "i18next-chained-backend";
14 | import HttpBackend from "i18next-http-backend";
15 | import resourcesToBackend from "i18next-resources-to-backend";
16 |
17 | const bundledResources = {
18 | en: {
19 | translation: {
20 | key: 'value'
21 | }
22 | }
23 | };
24 |
25 | i18next
26 | .use(ChainedBackend)
27 | .init({
28 | fallbackLng: "en",
29 | // ... your i18next config
30 | backend: {
31 | backends: [
32 | HttpBackend,
33 | resourcesToBackend(bundledResources)
34 | ],
35 | backendOptions: [{
36 | loadPath: '/locales/{{lng}}/{{ns}}.json'
37 | }]
38 | }
39 | });
40 | ```
41 |
42 | ### You can also lazy load the in memory translations, i.e. when using webpack
43 |
44 | ```javascript
45 | import i18next from "i18next";
46 | import ChainedBackend from "i18next-chained-backend";
47 | import HttpBackend from "i18next-http-backend";
48 | import resourcesToBackend from "i18next-resources-to-backend";
49 |
50 | i18next
51 | .use(ChainedBackend)
52 | .init({
53 | fallbackLng: "en",
54 | // ... your i18next config
55 | backend: {
56 | backends: [
57 | HttpBackend,
58 | resourcesToBackend((lng, ns) => import(`./locales/${lng}/${ns}.json`))
59 | ],
60 | backendOptions: [{
61 | loadPath: '/locales/{{lng}}/{{ns}}.json'
62 | }]
63 | }
64 | });
65 | ```
66 |
67 | {% hint style="info" %}
68 | More information can be found here:\
69 | [i18next-chained-backend](https://github.com/i18next/i18next-chained-backend)\
70 | [i18next-resources-to-backend](https://github.com/i18next/i18next-resources-to-backend)\
71 | [i18next-http-backend](https://github.com/i18next/i18next-http-backend)
72 | {% endhint %}
73 |
74 | ## Server side fallback with filesystem
75 |
76 | On server side you can also use the i18next-fs-backend for example instead of the in memory fallback.
77 |
78 | ```javascript
79 | import i18next from "i18next";
80 | import ChainedBackend from "i18next-chained-backend";
81 | import HttpBackend from "i18next-http-backend";
82 | import FsBackend from "i18next-fs-backend";
83 |
84 | i18next
85 | .use(ChainedBackend)
86 | .init({
87 | fallbackLng: "en",
88 | // ... your i18next config
89 | backend: {
90 | backends: [
91 | HttpBackend,
92 | FsBackend
93 | ],
94 | backendOptions: [{
95 | loadPath: '/locales/{{lng}}/{{ns}}.json'
96 | }, {
97 | loadPath: './locales_cache/{{lng}}/{{ns}}.json'
98 | }]
99 | }
100 | });
101 | ```
102 |
103 | {% hint style="info" %}
104 | More information can be found here:\
105 | [i18next-chained-backend](https://github.com/i18next/i18next-chained-backend)\
106 | [i18next-fs-backend](https://github.com/i18next/i18next-fs-backend)\
107 | [i18next-http-backend](https://github.com/i18next/i18next-http-backend)
108 | {% endhint %}
109 |
110 | {% hint style="danger" %}
111 | We suggest not to use multiple backends with the [i18next-chained-backend](https://github.com/i18next/i18next-chained-backend) in combination with saveMissing or updateMissing, because it may happen, that the trigger for this is based on stale data.
112 | {% endhint %}
113 |
--------------------------------------------------------------------------------
/how-to/caching.md:
--------------------------------------------------------------------------------
1 | # Caching
2 |
3 | ## Browser caching with local storage
4 |
5 | With i18next you can configure a cache layer to be used in the browser. It will load and cache resources from [localStorage](https://github.com/i18next/i18next-localstorage-backend) and can be used in combination with the [chained backend](https://github.com/i18next/i18next-chained-backend).
6 |
7 | ```javascript
8 | import i18next from "i18next";
9 | import ChainedBackend from "i18next-chained-backend";
10 | import HttpBackend from "i18next-http-backend";
11 | import LocalStorageBackend from "i18next-localstorage-backend";
12 |
13 | i18next
14 | .use(ChainedBackend)
15 | .init({
16 | fallbackLng: "en",
17 | // ... your i18next config
18 | backend: {
19 | backends: [
20 | LocalStorageBackend,
21 | HttpBackend
22 | ],
23 | backendOptions: [{
24 | expirationTime: 7 * 24 * 60 * 60 * 1000 // 7 days
25 | }, {
26 | loadPath: '/locales/{{lng}}/{{ns}}.json'
27 | }]
28 | }
29 | });
30 | ```
31 |
32 | {% hint style="info" %}
33 | More information can be found here:
34 | [i18next-chained-backend](https://github.com/i18next/i18next-chained-backend)
35 | [i18next-localstorage-backend](https://github.com/i18next/i18next-localstorage-backend)
36 | [i18next-http-backend](https://github.com/i18next/i18next-http-backend)
37 | {% endhint %}
38 |
39 | ## Server side caching with filesystem
40 |
41 | With i18next you can configure a cache layer to be used on server side. It will load and cache resources from the [filesystem](https://github.com/i18next/i18next-fs-backend) and can be used in combination with the [chained backend](https://github.com/i18next/i18next-chained-backend).
42 |
43 | ```javascript
44 | import i18next from "i18next";
45 | import ChainedBackend from "i18next-chained-backend";
46 | import HttpBackend from "i18next-http-backend";
47 | import FsBackend from "i18next-fs-backend";
48 |
49 | i18next
50 | .use(ChainedBackend)
51 | .init({
52 | fallbackLng: "en",
53 | // ... your i18next config
54 | backend: {
55 | backends: [
56 | FsBackend,
57 | HttpBackend
58 | ],
59 | backendOptions: [{
60 | expirationTime: 7 * 24 * 60 * 60 * 1000, // 7 days
61 | loadPath: './locales_cache/{{lng}}/{{ns}}.json',
62 | addPath: './locales_cache/{{lng}}/{{ns}}.json' // make sure the folders "locales_cache/{{lng}}" exists
63 | }, {
64 | loadPath: '/locales/{{lng}}/{{ns}}.json'
65 | }]
66 | }
67 | });
68 | ```
69 |
70 | {% hint style="info" %}
71 | More information can be found here:
72 | [i18next-chained-backend](https://github.com/i18next/i18next-chained-backend)
73 | [i18next-fs-backend](https://github.com/i18next/i18next-fs-backend)
74 | [i18next-http-backend](https://github.com/i18next/i18next-http-backend)
75 | {% endhint %}
76 |
77 | ## React-native caching with AsyncStorage
78 |
79 | With i18next you can configure a cache layer to be used on react-native. It will load and cache resources from the [AsyncStorage](https://github.com/timbrandin/i18next-async-storage-backend) and can be used in combination with the [chained backend](https://github.com/i18next/i18next-chained-backend).
80 |
81 | ```javascript
82 | import i18next from "i18next";
83 | import ChainedBackend from "i18next-chained-backend";
84 | import HttpBackend from "i18next-http-backend";
85 | import AsyncStorageBackend from "i18next-async-storage-backend";
86 |
87 | i18next
88 | .use(ChainedBackend)
89 | .init({
90 | fallbackLng: "en",
91 | // ... your i18next config
92 | backend: {
93 | backends: [
94 | AsyncStorageBackend,
95 | HttpBackend
96 | ],
97 | backendOptions: [{
98 | expirationTime: 7 * 24 * 60 * 60 * 1000 // 7 days
99 | }, {
100 | loadPath: '/locales/{{lng}}/{{ns}}.json'
101 | }]
102 | }
103 | });
104 | ```
105 |
106 | {% hint style="info" %}
107 | More information can be found here:
108 | [i18next-chained-backend](https://github.com/i18next/i18next-chained-backend)
109 | [i18next-async-storage-backend](https://github.com/timbrandin/i18next-async-storage-backend)
110 | [i18next-http-backend](https://github.com/i18next/i18next-http-backend)
111 | {% endhint %}
112 |
113 | ## Server side Next.js caching with filesystem
114 |
115 | Similar to the normal [server side caching with filesystem](caching.md#server-side-caching-with-filesystem), you can use the same approach in a Next.js app in combination with [next-i18next](https://github.com/isaachinman/next-i18next). It will load and cache resources from the [filesystem](https://github.com/i18next/i18next-fs-backend) and can be used in combination with the [chained backend](https://github.com/i18next/i18next-chained-backend).
116 |
117 | The config file, will probably look similar to this, but for a more complete example have a look [at this example by locize](https://github.com/locize/next-i18next-locize/tree/local-caching#optional-server-side-caching-to-filesystem).
118 |
119 | ```javascript
120 | // next-i18next.config.js
121 | const ChainedBackend = require('i18next-chained-backend')
122 | const FSBackend = require('i18next-fs-backend/cjs')
123 | const HttpBackend = require('i18next-http-backend/cjs')
124 |
125 | module.exports = {
126 | i18n: {
127 | defaultLocale: 'en',
128 | locales: ['en', 'de'],
129 | },
130 | backend: {
131 | backends: [
132 | FSBackend,
133 | HttpBackend
134 | ],
135 | backendOptions: [{ // make sure public/locales_cache/en and public/locales_cache/de exists
136 | loadPath: './public/locales_cache/{{lng}}/{{ns}}.json',
137 | addPath: './public/locales_cache/{{lng}}/{{ns}}.json',
138 | expirationTime: 7 * 24 * 60 * 60 * 1000 // 7 days
139 | }, {
140 | loadPath: '/locales/{{lng}}/{{ns}}.json'
141 | }]
142 | },
143 | use: [ChainedBackend],
144 | ns: ['common', 'footer', 'second-page'], // the namespaces needs to be listed here, to make sure they got preloaded
145 | serializeConfig: false, // because of the custom use i18next plugin
146 | // debug: true,
147 | }
148 | ```
149 |
150 | {% hint style="info" %}
151 | More information can be found here:
152 | [next-i18next-locize example](https://github.com/locize/next-i18next-locize/tree/local-caching#optional-server-side-caching-to-filesystem)
153 | [i18next-chained-backend](https://github.com/i18next/i18next-chained-backend)
154 | [i18next-fs-backend](https://github.com/i18next/i18next-fs-backend)
155 | [i18next-http-backend](https://github.com/i18next/i18next-http-backend)
156 | {% endhint %}
157 |
158 | {% hint style="danger" %}
159 | We suggest not to use multiple backends with the [i18next-chained-backend](https://github.com/i18next/i18next-chained-backend) in combination with saveMissing or updateMissing, because it may happen, that the trigger for this is based on stale data.
160 | {% endhint %}
161 |
162 |
--------------------------------------------------------------------------------
/how-to/extracting-translations.md:
--------------------------------------------------------------------------------
1 | # Extracting translations
2 |
3 | At some point you will come to the question how to get new translation key/values into your namespace \(translation\) file.
4 |
5 | ## 1\) Adding new strings manually
6 |
7 | While for sure this is the least efficient method for adding new translations, we know a lot of projects are doing this. There is actually nothing wrong with it beside being some extra work developers could avoid.
8 |
9 | ## 2\) Using an extraction tool
10 |
11 | Static extraction tools can read through your code files to automatically find and export translation keys. [i18next-scanner](http://i18next.github.io/i18next-scanner), [i18next-parser](https://github.com/i18next/i18next-parser) and [babel-plugin-i18next-extract](https://github.com/gilbsgilbs/babel-plugin-i18next-extract) are sensible choices to achieve this goal.
12 |
13 | _Or try_ [_translation-check_](https://github.com/locize/translation-check)_, it shows an overview of your translations in a nice UI. Check which keys are not yet translated._
14 |
15 | For more information about extraction tools, see [plugin and utils](https://www.i18next.com/overview/plugins-and-utils#extraction-tools) documentation page.
16 |
17 | ## 3\) Runtime extraction
18 |
19 | I18next has a setting to send all keys that it was unable to resolve during runtime using the attached backend.
20 |
21 | In case of the http-backend just set `saveMissing: true` on init:
22 |
23 | ```javascript
24 | import i18n from "i18next";
25 | import detector from "i18next-browser-languagedetector";
26 | import backend from "i18next-http-backend";
27 | import { initReactI18next } from "react-i18next";
28 |
29 | i18n
30 | .use(detector)
31 | .use(backend)
32 | .use(initReactI18next) // passes i18n down to react-i18next
33 | .init({
34 | fallbackLng: "en", // use en if detected lng is not available
35 | saveMissing: true // send not translated keys to endpoint
36 | });
37 |
38 | export default i18n;
39 | ```
40 |
41 | Check the [options](https://github.com/i18next/i18next-http-backend#backend-options) for where missing translation gets sent.
42 |
43 | Using node.js and express? You can get that endpoint for free: [https://github.com/i18next/i18next-http-middleware\#add-routes](https://github.com/i18next/i18next-http-middleware#add-routes)
44 |
45 | This is the most convenient way of working with react-i18next: just develop and run your applications without worrying too much about adding translations to your catalog as those get added automatically.
46 |
47 | {% hint style="info" %}
48 | Wanna have this process on steroids? Just hook up a [locize.com](https://locize.com/) localization project using the provided backend and get both the saveMissing and loading of translations automated in a true continuous localization process. [Check out this tutorial!](https://github.com/locize/react-tutorial)
49 | {% endhint %}
50 |
51 | {% embed url="https://youtu.be/osScyaGMVqo" %}
52 |
53 |
--------------------------------------------------------------------------------
/how-to/faq.md:
--------------------------------------------------------------------------------
1 | # FAQ
2 |
3 | ## Misc
4 |
5 | ### **i18next is awesome. How can I support the project?**
6 |
7 | _There are a lot of ways to support us. Make a PR for a feature requested. Improve the documentation. Help others to get started. Spread the word._
8 |
9 | _Further you could try_ [_locize.com_](http://locize.com) _- our localization as a service offering. It's like donating to i18next but with additional benefits for you - like saving hours of time translating your project._
10 |
11 | ## Loading issues
12 |
13 | ### **I don't see my translations!!!**
14 |
15 | _Try setting_ `debug: true` _on init and check the console log. There is rather sure a warning for unable to resolve the loadPath or invalid json. Check if the translation files are accessible via browser._
16 |
17 | ## Translation
18 |
19 | ### **How to translate the resource files?**
20 |
21 | 
<<How we translated the Avocode website written in Next.js with the i18next package ...>> | https://locize.com/customers.html#avocode | avocode.jpg | ||
<<... Using i18next as our international framework enables us to use the same technology around our whole software stack, regardless the actual backend or framework we use. locize is the icing on the cake – it made translation management unspeakably easier. ...> | https://locize.com/customers.html#logiscool | logiscool.jpg | ||
<<... We have separated help pages for en, ja, zh, zh-TW. i18next automatically switched the link to appropriated lang help’s page ....>> | https://locize.com/customers.html#worldshopping | worldshopping.jpg | ||
<<Using locize and its tools (i18next) saves us a LOT of time by not thinking about the texts and focusing on development only. ...>> | https://locize.com/customers.html#fideli | fideli.jpg | ||
<<... We used i18next with React and were translating JSON files by hand, which was really cumbersome. ...>> | https://locize.com/customers.html#realadvisor | realadvisor.jpg | ||
<<... Switching to locize was pretty straightforward, thanks to i18next and the possiblity to import JSON files in the admin dashboard. ...>> | https://locize.com/customers.html#photogram | photogram.jpg | ||
<<... Support was also very reactive and fixed a bug in under 1 hour after it was reported. I would recommend for use with i18next on a React.js platform.>> | https://locize.com/customers.html#beelance | beelance.jpg | ||
<<... We use i18next as an internationalization framework. locize being perfectly integrated with the framework become a really good translation management tool for us. ...>> | https://locize.com/customers.html#2captcha | 2captcha.jpg | ||
<<... Using i18next in conjunction with react-i18next (there’s an Angular, Vue and even jQuery support, among others) will help you maintain expressive code that’s i18n ready. ...>> | https://dutzi.party/utilizing-i18next/ | dutzi.jpg |
Passing this function is considered LEGACY in i18next>=21.3.0
format function function format(value, format, lng, edit) {}
true
(was false for <v21.0.0)
|Will skip to interpolate the variables, example:
t('key', { a: '$t(nested)' })
this will not resolve the nested key and will use$t(nested) as the variable value.
Another example:
t('key', { a: '{{otherVar}}': otherVar: 'another value' })
this will not resolve the otherVar variable and will use{{otherVar}}as the variable value.
If your interpolation variables are user provided or loaded from an external source, we strongly suggest to keep this option to true.
If you know what you're doing, you can also set this to false.
| 132 | 133 | ## Implications for localization 134 | 135 | Checkout the [best practices](../principles/best-practices.md#implications-of-interpolation-for-localization) on this topic. 136 | -------------------------------------------------------------------------------- /translation-function/nesting.md: -------------------------------------------------------------------------------- 1 | # Nesting 2 | 3 | Nesting allows you to reference other keys in a translation. Could be useful to build glossary terms. 4 | 5 | ## Basic 6 | 7 | keys 8 | 9 | ```javascript 10 | { 11 | "nesting1": "1 $t(nesting2)", 12 | "nesting2": "2 $t(nesting3)", 13 | "nesting3": "3", 14 | } 15 | ``` 16 | 17 | sample 18 | 19 | ```javascript 20 | i18next.t('nesting1'); // -> "1 2 3" 21 | ``` 22 | 23 | You can reference keys from other namespaces by prepending the namespace: `"nesting1": "1 $t(common:nesting2)",` 24 | 25 | ## Passing options to nestings 26 | 27 | You can pass entire data models in options. 28 | 29 | keys 30 | 31 | ```javascript 32 | { 33 | "girlsAndBoys": "They have $t(girls, {\"count\": {{girls}} }) and $t(boys, {\"count\": {{boys}} })", 34 | "boys": "{{count}} boy", 35 | "boys_other": "{{count}} boys", 36 | "girls": "{{count}} girl", 37 | "girls_other": "{{count}} girls", 38 | } 39 | ``` 40 | 41 | sample 42 | 43 | ```javascript 44 | i18next.t('girlsAndBoys', {girls: 3, boys: 2}); 45 | // -> "They have 3 girls and 2 boys" 46 | ``` 47 | 48 | {% hint style="info" %} 49 | Make sure the options string is valid JSON and can be parsed using JSON.parse 50 | 51 | `'sampleKey': 'test $t(nest2, { "changedVarName": "{{var}}" })'` 52 | {% endhint %} 53 | 54 | ## Passing nesting to interpolated 55 | 56 | keys 57 | 58 | ```javascript 59 | { 60 | "key1": "hello world", 61 | "key2": "say: {{val}}" 62 | } 63 | ``` 64 | 65 | sample 66 | 67 | ```javascript 68 | i18next.t('key2', {val: '$t(key1)'}); 69 | // -> "say: hello world" 70 | ``` 71 | 72 | {% hint style="info" %} 73 | If you're using >= v21.0.0 you need to set [skipOnVariables](../misc/migration-guide.md#skiponvariables-true) to false: 74 | 75 | ``` 76 | interpolation: { 77 | skipOnVariables: false 78 | } 79 | ``` 80 | {% endhint %} 81 | 82 | ## Additional options 83 | 84 | Prefix/Suffix for nesting and other options can be overridden in init [interpolation options](interpolation.md#all-interpolation-options) or by passing additional options to t function: 85 | 86 | sample 87 | 88 | ```javascript 89 | i18next.init({ 90 | interpolation: { ... } 91 | }); 92 | 93 | i18next.t('key', { 94 | interpolation: { ... } 95 | }); 96 | ``` 97 | 98 | | option | default | description | 99 | | -------------------- | --------- | -------------------------------------- | 100 | | nestingPrefixEscaped | undefined | escaped prefix for nesting (regexSafe) | 101 | | nestingSuffixEscaped | undefined | escaped suffix for nesting (regexSafe) | 102 | 103 | While there are a lot of options going with the defaults should get you covered. 104 | -------------------------------------------------------------------------------- /translation-function/objects-and-arrays.md: -------------------------------------------------------------------------------- 1 | # Objects and Arrays 2 | 3 | ## Objects 4 | 5 | You can return objects or arrays to be used by third party modules localization: 6 | 7 | keys 8 | 9 | ```javascript 10 | { 11 | "tree": { 12 | "res": "added {{something}}" 13 | }, 14 | "array": ['a', 'b', 'c'] 15 | } 16 | ``` 17 | 18 | sample 19 | 20 | ```javascript 21 | i18next.t('tree', { returnObjects: true, something: 'gold' }); 22 | // -> { res: 'added gold' } 23 | 24 | i18next.t('array', { returnObjects: true }); 25 | // -> ['a', 'b', 'c'] 26 | ``` 27 | 28 | The returned value supports interpolation, plurals, nesting, ... 29 | 30 | `returnObjects` can be set to true on init. 31 | 32 | ## Arrays 33 | 34 | You can access array values or join them. 35 | 36 | keys 37 | 38 | ```javascript 39 | { 40 | "arrayJoin": [ 41 | "line1", 42 | "line2", 43 | "line3" 44 | ], 45 | "arrayJoinWithInterpolation": [ 46 | "you", 47 | "can", 48 | "{{myVar}}" 49 | ], 50 | "arrayOfObjects": [ 51 | { "name": "tom" }, 52 | { "name": "steve" } 53 | ] 54 | } 55 | ``` 56 | 57 | sample 58 | 59 | ```javascript 60 | i18next.t('arrayJoin', { joinArrays: '+' }); 61 | // -> "line1+line2+line3" 62 | 63 | i18next.t('arrayJoinWithInterpolation', { myVar: 'interpolate', joinArrays: ' ' }); 64 | // -> "you can interpolate" 65 | 66 | i18next.t('arrayOfObjects.0.name'); 67 | // -> "tom" 68 | ``` 69 | 70 | The returned value supports interpolation, plurals, nesting, ... 71 | 72 | `joinArrays` can be set to a value on init. 73 | 74 | -------------------------------------------------------------------------------- /translation-function/plurals.md: -------------------------------------------------------------------------------- 1 | # Plurals 2 | 3 | Plural can be combined with interpolation, context, ... 4 | 5 | These plurals are streamlined with the one used in the [Intl API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules/PluralRules).\ 6 | &#xNAN;_You need to_ [_polyfill_](https://github.com/eemeli/intl-pluralrules) _the_ [_Intl.PluralRules_](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/PluralRules) _API._ 7 | 8 | {% hint style="danger" %} 9 | Note: The variable name must be `count`.\ 10 | And it must be present: `i18next.t('key', {count: 1});`\ 11 | There will be **no** fallback to the `'key'` value if count is not provided. 12 | {% endhint %} 13 | 14 | {% hint style="info" %} 15 | If you need multiple counts, take a look at [nesting](nesting.md#passing-options-to-nestings) 16 | {% endhint %} 17 | 18 | {% hint style="info" %} 19 | We provide the ability to have special translation for `{count: 0}`, so that a more natural language can be used. If the count is 0, and a `_zero` entry is present, then it will be used instead of the language plural suffix. 20 | {% endhint %} 21 | 22 | {% hint style="info" %} 23 | 🎓 Check out this topic in the [i18next crash course video](https://youtu.be/SA_9i4TtxLQ?t=485). 24 | {% endhint %} 25 | 26 | ## Singular / Plural 27 | 28 | keys 29 | 30 | ```javascript 31 | { 32 | "key_one": "item", 33 | "key_other": "items", 34 | "keyWithCount_one": "{{count}} item", 35 | "keyWithCount_other": "{{count}} items" 36 | } 37 | ``` 38 | 39 | sample 40 | 41 | ```javascript 42 | i18next.t('key', {count: 0}); // -> "items" 43 | i18next.t('key', {count: 1}); // -> "item" 44 | i18next.t('key', {count: 5}); // -> "items" 45 | i18next.t('key', {count: 100}); // -> "items" 46 | i18next.t('keyWithCount', {count: 0}); // -> "0 items" 47 | i18next.t('keyWithCount', {count: 1}); // -> "1 item" 48 | i18next.t('keyWithCount', {count: 5}); // -> "5 items" 49 | i18next.t('keyWithCount', {count: 100}); // -> "100 items" 50 | ``` 51 | 52 | {% hint style="warning" %} 53 | With [v21.0.0](../misc/migration-guide.md#json-format-v4-pluralization) a new [JSON format v4](../misc/json-format.md#i-18-next-json-v4) was introduced that changed the suffixes.\ 54 | To convert your existing translations to the new v4 format, have a look at [i18next-v4-format-converter](https://github.com/i18next/i18next-v4-format-converter) or [this web tool](https://i18next.github.io/i18next-v4-format-converter-web/). 55 | {% endhint %} 56 | 57 | ## Languages with multiple plurals 58 | 59 | Sample uses arabic which has 5 plural forms beside the singular. 60 | 61 | keys 62 | 63 | ```javascript 64 | { 65 | "key_zero": "zero", 66 | "key_one": "singular", 67 | "key_two": "two", 68 | "key_few": "few", 69 | "key_many": "many", 70 | "key_other": "other" 71 | } 72 | ``` 73 | 74 | sample 75 | 76 | ```javascript 77 | i18next.t('key', {count: 0}); // -> "zero" 78 | i18next.t('key', {count: 1}); // -> "singular" 79 | i18next.t('key', {count: 2}); // -> "two" 80 | i18next.t('key', {count: 3}); // -> "few" 81 | i18next.t('key', {count: 4}); // -> "few" 82 | i18next.t('key', {count: 5}); // -> "few" 83 | i18next.t('key', {count: 11}); // -> "many" 84 | i18next.t('key', {count: 99}); // -> "many" 85 | i18next.t('key', {count: 100}); // -> "other" 86 | ``` 87 | 88 | ## How to find the correct plural suffix? 89 | 90 | You can use this small utility to get the correct plural suffixes. 91 | 92 | [source code](https://jsfiddle.net/6bpxsgd4) 93 | 94 | _Or try_ [_translation-check_](https://github.com/locize/translation-check)_, it shows an overview of your translations in a nice UI. It shows also the appropriate plural forms._ 95 | 96 | #### Or you use a smart translation management system, like [locize](https://locize.com) 97 | 98 |  99 | 100 | ## Ordinal plurals 101 | 102 | There is also support for ordinal numbers _(referring to the ordering or ranking of things, e.g. "1st", "2nd", "3rd" in English)_. The `ordinal` option (and the \_ordinal suffix) tells the helper to use the ordinal digit to determine the plurality key used. E.g., for "32" the ordinal digit is "2" so `key_two` is used. 103 | 104 | keys 105 | 106 | ```javascript 107 | // i.e. english 108 | { 109 | "key_ordinal_one": "{{count}}st place", // 1st, 21st, 31st 110 | "key_ordinal_two": "{{count}}nd place", // 2nd, 22nd, 32nd 111 | "key_ordinal_few": "{{count}}rd place", // 3rd, 23rd, 33rd 112 | "key_ordinal_other": "{{count}}th place" // 4th, 5th, 24th, 11th 113 | } 114 | ``` 115 | 116 | sample 117 | 118 | ```javascript 119 | i18next.t('key', { count: 1, ordinal: true }); // -> "1st place" 120 | i18next.t('key', { count: 21, ordinal: true }); // -> "21st place" 121 | i18next.t('key', { count: 2, ordinal: true }); // -> "2nd place" 122 | i18next.t('key', { count: 11, ordinal: true }); // -> "11th place" 123 | i18next.t('key', { count: 32, ordinal: true }); // -> "32nd place" 124 | ``` 125 | 126 | ## Interval plurals 127 | 128 | Want to define phrases expressing the number of items lies in a range. Like _a few items_ or _a lot of items_. 129 | 130 | You will need to add a post processor: [i18next-intervalplural-postprocessor](https://github.com/i18next/i18next-intervalplural-postprocessor) 131 | 132 | ```javascript 133 | import i18next from 'i18next'; 134 | import intervalPlural from 'i18next-intervalplural-postprocessor'; 135 | 136 | i18next 137 | .use(intervalPlural) 138 | .init(i18nextOptions); 139 | ``` 140 | 141 | keys 142 | 143 | ```javascript 144 | { 145 | "key1_one": "{{count}} item", 146 | "key1_other": "{{count}} items", 147 | "key1_interval": "(1)[one item];(2-7)[a few items];(7-inf)[a lot of items];", 148 | "key2_one": "{{count}} item", 149 | "key2_other": "{{count}} items", 150 | "key2_interval": "(1)[one item];(2-7)[a few items];" 151 | } 152 | ``` 153 | 154 | sample 155 | 156 | ```javascript 157 | i18next.t('key1_interval', {postProcess: 'interval', count: 1}); // -> "one item" 158 | i18next.t('key1_interval', {postProcess: 'interval', count: 4}); // -> "a few items" 159 | i18next.t('key1_interval', {postProcess: 'interval', count: 100}); // -> "a lot of items" 160 | 161 | // not matching into a range it will fallback to 162 | // the regular plural form 163 | i18next.t('key2_interval', {postProcess: 'interval', count: 1}); // -> "one item" 164 | i18next.t('key2_interval', {postProcess: 'interval', count: 4}); // -> "a few items" 165 | i18next.t('key2_interval', {postProcess: 'interval', count: 100}); // -> "100 items" 166 | ``` 167 | 168 | {% hint style="danger" %} 169 | Note: The regex for the interval entry has changed in `v3.0.0` of `i18next-intervalPlural-postProcessor` so if you are using the older versions, you need to use the curly braces instead of the bracketes, e.g.: 170 | 171 | ```javascript 172 | "key2_interval": "(1){one item};(2-7){a few items};" 173 | ``` 174 | {% endhint %} 175 | --------------------------------------------------------------------------------
