Переводы
Как перевести проект
Использование
Запустите это в конвейере CI до сборки приложения для продакшена.
npx gtx-cli translateПримечание: Для этой команды требуется production API‑ключ! Получите его на платформе.
Обзор
Команда gtx-cli translate переводит ваш проект.
Она обходит дерево файлов проекта и переводит любой контент, обёрнутый в компонент <T>,
или использующий функции useGT.
Кроме того, она включает контент из файла словаря (если он указан).
Эта команда — основной способ работы с General Translation API и связанными сервисами.
Только для продакшна!
Эта команда предназначена для продакшн-сборок и не должна использоваться в разработке.
Перед запуском убедитесь, что вы на ветке, предназначенной для продакшна.
Не забудьте также указать продакшн API‑ключ (GT_API_KEY) и Project ID (GT_PROJECT_ID) в переменных окружения.
Использование
Есть три способа использовать команду translate. Для способов 1 и 2 требуется production API key:
Рекомендуем запустить мастер настройки: npx gtx-cli configure, чтобы настроить проект перед запуском команды translate.
В зависимости от конфигурации вашего проекта поведение команды translate может отличаться.
Метод 1: Перевод JSON‑файлов вашего проекта.
Если вы используете другие библиотеки i18n, такие как next-intl, react-i18next или next-i18next, вы можете воспользоваться этим методом для перевода JSON‑файлов вашего проекта.
Переводы будут автоматически сохраняться в вашем репозитории кода.
Чтобы использовать CLI‑инструмент для перевода JSON‑файлов вашего проекта, измените файл gt.config.json, добавив json в свойство files.
См. документацию по настройке CLI для получения подробной информации.
npx gtx-cli translateCLI‑инструмент автоматически определит используемую библиотеку i18n, прочитав ваш файл package.json, и переведёт ваши JSON‑файлы с учётом синтаксиса этой библиотеки.
Способ 2: Переведите проект GT
Если ваш проект использует gt-next или gt-react, вы можете воспользоваться этим способом, чтобы сгенерировать переводы для своего проекта.
npx gtx-cli translateПо умолчанию переводы сохраняются на CDN GT.
Если вы хотите хранить переводы в своём кодовой базе, добавьте свойство gt в объект files в файле gt.config.json.
gt-next и gt-react поддерживают локальную выдачу переводов, а также использование публичного CDN General Translation.
Рекомендуем использовать CDN для снижения задержки, повышения производительности и уменьшения размера бандла.
См. документацию по конфигурации CLI для подробностей.
Метод 3: Проверьте компоненты <T> в проекте и файл словаря.
Этот метод помогает проверить компоненты <T> в вашем проекте и файл словаря.
Это гарантирует корректную конфигурацию проекта и то, что переводы будут валидными и точными.
Переводы не будут сгенерированы, если указан флаг --dry-run.
npx gtx-cli translate --dry-runФлаги
| Параметр | Описание | Тип | Необязательно | Значение по умолчанию |
|---|---|---|---|---|
--api-key | Указать рабочий (production) API‑ключ | string | true | |
--project-id | Указать ID проекта | string | true | |
--version-id | Указать ID версии (по умолчанию — хеш содержимого) | string | true | |
--config <path> | Указать путь к конфигурационному файлу GT | string | true | "gt.config.json" |
--tsconfig, --jsconfig <path> | Указать путь к файлу конфигурации TS или JS | string | true | |
--src <paths> | Список glob‑шаблонов, разделённых пробелами, для поиска исходных файлов. Пути должны быть относительными к корневому каталогу. | [string] | true | [ 'src/**/*.{js,jsx,ts,tsx}', 'app/**/*.{js,jsx,ts,tsx}', 'pages/**/*.{js,jsx,ts,tsx}', 'components/**/*.{js,jsx,ts,tsx}', ] |
--dictionary <path> | Указать путь к файлу словаря | string | true | |
--inline | Включать встроенные теги <T> в дополнение к словарю | boolean | true | true |
--timeout | Таймаут запроса на перевод (в секундах) | number | true | 600 |
--new, --locales <locales> | Локали, на которые переводить проект | [string] | true | |
--default-locale <locale> | Исходная локаль проекта | string | true | en |
--ignore-errors | Игнорировать ошибки и принудительно переводить валидный контент | flag | true | false |
--dry-run | Пробный запуск команды | flag | true | false |
--force | Принудительно выполнить повторный перевод проекта | flag | true | false |
--force-download | Принудительно скачать все переводы для проекта | flag | true | false |
Все эти параметры необязательны.
Не добавляйте свой API‑ключ в файл gt.config.json!
Вместо этого задайте его как переменную окружения. CLI автоматически прочитает GT_API_KEY, если она задана.
Есть несколько ключевых параметров:
| Параметр | Описание |
|---|---|
--dry-run | Этот флаг заставит CLI проанализировать и провалидировать ваш проект, но не будет взаимодействовать с GT API. Полезно для проверки кодовой базы. |
--api-key | Если вы не используете --dry-run, необходимо указать рабочий (production) API‑ключ. |
--project-id | Аналогично, если вы не используете --dry-run, необходимо указать ID проекта. |
--new, --locales <locales> | Локали, на которые переводить ваш проект. Они будут добавлены к локалям, указанным в вашем файле gt.config.json. |
--force | Этот флаг принудительно выполнит повторный перевод вашего проекта и перезапишет все существующие переводы. |
--force-download | Этот флаг принудительно скачает все переводы и перезапишет любые локальные изменения в переводах. |
Файл конфигурации
При первом запуске CLI-инструмента он попытается создать файл gt.config.json в корне вашего проекта.
Этот файл содержит метаданные о проекте, используемые для перевода вашего контента.
Подробнее о файле gt.config.json читайте здесь.
Важные рекомендации
Источники контента
Команда translate рекурсивно ищет переводимый контент в вашем проекте.
По умолчанию поиск выполняется в следующих каталогах:
./src./app./pages./components
Вы можете указать другие каталоги для поиска с помощью флага --src
или изменив свойство src в файле gt.config.json.
Перезапись переводов
По умолчанию CLI‑инструмент не будет перезаписывать локальные изменения в переводах, если только исходное содержимое не изменилось.
Если вы хотите заново перевести уже переведённый контент проекта, используйте флаг --force.
При использовании --force все существующие переводы будут перезаписаны, и локальные изменения в переводах не сохранятся.
Если вы уже загрузили самые актуальные переводы проекта и хотите скачать их снова, используйте флаг --force-download.
При использовании --force-download локальные изменения в переводах будут перезаписаны, а также будут получены самые свежие переводы. Повторного перевода контента не происходит.
Файл словаря
Команда translate автоматически определит файл словаря в вашем проекте.
По умолчанию она ищет файл с именем dictionary.[json|ts|js] в следующих каталогах:
./src./
Вы можете указать другой файл словаря с помощью флага --dictionary или изменить свойство dictionary в файле gt.config.json.
Насколько полезно это руководство?