# i18next for Solid
[](https://codecov.io/gh/nerimity/solid-i18lite)
[](https://bundlephobia.com/package/@nerimity/solid-i18lite)
The purpose of this library is to provide ability to support [i18next](https://www.i18next.com/) library in Solid applications
with `` and `` components.
## Table of Contents
1. [Usage](#usage)
1. [Simple Example](#simple-example)
1. [Add Resources](#add-resources)
1. [Change a Language](#change-a-language)
1. [T Function](#t-function)
1. [Interpolation](#interpolation)
1. [Nested JSX](#nested-jsx)
1. [API](#api)
1. [Components](#components)
1. [Utilities](#utilities)
## Usage
Installation:
```sh
npm install @nerimity/solid-i18lite @nerimity/i18lite --save
```
### Simple Example
`` must wrap Solid application's most parent component (e.g. ``). `` component's `key` property is mandatory.
Default value can be wrapped with `` component or set with `options` or `children` property.
```tsx
// esm
import { TransProvider, Trans } from '@nerimity/solid-i18lite';
// cjs
const { TransProvider, Trans } = require('@nerimity/solid-i18lite');
render(() => (
{/* or */}
Hello!
{/* or */}
{/* or */}
{/* or */}
));
```
### Add Resources
Resources can be added on initialization with `options` property in `` or
by calling `addResources` method from `TransContext`, which can be got with `useTransContext()`.
```tsx
import { Trans, TransProvider, useTransContext } from '@nerimity/solid-18lite';
const resources = {
lt: {...},
pl: {...},
};
render(() => } />, container);
{/* or */}
const Component = () => {
const [, actions] = useTransContext();
actions.addResources('lt', 'translation', resources.lt);
actions.addResources('pl', 'translation', resources.pl);
return Hello!;
};
```
### Change a Language
Default language can be provided to `` with `lng` or `options` property.
`options.lng` overrides `lng` property.
```tsx
```
To change a language you need to use `TransContext` and call `changeLanguage`.
```tsx
import { useTransContext } from '@nerimity/solid-18lite';
const Component = () => {
const [, { changeLanguage }] = useTransContext();
return (
);
};
```
### T Function
**i18next** have `t` function, which is essential and sometimes there is need to use it without `` component.
`TransContext` provides it in case you need it.
```tsx
const Component = () => {
const [t] = useTransContext();
const messages = {
get greeting() {
return t('greeting', 'Hello!');
},
get bye() {
return t('bye', 'Bye!');
},
};
return <>{isLogin() ? messages.greeting : messages.bye};
};
```
## Interpolation
Default interpolation uses `{{` and `}}` as prefix and suffix. Solid uses `{` and `}` for properties propagation. In that case
messages with default interpolation must be put as string. Placeholder values should be provided
through `options` property of `` component.
```tsx
{'Hello {{name}}!'}
```
**i18next** also allows to define custom interpolation prefix and suffix.
```tsx
const resources = { lt: { greeting: 'Labas, ##name##!' } };
const interpolation = { prefix: '##', suffix: '##' };
Hello ##name##!
;
```
### Nested JSX
This library supports nested JSX messages, like [react-i18next](https://react.i18next.com/latest/trans-component). If you want use this feature, you need to install [html-parse-string](https://github.com/ryansolid/html-parse-string) separately:
```sh
npm i html-parse-string
```
Then you can define your translation strings, like described in [How to get the correct translation string?](https://react.i18next.com/latest/trans-component#how-to-get-the-correct-translation-string).
```tsx
const resources = {
lt: { translation: { greeting_nested: '<0>Sveiki, {{fullName}}! <1>Tavo profilis.' } },
};
{'Hello {{ name }}! '}
Your Profile.
;
```
Keep in mind that elements, with interpolation, must be a string, e.g: `'Hello {{name}}!'`.
## API
### Components
#### ``
| Property | Description | Required |
| -------- | ------------------------------------------------------------------------------------------------ | -------- |
| instance | i18next instance, see: [i18n](https://www.i18next.com/overview/api) | No |
| lng | default language, `options.lng` overrides it | No |
| options | i18next init options, see: [InitOptions](https://www.i18next.com/overview/configuration-options) | No |
#### ``
| Property | Description | Required |
| -------- | ------------------------------------------------------------------------------------------------------------------------- | -------- |
| key | translation key or keys [TFunctionKeys](https://www.i18next.com/translation-function/essentials) | Yes |
| options | t function's options, see: [TOptions \| string](https://www.i18next.com/translation-function/essentials#overview-options) | No |
### Utilities
#### `useTransContext`
`useTransContext` function returns `TransContext` as array: `[TFunction, TransProviderActions]`.
The first item is `t` function, second - the list of actions, which are listed below.
`TransProviderActions`
| Function | Description |
| ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| addResources( lng, ns, resources, bundleOptions?: { deep?; overwrite? } ) | adds translation resources, see [addResourcesBundle](https://www.i18next.com/overview/api#addresourcebundle) |
| changeLanguage(lng) | changes language and sets new t function |
| getI18next | returns **i18next** instance, see [i18n](https://www.i18next.com/overview/api) |