Как создавать многоязычные сайты на Gatsby React
Вы работаете над веб-сайтом Gatsby, который должен работать на нескольких языках? Обладая нашим опытом, мы подробно объясним, как этого можно достичь, выявив при этом общие ошибки.
В этой статье мы будем работать с файлами перевода json, используя i18n.
Выбор плагина
Есть несколько плагинов для интернационализации веб-сайтов Gatsby. Мы обнаружили, что gatsby-plugin-intl это один из самых популярных - около 6 тысяч загрузок в неделю на npm. Он использует reactintl за кулисами, который имеет около 950 тысяч еженедельных загрузок на npm!
Глядя на реализацию, он делает многое из коробки, а настройка очень минимальна, как видно на странице с инструкциями по настройке. Однако не позволяйте этому вводить вас в заблуждение, есть некоторые важные моменты, которые вам следует знать, поскольку для некоторых конкретных способов работы потребуются некоторые обходные пути с использованием этого модуля.
Настройка gatsby-plugin-intl
Документация для начальной настройки довольно ясна, но давайте рассмотрим ее вместе.
Прежде всего, вам необходимо установить пакет NPM npm install --save gatsby-plugin-intl.
Во-вторых, нам понадобится место для хранения файлов переводов. Обычно он хранится в формате /src/intl/[languagecode].json. Создайте пустые файлы json с этой структурой.
Настройте конфигурацию плагина gatsby-config.js, вставив приведенную ниже конфигурацию в свой массив плагинов. Я не нашел никаких проблем с его заказом в начале или в конце списка плагинов, но если вы получите какие-либо ошибки при настройке, вы можете попытаться переместить его в свой список плагинов, просто на случай, если есть какие-либо конфликтующие плагины Gatsby.
// from https://www.npmjs.com/package/gatsby-plugin-intl
plugins: [
{
resolve: `gatsby-plugin-intl`,
options: {
// language JSON resource path
path: `${__dirname}/src/intl`,
// supported language
languages: [`en`, `ko`, `de`],
// language file path
defaultLanguage: `ko`,
// option to redirect to `/ko` when connecting `/`
redirect: true,
},
},
]Обратите внимание, что массив языков должен содержать те же имена, что и файлы i18n json, которые вы создали ранее.
Теперь настройка завершена, убедитесь, что ваш экземпляр Gatsby по-прежнему работает правильно, быстро развернув его.
Использование файлов интернационализации
Далее мы можем начать использовать переводы. Представим, что у нас есть следующий простой файл json для переводов /src/intl/en.json. О вложении содержимого мы поговорим позже. Также создайте аналогичный файл для другого языка по выбору, например, /src/intl/nl.json если вы хотите, чтобы он был и на голландском.
{
"title": "My test website",
"description": "My website description"
}Использование хуков intl
Откройте любой компонент React, в котором вы хотите использовать метки из переводов. Прежде всего, импортируйте хук useIntl из пакета gatsby-plugin-intl.
import { useIntl } from 'gatsby-plugin-intl';
Затем мы можем получить объект intl с помощью этого хука следующим образом.
const intl = useIntl();
Действительно, очень просто. С этого момента мы можем получать переводы с помощью функции formatMessage или компонента React FormattedMessage.
// Using the function
const title = intl.formatMessage({ id: 'title' });
// Using the React component
import { FormattedMessage } from 'gatsby-plugin-intl';
<FormattedMessage id="title" />Теперь ваша очередь, попробуйте и посмотрите, получите ли вы правильные переводы! Переключение из папки localhost/en/ в папку localhost/nl/ даст вам переводы на другой язык, который вы определили в конфигурации.
Использование Intl HOC (компонент высшего порядка)
Использование версии HOC из пакета gatsby-plugin-intl не сильно отличается. Сначала мы импортируем функцию injectIntl.
import { injectIntl } from 'gatsby-plugin-intl';
Затем, когда мы экспортируем наш компонент, мы оборачиваем его функцией injectIntl.
export default injectIntl(MyComponent);
Затем мы получим объект intl как опору.
function MyComponent({ intl }) {
// Here you can use intl
}Создание ссылок на другие страницы
Поскольку структура URL-адреса немного изменилась, включая языковой стандарт внутри пути, вам также необходимо позаботиться об этом.
Либо вы можете использовать intl.locale в качестве значения и самостоятельно сгенерировать путь, например /${intl.locale}/contact, либо вы можете использовать специально созданный компонент из пакета gatsby-plugin-intl. Вот пример:
<Link to="/contact">
{intl.formatMessage({ id: "go_to_contact" })}
</Link>Подводные камни
При первой настройке есть некоторые подводные камни gatsby-plugin-intl. Пройдемся по самым важным.
Вложенные переводы
Прежде всего, не объясняется структура, разрешенная в файлах i18n json. Фактически, в настоящее время допускается вложение первого уровня. Например:
// en.json
{
"website": {
"title": "My website"
}
}
// .jsx
const title = intl.formatMessage({ id: "website.title" });Однако вложение более чем на один уровень пока не поддерживается! К сожалению, в настоящее время мы застряли только на одном уровне вложенности. Если вы все же попытаетесь это сделать, вы можете получить загадочную ошибку перекрестной среды React. Копнув глубже, вы найдете журнал ошибок, в котором упоминается, что локализация не была найдена.
Переводы со списками
Определение массивов в файлах i18n не сработало так, как мы ожидали. Сообщения были определены правильно, но в настоящее время метод formatMessage не может возвращать массивы. Например:
// en.json
{
"items": [
{
title: "abc"
},
{
title: "def"
}
]
}
// .jsx
const titleFirst = intl.formatMessage({ id: "items.0.title" });
const titleSecond = intl.formatMessage({ id: "items.1.title" });Мы видим, что мы можем получить элементы, специально указав полный путь, но невозможно получить сразу весь массив.
Обходной путь - не использовать файлы /src/intl, а вместо этого создать свои собственные файловые структуры. Затем, используя значение intl.locale, вы можете импортировать правильный файл. Это идея, хотя мы еще не тестировали, что это будет означать с точки зрения SEO, будут ли метки анализироваться немедленно.
Обновление файлов переводов
После обновления файлов перевода i18n необходимо полностью перезапустить сервер gatsby. Горячая перезагрузка на сервере gatsby develop работать не будет!
Заключение
gatsby-plugin-intlотличный продукт, который автоматизирует многие задачи, связанные с разработкой многоязычных веб-сайтов. Однако вы должны точно знать, как его использовать, какова может быть структура файлов i18n и так далее.
Еще жаль, что он не поддерживает многоуровневую вложенность и массивы в файлах перевода. Такая поддержка станет отличным дополнением и поможет в использовании более динамичных форматов контента.
Дальнейшее чтение
В целом, мы вполне довольны gatsby-plugin-intl, но это не единственная доступная реализация. Есть еще один плагин gatsby-plugin-i18n с примерно 5 тыс. еженедельных загрузок, немного меньше, чем у gatsby-plugin-intl.
Мы настоятельно рекомендуем прочитать документацию по npm, чтобы понять полный набор функций. В этой статье мы только выделили то, что считаем наиболее важными
