# General Translation Overview: Использование ИИ-агентов для написания кода URL: https://generaltranslation.com/ru/docs/overview/for-coding-agents.mdx Docs index: https://generaltranslation.com/llms.txt 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. Используйте кнопку копирования в правом верхнем углу блока или получите то же руководство напрямую из [`/AGENTS.md`](/AGENTS.md). ````markdown title="AGENTS.md" # General Translation — agent guide Instructions for AI coding agents adding [General Translation](https://generaltranslation.com) to a project. General Translation is a full-stack localization product: open-source i18n libraries plus a CLI that translate an app and its content into any language. Follow these rules when internationalizing code or wiring up translations. ## What to use Pick the package that matches the stack: - **Next.js (App Router or Pages Router)** → `gt-next` - **React (SPA, e.g. Vite)** → `gt-react` - **Vue 3** → `gt-vue` - **Node.js server** → `gt-node` - **Any JavaScript runtime, or lower-level control** → `generaltranslation` (the Core library) - **Translating content files (JSON, MDX, YAML, and more) or running translation in CI** → the `gt` CLI All of these are free and open-source. The libraries work with or without a General Translation account; an API key unlocks on-demand translation in development and the hosted translation API. ## Setup Prefer the wizard. From the project root, run: ```bash npx gt init ``` It installs the right library and the `gt` CLI, wires up the framework (for Next.js, adds `withGTConfig` and `GTProvider`), creates `gt.config.json`, and generates API credentials. For manual setup, install the packages yourself: ```bash npm install gt-next # or gt-react / gt-node / generaltranslation npm install -D gt ``` Then create `gt.config.json` in the project root — this is the single source of truth for locales: ```json { "defaultLocale": "en", "locales": ["es", "fr", "ja"], "files": { "gt": { "output": "public/_gt/[locale].json" } } } ``` - `defaultLocale` — the language the source is written in. - `locales` — the languages to translate into. - `files.gt.output` — where the CLI writes translation files (`[locale]` is replaced per language). Add this directory to `.gitignore`; the files are generated. Set API credentials as environment variables (in `.env.local` for Next.js, `.env` otherwise): ```bash GT_API_KEY="gtx-dev-..." # gtx-dev- in development, gtx-api- in production/CI GT_PROJECT_ID="..." ``` Never commit `GT_API_KEY`, expose it to the browser, or prefix it with `NEXT_PUBLIC_`. ## Core usage Wrap user-facing JSX in ``. Write source copy directly — no translation keys needed: ```tsx import { T } from 'gt-next'; // or 'gt-react' // Everything inside is translated as a unit

Welcome to my app

; ``` Use `useGT()` for standalone strings (placeholders, `aria-label`, `alt`, button labels). `useGT()` returns the translation function directly: ```tsx import { useGT } from 'gt-next'; const gt = useGT(); // ✅ correct // const { gt } = useGT(); // ❌ wrong — useGT returns the function, not an object ; ``` In async App Router components, use `getGT` instead. `gt-next/server` does not work with the Pages Router: ```tsx import { getGT } from 'gt-next/server'; const gt = await getGT(); ``` Wrap dynamic or private values (names, emails, IDs) in `` so they are not translated and never sent to the API. Use ``, ``, and `` for values that should be reformatted but not translated: ```tsx import { T, Var } from 'gt-next'; // Generates one translation, keeps the name unchanged Hello, {name}! ; ``` For Node.js servers, initialize once and resolve translations per request: ```js import { initializeGT, withGT, getGT } from 'gt-node'; initializeGT({ defaultLocale: 'en', locales: ['en', 'es', 'fr'] }); // оборачивайте обработчики в 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` | Чтобы перевести проект через API General Translation. Запускайте в CI **перед** сборкой для продакшена; добавляйте `--save-local`, только если сначала нужно синхронизировать локальные правки. | | `npx gt generate` | Чтобы создать шаблоны файлов переводов для ручного перевода (API-ключ не нужен). | | `npx gt api --spec` | Чтобы просмотреть OpenAPI-контракт, поставляемый с установленным CLI. | | `npx gt api ` | Чтобы выполнить аутентифицированный низкоуровневый запрос к API из скрипта или терминала. | | `npx gt project create --org-id --name --default-locale ` | Чтобы создать проект с ключом организации. | | `npx gt project status ` | Чтобы просмотреть задачу перевода или генерации контекста проекта. | Добавьте перевод в продакшен-сборку, чтобы переводы оставались актуальными, например: `"build": "npx gt translate && next build"`. ## Правила — что делать и чего не делать Делайте: - Оборачивайте каждый новый пользовательский текст в `` (или `useGT()`/`getGT()` для отдельных строк) сразу при написании. - Запускайте `npx gt translate` перед коммитом или сборкой для продакшена, чтобы новый текст был переведён. - Храните список локалей только в `gt.config.json`. - Оборачивайте динамические и приватные значения в `` и добавляйте `context`, когда строка неоднозначна. - Если вы намеренно отредактировали сгенерированный файл перевода, запустите `npx gt save-local` перед следующим скачиванием переводов или передайте `--save-local` при следующем запуске перевода. Не делайте: - Не хардкодьте уже переведённые строки в исходниках и не добавляйте ветвления `if`/`switch` по языкам — вместо этого переводите исходный текст. - Не редактируйте сгенерированные файлы переводов без синхронизации изменений: последующее скачивание может перезаписать несохранённые правки. - Не коммитьте `GT_API_KEY` и не передавайте его клиенту. - Не дублируйте конфигурацию локалей вне `gt.config.json`. ## Ссылки - [`llms.txt`](/llms.txt) — курируемая машиночитаемая точка входа в документацию. - [`llms-index.txt`](/llms-index.txt) — исчерпывающий индекс всех страниц документации. - [`llms-full.txt`](/llms-full.txt) — полное содержимое документации для инструментов, способных загрузить больший контекст. - [Индекс React](/docs/react/llms.txt), [индекс CLI](/docs/cli/llms.txt) и [индекс OpenAPI](/docs/platform/openapi/llms.txt) — точки входа для типовых задач. - [`AGENTS.md`](/AGENTS.md) — это готовое руководство в виде исходного Markdown. - [`openapi.yaml`](/openapi.yaml) — каноническая спецификация API General Translation. - [`sitemap.md`](/sitemap.md) — Markdown-индекс всех страниц документации и записей блога. - [`sitemap.xml`](/sitemap.xml) — стандартная карта сайта для всех опубликованных страниц. - Быстрые старты: [React](/docs/react/react-quickstart), [Vue](/docs/vue/quickstart), [Node](/docs/node/quickstart), [библиотека Core](/docs/platform/core/quickstart) и [CLI](/docs/cli/quickstart). - [Ключевые концепции](/docs/overview/key-concepts) — локали, контекст, статический и динамический контент. - Справочник CLI: [`gt api`](/docs/cli/reference/commands/api), [`gt project create`](/docs/cli/reference/commands/project-create) и [`gt project status`](/docs/cli/reference/commands/project-status). ```` ## Направьте агентов на документацию [#point-agents] Дайте агенту прямой доступ к документации, чтобы его ответы оставались точными. General Translation публикует несколько машиночитаемых точек входа в корне сайта и по пути `/docs` на хосте документации: * [`llms.txt`](/llms.txt) — тщательно отобранная точка входа в стиле [llmstxt.org](https://llmstxt.org/) с основными Quickstart и тематическими указателями. * [`llms-index.txt`](/llms-index.txt) — исчерпывающий указатель ссылок на все опубликованные страницы документации. * [`llms-full.txt`](/llms-full.txt) — полное содержимое документации в одном файле, без сгенерированного справочника OpenAPI. * [`AGENTS.md`](/AGENTS.md) — приведённое выше готовое руководство в виде raw Markdown. * [`sitemap.md`](/sitemap.md) — указатель в формате Markdown по всем страницам документации и публикациям блога. * [`sitemap.xml`](/sitemap.xml) — стандартная XML-карта сайта для всех опубликованных страниц. Используйте узконаправленный указатель, если агент уже знает, какая часть продукта ему нужна: * [Overview](/docs/overview/llms.txt) * [Платформа](/docs/platform/llms.txt) с тематическими указателями для [Dashboard](/docs/platform/dashboard/llms.txt), [Locadex](/docs/platform/locadex/llms.txt), [Ядра](/docs/platform/core/llms.txt) и [OpenAPI](/docs/platform/openapi/llms.txt) * [CLI](/docs/cli/llms.txt) * [React](/docs/react/llms.txt) * [Vue](/docs/vue/llms.txt) * [Node.js](/docs/node/llms.txt) * [Python](/docs/python/llms.txt) * [Integrations](/docs/integrations/llms.txt) Для работы с API используйте [бандл операций OpenAPI](/docs/platform/openapi/llms-full.txt) или каноническую спецификацию [`openapi.yaml`](/openapi.yaml) вместо парсинга интерактивных страниц эндпоинтов. Хост документации также отдаёт корневые файлы по пути `/docs`, включая `/docs/llms.txt`, `/docs/llms-index.txt` и `/docs/llms-full.txt`. Каждая страница документации доступна в виде **raw Markdown**: добавьте `.md` или `.mdx` к URL любой страницы, чтобы получить чистый исходник вместо разбора отрендеренного HTML. Сгенерированные указатели и метаданные для обнаружения используют `.mdx`, например `/docs/cli/quickstart.mdx`. Чтобы добавить документацию в качестве контекста, вставьте URL страницы документации или ссылку на `llms.txt` в контекст вашего агента либо добавьте документацию как источник в инструментах, поддерживающих индексацию документации. ## MCP-сервер [#mcp] Используйте опубликованный пакет [`@generaltranslation/mcp`](https://www.npmjs.com/package/@generaltranslation/mcp), если вашему агенту нужна документация через локальное подключение [Model Context Protocol](https://modelcontextprotocol.io) (MCP) по стандартным потокам ввода и вывода: ```json title=".mcp.json" { "mcpServers": { "generaltranslation-docs": { "command": "npx", "args": ["-y", "@generaltranslation/mcp@latest"] } } } ``` Пакет предоставляет инструменты для получения списка и загрузки документации. Для более простого доступа к документации направьте своего агента напрямую на [машиночитаемую документацию](#point-agents). Для получения актуальной информации о проекте используйте хостируемый MCP-сервер по адресу `https://api.gtx.dev/mcp`. Он использует streamable HTTP. Хостируемый сервер также предоставляет [MCP-инструменты Google Drive](/docs/integrations/google-drive/reference/mcp-tools) для поиска подключённых проектов, перевода Google Docs и Google Slides, а также отслеживания прогресса перевода копий. Добавьте подключение в конфигурационный файл MCP вашего инструмента (например, `.mcp.json`). Названия транспортов и поля конфигурации могут различаться в зависимости от клиента: ```json title=".mcp.json" { "mcpServers": { "generaltranslation": { "type": "http", "url": "https://api.gtx.dev/mcp" } } } ``` ### Аутентификация в удалённом API Подключайтесь через поток входа OAuth вашего MCP-клиента или настройте `Authorization: Bearer ` в его параметрах секретного заголовка. Подключения по API-ключу принимают продакшен-ключи проекта (`gtx-api-`), ключи разработки проекта (`gtx-dev-`) и ключи организации (`gtx-org-`). Каждый инструмент сам решает, допускаются ли ключи разработки: runtime translation и [MCP-инструменты Google Drive](/docs/integrations/google-drive/reference/mcp-tools) их принимают, тогда как другие инструменты могут их отклонять. Сервер публикует метаданные защищённого ресурса и сервера авторизации. Клиент с поддержкой OAuth регистрируется динамически, использует поток Authorization Code с Proof Key for Code Exchange (PKCE) и открывает экран согласия в Dashboard. Запрашивайте `openid` и `profile` для получения сведений об identity и `offline_access`, если клиенту нужен refresh token. Используйте `list_projects`, чтобы найти ID проекта, а затем передайте его как `projectId` в инструменты проекта. Продакшен-ключ проекта может не указывать `projectId` — тогда используется его собственный проект. После подключения попросите агента использовать MCP-сервер `generaltranslation`. Попробуйте: «Выведи список моих проектов и покажи настройки локалей для одного из них». ## Советы для отдельных редакторов [#editor-tips] Большая часть настройки одинакова для всех агентов; вот лишь несколько моментов, где рекомендации отличаются. * **Cursor** — зарегистрируйте MCP-сервер, затем попросите его «использовать инструмент `generaltranslation`». Добавьте документацию как источник или укажите в запросе `/llms.txt`. * **Claude Code** — автоматически читает корневой `CLAUDE.md`, поэтому скопируйте [руководство по быстрому подключению агента](#agent-guide) в `CLAUDE.md` вашего проекта. Зарегистрируйте MCP-сервер и попросите его «использовать MCP-сервер `generaltranslation`». * **Copilot** — поместите общие инструкции для всего репозитория в файл инструкций (например, `.github/copilot-instructions.md`) и укажите там `/llms.txt` из документации. ## Рекомендации [#best-practices] Агенты хорошо справляются с механической i18n-работой, но качество перевода и конфигурацию всё равно должен проверять человек. Используйте такое разделение: * **Поручите агенту:** оборачивать пользовательский текст в [``](/docs/react/reference/components/t), добавлять [`useGT()`](/docs/react/reference/hooks/use-gt) для отдельных строк, подготавливать `gt.config.json` и запускать [`npx gt init`](/docs/cli/reference/commands/init). * **Проверяйте вручную:** [контекст перевода](/docs/overview/key-concepts#context) (Glossary и Custom Prompts), который создаёт агент, конфигурацию локалей (`defaultLocale` и `locales`), а также то, что динамические или приватные значения обернуты в [``](/docs/react/reference/components/var). * **Никогда не позволяйте агенту:** редактировать сгенерированные файлы перевода без синхронизации изменений или хардкодить уже переведённые строки вместо перевода исходного текста через CLI. ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.