Использование Transifex Native для добавления интернационализации (i18n) в приложение React

Интернационализация в приложении обеспечивает поддержку нескольких языков для целевого набора пользователей приложения, которые различаются по регионам и языкам. Создание такого приложения может быть непростой задачей, но существует множество решений, позволяющих добавить поддержку нескольких языков в экосистему React. Одним из таких решений является Transifex. Это облачный сервис, который предоставляет фразы перевода при реализации интернационализации и локализации в ваших React-приложениях.

Переводы непрерывно поступают в приложение по воздуху (OTA). Таким образом, вы получаете перевод как отдельный слой на этапе разработки приложения.

В этом руководстве мы рассмотрим, как интегрировать Transifex Native в приложение React для использования интернационализации. Мы проведем вас через настройку нового приложения на Transifex и шаги по реализации, необходимые для интеграции его SDK в приложение React. После интеграции SDK мы увидим, как создавать и управлять переводимым контентом, который может управляться и обновляться в облаке.

Предварительные условия

Чтобы следовать этому руководству, вам понадобятся:

  • учетная запись Transifex
  • Установленный Node.js 14.x.x или выше
  • базовое понимание React

Полный код этого руководства вы найдете в этом репозитории GitHub.

Настройка приложения React

Давайте начнем с создания приложения React. Откройте окно терминала и создайте новый проект React с помощью инструментария create-react-app.

npx create-react-app transifex-react

# after the project directory is created
# navigate inside it
cd transifex-react
Войдите в полноэкранный режим Выйдите из полноэкранного режима

После навигации внутри каталога проекта вы наткнетесь на знакомый каталог src, часть предопределенной структуры папок, которую создает create-react-app. Эта директория содержит исходный код вашего приложения React. Давайте в качестве примера создадим общую страницу входа в систему в файле src/App.js.

Страница входа будет представлять собой простую форму с заголовком и подзаголовком, описывающим форму, полями ввода электронной почты и пароля, а также кнопкой. Основной упор в примере сделан на то, чтобы сделать его минимальным и научиться использовать Transifex Native SDK. Однако пример завершится, когда пользователь приложения заполнит данные в форме и нажмет кнопку входа. После нажатия кнопки будет показано окно с предупреждением.

Откройте файл App.js и добавьте следующий фрагмент кода:

import './App.css';

function App() {
  const handleSubmit = event => {
    event.preventDefault();
    alert('Your form is submitted!');
  };

  return (
    <div className="app">
      <div className="form">
        <h1>Login form</h1>
        <p className="subtitle">Please enter your credentials to proceed.</p>
        <form onSubmit={handleSubmit}>
          <div className="input-container">
            <label>Email</label>
            <input type="text" name="email" required />
          </div>
          <div className="input-container">
            <label>Password</label>
            <input type="password" name="password" required />
          </div>
          <button className="button-container" type="submit">
            <p className="button-text">Sign in</p>
          </button>
        </form>
      </div>
    </div>
  );
}

export default App;
Вход в полноэкранный режим Выход из полноэкранного режима

Также добавьте следующие стили CSS в файл App.css:

.app {
  display: flex;
  margin-top: 20px;
  justify-content: center;
  height: 100vh;
  background-color: #fff;
}

.subtitle {
  padding-bottom: 20px;
}

.button-container {
  display: flex;
  justify-content: center;
  align-items: center;
  border-radius: 8px;
  background: #01d28e;
  width: 100%;
  height: 40px;
  margin-top: 20px;
  padding: 10px 20px;
}

.button-text {
  color: #fff;
  font-size: 18px;
  font-weight: bold;
}

.input-container {
  display: flex;
  flex-direction: column;
  gap: 8px;
  margin: 10px;
}
Вход в полноэкранный режим Выход из полноэкранного режима

В окне терминала выполните команду npm start, чтобы увидеть страницу входа в систему в действии. В окне браузера вы увидите следующий вывод:

Установка Transifex Native SDK

Чтобы использовать Transifex Native, первым шагом будет установка Transifex JavaScript SDK. Он также предоставляет пакеты для различных фреймворков. Поскольку пример приложения построен с использованием React, установите также расширение Transifex SDK для React.

Для этого выполните следующую команду из каталога проекта:

npm install @transifex/native @transifex/cli @transifex/react --save
Войти в полноэкранный режим Выйти из полноэкранного режима

Вкратце рассмотрим, что делает каждый пакет:

Transifex Native SDK извлекает фразы перевода с помощью собственной CDN под названием Content Delivery Service (CDS). Как разработчик, вы можете использовать хостинговую службу Transifex или выбрать самостоятельный хостинг.

Создание проекта Transifex Native

После входа в учетную запись Transifex начните с создания нового проекта.

На странице Добавить новый проект:

  • Добавьте название проекта
  • Для Choose project type выберите опцию Native, так как в примере приложения используется JavaScript SDK. Transifex также предлагает варианты типа проекта на основе файлов и Live.
  • Для Назначить команде выберите Создать новую команду для этого проекта. Вы также можете выбрать Назначить этот проект существующей команде, а затем выбрать команду из выпадающего меню, если у вас уже есть команда.
  • В разделе Выбрать языки установите источником языка английский. В разделе Целевые языки выберите столько языков, сколько необходимо для обеспечения поддержки перевода в вашем приложении. Для примера приложения выберите испанский и французский языки.

После добавления этих данных нажмите кнопку Создать проект, чтобы создать новый проект Transifex. В окне браузера вы увидите следующий экран приборной панели:

Чтобы связать Transifex Native SDK с вашей учетной записью, необходимо добавить в проект учетные данные вашей учетной записи Transifex. Затем нажмите Ресурсы в боковом меню на приборной панели. Вы увидите следующий экран:

Нажмите кнопку Generate Native Credentials now в нижней части страницы. Откроется всплывающее окно, в котором будут отображены ключи token и secret.

Ключ token необходим для инициализации Transifex Native SDK в приложении React. И token, и secret используются для передачи фраз перевода из приложения React в сервис Transifex.

Вам понадобятся оба этих ключа в вашем приложении React. Создайте файл .env в приложении React и вставьте их, как показано в следующем фрагменте кода:

REACT_APP_TRANSIFEX_TOKEN=XXXX
REACT_APP_TRANSIFEX_SECRET=XXXX
Войти в полноэкранный режим Выйти из полноэкранного режима

Символы X представляют фактическую клавишу в приведенном выше фрагменте кода. После копирования ключей в файл .env, вы можете закрыть всплывающее окно.

Инициализация Transifex Native SDK в приложении React

Чтобы инициализировать Transifex Native SDK, необходимо импортировать пакет @transifex/native в ваше приложение React. В файле App.js добавьте следующий оператор import:

// rest of the import statements

import { tx } from '@transifex/native';
Вход в полноэкранный режим Выйти из полноэкранного режима

Пакет tx имеет метод init, который используется для инициализации Transifex Native SDK. Он требует передачи значения токена. Например, добавьте следующий фрагмент кода перед функцией App:

tx.init({
  token: process.env.REACT_APP_TRANSIFEX_TOKEN,
});
Войти в полноэкранный режим Выйти из полноэкранного режима

Если вы используете последнюю версию create-react-app, вы можете напрямую читать значение переменных окружения, определенных внутри файла .env, используя префикс process.env.REACT_APP_.

Использование Transifex в приложении React

Пакет расширения Transifex React предоставляет компонент T, который будет переводить текст, переданный в качестве реквизита. Он также предоставляет LanguagePicker, который будет отображать выпадающее меню с включенными языками в вашем проекте Transifex.

Компонент T имеет обязательный параметр _str, который принимает фазу перевода как строковое значение. После заголовка и подзаголовка добавим компонент LanguagePicker, чтобы отобразить выпадающее меню для отображения языковых опций.

Измените JSX в компоненте App, как показано ниже:

return (
  <div className="app">
    <div className="form">
      <h1>
        <T _str="Login form" />
      </h1>
      <p className="subtitle">
        <T _str="Please enter your credentials to proceed." />
      </p>
      <div className="picker">
        <p className="picker-title">
          <T _str="Select the language: " />
        </p>{' '}
        <LanguagePicker />
      </div>
      <form onSubmit={handleSubmit}>
        <div className="input-container">
          <label>
            <T _str="Email" />
          </label>
          <input type="text" name="email" required />
        </div>
        <div className="input-container">
          <label>
            <T _str="Password" />
          </label>
          <input type="password" name="password" required />
        </div>
        <button className="button-container" type="submit">
          <p className="button-text">
            <T _str="Sign in" />
          </p>
        </button>
      </form>
    </div>
  </div>
);
Вход в полноэкранный режим Выйти из полноэкранного режима

В приведенном выше фрагменте кода обратите внимание, что компонент T обернут другими компонентами HTML и React для применения пользовательской стилизации, определенной ранее.

Для компонента T доступны дополнительные реквизиты.

Измените файл App.css и следующий фрагмент кода, чтобы применить некоторые стили для текста, предшествующего компоненту LanguagePicker.

/* After the rest of the code */

.picker {
  display: flex;
  margin-top: 10px;
  padding: 10px;
  flex-direction: row;
}

.picker-title {
  font-size: 18px;
  font-weight: bold;
  margin-right: 10px;
}
Вход в полноэкранный режим Выход из полноэкранного режима

Если вы запускали dev-сервер, вам нужно перезапустить сервер, чтобы увидеть изменения. Повторно выполните команду npm start из окна терминала и вернитесь в окно браузера, чтобы увидеть изменения:

На скриншоте выше обратите внимание, что LanguagePicker отображает языки, включенные в проект Transifex (например, английский, язык источника, и целевые языки, испанский и французский).

Синхронизация строк перевода с Transifex

Следующим шагом для включения перевода является синхронизация строк перевода, добавленных в предыдущем разделе с помощью компонента T, с проектом Transifex. После этого с помощью Transifex Native CLI будут собраны все фразы перевода из приложения React и переданы в проект Transifex.

Для этого определим пользовательский npm-скрипт в файле package.json:

{
  // ...
  "scripts": {
    "sync-translations": "./node_modules/.bin/txjs-cli push src/ --token=<TOKEN> --secret=<SECRET>"
  }
}
Войти в полноэкранный режим Выйти из полноэкранного режима

В приведенном выше фрагменте замените <TOKEN> и <SECRET> на фактические значения ключей token и secret.

Затем запустите этот npm-скрипт из окна терминала, чтобы запустить фазы перевода.

npm run sync-translations
Войти в полноэкранный режим Выход из полноэкранного режима

Чтобы убедиться, что строки перевода перенесены в проект Transifex, перейдите в проект Transifex в окне браузера. Вы увидите, как увеличилось количество исходных строк (в зависимости от того, сколько строк перевода было добавлено в приложении React).

Как показано выше, текущее приложение React имеет шесть фраз, которые могут быть переведены.

Добавление переводов

После размещения строк перевода вы можете добавить перевод для каждой фразы. Затем на экране приборной панели нажмите кнопку Перевести. Откроется новая страница интерфейса, где вы можете вручную добавить перевод для каждой фразы.

Сначала будет предложено выбрать исходный язык. Выберите французский из выпадающего меню.

После выбора языка все строки отображаются с левой стороны. Выберите каждую из строк, а затем в правой части добавьте соответствующий перевод для каждой строки в зависимости от языка перевода. Нажмите кнопку Сохранить перевод, чтобы сохранить переведенную строку.

Повторите эти действия для всех фраз и обоих языков. После добавления всех переводов статус каждой фразы изменится с серого на зеленый. Он используется для обозначения того, что перевод конкретной фразы активен и переведен.

Запуск приложения React

Давайте вернемся к приложению React, чтобы увидеть перевод в действии. Поскольку синхронизация между Transifex и приложением React осуществляется с помощью CDN-сервиса, перезагрузка сервера не требуется.

Изучение пакета Transifex React

Пакет Transifex React также предоставляет другие утилиты в виде крючков.

Например, вы можете использовать хук useLanguages для асинхронной выборки поддерживаемых языков (как исходных, так и целевых) из проекта Transifex.

Еще один полезный хук, предоставляемый пакетом, — это хук useLocal. Он используется для возврата переменной состояния с текущей выбранной локалью. Чтобы увидеть его в действии, давайте изменим компонент функции App:

import { tx } from '@transifex/native';
import { T, LanguagePicker, useLocale } from '@transifex/react';

import './App.css';

tx.init({
  token: process.env.REACT_APP_TRANSIFEX_TOKEN,
});

function App() {
  const currentLocale = useLocale();

  const handleSubmit = event => {
    event.preventDefault();
    alert('Your form is submitted!');
  };

  return (
    <div className="app">
      <div className="form">
        <h1>
          <T _str="Login form" />
        </h1>
        <p className="subtitle">
          <T _str="Please enter your credentials to proceed." />
          <p>Currently selected locale is {currentLocale}.</p>
        </p>
        <div className="picker">
          <p className="picker-title">
            <T _str="Select the language: " />
          </p>{' '}
          <LanguagePicker />
        </div>

        {/* rest of the code remains same*/}
      </div>
    </div>
  );
}
Вход в полноэкранный режим Выйти из полноэкранного режима

Вот результат, полученный после этого шага:

Заключение

Спасибо, что прочитали эту статью. Использовать Transifex довольно просто, и лично я нашел его интересным в использовании. По сравнению с альтернативой с открытым исходным кодом, он является платным при использовании услуги хостинга Transifex, но предоставляет возможность самостоятельного хостинга.

Еще одна особенность, которая мне нравится, — это функция Over the Air, позволяющая управлять и обновлять переводы в автоматическом режиме. Вместо того чтобы иметь большие json-файлы, переводимые фразы поддерживаются с помощью интерфейса. Это также устраняет разрыв между управлением переводами на разные языки и разработкой приложения.

Дальнейшее чтение

Ознакомьтесь с руководством по реализации локализации в приложениях React с помощью Transifex Native

Оцените статью
Procodings.ru
Добавить комментарий