Как настроить интернационализацию в React с помощью Lingui.js
Интернационализация (i18n) и локализация имеют решающее значение при разработке программного обеспечения для расширения охвата вашего приложения. Иногда даже требуется создать приложение со встроенным в него определенным языком. Например, большинство страниц правительственных веб-сайтов переведены на местный и национальный язык своей страны.
Поскольку большинство веб-сайтов полагаются на JavaScript, неудивительно, что существует множество популярных библиотек JavaScript, настроенных для обработки интернационализации приложений. Некоторые из наиболее известных библиотек:
В этой статье я продемонстрирую, как использовать Lingui.js. Это мощная библиотека, которая не только обрабатывает интернационализацию в собственных приложениях JavaScript, но и в React, одной из самых известных библиотек JavaScript. Lingui.js имеет небольшой размер всего 5 КБ, и с ним очень легко начать работу новичкам.
Представляем Lingui.js
Lingui.js - относительно новая библиотека интернационализации, но она предлагает некоторые функции, недоступные в популярных библиотеках конкурентов, таких как react-intl и i18next. Например, Lingui.js упакован макросами, которые можно использовать для создания синтаксиса сообщений для компонентов. Некоторые другие важные особенности Lingui.js:
- Оптимизирован для производительности (размер всего 5 КБ)
- Легко интегрируется с приложениями React и React Native
- Его сообщество активно на GitHub, а также на Spectrum.
- Lingui.js предоставляет подробную документацию с пошаговыми руководствами и ссылками на API.
- Он использует ICU MessageFormat, который делает переводы пользовательского интерфейса читаемыми.
- Предлагает поддержку форматированного текста, которого нет во многих конкурирующих библиотеках.
- Lingui.js имеет собственный интерфейс командной строки для оптимизации всего процесса перевода пользовательского интерфейса.
В общем, Lingui.js можно интегрировать в статические приложения любого типа. А если у вас есть приложение, работающее в режиме реального времени, например чат или онлайн-игра, то Lingui.js может стать отличным выбором, поскольку он разработан для работы с ресурсоемкими приложениями. Например, Caliopen (единая платформа обмена сообщениями) активно использует Lingui.js.
В этой статье мы будем работать над примером проекта по интеграции Lingui.js в приложение React. Чтобы упростить задачу, воспользуемся пакетом create-react-app.
Предпосылки
Чтобы следовать этому руководству, в вашей системе уже должен быть установлен Node.js. Его последняя версия содержит такие инструменты, как npm и npx, поэтому вам не нужно устанавливать их отдельно.
Начнем
Нашим первым шагом является установка последней версии пакета create-response-app на нашем локальном компьютере. Для этого откройте консоль / терминал в нужной папке в вашей системе. После этого выполните эту команду:
npx create-react-app my-app
Чтобы установить все зависимости и настроить базовое приложение React, потребуется некоторое время, поэтому проявите терпение. После завершения установки запустите эту команду:
cd my-app
Теперь вы окажетесь в папке проекта и будете готовы к установке Lingui.js.
По сути, разработчики Lingui.js разделили всю библиотеку на разные модули. На данный момент нас интересуют CLI, macro и React. Нам также нужно ядро компилятора Babel и babel-bridge для поддержки старых версий Babel.
Давайте установим все эти зависимости в нашем проекте React:
npm i --save-dev @lingui/cli @lingui/macro @babel/core babel-core@bridge
npm i --save @lingui/react
Конфигурация Lingui.js
Пришло время настроить Lingui.js, сообщив ему местоположение файла сообщений, используемый формат и язык пользовательского интерфейса по умолчанию. Для этого вы должны создать файл с именем .linguirc в корне вашего проекта. Содержимое этого файла должно выглядеть так:
{
"localeDir": "src/locales/",
"srcPathDirs": ["src/"],
"format": "minimal",
"sourceLocale": "en"
}Каталог src будет содержать исходные файлы сообщений, в то время как Lingui.js будет извлекать сообщения из этих файлов и записывать их в папке для конкретного языка. Каждый язык (например, английский, урду, китайский и т.д.) Будет иметь свои собственные подпапки внутри папки src/locales/.
Также важно выбрать правильный формат для перевода сообщения. Некоторые из доступных форматов включают:
lingui: каждое сообщение возвращается в заранее определенном формате, как этоminimal: каждое сообщение возвращается в простом формате JSON, подобном этомуpo: Каждое сообщение возвращается в виде файла
Lingui.js рекомендует формат po. В общем, это вопрос личных предпочтений и настройки вашего текущего приложения. Большинству из нас может показаться, что формат minimal (например, JSON) легче читать, чем другие. Итак, в этом уроке мы будем использовать формат minimal. Чтобы узнать больше о каждом формате, обратитесь к этому разделу документации.
Обновить package.json
На этом этапе мы должны добавить несколько скриптов в package.json
{
"scripts": {
"add-locale": "lingui add-locale",
"extract": "lingui extract",
"compile": "lingui compile"
}
}С помощью приведенных выше команд мы сможем создавать новые языковые стандарты, а также компилировать и извлекать текущие языковые стандарты в нашем приложении.
Добавить языки пользовательского интерфейса
Выполнение скрипта add-locale позволит нам создавать разные языки для нашего пользовательского интерфейса:
npm run add-locale en zh ur
Для этого вы можете посмотреть поддерживаемые языковые коды на официальном веб-сайте IANA.
Создать веб-страницу
Приложение CRA уже имеет базовую домашнюю страницу. Вы можете найти этот файл в папке /src/App.js. Мы изменим этот файл следующим образом:
import React, { useState, useEffect } from 'react';
import { Trans } from '@lingui/macro';
import LanguageSelector from './components/LanguageSelector';
function App({ language, onLanguageChange }) {
return (
<div className="App">
<LanguageSelector
language={language}
onChangeLangage={onLanguageChange}
/>
<header className="App-header">
<h1><Trans>Name of Countries</Trans></h1>
</header>
<ul>
<li><Trans>United States</Trans></li>
<li><Trans>Finland</Trans></li>
</ul>
</div>
);
}
export default App;
Вы заметили, что мы используем компонент LanguageSelector?
Это помогает нам динамически изменять язык пользовательского интерфейса. Он использует простое раскрывающееся меню выбора HTML. Вот как выглядит этот компонент:
import React from 'react';
function LanguageSelector({ language, onChangeLangage }) {
function handleChange(event) {
event.preventDefault();
onChangeLangage(event.target.value);
}
return (
<div className="select">
<select onChange={handleChange} value={language}>
<option value="en">English</option>
<option value="ur">Urdu</option>
<option value="zh">Chinese</option>
</select>
</div>
);
}
export default LanguageSelector;
Наконец, нам нужно обновить наш основной файл /src/index.js. Этот файл отвечает за импорт переводов выбранного языка и отображение всей веб-страницы.
import React, { useState } from 'react';
import ReactDOM from 'react-dom';
import { I18nProvider } from '@lingui/react';
import App from './App';
async function loadMessages(language) {
return await import(`@lingui/loader!./locales/${language}/messages.json`);
}
function LocalizedApp() {
const [catalogs, setCatalogs] = useState({})
const [language, setLanguage] = useState('en');
async function handleLanguageChange(language) {
const newCatalog = await loadMessages(language);
const newCatalogs = { ...catalogs, [language]: newCatalog };
setCatalogs(newCatalogs);
setLanguage(language);
}
return (
<I18nProvider language={language} catalogs={catalogs}>
<App
language={language}
onLanguageChange={handleLanguageChange}
/>
</I18nProvider>
);
}
ReactDOM.render(<LocalizedApp />, document.getElementById('root'));
Извлечь сообщения из исходного кода
Теперь, когда мы обернули некоторый текст внутри макроса <Trans> … </Trans>, пришло время извлечь все эти сообщения из исходного кода, а затем создать пары ключ-значение внутри каждой локали. Ключ будет работать как идентификатор, а значение будет его переводом на определенный язык.
В английском языке пара ключ и значение останется прежней. Но мы должны изменить значения в других языках. По умолчанию их значением будут пустые строки, и нам придется добавлять переводы вручную.
Выполните команду npm run extract для извлечения сообщений из исходного кода.
Перевод пользовательского интерфейса
Мы создали веб-страницу со списком двух стран: Финляндии и США. Теперь нам нужно перевести пользовательский интерфейс на все поддерживаемые языки.
Ранее мы добавляли в наш проект языковой стандарт на английский, китайский и урду. Язык по умолчанию - английский, и Lingui.js достаточно умен, чтобы автоматически заполнять английские переводы:
{
"Finland": "Finland",
"Name of Countries": "Name of Countries",
"United States": "United States"
}
Теперь откройте /src/locales/ur/messages.json и замените его содержимое приведенным ниже кодом.
{
"Finland": "فن لینڈ",
"Name of Countries": "ممالک کا نام",
"United States": "امریکہ"
}Точно так же откройте /src/locales/zh/messages.json и обновите его следующими переводами.
{
"Finland": "芬兰",
"Name of Countries": "国家名称",
"United States": "美国"
}На этом этапе мы готовы скомпилировать переводы, чтобы использовать их в нашем приложении. Для этого выполните команду компиляции npm run compile.
Запустить проект
Чтобы запустить приложение, запустите команду npm start.
Вывод
Вместе мы узнали, насколько легко интегрировать Lingui.js с приложением React и добавить в ваше приложение возможности интернационализации.
Одним из лучших преимуществ Lingui.js является то, что он может автоматически управлять парами "ключ-значение" перевода для всех языков. Это инициализирует сообщение с пустой строкой, чтобы предотвратить ошибки во время выполнения. После этого вы просто добавите конкретные переводы для разных пар "ключ-значение" и увидите свое приложение на новом языке.
