i18next / i18next-localstorage-backend

This is a i18next cache layer to be used in the browser. It will load and cache resources from localStorage and can be used in combination with the chained backend.

i18next: learn once - translate everywhere

i18next is a very popular internationalization framework for browser or any other javascript environment (eg. Node.js, Deno).

i18next provides:

• Flexible connection to backend (loading translations via xhr, ...)
• Optional caching, user language detection, ...
• Proper pluralizations
• Translation context
• Nesting, Variable replacement
• Flexibility: Use it everywhere
• Extensibility: eg. sprintf
• ...

For more information visit the website:

• Getting started
• Translation Functionality
• API

Our focus is providing the core to building a booming ecosystem. Independent of the building blocks you choose, be it react, angular or even good old jquery proper translation capabilities are just one step away.

Documentation

The general i18next documentation is published on www.i18next.com and PR changes can be supplied here.

The react specific documentation is published on react.i18next.com and PR changes can be supplied here.

---

Gold Sponsors

---

From the creators of i18next: localization as a service - locize.com

A translation management system built around the i18next ecosystem - locize.com.

With using locize you directly support the future of i18next.

---

i18next-localstorage-backend's Issues

Implementing Default Versions to Clear Cache

When trying to implement the default version feature I found a bug.

Repo Code:
https://github.com/i18next/i18next-localstorage-backend/blob/master/i18nextLocalStorageBackend.js#L146

Inside the if statement the logic is such that it will never clear cache when version is updated. The current logic statues that if the time expires and the version is the same then clear cache. But, it does not address if the version is different clear cache. The logic should be:
if ( local.i18nStamp && local.i18nStamp + this.options.expirationTime < nowMS || version !== local.i18nVersion)

Could this bug fix be made to the repo? Or advise if further details on my implementation are needed.

Cache fallback values in the users language

🚀 Feature Proposal

Add option to cache translations of the fallback language for the originally requested language.

Motivation

If translations for a language do not exist and the fallback language is used, it would make sense to cache that result for the requested language to avoid multiple requests that always result in a 404.

If translations in the requested language do not exist, we make a bunch of 404 requests with the HTTP backend.
Then the fallback language is used and the translations are cached for the fallback language.
If the user reloads the page, they have to go through the 404 requests again before falling back to the cache.
This could be avoided

Example

Imagine a setup with a localstorage-backend before a http-backend:

• A user with language DE visits the site
• DE translations are not available in localstorage
• Requests are made to the http-backend returning 404
• The fallback language is used

Whenever the page is reloaded the 404ing requests would be repeated.

Versions doco

Could you please expand on your explanation of the versions option? I don't really understand how it's supposed to be used.

I want to know how to invalidate the local storage cache of my user when releasing a new version of my translations. How can I do that?

Thanks

Benchmarks vs browser cache

Hi, when is a good time to use this backend vs relying on the browser cache? Localstorage isn't particularly fast. Has there been a benchmark that shows this is faster? Often re-fetching it is even faster than localstorage retrieval in cases like mobile. Thanks.

Version option for all languages.

In general, we always update all of the language files when the strings are updated.
So this option will be very helpful as well:

      backendOptions: {
        prefix: 'i18next_res_',
        versions: 'v1.0',
      },

Dynamic versions

It would be great if this library could have an option to allow for a version to be passed with the incoming XHR response. If the version of the response JSON is different from version of the localStorage JSON, then the localStorage data is updated. The order of events would be:

1. i18next first loads from localStorage like normal.
2. In background, i18next sends an XHR request to backend. If the version of the response is different from version stored in localStorage, then update localstorage with newest version and load newest version.

In this scenario the current version number would also be stored in localStorage. It would be compared against the XHR response's version. The XHR response could provide the version number in an HTTP header, or perhaps a dedicated string key in the file that is named something like "I18NEXT_VERSION_NUMBER".

This would be really useful as a developer so I don't have to manually change the version number on the frontend every time I have a new version on my server.

Translations are not set to localStorage

Why my translations are not set automatically to the locaStorage. am I missing something?
BTW, i tried to call it manually with i18next.services.backendConnector.backend.backends[0].save('en', [ns], { translation }) and i am able to see it on LocalStorage.

Also, how can I validate that subsequent requests for the same translations will be served directly from the local storage cache?

Here is my config

i18n
  .use(LanguageDetector)
  .use(LocalStorageBackend)
  .use(initReactI18next)
  .init({
    debug: true, // Set this to true to see logs in the console
    fallbackLng: "en",
    resources: {
      en: {
        translation: {
          greeting: "Hello, World!",
          language: "English",
        },
      },
      ar: {
        translation: {
          greeting: "مرحبًا بالعالم!",
          language: "العربية",
        },
      },
    },
    backend: {
      backends: [LocalStorageBackend],
      backendOptions: [
        {
          expirationTime: 7 * 24 * 60 * 60 * 1000, // 7 days
          versions: {
            en: "v1.0.0",
            ar: "v1.0.0",
          },
        },
      ],
    },
  });

Your Environment

• i18next version: i.e. 21.6.16
• os: Mac

Can't find the API reference for backendOptions option

I've searched almost everywhere, but I can't find any explanation for the backendOptions option. For what is the first parameter, for what the second (and thrid)?

Please clarify this:

...
      backend: {
        backends: [
          resourcesToBackend(bundledResources),
          LocalStorageBackend,
          HttpBackend
        ],
        backendOptions: [{
            // options below <--- for what is this
          },
          {
            prefix: "imv_resource_", // prefix for stored languages
            expirationTime: 4 * 24 * 60 * 60 * 1000, // 4 days
            loadPath: "/locales/{{lng}}/{{ns}}.json"
          },
          {
            // shall i put there a third one as fallback?
            // f. e. loadPath: "/locales/{{lng}}/{{ns}}.json"
          }
        ],
      },
...

Thank you, anyway great work.

SWR behavior

🚀 Feature Proposal

Implement SWR behavior, that the cached data is returned while new data are fetched in the background.

Motivation

This can help prevent the splash blank page while the translation data are loading.

Provide support for indexedDB and localforage

🚀 Feature Proposal

Add support for indexedDB and localforage library in addition to localstorage

Motivation

Right now, You could only store permanent translation cache in local storage which has some known issues e.g. It's synchronous blocking the UI, this could be problematic if the file has so many translation keys. IndexedDB is much better. Also, you could go further and support localforage library which wraps all of these technologies and fallbacks to local storage if the user browser doesn't support them

Namespaces added via addResourceBundle after init to localstorage/cache

Is it possible to store namespaces that are added after init via addResourceBundle in localstorage?

I asked the question on stackoverflow and have not had an answer.

---

Question posted on stackoverflow: https://stackoverflow.com/questions/74475045/addresourcebundle-after-init-and-cacheing

I am fetching namespaces for each component from a database that store JSON and adding them via addResourceBundle after init:

    // Component
          i18next.addResourceBundle('ar', 'topicNS', {
            topics,
          });

I would like to add these to the cache/localstorage. I am using the localStorageBackend to cache the static JSON resources, how can I add to the cached namespaces after init?

I have tried using the resourcesToBackend plugin, but am not sure how to make it work.

    // i18n.js
        backend: {
          backends: [
            LocalStorageBackend,
            HttpApi,
            resourcesToBackend((language, namespace, callback) => {
              // ???????
            }),
          ],
          loadPath: `${process.env.PUBLIC_URL}/locales/{{lng}}/{{ns}}.json`,
        },

Uncaught error thrown in localStorage-blocked environment (e.g. iframe)

🐛 Bug Report

Hello,
When a library is running in an environment that blocks localStorage from access, whenever it tries to run window.localStorage the env throws error, e.g.:

Error: Failed to read the 'localStorage' property from 'Window': The document is sandboxed and lacks the 'allow-same-origin' flag.

To Reproduce

Make any minimal example, open about:blank, replace body with <iframe src="<link_to_your_example>" />.

Expected behavior

Library silently (or verbosely) fails to run.

Cache is not always being cleaned when increasing the version

🐛 Bug Report

I'm using i18next-localstorage-backend and i18next-http-backend on my React app. I set the defaultVersion to be the same as my package.json's. When increasing the version, the translations are not always fetched. Looking at the Local Storage, version is updated but the new missing translations are not being fetched.

I checked #23 and it seems that the problem was fixed, but probably it has arisen again.

Your Environment

• runtime version: node v14.17.5, React v18.0.0
• i18next version: 21.6.11
• i18next-localstorage-backend version: "3.1.3"
• os: Windows

[Feature] Fallback if missing keys

So let say i18next-localstorage-backend cached the following resource:

{
     "keyA": "valueA
}

Current Behavior

If the code request for t("keyB"), it will return the default value and will not fallback to other backends.

Feature Request

If the code request for t("keyB"), is it possible to fallback to the next backend (e.g. i18next-xhr-backend)?

Get the REST API data translations stored in localstorage

🐛 Bug Report

Hi all, I'm facing problem related to this same issue #48 , but I have set my locales to my public dir, so there is no in-memory translation resources.
I read all docs and closed issues even i18next-localstorage-backend and halfway I am stuck on how to get the translations in localStorage.

I'm using react-i18next, i18next-browser-languagedetector, i18next-http-backend, i18next-localstorage-backend and i18next-chained-backend.

So here is my process:

• I am fetching the REST API data and storing in localStorage and trying to translate that data and want to show it in page.

To Reproduce

my i18n.js config file:

import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import LanguageDetector from "i18next-browser-languagedetector";
import HttpBackend from "i18next-http-backend";
import LocalStorageBackend from "i18next-localstorage-backend";
import ChainedBackend from "i18next-chained-backend";

const detectorOptions = {
  order: ["cookie", "localStorage", "navigator"],
  lookupCookie: "locales",
  lookupLocalStorage: "locales",
  caches: ["localStorage", "cookie"],
  checkWhiteList: true,
};

i18n
  .use(ChainedBackend)
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    debug: true,
    fallbackLng: "en",
    ns: "translation",
    load: "languageOnly",  
    detection: detectorOptions,
    whitelist: ["en", "zh", "jp", "fr"],
    interpolation: {
      escapeValue: false,
    },
    backend: {
      backends: [LocalStorageBackend, HttpBackend],
      backendOptions: [
        {
          prefix: "i18next_res_",
          expirationTime: 7 * 24 * 60 * 60 * 1000, //for 7 days
        },

        {
          loadPath: "/locales/{{lng}}/translation.json",
        },
      ],
    },
    react: {
      useSuspense: false,
    },
  });

export default i18n;

translation.json:

{
  "data": [
    {
      "title": "{{title}}",
      "body": "{{body}}"
    }
  ]
}

I saw this

//
"arrayJoinWithInterpolation": [
        "you",
        "can",
        "{{myVar}}"
      ],

i18next.t('arrayJoinWithInterpolation', { myVar: 'interpolate'});

from Objects and Arrays
and tried like this interpolation {{myvar}} but doesn't work for me.

Demo.js:

const { t } = useTranslation();
  const [data, setData] = useState([]);

  useEffect(() => {
    axios
      .get("https://jsonplaceholder.typicode.com/posts")
      .then((res) => {
        localStorage.setItem("data", JSON.stringify(res.data.slice(0, 3)));
        setData(JSON.parse(localStorage.getItem("data")));
      })
      .catch((err) => {
        console.log(err);
      });
  }, []);

return (<>
     <section>
        {data.map((i, index) => {
          return (
            <>
              <div key={index}>
                <h4>{t("title", { title: i.title })}</h4>
                <p>{i.body}</p>
              </div>
            </>
          );
        })}
      </section>
  </>)

This what I'm getting some changes in my localStorage:

Also, have one more question, Is it okay to use both load and whitelist or one of them?
Can you give some suggestions on this issue?

Expected behavior

I am expecting to get translations in localstorage.

Your Environment

• runtime version: i.e. node v16
• i18next version: i.e. 23.7.6
• os: Windows

empty string as default version breaks expiry validation

Hi,

noticed that my geti18n endpoint receives requests although its data is definitely already stored. Providing defaultVersion: anyString fixed it.

https://github.com/i18next/i18next-localstorage-backend/blob/master/src/index.js#L33
ensures the default version is an empty string

https://github.com/i18next/i18next-localstorage-backend/blob/master/src/index.js#L85
falls back to the defaultValue if none was provided for the current language
right after, it checks whether a version was found and only then sets it - '' is falsy though, so the value won't get set

https://github.com/i18next/i18next-localstorage-backend/blob/master/src/index.js#L69
which leads to this always being false, leading to a permanent refetch

proposed solutions:

• unconditionally set version in save: data.i18nVersion = this.getVersion(language); - would lead to an unecessary key in localStorage though
• more validation logic against this.options.defaultVersion in read

Both sound kinda stupid to me right now, but that's because I've been debugging this for an hour and now its past 4 am. 😅 I can create a PR later.

Error: "window is not defined" while using this package in NextJS environment

🐛 Bug Report

I'm getting an error on i18next-localstorage-backend:

(node:79871) UnhandledPromiseRejectionWarning: ReferenceError: window is not defined
    at getDefaults (/Users/bert/Project/projectname/node_modules/i18next-localstorage-backend/dist/cjs/i18nextLocalStorageBackend.js:51:12)

To Reproduce

Use this package in a NextJS environment.

Expected behavior

We expect that this package handles 'window' in SSR environments by, for example, checking for the 'window' variable and ignoring SSR.

Your Environment

Relevant packages in package.json:

 "dependencies": {
    
    "i18next": "^20.2.4",
    "i18next-chained-backend": "^3.0.2",
    "i18next-http-backend": "^1.2.4",
    "i18next-localstorage-backend": "^3.1.2",
  
    "next": "10.2.0",

    "react": "17.0.2",
    "react-children-utilities": "^2.5.0",
    "react-dom": "17.0.2",
 
    "react-i18next": "^11.8.15",
  
    "react-router-dom": "^5.2.0",

  },

Typescript types

Kinda related to i18next/i18next-xhr-backend#295

If I want to add typescript type. Should I prefer DefinitivelyTyped or here ?

Missing lint packages

After working with this package today I found this issue which would be helpful for future development:

Adding the script:

"lint": "eslint ./src/*"

to the package.json eslint fails to run.

Eslint cites:

Tavurth i18next-localstorage-backend > yarn lint
yarn lint v0.18.1
$ eslint ./src/*

Oops! Something went wrong! :(

ESLint couldn't find the plugin "eslint-plugin-jsx-a11y". This can happen for a couple different reasons:

And numerous other missing packages.

Perhaps we could add these to the package.json?

eslint-plugin-jsx-a11y
eslint-plugin-react
eslint-plugin-import

Which then fails with:

$ eslint ./src/*
/Users/Tavurth/projects/i18next-localstorage-backend/node_modules/eslint-config-airbnb-base/rules/style.js:
	Configuration for rule "no-restricted-syntax" is invalid:
	Value "[object Object]" must be an enum value.

Referenced from: /Users/Tavurth/projects/i18next-localstorage-backend/node_modules/eslint-config-airbnb-base/index.js
Referenced from: airbnb
Referenced from: /Users/Tavurth/projects/i18next-localstorage-backend/.eslintrc
Error: /Users/Tavurth/projects/i18next-localstorage-backend/node_modules/eslint-config-airbnb-base/rules/style.js:
	Configuration for rule "no-restricted-syntax" is invalid:
	Value "[object Object]" must be an enum value.

Referenced from: /Users/Tavurth/projects/i18next-localstorage-backend/node_modules/eslint-config-airbnb-base/index.js
Referenced from: airbnb
Referenced from: /Users/Tavurth/projects/i18next-localstorage-backend/.eslintrc
    at validateRuleOptions (/Users/Tavurth/projects/i18next-localstorage-backend/node_modules/eslint/lib/config/config-validator.js:109:15)
    at Object.keys.forEach.id (/Users/Tavurth/projects/i18next-localstorage-backend/node_modules/eslint/lib/config/config-validator.js:156:13)
    at Array.forEach (<anonymous>)
    at Object.validate (/Users/Tavurth/projects/i18next-localstorage-backend/node_modules/eslint/lib/config/config-validator.js:155:35)
    at load (/Users/Tavurth/projects/i18next-localstorage-backend/node_modules/eslint/lib/config/config-file.js:529:19)
    at configExtends.reduceRight (/Users/Tavurth/projects/i18next-localstorage-backend/node_modules/eslint/lib/config/config-file.js:391:36)
    at Array.reduceRight (<anonymous>)
    at applyExtends (/Users/Tavurth/projects/i18next-localstorage-backend/node_modules/eslint/lib/config/config-file.js:362:28)
    at load (/Users/Tavurth/projects/i18next-localstorage-backend/node_modules/eslint/lib/config/config-file.js:536:22)
    at configExtends.reduceRight (/Users/Tavurth/projects/i18next-localstorage-backend/node_modules/eslint/lib/config/config-file.js:391:36)
error Command failed with exit code 1.

Which was fixed by:

Upgrading eslint to 4.x.

Which fails with:

Error: Cannot find module 'escope'

Finally, we can run yarn lint.

The script then fails with:

Tavurth i18next-localstorage-backend > yarn lint
yarn lint v0.18.1
$ eslint ./src/*

/Users/Tavurth/projects/i18next-localstorage-backend/src/index.js
   5:9   error  'window' is not defined                                 no-undef
   7:9   error  'window' is not defined                                 no-undef
  14:9   error  'window' is not defined                                 no-undef
  16:16  error  'window' is not defined                                 no-undef
  45:3   error  Expected to return a value at the end of method 'read'  consistent-return
  46:11  error  'store' is assigned a value but never used              no-unused-vars
  49:10  error  'window' is not defined                                 no-undef
  74:9   error  'window' is not defined                                 no-undef
  75:7   error  Assignment to property of function parameter 'data'     no-param-reassign
  79:9   error  Assignment to property of function parameter 'data'     no-param-reassign

/Users/Tavurth/projects/i18next-localstorage-backend/src/utils.js
   1:5   error    'arr' is never reassigned. Use 'const' instead                                                                                                                         prefer-const
   2:5   error    'each' is never reassigned. Use 'const' instead                                                                                                                        prefer-const
   3:5   error    'slice' is never reassigned. Use 'const' instead                                                                                                                       prefer-const
   3:5   error    Use object destructuring                                                                                                                                               prefer-destructuring
   6:24  error    Use the rest parameters instead of 'arguments'                                                                                                                         prefer-rest-params
   6:39  error    Unexpected function expression                                                                                                                                         prefer-arrow-callback
   6:39  warning  Unexpected unnamed function                                                                                                                                            func-names
   6:47  error    Missing space before function parentheses                                                                                                                              space-before-function-paren
   8:7   error    for..in loops iterate over the entire prototype chain, which is virtually never what you want. Use Object.{keys,values,entries}, and iterate over the resulting array  no-restricted-syntax
   8:12  error    Unexpected var, use let or const instead                                                                                                                               no-var
   8:12  error    All 'var' declarations must be at the top of the function scope                                                                                                        vars-on-top
   9:38  error    Assignment to property of function parameter 'obj'                                                                                                                     no-param-reassign
  17:24  error    Use the rest parameters instead of 'arguments'                                                                                                                         prefer-rest-params
  17:39  warning  Unexpected unnamed function                                                                                                                                            func-names
  17:39  error    Unexpected function expression                                                                                                                                         prefer-arrow-callback
  17:47  error    Missing space before function parentheses                                                                                                                              space-before-function-paren
  19:7   error    The body of a for-in should be wrapped in an if statement to filter unwanted properties from the prototype                                                             guard-for-in
  19:7   error    for..in loops iterate over the entire prototype chain, which is virtually never what you want. Use Object.{keys,values,entries}, and iterate over the resulting array  no-restricted-syntax
  19:12  error    Unexpected var, use let or const instead                                                                                                                               no-var
  19:12  error    All 'var' declarations must be at the top of the function scope                                                                                                        vars-on-top
  20:9   error    Assignment to property of function parameter 'obj'                                                                                                                     no-param-reassign
  28:1   error    Expected indentation of 2 spaces but found 1 tab                                                                                                                       indent
  28:2   error    Unexpected tab character                                                                                                                                               no-tabs
  28:2   error    Unexpected var, use let or const instead                                                                                                                               no-var
  29:1   error    Expected indentation of 2 spaces but found 1 tab                                                                                                                       indent
  29:2   error    Unexpected tab character                                                                                                                                               no-tabs
  29:9   warning  Unexpected unnamed function                                                                                                                                            func-names
  29:17  error    Missing space before function parentheses                                                                                                                              space-before-function-paren
  30:1   error    Expected indentation of 4 spaces but found 2 tabs                                                                                                                      indent
  30:2   error    Unexpected tab character                                                                                                                                               no-tabs
  30:3   error    Split 'var' declarations into multiple statements                                                                                                                      one-var
  30:3   error    Unexpected var, use let or const instead                                                                                                                               no-var
  30:23  error    Expected variable declaration to be on a new line                                                                                                                      one-var-declaration-per-line
  30:30  error    Use the rest parameters instead of 'arguments'                                                                                                                         prefer-rest-params
  31:1   error    Expected indentation of 4 spaces but found 2 tabs                                                                                                                      indent
  31:2   error    Unexpected tab character                                                                                                                                               no-tabs
  31:3   error    Unexpected var, use let or const instead                                                                                                                               no-var
  31:15  warning  Unexpected unnamed function                                                                                                                                            func-names
  31:23  error    Missing space before function parentheses                                                                                                                              space-before-function-paren
  32:1   error    Expected indentation of 6 spaces but found 3 tabs                                                                                                                      indent
  32:2   error    Unexpected tab character                                                                                                                                               no-tabs
  33:1   error    Expected indentation of 6 spaces but found 3 tabs                                                                                                                      indent
  33:2   error    Unexpected tab character                                                                                                                                               no-tabs
  34:1   error    Expected indentation of 4 spaces but found 2 tabs                                                                                                                      indent
  34:2   error    Unexpected tab character                                                                                                                                               no-tabs
  35:1   error    Expected indentation of 4 spaces but found 2 tabs                                                                                                                      indent
  35:2   error    Unexpected tab character                                                                                                                                               no-tabs
  35:3   error    Unexpected var, use let or const instead                                                                                                                               no-var
  36:1   error    Expected indentation of 4 spaces but found 2 tabs                                                                                                                      indent
  36:2   error    Unexpected tab character                                                                                                                                               no-tabs
  37:1   error    Expected indentation of 4 spaces but found 2 tabs                                                                                                                      indent
  37:2   error    Unexpected tab character                                                                                                                                               no-tabs
  38:1   error    Expected indentation of 4 spaces but found 2 tabs                                                                                                                      indent
  38:2   error    Unexpected tab character                                                                                                                                               no-tabs
  39:1   error    Expected indentation of 2 spaces but found 1 tab                                                                                                                       indent
  39:2   error    Unexpected tab character                                                                                                                                               no-tabs
  40:2   error    Unnecessary semicolon                                                                                                                                                  no-extra-semi

✖ 67 problems (63 errors, 4 warnings)
  29 errors, 0 warnings potentially fixable with the `--fix` option.

error Command failed with exit code 1.

Locize requests are submitted after caching.

🐛 Bug Report

After caching results subsequent requests are submitted to locize service on page refresh.

To Reproduce

GitHub repo

Expected behavior

No subsequent requests to locize after caching.

Your Environment

• runtime version:
  • node v14.17.5
  • Chrome Version 93.0.4577.63 (Official Build) (x86_64)
• module version:
  • "i18next-locize-backend": "^4.2.3",
• os: Mac