# General Translation Changelog: gt 2.23.0 / @generaltranslation/api 0.5.0: Вход в систему и настройка проектов из CLI
URL: https://generaltranslation.com/ru/blog/gt_v2_23_0_generaltranslation-api_v0_5_0.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Входите в систему, настраивайте проект и создавайте ключи с явно заданными разрешениями прямо из CLI или запускайте настройку в headless-режиме из скриптов и агентов.
Authors: Chenxin (Cyan) Yan
Published: 2026-09-29

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

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

Выполните [`gt init`](/docs/cli/reference/commands/init), чтобы настроить проект. Вход в систему потребуется, только если команда создаёт проект или ключ:

```bash
npx gt init
```

Используйте [`gt login`](/docs/cli/reference/commands/login), чтобы войти без запуска настройки, или [`npx gt login --no-browser`](/docs/cli/reference/commands/login#flags), чтобы подтвердить вход на другом устройстве. В обоих случаях требуется ручное утверждение.

[`gt whoami`](/docs/cli/reference/commands/whoami) показывает, под какой учётной записью выполнен вход, а [`gt logout`](/docs/cli/reference/commands/logout) удаляет сохранённый сеанс. Для автоматических рабочих процессов без участия человека используйте API-ключи с ограниченными правами из хранилища секретов вашего CI-провайдера.

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

Для каждого вопроса настройки есть свой флаг. Если терминал недоступен или указан флаг `--no-interactive`, команда [`gt init`](/docs/cli/reference/commands/init#headless) выводит список всех недостающих параметров ещё до изменения файлов, а `--json` выдаёт события входа, передачи управления и результата:

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

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

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

[`gt init`](/docs/cli/reference/commands/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](/docs/react/nextjs/config#credentials)).

Чтобы создать дополнительный ключ проекта с нужными вам разрешениями, используйте [`gt api-key create`](/docs/cli/reference/commands/api-key-create):

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

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

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

Используйте [`paginate`](/docs/platform/core/reference/api-client#pagination) из [`generaltranslation/api`](/docs/platform/core/reference/api-client), чтобы перебрать все проекты, доступные вашему API-ключу, без ручной работы с курсорами:

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

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

При использовании клиента `createApiClient` ошибки HTTP в вызовах с `throwOnError` теперь приводят к выбрасыванию исключения [`ApiError`](/docs/platform/core/reference/api-client#api-error), а HTTP-статус передаётся в поле `code`.

[Вспомогательные функции опроса API-клиента](/docs/platform/core/reference/api-client#job-polling) позволяют дождаться завершения заданий перевода и при истечении тайм-аута возвращают `complete: false`. Завершение не означает, что все задания выполнены успешно. Прежде чем скачивать переводы, проверьте результаты заданий.

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

## Обновление

* **Обновитесь, чтобы получать списки проектов и организаций.** Теперь API возвращает их в `items` вместо `projects` или `orgs` и отклоняет курсоры, выданные до этого изменения. Более ранние версии CLI не могут получать их списки в [`gt init`](/docs/cli/reference/commands/init). Код, обращающийся к API напрямую по HTTP или через SDK, должен читать `items` и начинать пагинацию заново.
* **Перехватывайте `ApiError` в вызовах, выбрасывающих исключения.** При HTTP-ошибках вызовы с `throwOnError` и [`awaitJobs`](/docs/platform/core/reference/api-client#job-polling) выбрасывают исключение `ApiError` вместо декодированного тела ответа. Вызовы без `throwOnError` по-прежнему возвращают тело ответа в `error`.
* **Переместите `src/gt.config.json`.** CLI больше не читает этот файл. Переместите его в корень проекта или передайте `--config src/gt.config.json`.
* **Замените `gt auth` и `--key-type`.** Для аутентификации учётной записи используйте вход в систему, для пошаговой настройки проекта — init, а для дополнительных учётных данных — явное создание ключей. [`gt configure`](/docs/cli/reference/commands/configure) не является заменой без побочных эффектов: в зависимости от вашей конфигурации эта команда может устанавливать зависимости и создавать учётные данные.
* **Разделяйте учётные данные для среды выполнения и для инструментов.** `GT_DEV_API_KEY` остаётся настройкой среды выполнения фреймворка. Сам по себе вход в систему не настраивает учётные данные SDK для среды выполнения. Явно заданные API-ключи по-прежнему имеют приоритет над сохранённым входом CLI; см. раздел [выбор учётных данных](/docs/cli/guides/configuring#credentials).
* **Пересмотрите допущения о повторных попытках.** Управляющие POST-запросы не повторяются автоматически при сетевых ошибках и ошибках сервера, однако при включённых повторных попытках запросы с ответом 429 по-прежнему могут повторяться. Runtime-перевод в Ядре не повторяет автоматически ни эти ошибки, ни ответы 429. Не повторяйте вслепую создание проектов или ключей: каждый успешный запрос создаёт ещё один ресурс.
* **Продолжайте использовать поддерживаемые API совместимости.** Резервный вариант `devApiKey` в Ядре и [`getProjectData`](/docs/platform/core/reference/gt-class-methods/translation/get-project-data) остаются доступными, но считаются устаревшими. Используйте `apiKey`, а для новых вызовов получения информации о проекте лучше применять [`getProjectInfo`](/docs/platform/core/reference/gt-class-methods/project/project-management#get-project-info).
* **Учитывайте изменения в проверке и результатах.** Неподдерживаемые значения поставщика модели приводят к ошибке ещё до отправки запроса. Результаты загрузки шрифтов больше не содержат поле `deduped`.

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.