1 | # Introduction
|
2 |
|
3 | [![Travis](https://img.shields.io/travis/i18next/i18next-xhr-backend/master.svg?style=flat-square)](https://travis-ci.org/i18next/i18next-xhr-backend)
|
4 | [![Coveralls](https://img.shields.io/coveralls/i18next/i18next-xhr-backend/master.svg?style=flat-square)](https://coveralls.io/github/i18next/i18next-xhr-backend)
|
5 | [![npm version](https://img.shields.io/npm/v/i18next-xhr-backend.svg?style=flat-square)](https://www.npmjs.com/package/i18next-xhr-backend)
|
6 | [![Bower](https://img.shields.io/bower/v/i18next-xhr-backend.svg)]()
|
7 | [![David](https://img.shields.io/david/i18next/i18next-xhr-backend.svg?style=flat-square)](https://david-dm.org/i18next/i18next-xhr-backend)
|
8 |
|
9 | This is a simple i18next backend to be used in the browser. It will load resources from a backend server using xhr.
|
10 |
|
11 | # Getting started
|
12 |
|
13 | Source can be loaded via [npm](https://www.npmjs.com/package/i18next-xhr-backend), bower or [downloaded](https://github.com/i18next/i18next-xhr-backend/blob/master/i18nextXHRBackend.min.js) from this repo.
|
14 |
|
15 | ```
|
16 | # npm package
|
17 | $ npm install i18next-xhr-backend
|
18 |
|
19 | # bower
|
20 | $ bower install i18next-xhr-backend
|
21 | ```
|
22 |
|
23 | Wiring up:
|
24 |
|
25 | ```js
|
26 | import i18next from 'i18next';
|
27 | import XHR from 'i18next-xhr-backend';
|
28 |
|
29 | i18next
|
30 | .use(XHR)
|
31 | .init(i18nextOptions);
|
32 | ```
|
33 |
|
34 | - As with all modules you can either pass the constructor function (class) to the i18next.use or a concrete instance.
|
35 | - If you don't use a module loader it will be added to `window.i18nextXHRBackend`
|
36 |
|
37 | ## Backend Options
|
38 |
|
39 | ```js
|
40 | {
|
41 | // path where resources get loaded from, or a function
|
42 | // returning a path:
|
43 | // function(lngs, namespaces) { return customPath; }
|
44 | // the returned path will interpolate lng, ns if provided like giving a static path
|
45 | loadPath: '/locales/{{lng}}/{{ns}}.json',
|
46 |
|
47 | // path to post missing resources
|
48 | addPath: 'locales/add/{{lng}}/{{ns}}',
|
49 |
|
50 | // your backend server supports multiloading
|
51 | // /locales/resources.json?lng=de+en&ns=ns1+ns2
|
52 | // Adapter is needed to enable MultiLoading https://github.com/i18next/i18next-multiload-backend-adapter
|
53 | // Returned JSON structure in this case is
|
54 | // {
|
55 | // lang : {
|
56 | // namespaceA: {},
|
57 | // namespaceB: {},
|
58 | // ...etc
|
59 | // }
|
60 | // }
|
61 | allowMultiLoading: false, // set loadPath: '/locales/resources.json?lng={{lng}}&ns={{ns}}' to adapt to multiLoading
|
62 |
|
63 | // parse data after it has been fetched
|
64 | // in example use https://www.npmjs.com/package/json5
|
65 | // here it removes the letter a from the json (bad idea)
|
66 | parse: function(data) { return data.replace(/a/g, ''); },
|
67 |
|
68 | // allow cross domain requests
|
69 | crossDomain: false,
|
70 |
|
71 | // allow credentials on cross domain requests
|
72 | withCredentials: false,
|
73 |
|
74 | // overrideMimeType sets request.overrideMimeType("application/json")
|
75 | overrideMimeType: false,
|
76 |
|
77 | // custom request headers sets request.setRequestHeader(key, value)
|
78 | customHeaders: {
|
79 | authorization: 'foo',
|
80 | // ...
|
81 | },
|
82 |
|
83 | // define a custom xhr function
|
84 | // can be used to support XDomainRequest in IE 8 and 9
|
85 | //
|
86 | // 'url' will be passed the value of 'loadPath'
|
87 | // 'options' will be this entire options object
|
88 | // 'callback' is a function that takes two parameters, 'data' and 'xhr'.
|
89 | // 'data' should be the key:value translation pairs for the
|
90 | // requested language and namespace, or null in case of an error.
|
91 | // 'xhr' should be a status object, e.g. { status: 200 }
|
92 | // 'data' will be a key:value object used when saving missing translations
|
93 | ajax: function (url, options, callback, data) {},
|
94 |
|
95 | // adds parameters to resource URL. 'example.com' -> 'example.com?v=1.3.5'
|
96 | queryStringParams: { v: '1.3.5' }
|
97 | }
|
98 | ```
|
99 |
|
100 | Options can be passed in:
|
101 |
|
102 | **preferred** - by setting options.backend in i18next.init:
|
103 |
|
104 | ```js
|
105 | import i18next from 'i18next';
|
106 | import XHR from 'i18next-xhr-backend';
|
107 |
|
108 | i18next
|
109 | .use(XHR)
|
110 | .init({
|
111 | backend: options
|
112 | });
|
113 | ```
|
114 |
|
115 | on construction:
|
116 |
|
117 | ```js
|
118 | import XHR from 'i18next-xhr-backend';
|
119 | const xhr = new XHR(null, options);
|
120 | ```
|
121 |
|
122 | via calling init:
|
123 |
|
124 | ```js
|
125 | import XHR from 'i18next-xhr-backend';
|
126 | const xhr = new XHR();
|
127 | xhr.init(null, options);
|
128 | ```
|
129 |
|
130 | ## Misc
|
131 |
|
132 | #### TypeScript definitions
|
133 |
|
134 | - Install from `@types` (for TypeScript v2 and later):
|
135 |
|
136 | npm install --save-dev @types/i18next-xhr-backend
|
137 |
|
138 | - Install from `typings`:
|
139 |
|
140 | typings install --save --global dt~i18next-xhr-backend
|
141 |
|
142 | --------------
|
143 |
|
144 | <h3 align="center">Gold Sponsors</h3>
|
145 |
|
146 | <p align="center">
|
147 | <a href="https://locize.com/" target="_blank">
|
148 | <img src="https://raw.githubusercontent.com/i18next/i18next/master/assets/locize_sponsor_240.gif" width="240px">
|
149 | </a>
|
150 | </p>
|