# General Translation Overview: Использование ИИ-агентов для написания кода
URL: https://generaltranslation.com/ru/docs/overview/for-coding-agents.mdx
---

title: Использование ИИ-агентов для написания кода
description: Как использовать ИИ-агентов для написания кода и LLMs с General Translation, направляя их на машиночитаемую документацию, MCP-сервер и наше руководство по быстрому подключению агента.

---

General Translation создана для работы с ИИ-агентами для написания кода и LLMs. Библиотеки имеют открытый исходный код, конфигурация предсказуема, а документация публикуется в машиночитаемых форматах. Агент, такой как Cursor, Claude Code или Copilot, может добавить и запустить General Translation за вас, используя точный и актуальный контекст.

*Для полностью автоматизированной локализации, которая сама открывает pull request, используйте наш специализированный агент [Locadex](/docs/platform/locadex/quickstart), а не собственного агента.*

## Руководство по быстрому подключению агента [#agent-guide]

Дайте своему агенту всё необходимое одной вставкой. Скопируйте приведённое ниже руководство в `AGENTS.md` (или `CLAUDE.md`, правило Cursor либо файл инструкций вашего инструмента) в корне проекта, и ваш агент сможет корректно добавить и запустить General Translation. Используйте кнопку копирования в правом верхнем углу блока.

````markdown title="AGENTS.md"
# General Translation — agent guide

Инструкции для AI-агентов по добавлению [General Translation](https://generaltranslation.com) в проект. General Translation — это продукт для комплексной локализации: библиотеки i18n с открытым исходным кодом и CLI для перевода приложения и его контента на любой язык. Следуйте этим правилам при интернационализации кода или настройке переводов.

## Что использовать

Выберите пакет, соответствующий вашему стеку:

- **Next.js (App Router или Pages Router)** → `gt-next`
- **React (SPA, например Vite)** → `gt-react`
- **Node.js сервер** → `gt-node`
- **Любой JavaScript runtime или низкоуровневое управление** → `generaltranslation` (core library)
- **Перевод файлов контента (JSON, MDX, YAML и других) или запуск перевода в CI** → CLI `gt`

Все они бесплатны и имеют открытый исходный код. Библиотеки работают как с учётной записью General Translation, так и без неё; API Key открывает доступ к переводу по запросу в процессе разработки и к размещённому translation API.

## Настройка

Рекомендуется использовать мастер настройки. Из корня проекта выполните:

```bash
npx gt init
```

Он устанавливает нужную библиотеку и CLI `gt`, настраивает фреймворк (для Next.js добавляет `withGTConfig` и `GTProvider`), создаёт `gt.config.json` и генерирует API-учётные данные.

Для ручной настройки установите пакеты самостоятельно:

```bash
npm install gt-next   # or gt-react / gt-node / generaltranslation
npm install -D gt
```

Затем создайте `gt.config.json` в корне проекта — это единственный источник истины для локалей:

```json
{
  "defaultLocale": "en",
  "locales": ["es", "fr", "ja"],
  "files": { "gt": { "output": "public/_gt/[locale].json" } }
}
```

- `defaultLocale` — язык, на котором написан исходный текст.
- `locales` — языки, на которые нужно переводить.
- `files.gt.output` — путь, по которому CLI записывает файлы перевода (`[locale]` заменяется для каждого языка). Добавьте эту директорию в `.gitignore` — файлы генерируются автоматически.

Задайте API-учётные данные в виде переменных окружения (в `.env.local` для Next.js, иначе в `.env`):

```bash
GT_API_KEY="gtx-dev-..."   # gtx-dev- in development, gtx-api- in production/CI
GT_PROJECT_ID="..."
```

Никогда не коммитьте `GT_API_KEY`, не передавайте его в браузер и не добавляйте к нему префикс `NEXT_PUBLIC_`.

## Основное использование

Оборачивайте пользовательский JSX в `<T>`. Пишите исходный текст напрямую — ключи перевода не нужны:

```tsx
import { T } from 'gt-next'; // or 'gt-react'

// Всё внутри <T> переводится как единое целое
<T>
  <h1>Welcome to my app</h1>
</T>;
```

Используйте `useGT()` для отдельных строк (плейсхолдеры, `aria-label`, `alt`, подписи кнопок). `useGT()` возвращает функцию перевода напрямую:

```tsx
import { useGT } from 'gt-next';

const gt = useGT(); // ✅ правильно
// const { gt } = useGT(); // ❌ неправильно — useGT возвращает функцию, а не объект

<input placeholder={gt('Search products')} />;
```

В асинхронных компонентах App Router используйте вместо него `getGT`. `gt-next/server` не работает с Pages Router:

```tsx
import { getGT } from 'gt-next/server';

const gt = await getGT();
```

Оборачивайте динамические или приватные значения (имена, email-адреса, идентификаторы) в `<Var>`, чтобы они не переводились и никогда не отправлялись в API. Используйте `<Currency>`, `<DateTime>` и `<Num>` для значений, которые нужно переформатировать, но не переводить:

```tsx
import { T, Var } from 'gt-next';

// Генерирует один перевод, оставляя имя без изменений
<T>
  Hello, <Var>{name}</Var>!
</T>;
```

Для Node.js серверов инициализируйте один раз и разрешайте переводы для каждого запроса:

```js
import { initializeGT, withGT, getGT } from 'gt-node';

initializeGT({ defaultLocale: 'en', locales: ['en', 'es', 'fr'] });
// оборачивайте handler'ы в withGT(locale, ...); затем используйте `const gt = await getGT()` внутри них
```

Храните всю конфигурацию локалей в `gt.config.json` — не разбрасывайте списки локалей по всей кодовой базе.

## Команды

| Команда | Когда запускать |
| --- | --- |
| `npx gt init` | Один раз, для настройки проекта (устанавливает зависимости, настраивает фреймворк, создаёт `gt.config.json`, генерирует учётные данные). |
| `npx gt configure` | Для создания или обновления `gt.config.json` (локали и файлы) без полного мастера настройки. |
| `npx gt auth` | Для генерации или обновления API-учётных данных. |
| `npx gt translate` | Для перевода проекта через General Translation API. Запускайте в CI **перед** сборкой для production. |
| `npx gt generate` | Для создания шаблонов файлов перевода для ручного перевода (API Key не требуется). |

Добавьте перевод в production-сборку, чтобы переводы оставались актуальными, например: `"build": "npx gt translate && next build"`.

## Правила — что делать и чего не делать

Делайте:

- Оборачивайте каждый новый пользовательский текст в `<T>` (или `useGT()`/`getGT()` для отдельных строк) по мере написания.
- Запускайте `npx gt translate` перед коммитом или сборкой для production, чтобы новый текст был переведён.
- Храните список локалей только в `gt.config.json`.
- Оборачивайте динамические и приватные значения в `<Var>` и добавляйте `context`, когда строка неоднозначна.

Не делайте:

- Не хардкодьте уже переведённые строки в исходном коде и не добавляйте ветки `if`/`switch` для каждого языка — переводите исходный текст.
- Не редактируйте вручную сгенерированные файлы перевода (CLI перезаписывает их).
- Не коммитьте `GT_API_KEY` и не передавайте его клиенту.
- Не дублируйте конфигурацию локалей за пределами `gt.config.json`.

## Ссылки

- [`llms.txt`](/llms.txt) — краткий машиночитаемый индекс документации.
- [`sitemap.md`](/sitemap.md) — карта всех страниц документации.
- Quickstart'ы: [React](/docs/react/react-quickstart), [Node](/docs/node/quickstart), [Core library](/docs/platform/core/quickstart) и [CLI](/docs/cli/quickstart).
- [Ключевые концепции](/docs/overview/key-concepts) — локали, context и статический vs. динамический контент.
````

## Дайте агентам доступ к документации [#point-agents]

Предоставьте агенту прямой доступ к документации, чтобы его ответы оставались точными. General Translation публикует несколько машиночитаемых точек входа в корневом каталоге сайта:

* [`llms.txt`](/llms.txt) — краткий указатель документации в стиле [llmstxt.org](https://llmstxt.org/).
* [`sitemap.md`](/sitemap.md) — карта со ссылками на все страницы в порядке навигации.

Каждая страница документации также доступна в формате **raw Markdown**: добавьте `.md` к URL любой страницы (например, `/docs/cli/quickstart.md`), чтобы получить чистый исходник вместо того, чтобы разбирать отрендеренный HTML.

Чтобы добавить документацию в контекст, вставьте URL страницы документации или ссылку на `llms.txt` в контекст агента либо добавьте документацию как источник в инструментах, которые поддерживают индексацию документации.

## MCP-сервер [#mcp]

General Translation предоставляет сервер [Model Context Protocol](https://modelcontextprotocol.io) (MCP), который позволяет агентам напрямую обращаться к документации. Он доступен в двух вариантах:

* **Локальный (stdio)** — опубликованный npm-пакет [`@generaltranslation/mcp`](https://www.npmjs.com/package/@generaltranslation/mcp), который запускается на вашем компьютере через `npx`. Лучше всего подходит для инструментов, которые поддерживают постоянное подключение, таких как Cursor и Claude Code.
* **Удалённый (HTTP/SSE)** — размещённый эндпоинт по адресу `https://mcp.gtx.dev`. Используйте SSE-эндпоинт только в том случае, если ваш инструмент не поддерживает streamable HTTP.

Настройте подключение, используя транспорт, который поддерживает ваш инструмент. Формат конфигурации одинаков для всех инструментов — добавьте его в конфигурационный файл MCP вашего инструмента (например, `.mcp.json`):

<Tabs items={['Локальный', 'Потоковый HTTP', 'SSE']}>
  <Tab value="Локальный">
    ```json title=".mcp.json"
    {
      "mcpServers": {
        "generaltranslation": {
          "command": "npx",
          "args": ["-y", "@generaltranslation/mcp@latest"]
        }
      }
    }
    ```
  </Tab>

  <Tab value="Потоковый HTTP">
    ```json title=".mcp.json"
    {
      "mcpServers": {
        "generaltranslation": {
          "type": "streamable-http",
          "url": "https://mcp.gtx.dev"
        }
      }
    }
    ```
  </Tab>

  <Tab value="SSE">
    ```json title=".mcp.json"
    {
      "mcpServers": {
        "generaltranslation": {
          "type": "sse",
          "url": "https://mcp.gtx.dev/sse"
        }
      }
    }
    ```
  </Tab>
</Tabs>

После подключения попросите своего агента использовать MCP-сервер `generaltranslation`. *Пример: &quot;Используй MCP-сервер generaltranslation, чтобы объяснить, как использовать компонент [`<T>`](/docs/react/reference/components/t).&quot;*

## Советы для отдельных редакторов [#editor-tips]

Большая часть настройки одинакова для всех агентов; вот лишь несколько моментов, где рекомендации отличаются.

* **Cursor** — зарегистрируйте MCP-сервер, затем попросите его «использовать инструмент `generaltranslation`». Добавьте документацию как источник или укажите в запросе `/llms.txt`.
* **Claude Code** — автоматически читает корневой `AGENTS.md`, поэтому достаточно добавить [руководство по быстрому подключению агента](#agent-guide) в `AGENTS.md` вашего проекта, чтобы задать нужный контекст. Зарегистрируйте MCP-сервер и попросите его «использовать MCP-сервер `generaltranslation`».
* **Copilot** — поместите общие инструкции для всего репозитория в файл инструкций (например, `.github/copilot-instructions.md`) и укажите там `/llms.txt` из документации.

## Рекомендации [#best-practices]

Агенты хорошо справляются с механической i18n-работой, но качество перевода и конфигурацию всё равно должен проверять человек. Используйте такое разделение:

* **Поручите агенту:** оборачивать пользовательский текст в `<T>`, добавлять [`useGT()`](/docs/react/reference/hooks/use-gt) для отдельных строк, подготавливать `gt.config.json` и запускать `npx gt init`.
* **Проверяйте вручную:** [контекст перевода](/docs/overview/key-concepts#context) (Glossary и директивы), который создаёт агент, конфигурацию локалей (`defaultLocale` и `locales`), а также то, что динамические или приватные значения обернуты в [`<Var>`](/docs/react/reference/components/var).
* **Никогда не позволяйте агенту:** вручную редактировать сгенерированные файлы перевода или хардкодить уже переведённые строки вместо перевода исходного текста через CLI.