Процесс локализации иногда очень сложен. При создании приложений с большим количеством текстов для перевода это повторяющаяся задача. Добавление ключа перевода в код, добавление его в файлы локализации, исправление опечаток, снова и снова. При предоставлении этих файлов переводчикам контекст исчезает, и они просто не могут правильно перевести содержимое. Но… Что, если есть решение, которое позволит вам, вашим коллегам и переводчикам просто ALT + Click просто ALT + Click перевести текст и перевести его непосредственно в разрабатываемом вами приложении. С Tolgee Toolkit вы можете легко это сделать. Давайте посмотрим, как перевести простое приложение React ToDo.

Для выполнения этого руководства вам потребуются установленные на вашем компьютере docker, git, node и npm.

Начнем с простого приложения React ToDo, созданного с помощью Create React App (CRA), которое вы можете клонировать из моего репозитория GitHub.

$ git clone https://github.com/JanCizmar/tolgee-todo-react-example

Для запуска приложения вам потребуется установить зависимости npm.

$ npm install

Затем запустите сервер разработки.

$ npm run start

Ваш веб-сервер CRA, вероятно, работает на порту 3000, поэтому вы можете получить к нему доступ по http://localhost:3000.

Поскольку приложение очень простое, весь код приложения в основном представляет собой один Компонент приложения, хранящийся в файле src/App.tsx.

В компоненте есть несколько текстов, которые мы хотели бы перевести:

<Typography variant=”h3">My To Do App</Typography>
<Typography variant=”body1">Welcome to my brand new to do app!</Typography>

Чтобы их перевести, давайте интегрируем библиотеку Tolgee React!

Запуск сервера Tolgee с помощью Docker

Прежде всего, вам нужно будет запустить док-контейнер Tolgee.

$ docker run -v tolgee_data:/data/ -p 8085:8080 \
-e tolgee.authentication.enabled=false \
tolgee/tolgee

Эта команда запускает образ tolgee/tolgee с томом tolgee_data, смонтированным в каталог /data, и открывает порт 8085. Параметр -e tolgee.authentication.enable=false отключает аутентификацию, поэтому вы можете использовать сервер Tolgee локально без входа в систему. Вывод этой команды должен заканчиваться примерно следующим образом:

..... Tomcat started on port(s): 8080 (http) with context path 
..... Application.Companion in 9.108 seconds (JVM running for 9.564)

Это означает, что сервер запущен, и вы должны получить доступ к веб-приложению на http://localhost:8085. При доступе к этому URL-адресу вы должны увидеть веб-приложение, выглядящее следующим образом:

Как следует из сообщения, давайте добавим что-нибудь, чтобы продолжить. Нажмите кнопку + и создайте свой первый репозиторий. Я собираюсь перевести на английский и чешский языки, поэтому я создаю репозиторий с этими языками.

Создав репозиторий, сгенерируем для него ключ API. Выберите репозиторий «To do app» из списка и нажмите кнопку «Ключи API» в меню. Снова нажмите кнопку +, оставьте выбранными все области видимости и нажмите GENERATE.

В итоге вы должны получить сгенерированный ключ API следующим образом:

Прохладный! Теперь вы готовы использовать этот ключ API в коде нашего приложения ToDo.

Перевод приложения React

Чтобы перевести приложение React, вам необходимо установить необходимые пакеты, сохранить ключ API и URL-адрес API в .env файлах, обернуть все приложение настроенным компонентом TolgeeProvider и использовать компонент T для перевода наших ключей.

Установка зависимостей Tolgee

Установите эти зависимости через npm:

$ npm install --save-dev @tolgee/core @tolgee/react @tolgee/ui

Хранение ключа API и URL-адреса API в файлах .env

Прежде всего, вам нужно будет предоставить ключ API и URL-адрес API для вашего приложения. Для этого мы будем использовать .env файлов. Create React App обеспечивает отличную поддержку для этого, поэтому использовать переменные среды очень просто. Сначала создайте файл .env в корневом каталоге со следующим содержимым:

REACT_APP_TOLGEE_API_KEY=
REACT_APP_TOLGEE_API_URL=http://localhost:8085

Этот файл хранится в репозитории git. Вы действительно не хотите, чтобы ваш API-ключ утек, поэтому давайте создадим второй файл с именем .env.local. Этот файл не хранится в репозитории git, так как он упоминается в .gitignore. Итак, здесь вы можете безопасно хранить свой ключ API на своем локальном компьютере.

REACT_APP_TOLGEE_API_KEY=g4t8mk7ubrrqq80u7jquog2upb
REACT_APP_TOLGEE_API_URL=http://localhost:8085

Не забудьте заменить ключ API на свой, полученный в веб-приложении Tolgee.

Приложение-обертка с компонентом TolgeeProvider

Поскольку мы предоставили нашу конфигурацию с помощью файлов .env, теперь мы можем использовать ее в нашем приложении. Давайте отредактируем src/index.tsx и обернем компонент <App/> компонентом TolgeeProvider. Результат будет выглядеть так:

...
import {TolgeeProvider} from "@tolgee/react";
import {UI} from "@tolgee/ui";

ReactDOM.render(
    <React.StrictMode>
        <TolgeeProvider
            apiKey={process.env.REACT_APP_TOLGEE_API_KEY}
            apiUrl={process.env.REACT_APP_TOLGEE_API_URL}
            ui={process.env.REACT_APP_TOLGEE_API_URL ? UI : undefined}
            availableLanguages={["en", "cs"]}
        >
            <App/>
        </TolgeeProvider>
    </React.StrictMode>,
    document.getElementById('root')
);
...

Свойство ui предоставляет конструктор класса пользовательского интерфейса. Пакет пользовательского интерфейса отделен от @tolgee/core, чтобы сэкономить размер пакета в рабочем режиме. availableLanguages prop сообщает Tolgee, какие языки поддерживаются. Он автоматически выбирает язык по умолчанию в соответствии с системными настройками пользователя, поэтому ему необходимо знать, какие языки поддерживаются.

ОК, вот и все! Теперь мы готовы подготовить наше приложение для контекстного перевода, обернув каждый ключ локализации компонентом <T/>.

Обертывание ключей локализации

Чтобы подготовить наше приложение к переводу, давайте откроем файл src/App.tsx и обернем каждый текст, который вы хотите перевести, компонентом <T>. После этого части кода должны выглядеть так:

import {T} from "@tolgee/react";
...
<Typography variant="h3"><T>My ToDo App</T></Typography>
<Typography variant="body1"><T>Welcome to my brand new to do app!</T></Typography>
...
<TextField size={"small"} fullWidth value={taskTextValue}
           onChange={event => setTaskTextValue(event.target.value)}
           id="filled-basic" label={<T>New task</T>} variant="outlined"
/>
...

Вы также можете изменить ключи на более традиционные, например: my_todo_app_title или header_welcome_message. Но для этого примера мы можем просто обернуть исходные строки.

Когда вы подготовите свои ключи, вы можете перезапустить сервер разработки CRA.

$ npm run start

Требуется перезагрузка, так как CRA не перезагружает переменные среды автоматически.

И это все! Ваше приложение готово к переводу. Давайте сначала дадим пользователям возможность переключаться между языками.

Добавление компонента LanguageMenu

Поскольку мы создаем локализованное приложение, нам нужно разрешить пользователям нашего приложения ToDo переключаться между языками. Для этого создадим компонент LanguageMenu. В нашем случае это просто Material UI menu. Так как код компонента немного шаблонный. Просто создайте файл src/LanguageMenu.tsx и скопируйте и вставьте содержимое из git: https://github.com/JanCizmar/tolgee-todo-react-example/blob/with-tolgee/src/LanguageMenu.tsx

Затем используйте компонент в своем компоненте приложения.

import {LanguageMenu} from "./LanguageMenu";
import {ListAlt} from "@material-ui/icons";
...
<header>
    <Container maxWidth="sm">
        <Box mt={2} display="flex" justifyContent="space-between">
            <ListAlt fontSize={"large"}/>
            <LanguageMenu/>
        </Box>
        <Box mt={4}>
            <Typography variant="h3"><T>My ToDo App</T></Typography>
...

Прохладный. Вы только что подготовили свое приложение для переключения языков и контекстного перевода.

Контекстный перевод

Теперь откройте приложение ToDo в браузере, удерживайте клавишу ALT (или клавишу Option на Mac) и наведите указатель мыши на клавишу, которую вы обернули компонентом <T>. Он должен быть выделен.

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

Когда вы сохраняете эти значения, они сразу же сохраняются на сервере, и содержимое вашего приложения сразу же изменяется. Так что вы знаете, как это выглядит даже без обновления. Круто, не так ли? Таким образом, вы можете перевести почти все ваши ключи.

Перевод некликабельных ключей

В каждом приложении есть вхождения клавиш, которые по каким-то причинам не могут быть переведены нажатием на них. Всплывающие подсказки исчезают, так как мы подводим к ним мышь, некоторые клавиши перекрываются другими элементами, что не передает события мыши и так далее. В этих случаях вы все равно можете перевести их с помощью веб-приложения Tolgee.

В нашем приложении ToDo есть метка текстового поля новой задачи.

<TextField size={"small"} fullWidth value={taskTextValue}
           onChange={event => setTaskTextValue(event.target.value)}
           id="filled-basic" label={<T>New task</T>} variant="outlined"
/>

Даже если этот ключ упакован правильно, его нельзя перевести в контексте приложения. Чтобы перевести его, вам нужно будет войти в Веб-приложение Tolgee и перевести этот ключ вручную. Откройте раздел Переводы вашего репозитория и создайте следующий перевод.

После сохранения и обновления приложения ToDo ключ также переводится.

Вот и все. Теперь вы успешно перевели все свои ключи.

Подготовка вашего приложения к производству

Вы никогда не должны разглашать свой ключ API. Утечка ключа API может привести к тому, что любой сможет редактировать ваши данные перевода. Именно по этой причине мы сохранили ключ API в .env.local, который не является частью вашего репозитория git. Но когда теперь есть ключ API, как библиотека Tolgee может загружать переводы? Это невозможно. Поэтому нам нужно предоставить файлы локализации как статический ресурс. Для этого давайте экспортируем данные из веб-приложения Tolgee.

Войдите в приложение и выберите пункт «Экспорт» в боковом меню. Затем нажмите «ЭКСПОРТИРОВАТЬ ФАЙЛЫ .JSON КАК ZIP». Загрузка должна начаться немедленно.

Затем скопируйте файлы json из загруженного zip-файла в каталог public/i18n.

Если вы сейчас удалите значение ключа API из файла .env.local:

REACT_APP_TOLGEE_API_KEY=
REACT_APP_TOLGEE_API_URL=http://localhost:8085

и перезапустите инструмент CRA (npm run start), ваше приложение должно оставаться локализованным, и вы не сможете редактировать свои переводы, нажимая на них ALT+. Это означает, что ваше приложение готово к работе.

Итак, вот оно. Вы успешно перевели свое первое приложение с помощью Tolgee Toolkit!

Резюме

В этом руководстве вы узнали, как запустить сервер Togee Toolkit с докером, перевести ваше веб-приложение React и подготовить его к работе.

Чтобы узнать больше о Tolgee Toolkit, посетите нашу документацию на https://toolkit.tolgee.io. Мы будем рады любому вкладу или отзыву.

Не беспокойтесь, свяжитесь с нами через [email protected].