https://github.com/klis87/i18next-ts-loader
Webpack loader for i18next with the best developer experience
https://github.com/klis87/i18next-ts-loader
i18n i18next internationalization localization translation translations webpack-loader
Last synced: 11 days ago
JSON representation
Webpack loader for i18next with the best developer experience
- Host: GitHub
- URL: https://github.com/klis87/i18next-ts-loader
- Owner: klis87
- License: mit
- Created: 2022-05-21T21:07:42.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2023-07-14T21:21:05.000Z (almost 2 years ago)
- Last Synced: 2025-04-17T20:38:40.446Z (16 days ago)
- Topics: i18n, i18next, internationalization, localization, translation, translations, webpack-loader
- Language: JavaScript
- Homepage:
- Size: 300 KB
- Stars: 20
- Watchers: 2
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# i18next-ts-loader
[](https://badge.fury.io/js/i18next-ts-loader)
Webpack loader for i18next with the best developer experience
## Motivation
`i18next` in my opinion is by far the best translation library, at least for React. The big problem with it though is
that it is hard to keep translation files in sync with the places they are used. There are some methods to simplify
this, like some extraction tools, but none of them gives all the features which `i18next-ts-loader` does:
- importing json files with translations with standard ES6 modules, which can be located anywhere, especially next to components which need them
- creating autogenerated Typescript types, which gives you autocompletion in your text editor (if you use just `javascript`), or even type safety (if you use `typescript`)
- copying locale files to chosen place required by `i18next`
- compatibility with webpack HMR - when you update a locale file, you will see the translation updated without page reload
- content based hashing support - optionally copied locale files for `i18next` can contain content based hash, so that you could cache your locales forever, like you usually do for `js` and `css` files
## Installation
To install the loader, just run:
```bash
npm install --dev i18next-ts-loader
```
## Basic usage
First, add the loader to your rules, for example:
```js
rules: [
...otherRules,
{
test: /\.i18n$/,
exclude: /node_modules/,
loader: 'i18next-ts-loader',
options: {
localeFilesPattern: '/locales/{{lng}}/{{ns}}.json',
},
},
];
```
Then, let's say you have a place with a translation, for example below React component:
```jsx
import * as React from 'react';
import { useTranslation } from 'react-i18next';
const SomeComponent = () => {
const { t } = useTranslation('common');
return
{t(common.myKey)};
};
```
Let's assume, that we support two languages - English and Polish. With the help of this loader, you can refactor the code in the following way. First, create a file `common.i18n`
with translations, for example:
```json
{
"en": {
"myKey": "my key"
},
"pl": {
"myKey": "mój klucz"
}
}
```
Notice, that we define all languages in one file. Then, you can import it to your component, like so:
```jsx
import * as React from 'react';
import { useTranslation } from 'react-i18next';
import locale, { namespace } from './common.i18n';
const SomeComponent = () => {
const { t } = useTranslation(namespace);
return
{t(locale.myKey)};
};
```
As you can see, we can just import locales with the help of `import`, like you usually do for JS files.
So, despite the fact that `i18next` has its own way of loading locales, we can do it using ES6 modules,
and this loader will do its job to make `i18next` happy.
You can then use imported `locale` to get your locale keys to pass them to `t` function instead of manually writing
keys. Thanks to autogenerated `i18n.d.ts` files, you get nice autocomplete features, so no unsynchronized keys anymore!
Additionally, if you use `Typescript`, `ts` compiler will warn you, if you use any not existent key.
Based on the above example, using `locale.myKey` in `t`, apart from autocomplete or type safety has other benefits. To start with,
the translation is always bound to a proper namespace for you, in our case, to `common`. This is especially important, because
with this plugin, `namespace` is nothing else than a path to your locale file, including the file name. Moreover, if want to use
content based hashing feature, it will be also appended to the `namespace` name. So, wherever you need to pass a namespace name,
like in `useTranslation`, you should always use imported `namespace` variable.
## Nested keys
This loader supports nested keys in locale files, for example if you have below translation:
```json
{
"en": {
"nested": {
"myKey": "my key"
}
},
"pl": {
"nested": {
"myKey": "mój klucz"
}
}
}
```
you could then refer to those nested keys as `locale.nested.myKey`
## Plurals
This plugin is compatible with plural keys - for examples keys like `key_0`. It will strip plural suffixes from your keys,
so generated types will be still correct.
## Loader options
The loader has the following configuration options available, all of which are optional.
### localeFilesPattern
`'/locales/{{lng}}/{{ns}}.json'` by default. It is the place, into which you want your locale files to be copied for `i18next`.
This is the pattern you pass as `loadPath` to `i18next.init`. For example:
```js
rules: [
...otherRules,
{
test: /\.i18n$/,
exclude: /node_modules/,
loader: 'i18next-ts-loader',
options: {
localeFilesPattern: '/translations/{{lng}}/{{ns}}.json',
},
},
];
```
### basePath
In order to prevent namespaces collision, a created namespace is just a file path of each imported locale file.
For example, if you import a `src/components/component/some-locale.j18n`, its namespace will be
`src_components_component_some-locale`. However, it could happen that all your locale files are located in `src/components`
directory. Then you might consider doing the following:
```js
rules: [
...otherRules,
{
test: /\.i18n$/,
exclude: /node_modules/,
loader: 'i18next-ts-loader',
options: {
basePath: 'src/components/',
},
},
];
```
Then, `src_components_component_some-locale` namespace will become `component_some-locale`
### addContentHash
It adds content based hash to namespaces to allow caching locale files in browsers forever safely, in the same way
like we usually do for js and css files.
`false` for development mode and `true` for production mode by default. For example to disable this feature for production,
you could:
```js
rules: [
...otherRules,
{
test: /\.i18n$/,
exclude: /node_modules/,
loader: 'i18next-ts-loader',
options: {
addContentHash: false,
},
},
];
```
## Examples
There are following examples currently:
- [basic](https://github.com/klis87/i18next-ts-loader/tree/master/examples/basic)
## Licence
MIT