Консоль

Руководство по использованию

Руководство по использованию утилиты командной строки GT

Обзор

Это руководство поможет вам использовать CLI‑инструмент General Translation (gtx-cli) для перевода вашего проекта.

CLI‑инструмент совместим с любой библиотекой i18n — будь то gt-next, gt-react или сторонние решения, такие как next-intl и react-i18next.

CLI‑инструмент подключает ваш проект к AI‑сервису перевода General Translation.

Существует несколько способов использования CLI‑инструмента. Перейдите в соответствующий раздел под ваш сценарий.

Установка

Чтобы установить CLI‑инструмент, выполните следующую команду:

npm i gtx-cli
yarn add --dev gtx-cli
bun add --dev gtx-cli
pnpm add --save-dev gtx-cli

Сценарии применения

Перевод проектов GT

CLI‑инструмент можно использовать для перевода ваших проектов, которые используют gt-next или gt-react.

В этом руководстве предполагается, что вы уже настроили свой код для использования gt-next или gt-react в соответствии с руководствами gt-next и gt-react.

  1. Сначала вам нужно настроить параметры GT вашего проекта.
npx gtx-cli configure

Эта команда автоматически создаст ключ API и ID проекта для вашего проекта через панель управления.

Если же вы хотите задать ключ API и ID проекта вручную, выполните шаги 2 и 3 ниже.

  1. Далее создайте проект в панели управления General Translation.

После создания проекта сгенерируйте продакшен‑ключ API. Перейдите на страницу «API Keys» и нажмите кнопку «Create API Key».

  1. Затем добавьте ключ API и ID проекта в переменные окружения.
.env
GT_API_KEY=<ваш ключ API>
GT_PROJECT_ID=<идентификатор вашего проекта>
  1. Наконец, выполните команду перевода.
npx gtx-cli translate

По умолчанию CLI публикует переводы в CDN General Translation, чтобы их сразу можно было использовать в вашем проекте. Если хотите отключить это (например, если загружаете переводы из другого источника), выключите параметр CDN в настройках проекта в панели управления.

См. справочник по API для получения дополнительной информации о команде translate.

Перевод языковых файлов (сторонние библиотеки i18n или автономные проекты GT)

CLI‑инструмент позволяет переводить языковые файлы для сторонних библиотек i18n или для автономной реализации gt-next или gt-react.

Большинство библиотек i18n используют файлы JSON для хранения переводов. CLI‑инструмент можно использовать для автоматического перевода этих JSON‑файлов на нужные языки.

  1. Сначала необходимо настроить параметры GT в вашем проекте.
npx gtx-cli configure

Эта команда создаст файл gt.config.json в корне вашего проекта с базовыми настройками конфигурации, такими как локаль по умолчанию и поддерживаемые локали.

Эта команда автоматически сгенерирует API‑ключ и идентификатор проекта для вашего проекта через панель управления.

Однако если вы хотите задать API‑ключ и идентификатор проекта вручную, выполните шаги 2 и 3 ниже.

  1. Далее вам нужно создать проект в панели управления General Translation.

После создания проекта сгенерируйте рабочий (production) API‑ключ. Перейдите на страницу «API Keys» и нажмите кнопку «Create API Key».

  1. Затем добавьте ваш API‑ключ и идентификатор проекта в переменные окружения.
.env
GT_API_KEY=<ваш ключ API>
GT_PROJECT_ID=<идентификатор вашего проекта>
  1. Наконец, выполните команду для перевода.
npx gtx-cli translate

По умолчанию CLI‑инструмент ищет файлы для перевода согласно свойству files в вашем gt.config.json. В качестве исходного языка используется значение defaultLocale, указанное в gt.config.json.

Переведённые файлы будут сохранены по соответствующему пути вывода, указанному в gt.config.json.

Подробности о свойстве files см. в разделе configuration.

Генерация языковых файлов для проектов GT

CLI‑инструмент можно использовать для генерации языковых файлов для проектов, которые используют gt-next или gt-react.

Этот сценарий полезен, если вы хотите подключить собственного поставщика переводов.

В отличие от других библиотек i18n, gt-next и gt-react поддерживают инлайн‑переводы, то есть нет традиционной JSON‑структуры с ключами и значениями для каждого языка.

Поэтому для отслеживания изменений текста библиотеки GT сохраняют хэши исходного текста в кодовой базе.

Этой внутренней структурой данных (с хэшами) сложно оперировать, поэтому CLI‑инструмент предоставляет удобную команду для генерации языковых файлов для вашего проекта.

  1. Сначала нужно настроить параметры GT вашего проекта.
npx gtx-cli configure

Когда появится вопрос о сохранении переводов на GT CDN, выберите вариант «No».

  1. Выполните:
npx gtx-cli generate

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

Содержимое каждого файла одинаково и будет объединено с любыми ранее добавленными переводами в вашем проекте.

См. справочник API для получения дополнительной информации о команде generate.

Примечания

  • gtx-cli translate используется для автоматической генерации переводов в вашем проекте.
  • Если вы используете стороннюю библиотеку i18n, вы можете автоматически обновлять все JSON‑файлы переводов при каждом изменении проекта. Просто добавьте команду gtx-cli translate в процесс сборки или CD перед командой сборки, чтобы автоматически добавлять переводы в проект.

Дальнейшие шаги

Насколько полезно это руководство?

На этой странице

Обзор
Установка
Сценарии применения
Перевод проектов GT
Перевод языковых файлов (сторонние библиотеки i18n или автономные проекты GT)
Генерация языковых файлов для проектов GT
Примечания
Дальнейшие шаги
Руководство по использованию