{"id":22486006,"url":"https://github.com/locize/i18next-locize-backend","last_synced_at":"2025-08-02T18:34:26.765Z","repository":{"id":38310923,"uuid":"52196883","full_name":"locize/i18next-locize-backend","owner":"locize","description":"A simple i18next backend for locize.com which can be used in Node.js, in the browser and for Deno.","archived":false,"fork":false,"pushed_at":"2024-11-21T10:51:29.000Z","size":841,"stargazers_count":70,"open_issues_count":1,"forks_count":22,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-12-01T09:50:27.762Z","etag":null,"topics":["backend","fetch","i18next","locize","plugin","xhr"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/locize.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-02-21T08:03:11.000Z","updated_at":"2024-11-21T10:51:30.000Z","dependencies_parsed_at":"2024-08-21T11:52:23.618Z","dependency_job_id":null,"html_url":"https://github.com/locize/i18next-locize-backend","commit_stats":{"total_commits":268,"total_committers":15,"mean_commits":"17.866666666666667","dds":0.417910447761194,"last_synced_commit":"e0ad69ef029e2bf06d014f3a297ffaa383f5cf05"},"previous_names":[],"tags_count":98,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/locize%2Fi18next-locize-backend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/locize%2Fi18next-locize-backend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/locize%2Fi18next-locize-backend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/locize%2Fi18next-locize-backend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/locize","download_url":"https://codeload.github.com/locize/i18next-locize-backend/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228500067,"owners_count":17929995,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backend","fetch","i18next","locize","plugin","xhr"],"created_at":"2024-12-06T17:13:41.391Z","updated_at":"2025-08-02T18:34:26.750Z","avatar_url":"https://github.com/locize.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"[![Actions](https://github.com/locize/i18next-locize-backend/workflows/node/badge.svg)](https://github.com/locize/i18next-locize-backend/actions?query=workflow%3Anode)\n[![npm version](https://img.shields.io/npm/v/i18next-locize-backend.svg?style=flat-square)](https://www.npmjs.com/package/i18next-locize-backend)\n\nThis is an [i18next backend plugin](https://www.i18next.com/principles/plugins) to be used for [locize](http://locize.com) service. It will load resources from locize server using http fetch or xhr as fallback.\n\nIf you're not familiar with i18next and how i18next backend plugins works, please first have a look at the [i18next documentation](https://www.i18next.com/how-to/add-or-load-translations#load-using-a-backend-plugin).\n\nIt will allow you to save missing keys containing both **default value** and **context information** by calling:\n\n```js\ni18next.t(key, defaultValue, tDescription);\ni18next.t(key, { defaultValue, tDescription });\n```\n\n## Advice:\n\nTo see i18next-locize-backend in a working app example, you may have a look at:\n\n- [this react-tutorial](https://github.com/locize/react-tutorial) starting from [Step 2](https://github.com/locize/react-tutorial#step-2---use-the-locize-cdn)\n- [this guide](https://www.locize.com/blog/react-i18next) starting from the step of [replacing i18next-http-backend with i18next-locize-backend](https://www.locize.com/blog/react-i18next#how-look)\n- [this Angular blog post](https://locize.com/blog/angular-i18next) [introducing i18next-locize-backend](https://locize.com/blog/angular-i18next/#how-look)\n- [the code integration part](https://www.youtube.com/watch?v=TFV_vhJs5DY\u0026t=294s) in this [YouTube video](https://www.youtube.com/watch?v=TFV_vhJs5DY)\n# Troubleshooting\n\nMake sure you set the `debug` option of i18next to `true`. This will maybe log more information in the developer console.\n\n**SaveMissing is not working**\n\nDid you wait 5-10 seconds before refreshing the locize UI? It may take a couple of seconds until the missing keys are sent and saved.\n\nPer default only `localhost` is allowed to send missing keys ([or update missing keys](https://www.i18next.com/overview/configuration-options#missing-keys)) (to avoid using this feature accidentally [in production](https://www.locize.com/docs/going-to-production)). If you're not using `localhost` during development you will have to set the `allowedAddOrUpdateHosts: ['your.domain.tld']` for the [backend options](https://github.com/locize/i18next-locize-backend#backend-options).\n\nIt's also recommended to set the `fallbackLng` equal to the source language defined in locize. i.e. if your source language in locize is `de`, set the fallbackLng also to `de`.\n\n\n**Loading translations not working**\n\nMake sure the translations are published, either by having enabled auto publishing for your version or by [manually publishing](https://www.locize.com/docs/how-to-manually-publish-a-specific-version) the version. Alternatively, you can publish via [CLI](https://github.com/locize/locize-cli#publish-version) or directly by consuming the [API](https://www.locize.com/docs/api#publish-version).\n\nIn case you're using the private publish mode, make sure you're using the correct api key and are setting the `private` option to `true`.\n\n```javascript\nimport i18next from \"i18next\";\nimport Locize from \"i18next-locize-backend\";\n\ni18next.use(Locize).init({\n  backend: {\n    projectId: \"[PROJECTID]\",\n    apiKey: \"[APIKEY]\",\n    version: \"[VERSION]\",\n    private: true,\n    referenceLng: \"en\"\n  }\n});\n```\n\n\n**On server side: process is not exiting**\n\nIn case you want to use i18next-locize-backend on server side for a short running process, you might want to set the `reloadInterval` option to `false`:\n\n```javascript\n{\n  reloadInterval: false,\n  projectId: \"[PROJECTID]\",\n  version: 'latest',\n  referenceLng: 'en',\n}\n```\n\n**Not all languages are loaded**\n\nBy default the supportedLngs are defined by having a minimum of 90% of done translations.\nYou can set a threshold for languages to be added to supportedLngs by setting translatedPercentageThreshold in backend options (eg: 1 = 100% translated, 0.9 = 90% translated).\n\n# Getting started\n\nSource can be loaded via [npm](https://www.npmjs.com/package/i18next-locize-backend), `yarn`, `bower` or [downloaded](https://cdn.rawgit.com/locize/i18next-locize-backend/master/i18nextLocizeBackend.min.js) from this repo.\n\n```bash\n# npm package\n$ npm install i18next-locize-backend\n\n# yarn\n$ yarn add i18next-locize-backend\n\n# bower\n$ bower install i18next-locize-backend\n```\n\nWiring up:\n\n```js\nimport i18next from 'i18next';\nimport Locize from 'i18next-locize-backend';\n// or\nconst i18next = require('i18next');\nconst Locize = require('i18next-locize-backend');\n\ni18next.use(Locize).init(i18nextOptions);\n```\n\nfor Deno:\n\n```js\nimport i18next from 'https://deno.land/x/i18next/index.js'\nimport Backend from 'https://deno.land/x/i18next_locize_backend/index.js'\n\ni18next.use(Backend).init(i18nextOptions);\n```\n\n- As with all modules you can either pass the constructor function (class) to the i18next.use or a concrete instance.\n- If you don't use a module loader it will be added to `window.i18nextLocizeBackend`\n\n## Backend Options\n\n**IMPORTANT** make sure you do not add your apiKey in the production build to avoid misuse by strangers\n\n```js\n{\n  // the id of your locize project\n  projectId: '[PROJECTID]',\n\n  // add an api key if you want to send missing keys\n  apiKey: '[APIKEY]',\n\n  // the reference language of your project\n  referenceLng: '[LNG]',\n\n  // version - defaults to latest\n  version: '[VERSION]',\n\n  // private - set to true if you version on locize is set to use private publish\n  private: false,\n\n  // hostnames that are allowed to create, update keys\n  // please keep those to your local system, staging, test servers (not production)\n  // can be array of allowed hosts or a function (hostname) =\u003e { return true; // or false if not allowed }\n  allowedAddOrUpdateHosts: ['localhost'],\n\n  // optional event triggered on saved to backend\n  onSaved: (lng, ns) =\u003e { ... },\n\n  // can be used to reload resources in a specific interval (useful in server environments)\n  reloadInterval: typeof window !== 'undefined' ? false : 60 * 60 * 1000,\n  \n  // define the threshold for languages to be added to supportedLngs (eg: 1 = 100% translated, 0.9 = 90% translated [default]).\n  translatedPercentageThreshold: 0.8,\n\n  // define a custom request function\n  // can be used to support Angular http client\n  //\n  // 'info' contains 'url', 'method', 'body' and 'headers'\n  //   'url' the url that should be requested\n  //   'method' GET for fetching translations and POST for saving missing translations\n  //   'body' will be a key:value object used when saving missing translations\n  //   'headers' will be a key:value object containing the header information that should be sent\n  // 'callback' is a function that takes two parameters, 'err' and 'res'.\n  //            'err' should be an error\n  //            'res' should be an object with a 'status' property and a 'data' property containing a stringified object instance beeing the key:value translation pairs for the\n  //            requested language and namespace, or null in case of an error.\n  request: function (info, callback) {},\n  // or async / promise\n  //request: async (info) {},\n}\n```\n\nTo load translations only `projectId` needs to be filled. To use the **saveMissing** feature of i18next additional to the projectId both `apiKey` and `referenceLng` have to be set.\n\nOptions can be passed in:\n\n**preferred** - by setting options.backend in i18next.init:\n\n```js\nimport i18next from \"i18next\";\nimport Locize from \"i18next-locize-backend\";\n\ni18next.use(Locize).init({\n  backend: options\n});\n```\n\non construction:\n\n```js\nimport Locize from \"i18next-locize-backend\";\nconst locize = new Locize(options);\n```\n\nvia calling init:\n\n```js\nimport Locize from \"i18next-locize-backend\";\nconst locize = new Locize();\nlocize.init(options);\n```\n\n## Additional API endpoints\n\n### backend.getLanguages\n\nWill return a list of all languages in your project including percentage of translations done per version.\n\n```js\nimport Locize from \"i18next-locize-backend\";\nconst locize = new Locize(options);\n\nlocize.getLanguages((err, data) =\u003e {\n  /*\n  data is:\n\n  {\n    \"en\": {\n      \"name\": \"English\",\n      \"nativeName\": \"English\",\n      \"isReferenceLanguage\": true,\n      \"translated\": {\n        \"latest\": 1\n      }\n    },\n    \"de\": {\n      \"name\": \"German\",\n      \"nativeName\": \"Deutsch\",\n      \"isReferenceLanguage\": false,\n      \"translated\": {\n        \"latest\": 0.9\n      }\n    }\n  }\n  */\n});\n\n// or\nconst data = await locize.getLanguages();\n\n// or\ni18next.services.backendConnector.backend.getLanguages(callback);\n\n// or\nconst data = await i18next.services.backendConnector.backend.getLanguages();\n```\n\n### backend.getOptions\n\nWill return an object containing useful informations for the i18next init options.\n\n```js\nimport Locize from \"i18next-locize-backend\";\nconst locize = new Locize(options);\n\nlocize.getOptions((err, data) =\u003e {\n  /*\n  data is:\n\n  {\n    fallbackLng: 'en',\n    referenceLng: 'en',\n    supportedLngs: ['en', 'de'],\n    load: 'languageOnly|all' // depending on your supportedLngs has locals having region like en-US\n  }\n  */\n});\n\n// or\nconst data = await locize.getOptions();\n\n// or\ni18next.services.backendConnector.backend.getOptions(callback);\n\n// or\nconst data = await i18next.services.backendConnector.backend.getOptions();\n```\n\nYou can set a threshold for languages to be added to supportedLngs by setting translatedPercentageThreshold in backend options (eg: 1 = 100% translated, 0.9 = 90% translated).\n\n## SPECIAL - let the backend determine some options to improve loading\n\nYou can load some information from the backend to eg. set supportedLngs for i18next just supporting languages you got in your locize project.\n\nYou will get i18next options for (same as above backend.getOptions):\n\n- fallbackLng\n- supportedLngs\n- load\n\n```js\nimport i18next from \"i18next\";\nimport Locize from \"i18next-locize-backend\";\n\nconst locize = new Locize(\n  {\n    projectId: \"[PROJECTID]\",\n    apiKey: \"[APIKEY]\",\n    version: \"[VERSION]\"\n    // referenceLng -\u003e not needed as will be loaded from API\n  },\n  (err, opts, lngs) =\u003e {\n    i18next.use(locize).init({ ...opts, ...yourOptions }); // yourOptions should not include backendOptions!\n  }\n);\n```\n\n### Special usage with react-i18next without using Suspense\n\nUse `setI18n` to pass in the i18next instance before initializing:\n\n```js\nimport i18n from \"i18next\";\nimport { initReactI18next, setI18n } from \"react-i18next\";\nimport LocizeBackend from \"i18next-locize-backend\";\n\nconst backendOptions = {\n  projectId: \"1d0aa5aa-4660-4154-b6d9-907dbef10bb3\"\n};\n\nconst yourOptions = {\n  debug: true,\n  interpolation: {\n    escapeValue: false\n  },\n  react: {\n    useSuspense: false\n  }\n};\n\n// this is only used if not using suspense\ni18n.options.react = yourOptions.react;\nsetI18n(i18n);\n\nconst backend = new LocizeBackend(backendOptions, (err, opts) =\u003e {\n  if (err) return console.error(err);\n  i18n\n    .use(backend)\n    // .use(initReactI18next) // keep this if using suspense\n    // yourOptions should not include backendOptions!\n    .init({ ...opts, ...yourOptions }, (err, t) =\u003e {\n      if (err) return console.error(err);\n    });\n});\n\nexport default i18n;\n```\n\n## IMPORTANT ADVICE FOR SERVERLESS environments - AWS lambda, Google Cloud Functions, Azure Functions, etc...\n\n\u003cfont color=\"red\"\u003e\n  \u003cb\u003ePlease be aware\u003c/b\u003e\n\u003c/font\u003e\n\nDue to how serverless functions work, you cannot guarantee that a cached version of your data is available. Serverless functions are short-lived, and can shut down at any time, purging any in-memory or filesystem cache. This may be an acceptable trade-off, but sometimes it isn't acceptable.\n\n**Because of this we suggest to download the translations in your CI/CD pipeline (via [cli](https://github.com/locize/locize-cli#download-current-published-files) or via [api](https://www.locize.com/docs/api#list-all-namespace-resources)) and package them with your serverless function.**\n\n### For example with [i18next-fs-backend](https://github.com/i18next/i18next-fs-backend)\n\n```js\nimport i18next from 'i18next';\nimport Backend from 'i18next-fs-backend';\n\nconst backend = new Backend({\n  // path where resources get loaded from\n  loadPath: '/locales/{{lng}}/{{ns}}.json'\n});\n\ni18next\n  .use(backend)\n  .init({\n    // initImmediate: false, // setting initImediate to false, will load the resources synchronously\n    ...opts,\n    ...yourOptions\n  }); // yourOptions should not include backendOptions!\n```\n\n### or just [import/require](https://www.i18next.com/how-to/add-or-load-translations#add-on-init) your files directly\n\n```js\nimport i18next from 'i18next';\nimport en from './locales/en.json'\nimport de from './locales/de.json'\n\ni18next\n  .init({\n    ...opts,\n    ...yourOptions,\n    resources: {\n      en,\n      de\n    }\n  });\n```\n## TypeScript\n\nTo properly type the backend options, you can import the `LocizeBackendOptions` interface and use it as a generic type parameter to the i18next's `init` method, e.g.:\n\n```ts\nimport i18n from 'i18next'\nimport LocizeBackend, { LocizeBackendOptions } from 'i18next-locize-backend'\n\ni18n\n  .use(LocizeBackend)\n  .init\u003cLocizeBackendOptions\u003e({\n    backend: {\n      // locize backend options\n    },\n\n    // other i18next options\n  })\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocize%2Fi18next-locize-backend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flocize%2Fi18next-locize-backend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocize%2Fi18next-locize-backend/lists"}