@nerimity/solid-i18lite

i18next for Solid

The purpose of this library is to provide ability to support i18next library in Solid applications with <TransProvider /> and <Trans /> components.

Table of Contents

• Usage
  • Simple Example
  • Add Resources
  • Change a Language
  • T Function
• Interpolation
  • Nested JSX
• API
  • Components
  • Utilities

Usage

Installation:

npm install @nerimity/solid-i18lite @nerimity/i18lite --save

Simple Example

<TransProvider /> must wrap Solid application's most parent component (e.g. <App />). <Trans /> component's key property is mandatory.

Default value can be wrapped with <Trans /> component or set with options or children property.

// esm
import { TransProvider, Trans } from '@nerimity/solid-i18lite';

// cjs
const { TransProvider, Trans } = require('@nerimity/solid-i18lite');

render(() => (
  <TransProvider>
    <App>
      <Trans key="greeting" />
      {/* or */}
      <Trans key="greeting">Hello!</Trans>
      {/* or */}
      <Trans key="greeting" options={{ defaultValue: 'Hello!' }} />
      {/* or */}
      <Trans key="greeting" options="Hello!" />
      {/* or */}
      <Trans key="greeting" children="Hello!" />
    </App>
  </TransProvider>
));

Add Resources

Resources can be added on initialization with options property in <TransProvider /> or by calling addResources method from TransContext, which can be got with useTransContext().

import { Trans, TransProvider, useTransContext } from '@nerimity/solid-18lite';

const resources = {
    lt: {...},
    pl: {...},
};

render(() => <TransProvider options={{ resources }} children={<App />} />, container);

{/* or */}

const Component = () => {
    const [, actions] = useTransContext();
    actions.addResources('lt', 'translation', resources.lt);
    actions.addResources('pl', 'translation', resources.pl);

    return <Trans key="greeting">Hello!</Trans>;
};

Change a Language

Default language can be provided to <TransProvider /> with lng or options property.

options.lng overrides lng property.

<TransProvider lng="lt" children={...} />
<TransProvider options={{lng: 'pl'}} children={...} />

To change a language you need to use TransContext and call changeLanguage.

import { useTransContext } from '@nerimity/solid-18lite';

const Component = () => {
  const [, { changeLanguage }] = useTransContext();

  return (
    <article>
      <button type="button" onClick={() => changeLanguage('en')}>
        English
      </button>
      <button type="button" onClick={() => changeLanguage('lt')}>
        Lietuvių
      </button>
    </article>
  );
};

T Function

i18next have t function, which is essential and sometimes there is need to use it without <Trans /> component. TransContext provides it in case you need it.

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 <Trans /> component.

<Trans key="greeting" options={{ name: 'John Doe' }}>
  {'Hello {{name}}!'}
</Trans>

i18next also allows to define custom interpolation prefix and suffix.

const resources = { lt: { greeting: 'Labas, ##name##!' } };
const interpolation = { prefix: '##', suffix: '##' };

<TransProvider options={{ interpolation, resources }}>
  <Trans key="greeting" options={{ name: 'John Doe' }}>
    Hello ##name##!
  </Trans>
</TransProvider>;

Nested JSX

This library supports nested JSX messages, like react-i18next. If you want use this feature, you need to install html-parse-string separately:

npm i html-parse-string

Then you can define your translation strings, like described in How to get the correct translation string?.

const resources = {
  lt: { translation: { greeting_nested: '<0>Sveiki, {{fullName}}! </0><1>Tavo profilis</1>.' } },
};

<TransProvider options={{ interpolation, resources }}>
  <Trans key="greeting_nested" options={{ name: 'John Doe' }}>
    {'Hello {{ name }}! '}
    <a href="/profile">Your Profile</a>.
  </Trans>
</TransProvider>;

Keep in mind that elements, with interpolation, must be a string, e.g: 'Hello {{name}}!'.

API

Components

<TransProvider />

Property	Description	Required
instance	i18next instance, see: i18n	No
lng	default language, options.lng overrides it	No
options	i18next init options, see: InitOptions	No

<Trans />

Property	Description	Required
key	translation key or keys TFunctionKeys	Yes
options	t function's options, see: TOptions | string	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
changeLanguage(lng)	changes language and sets new t function
getI18next	returns i18next instance, see i18n