Как ограничить расход токенов Claude Code при генерации переводов

Описание проблемы

Запрос к Claude Code (или любому другому агенту разработки) на перевод контента является самым дорогостоящим способом. При каждом запуске агент вынужден:

• Загружать весь файл JSON или файл контента в свой контекст, включая уже переведенные ключи.
• Искать связанные файлы, чтобы понять, где находится контент и как он структурирован.
• Определять, какие локали отсутствуют и должны быть сгенерированы.
• Каждый раз заново считывать ваши пользовательские инструкции ("преобразовывать URL определенным образом", "оставлять название бренда на английском", "использовать обращение на ты").
• Переписывать весь файл целиком, включая части, которые не менялись.

Все это повторно отправляется на каждой итерации, поэтому стоимость возрастает по формуле размер контента × количество локалей × количество итераций, а любые расхождения в форматировании или ключах приходится отслеживать вручную.

Что Intlayer делает вместо этого

Преимущество Intlayer заключается в выполнении этой работы вне агента с помощью конвейера, созданного специально для перевода:

• Фильтрует существующие переводы для ограничения расхода токенов. Уже переведенные ключи в вашем JSON удаляются, и модели отправляются только недостающие.
• Переводит markdown по блокам. Для документации команды doc translate и doc review сравнивают каждый блок с исходным документом и пропускают уже переведенные или неизмененные блоки.
• Разбивает ваш JSON на части (chunking), если он слишком большой, чтобы оставаться в оптимальной части контекстного окна.
• Сглаживает и восстанавливает структуру JSON для оптимизации расхода токенов.
• Вставляет пользовательские промпты для специфических правил бренда и терминологии (applicationContext, --custom-instructions), позволяя написать их один раз вместо повторения в каждом диалоге.
• Проверяет структуру для обеспечения согласованности и предотвращения расхождения ключей, сохраняя форматирование (markdown, HTML, вставки, множественные числа).
• Реализует повторные попытки (retry) в случае некорректного формата ответа.
• Ставит в очередь и распараллеливает запросы по файлам, фрагментам и локалям для максимальной скорости.

Ничто из этого не проходит через контекст агента. Главное правило: пусть агент решает, что интернационализировать, а Intlayer выполняет повторяющуюся рутинную работу.

Решение

1. Делегируйте извлечение команде intlayer extract

Вместо того чтобы просить агента вручную переписывать каждый компонент, выполните команду extract. Она переносит жестко заданные строки в файл .content рядом с компонентом без загрузки всего исходного файла в контекст агента.

npx intlayer extract --file src/components/Header.tsx

2. Делегируйте перевод команде intlayer fill

Никогда не поручайте агенту перевод напрямую. Команда fill применяет описанный выше конвейер: она отправляет только недостающие ключи, разбивает их на части, обрабатывает локали параллельно и записывает результат обратно в ваши файлы контента.

npx intlayer fill

Несколько флагов позволяют оптимизировать запуск:

• --git-diff (или --uncommitted) обрабатывает только словари, измененные в текущей ветке.
• --file или --keys выбирает конкретные файлы контента.
• --output-locales fr es ограничивает выполнение только теми локалями, которые необходимы прямо сейчас.
• --skip-metadata пропускает создание заголовка, описания и тегов.
• --data-serialization toon передает более компактные данные модели (меньше токенов, немного менее предсказуемый вывод).

npx intlayer fill --git-diff --output-locales fr es --skip-metadata

3. Переводите markdown с помощью doc translate и doc review

Запрос агенту на перевод файла .md приводит к отправке всего документа для каждой локали при каждом изменении. Команды doc translate и doc review работают поблочно.

Используйте doc translate, если переведенного файла еще не существует. Команда разбивает markdown, переводит его параллельно и создает целевые файлы:

npx intlayer doc translate --doc-pattern "docs/**/*.md" --base-locale en --locales fr es

Используйте doc review, если переведенный файл уже существует. Команда сравнивает каждый блок с базовым документом, пропускает уже переведенные или неизмененные блоки и отправляет только отличающиеся:

npx intlayer doc review --doc-pattern "docs/**/*.md" --base-locale en --locales fr es

Обе команды принимают ваши инструкции один раз, избавляя от необходимости повторять их в каждом промпте:

npx intlayer doc translate --custom-instructions "Do not translate URLs. Keep the markdown structure and the code blocks untouched."

Два режима doc review особенно полезны, когда агенту необходимо участвовать в процессе без вызовов ИИ со стороны Intlayer:

• --mode report выводит блоки, требующие внимания, с номерами строк, позволяя агенту изменять только их.
• --mode synthesis сообщает только о том, какие документы актуальны, а какие содержат блоки для редактирования.

npx intlayer doc review --mode report --locales fr

4. Позвольте агенту обращаться к CLI через сервер MCP

Благодаря серверу MCP Intlayer агент отвечает на основе актуальной документации и запускает intlayer fill или intlayer doc review самостоятельно вместо повторной реализации логики в диалоге.

claude mcp add intlayer npx -y @intlayer/mcp

Установка Agent Skills с помощью npx intlayer init skills также избавляет агента от необходимости угадывать API Intlayer и перечитывать документацию при каждой задаче.

5. Повторно используйте подписку Claude с помощью claude setup-token

Настройка i18n в интерактивной сессии Claude Code сохраняет всю историю разговора в контексте. Перенесите ресурсоемкие операции в короткую headless-сессию.

Сгенерируйте долгоживущий токен из вашей подписки Claude:

claude setup-token

Сохраните его как CLAUDE_CODE_OAUTH_TOKEN (в файле .env или в секретах CI) и используйте для разовой сессии, запускающей команды Intlayer:

CLAUDE_CODE_OAUTH_TOKEN=... claude -p "Run npx intlayer extract on src/components, then npx intlayer fill --uncommitted"

Сессия будет содержать только этот промпт и вывод команды, исключая всю предыдущую переписку. Этот же токен работает в Claude Code GitHub Action для запуска intlayer fill при каждом pull request.

Токен, созданный командой claude setup-token, авторизует исключительно Claude Code. Его нельзя использовать в качестве ключа API Anthropic в параметре ai.apiKey. Для самого перевода intlayer fill задействует ваш аккаунт Intlayer (включая бесплатный тариф) или ваш собственный ключ провайдера, настроенный в секции ai.

Итоги