i18nano: локализация React приложений

Разрабатывая продукт, в какой-то момент задумываешься о поддержке языков. И, казалось бы, что могло пойти не так?

Иллюзия выбора

Давайте посмотрим, какие инструменты и библиотеки существуют, и что у них под капотом:

react-localization

Не самое популярное решение и на то есть причины, использование выглядит примерно так:

import LocalizedStrings from 'react-localization';

// Инициализация:
const strings = new LocalizedStrings({
  en: {
    how: "How do you want your egg today?",
    choice: "How to choose the egg"
  },
  it: {
    how: "Come vuoi il tuo uovo oggi?",
    choice: "Come scegliere l'uovo"
  }
});

// В компоненте:
<div>{strings.how}</div>

// Переключение:
strings.setLanguage('it');

Плюсы:

• Простой API

• Маленький вес (6.7kB)

Минусы:

• При переключении языков автоматически не обновляются компоненты, нужно писать свою обертку

• Нет поддержки асинхронной подгрузки переводов, вручную добавлять можно, но это, опять же, дополнительная сложность

• Нет полноценной поддержки фолбеков, если в текущей локали не найден перевод

Под капотом используется localized-strings.

react-i18next

Пожалуй, самое популярное и распространенное решения для локализации. Использование выглядит так:

import i18n from "i18next";
import { useTranslation, initReactI18next } from "react-i18next";

// Инициализация:
i18n.use(initReactI18next).init({
  resources: {
    en: {
      translation: {
        how: "How do you want your egg today?",
        choice: "How to choose the egg"
      }
    },
    it: {
      translation: {
        how: "Come vuoi il tuo uovo oggi?",
        choice: "Come scegliere l'uovo"
      }
    }
  },
  lng: "en", 
  fallbackLng: "en"
});

// В компоненте:
const { t } = useTranslation();
<div>{t('how')}</div>
// Или используя готовый компонент:
const { t } = useTranslation();
<Trans t={t}>how</Trans>

// Переключение:
const { i18n } = useTranslation();
i18n.changeLanguage('it');

Плюсы:

• Большое комьюнити

• Множество плагинов, которые позволяют, например, использовать асинхронную подгрузку других локалей

• Автоматическое обновление компонентов при смене языка

• Поддержка concurrent features (React 18), для упрощения работы с асинхронными манипуляциями

Минусы:

• Весит 20.1 kB, но не дайте себя обмануть! Для его работы требуется i18next, который добавляет 54.5 kB, и того мы имеем 74.6 kB

• Каждый плагин добавляет дополнительный вес вашему бандлу

Из примера использования понятно, что использует i18next.

@lingui/react

import { i18n } from '@lingui/core'

// Инициализация:
i18n.load('en', {
  how: "How do you want your egg today?",
  choice: "How to choose the egg"
});
i18n.load('it', {
  how: "Come vuoi il tuo uovo oggi?",
  choice: "Come scegliere l'uovo"
});
i18n.activate('en');

// В компоненте:
const context = useLingui();
<div>{context.i18n._('how')}</div>
// Или используя готовый компонент:
<Trans id="how" />

// Переключение:
const context = useLingui();
context.i18.activate('it');

Плюсы:

• Простое API

• Маленький вес (6.6 kB)

• Поддерживает асинхронную загрузку, правда, не обойдется без дополнительного кода

• Есть плагины, для более удобного использования, например, для автоматического определения языка

Минусы:

• Все удобные инструменты находятся в @lingui/macro, которые не понятно сколько на самом деле весят, так как там используются макросы babel

react-intl

Достаточно распространенное решение, так как использует нативные методы форматирования и предоставляет полифилы для них.

import { IntlProvider } from 'react-intl';

const messages = {
  en: {
    how: "How do you want your egg today?",
    choice: "How to choose the egg"
  },
  it: {
   	how: "Come vuoi il tuo uovo oggi?",
    choice: "Come scegliere l'uovo"
  }
};

// В рутовом компоненте:
const [lang, setLang] = useState('en');
<IntlProvider messages={messages[lang]} locale={lang}>
...
</IntlProvider>

// В компоненте:
const intl = useIntl();
<div>{intl.formatMessage({ id: 'how' })}</div>
// Или используя готовый компонент:
<FormattedMessage id="how" />

// Переключение:
// Нужно прокинуть в нужный компонент `setLang`
setLang('it');

Плюсы:

• Поддерживает AST для переводов (подробнее в документации), с помощью которого можно уменьшить вес конечного бандла

Минусы:

• Для переключения языков нужно реализовывать свою обертку

• Большой вес (56.7 kB)

• Имеет собственную достаточно специфичную реализацию форматирования

Под капотом использует formatjs.

Что имеем

Без рисков и излишнего бойлерплейта выбор падает на react-i18next, но не поймите меня не правильно, это не чистое решение в экосистеме React, да и вес оставляет желать лучшего.

i18nano

Давайте сформируем функциональные требования к библиотеке для локализации:

• Поддержка асинхронной загрузки переводов, без бойлерплейта и специфичных решений, чтобы не грузить на клиент все переводы сразу и не раздувать тем самым бандл

• Соответственно, поддержка лоадера или скелетона, пока загружается перевод

• Удобный способ переключения между языками и автоматическое переключение на текущую локаль в компонентах

• Поддержка фолбеков, если в текущем переводе не нашлось перевода

• Поддержка шаблонизации, например, чтобы вставлять имя пользователя в строку с переводом

Из хотелок можно выделить поддержку вложенных переводов для человекопонятой структуризации, то бишь, например, main.header.title и предзагрузку переводов.

Как выглядит?

import { TranslationProvider } from 'i18nano';

// Инициализация
const translations = {
  // Используя динамический импорт
  'en': () => import('translations/en.json'),
  // или с помощью собственной реализации загрузки
  'it': () => load('it')
};

// В рутовом компоненте:
<TranslationProvider translations={translations} language="en">
...
</TranslationProvider>

// В компоненте:
const t = useTranslation();
<div>{t('how')}</div>
// Или используя готовый компонент:
<Translation path="how" />

// Переключение:
const translation = useTranslationChange();
translation.change('it');

Для удобства

Поддерживается передача любого компонента в качестве лоадера или скелетона:

<Translation path="how">
	<Loader />
</Translation>

Передача всех переданных поддерживаемых языков:

const translation = useTranslationChange();

<select value={translation.lang} onChange={(event) => {
  translation.change(event.target.value);
}}>
{translation.all.map((lang) => (
  <option key={lang} value={lang}>
  	{lang}
  </option>
))}
</select>

Предзагрузка перевода отличного от текущего:

const translation = useTranslationChange();

<button onHover={() => translation.preload('it')}>
	Sono italiano
</button>

Использование concurrent features из React 18, которые позволяют показывать предыдущий перевод, вместо лоадера, при смене языка:

<TranslationProvider unstable_transition={true}>
...
</TranslationProvider>

Поддержка шаблонизации:

// В файле перевода:
hello: 'Hello {{user.name}}!'

// Использование:
<Translation path="hello" values={{ user: { name: 'Ivan' } }}>
	<Skeleton />
</Translation>
// -> Hello Ivan!

"Но есть один нюанс"

Кто-то может возразить, а как же форматирование дат? Как реализовать пруализацию?

Все проще, чем кажется: во-первых, можно реализовать через шаблонизацию, во-вторых, у всех встроенных типов, будь то Date или Number, есть методы toLocaleString и подобные, в которые можно передать свой язык, а не только установленный по-умолчанию в браузере.

Через шаблонизацию:

date: '{{day}}/{{month}}/{{year}}'

<Translation path="date" values={{ day: '1', month: '4', year: '2021' }} />
// -> 1/4/2021

Через встроенный метод:

date: '{{date}}'

const date = new Date('2022-04-01').toLocaleDateString('it');
<Translation path="date" values={{ date }} />
// -> 1/4/2021

По поводу поддержки браузерами можно посмотреть caniuse — там все очень хорошо.

Что касается поддержки множественных чисел, то тут тоже все просто:

count: ['zero', 'one', 'two']

<Translation path={`count[${2}]`} />
// -> two

Ссылки

1. react-localization

2. react-i18next

3. @lingui/react

4. react-intl

5. i18nano