{"id":13515389,"url":"https://github.com/i18next/i18next-http-backend","last_synced_at":"2025-04-29T18:52:35.005Z","repository":{"id":37702862,"uuid":"255368483","full_name":"i18next/i18next-http-backend","owner":"i18next","description":"i18next-http-backend is a backend layer for i18next using in Node.js, in the browser and for Deno.","archived":false,"fork":false,"pushed_at":"2025-04-04T08:45:52.000Z","size":5446,"stargazers_count":479,"open_issues_count":3,"forks_count":71,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-28T11:06:27.391Z","etag":null,"topics":["backend","deno","fetch","i18next","javascript","nodejs","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/i18next.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"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},"funding":{"github":["jamuhl","adrai"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":"https://locize.com"}},"created_at":"2020-04-13T15:37:02.000Z","updated_at":"2025-04-22T08:20:22.000Z","dependencies_parsed_at":"2024-11-15T14:55:23.439Z","dependency_job_id":"909ee748-5c79-4452-8d87-a8097aca4437","html_url":"https://github.com/i18next/i18next-http-backend","commit_stats":{"total_commits":254,"total_committers":31,"mean_commits":8.193548387096774,"dds":"0.17716535433070868","last_synced_commit":"8353d94165dccfc32ae4f754bb54d1828271e8e2"},"previous_names":[],"tags_count":71,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/i18next%2Fi18next-http-backend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/i18next%2Fi18next-http-backend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/i18next%2Fi18next-http-backend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/i18next%2Fi18next-http-backend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/i18next","download_url":"https://codeload.github.com/i18next/i18next-http-backend/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251565195,"owners_count":21609970,"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","deno","fetch","i18next","javascript","nodejs","plugin","xhr"],"created_at":"2024-08-01T05:01:10.642Z","updated_at":"2025-04-29T18:52:34.986Z","avatar_url":"https://github.com/i18next.png","language":"JavaScript","readme":"# Introduction\n\n[![Actions](https://github.com/i18next/i18next-http-backend/workflows/node/badge.svg)](https://github.com/i18next/i18next-http-backend/actions?query=workflow%3Anode)\n[![Actions deno](https://github.com/i18next/i18next-http-backend/workflows/deno/badge.svg)](https://github.com/i18next/i18next-http-backend/actions?query=workflow%3Adeno)\n[![npm version](https://img.shields.io/npm/v/i18next-http-backend.svg?style=flat-square)](https://www.npmjs.com/package/i18next-http-backend)\n\nThis is a simple i18next backend to be used in Node.js, in the browser and for Deno. It will load resources from a backend server using the XMLHttpRequest or the fetch API.\n\nGet a first idea on how it is used in [this i18next crash course video](https://youtu.be/SA_9i4TtxLQ?t=953).\n\nIt's based on the deprecated [i18next-xhr-backend](https://github.com/i18next/i18next-xhr-backend) and can mostly be used as a drop-in replacement.\n\n*[Why i18next-xhr-backend was deprecated?](https://github.com/i18next/i18next-xhr-backend/issues/348#issuecomment-663060275)*\n\n## Advice:\n\nIf you don't like to manage your translation files manually or are simply looking for a [better management solution](https://locize.com), take a look at [i18next-locize-backend](https://github.com/locize/i18next-locize-backend). The i18next [backed plugin](https://www.i18next.com/overview/plugins-and-utils#backends) for 🌐 [locize](https://locize.com) ☁️.\n\n*To see [i18next-locize-backend](https://github.com/locize/i18next-locize-backend) in a working app example, check out:*\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://locize.com/blog/react-i18next/) starting from the step of [replacing i18next-http-backend with i18next-locize-backend](https://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\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### Seeing failed http requests, like 404?\n\nAre you using a [language detector](https://github.com/i18next/i18next-browser-languageDetector) plugin that detects region specific languages you are not providing? i.e. you provide `'en'` translations but you see a `'en-US'` request first?\n\nThis is because of the default `load` [option](https://www.i18next.com/overview/configuration-options) set to `'all'`.\n\nTry to set the `load` [option](https://www.i18next.com/overview/configuration-options) to `'languageOnly'`\n\n```javascript\ni18next.init({\n  load: 'languageOnly',\n  // other options\n})\n```\n\n### Slow i18next initialization?\n\nThe chance is high, that your http requests fails. In that case i18next retries a couple of times before finishing the initialization.\nYou have 2 options to address this:\n\n*1) The correct way:*\nAnalyze your http requests and fix them. (Wrong path? Wrong server implementation? etc...)\n\n*2) Configure i18next to not retry:*\nModify the `retryTimeout` and/or `maxRetries` to match your needs. (i.e. set `maxRetries: 1`)\n\n```js\ni18next.init({\n  // ...\n  retryTimeout: 350,\n  maxRetries: 5,\n  // ...\n})\n```\n\n# Getting started\n\nSource can be loaded via [npm](https://www.npmjs.com/package/i18next-http-backend) or [downloaded](https://github.com/i18next/i18next-http-backend/blob/master/i18nextHttpBackend.min.js) from this repo.\n\nThere's also the possibility to directly import it via a CDN like [jsdelivr](https://cdn.jsdelivr.net/npm/i18next-http-backend@1.3.1/i18nextHttpBackend.min.js) or [unpkg](https://unpkg.com/i18next-http-backend@1.3.1/i18nextHttpBackend.min.js) or similar.\n\n```bash\n# npm package\n$ npm install i18next-http-backend\n```\n\nWiring up:\n\n```js\nimport i18next from 'i18next';\nimport HttpApi from 'i18next-http-backend';\n\ni18next.use(HttpApi).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_http_backend/index.js'\n\ni18next.use(Backend).init(i18nextOptions);\n```\n\nfor plain browser:\n\n```html\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/i18next-http-backend@1.3.1/i18nextHttpBackend.min.js\"\u003e\u003c/script\u003e\n\u003c!-- an example can be found in example/jquery/index.html --\u003e\n```\n\n```js\ni18next.use(i18nextHttpBackend).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.i18nextHttpBackend`\n\n## Backend Options\n\n```js\n{\n  // path where resources get loaded from, or a function\n  // returning a path:\n  // function(lngs, namespaces) { return customPath; }\n  // the returned path will interpolate lng, ns if provided like giving a static path\n  // the function might return a promise\n  // returning falsy will abort the download\n  //\n  // If not used with i18next-multiload-backend-adapter, lngs and namespaces will have only one element each,\n  // If used with i18next-multiload-backend-adapter, lngs and namespaces can have multiple elements\n  //   and also your server needs to support multiloading\n  //      /locales/resources.json?lng=de+en\u0026ns=ns1+ns2\n  //   Adapter is needed to enable MultiLoading https://github.com/i18next/i18next-multiload-backend-adapter\n  //   Returned JSON structure in this case is\n  //   {\n  //    lang : {\n  //     namespaceA: {},\n  //     namespaceB: {},\n  //     ...etc\n  //    }\n  //   }\n  loadPath: '/locales/{{lng}}/{{ns}}.json',\n\n  // path to post missing resources, or a function\n  // function(lng, namespace) { return customPath; }\n  // the returned path will interpolate lng, ns if provided like giving a static path\n  //\n  // note that this only works when initialized with { saveMissing: true }\n  // (see https://www.i18next.com/overview/configuration-options)\n  addPath: '/locales/add/{{lng}}/{{ns}}',\n\n  // parse data after it has been fetched\n  // in example use https://www.npmjs.com/package/json5 or https://www.npmjs.com/package/jsonc-parser\n  // here it removes the letter a from the json (bad idea)\n  parse: function(data) { return data.replace(/a/g, ''); },\n\n  // parse data before it has been sent by addPath\n  parsePayload: function(namespace, key, fallbackValue) { return { key: fallbackValue || \"\" } },\n\n  // parse data before it has been sent by loadPath\n  // if value returned it will send a POST request\n  parseLoadPayload: function(languages, namespaces) { return undefined },\n\n  // allow cross domain requests\n  crossDomain: false,\n\n  // allow credentials on cross domain requests\n  withCredentials: false,\n\n  // overrideMimeType sets request.overrideMimeType(\"application/json\")\n  overrideMimeType: false,\n\n  // custom request headers sets request.setRequestHeader(key, value)\n  customHeaders: {\n    authorization: 'foo',\n    // ...\n  },\n  // can also be a function, that returns the headers\n  customHeaders: () =\u003e ({\n    authorization: 'foo',\n    // ...\n  }),\n\n  requestOptions: { // used for fetch, can also be a function (payload) =\u003e ({ method: 'GET' })\n    mode: 'cors',\n    credentials: 'same-origin',\n    cache: 'default'\n  },\n\n  // define a custom request function\n  // can be used to support XDomainRequest in IE 8 and 9\n  //\n  // 'options' will be this entire options object\n  // 'url' will be passed the value of 'loadPath'\n  // 'payload' will be a key:value object used when saving missing translations\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 (options, url, payload, callback) {},\n\n  // adds parameters to resource URL. 'example.com' -\u003e 'example.com?v=1.3.5'\n  queryStringParams: { v: '1.3.5' },\n\n  reloadInterval: false // can be used to reload resources in a specific interval (milliseconds) (useful in server environments)\n}\n```\n\nOptions can be passed in:\n\n**preferred** - by setting options.backend in i18next.init:\n\n```js\nimport i18next from 'i18next';\nimport HttpApi from 'i18next-http-backend';\n\ni18next.use(HttpApi).init({\n  backend: options,\n});\n```\n\non construction:\n\n```js\nimport HttpApi from 'i18next-http-backend';\nconst HttpApi = new HttpApi(null, options);\n```\n\nvia calling init:\n\n```js\nimport HttpApi from 'i18next-http-backend';\nconst HttpApi = new HttpApi();\nHttpApi.init(null, options);\n```\n\n## TypeScript\n\nTo properly type the backend options, you can import the `HttpBackendOptions` 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 HttpBackend, { HttpBackendOptions } from 'i18next-http-backend'\n\ni18n\n  .use(HttpBackend)\n  .init\u003cHttpBackendOptions\u003e({\n    backend: {\n      // http backend options\n    },\n\n    // other i18next options\n  })\n```\n\n---\n\n\u003ch3 align=\"center\"\u003eGold Sponsors\u003c/h3\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://locize.com/\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/i18next/i18next/master/assets/locize_sponsor_240.gif\" width=\"240px\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n**From the creators of i18next: localization as a service - locize.com**\n\nA translation management system built around the i18next ecosystem - [locize.com](https://locize.com).\n\n![locize](https://locize.com/img/ads/github_locize.png)\n\nWith using [locize](http://locize.com/?utm_source=react_i18next_readme\u0026utm_medium=github) you directly support the future of i18next.\n\n---\n","funding_links":["https://github.com/sponsors/jamuhl","https://github.com/sponsors/adrai","https://locize.com"],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fi18next%2Fi18next-http-backend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fi18next%2Fi18next-http-backend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fi18next%2Fi18next-http-backend/lists"}