gt@2.23.0 / @generaltranslation/api@0.5.0

gt@2.23.0 позволяет прямо в терминале входить в учётную запись, выбирать проект, создавать ключи с ограниченными разрешениями и выполнять настройку из скриптов. В сопутствующих релизах @generaltranslation/api@0.5.0 и generaltranslation@9.5.2 появилось обнаружение проектов с автоматической пагинацией.

Начните с пошаговой настройки

Выполните gt init, чтобы настроить проект. Вход в систему потребуется, только если команда создаёт проект или ключ:

npx gt init

Используйте gt login, чтобы войти без запуска настройки, или npx gt login --no-browser, чтобы подтвердить вход на другом устройстве. В обоих случаях требуется ручное утверждение.

gt whoami показывает, под какой учётной записью выполнен вход, а gt logout удаляет сохранённый сеанс. Для автоматических рабочих процессов без участия человека используйте API-ключи с ограниченными правами из хранилища секретов вашего CI-провайдера.

Запуск настройки из скриптов и агентов

Для каждого вопроса настройки есть свой флаг. Если терминал недоступен или указан флаг --no-interactive, команда gt init выводит список всех недостающих параметров ещё до изменения файлов, а --json выдаёт события входа, передачи управления и результата:

npx gt init --no-interactive --json --defaults --locales fr es --no-dev-credentials

--defaults применяет рекомендуемые локальные настройки, но никогда не создаёт проекты и ключи.

Выбор проекта и разрешений ключа

gt init может выбрать доступный проект или создать новый в организации, где у вас есть соответствующее разрешение, а затем сохранить его ID и runtime-ключ для разработки в .env.local.

Этот ключ даёт только разрешение project:translations:generate: он предназначен для локальных runtime-переводов, а не для загрузки через CLI или использования в CI. Существующие значения GT_API_KEY не изменяются. Проекты Next.js с App Router получают NEXT_PUBLIC_GT_PROJECT_ID и NEXT_PUBLIC_GT_DEV_API_KEY, поэтому в режиме разработки переводятся и клиентские компоненты; не допускайте попадания обеих переменных в production-сборки (см. учётные данные Next.js).

Чтобы создать дополнительный ключ проекта с нужными вам разрешениями, используйте gt api-key create:

npx gt api-key create --project-id your-project-id \
  --name "Runtime translations" \
  --permission project:translations:generate

У вас должны быть права на создание ключей и на выдачу каждого из выбранных разрешений. Команда выводит секрет только один раз — сохраните его в надёжном месте. Для CI не используйте повторно этот пример, рассчитанный только на генерацию, а выберите разрешения, покрывающие весь рабочий процесс. Никогда не включайте API-ключи в бандлы, развёртываемые в браузере или на мобильных устройствах.

Используйте типизированные вызовы API и проверяйте результаты заданий

Используйте paginate из generaltranslation/api, чтобы перебрать все проекты, доступные вашему API-ключу, без ручной работы с курсорами:

import { listProjects, paginate } from 'generaltranslation/api';

for await (const project of paginate(listProjects, { client })) {
  console.log(project.id, project.name);
}

При использовании клиента createApiClient ошибки HTTP в вызовах с throwOnError теперь приводят к выбрасыванию исключения ApiError, а HTTP-статус передаётся в поле code.

Вспомогательные функции опроса API-клиента позволяют дождаться завершения заданий перевода и при истечении тайм-аута возвращают complete: false. Завершение не означает, что все задания выполнены успешно. Прежде чем скачивать переводы, проверьте результаты заданий.

Форматирование диагностических сообщений теперь доступно через публичную точку входа generaltranslation/diagnostics. Инструменты могут формировать сообщения с конкретными рекомендациями, не импортируя полную точку входа Ядра.

Обновление

Обновитесь, чтобы получать списки проектов и организаций. Теперь API возвращает их в items вместо projects или orgs и отклоняет курсоры, выданные до этого изменения. Более ранние версии CLI не могут получать их списки в gt init. Код, обращающийся к API напрямую по HTTP или через SDK, должен читать items и начинать пагинацию заново.
Перехватывайте ApiError в вызовах, выбрасывающих исключения. При HTTP-ошибках вызовы с throwOnError и awaitJobs выбрасывают исключение ApiError вместо декодированного тела ответа. Вызовы без throwOnError по-прежнему возвращают тело ответа в error.
Переместите src/gt.config.json. CLI больше не читает этот файл. Переместите его в корень проекта или передайте --config src/gt.config.json.
Замените gt auth и --key-type. Для аутентификации учётной записи используйте вход в систему, для пошаговой настройки проекта — init, а для дополнительных учётных данных — явное создание ключей. gt configure не является заменой без побочных эффектов: в зависимости от вашей конфигурации эта команда может устанавливать зависимости и создавать учётные данные.
Разделяйте учётные данные для среды выполнения и для инструментов. GT_DEV_API_KEY остаётся настройкой среды выполнения фреймворка. Сам по себе вход в систему не настраивает учётные данные SDK для среды выполнения. Явно заданные API-ключи по-прежнему имеют приоритет над сохранённым входом CLI; см. раздел выбор учётных данных.
Пересмотрите допущения о повторных попытках. Управляющие POST-запросы не повторяются автоматически при сетевых ошибках и ошибках сервера, однако при включённых повторных попытках запросы с ответом 429 по-прежнему могут повторяться. Runtime-перевод в Ядре не повторяет автоматически ни эти ошибки, ни ответы 429. Не повторяйте вслепую создание проектов или ключей: каждый успешный запрос создаёт ещё один ресурс.
Продолжайте использовать поддерживаемые API совместимости. Резервный вариант devApiKey в Ядре и getProjectData остаются доступными, но считаются устаревшими. Используйте apiKey, а для новых вызовов получения информации о проекте лучше применять getProjectInfo.
Учитывайте изменения в проверке и результатах. Неподдерживаемые значения поставщика модели приводят к ошибке ещё до отправки запроса. Результаты загрузки шрифтов больше не содержат поле deduped.