Як обмежити споживання токенів Claude Code під час генерації перекладів

Опис проблеми

Звернення до Claude Code (або будь-якого іншого кодинг-агента) для перекладу вашого контенту є найдорожчим способом. Під час кожного запуску агент змушений:

• Завантажувати повний файл JSON або файл контенту у свій контекст, навіть ті ключі, які вже перекладені.
• Шукати пов'язані файли, щоб зрозуміти, де розташований контент та як він структурований.
• Визначати, які локалі відсутні та мають бути згенеровані.
• Щоразу наново зчитувати ваші користувацькі інструкції ("перетворювати URL-адреси саме так", "залишати назву бренду англійською", "використовувати звернення на ти").
• Переписувати весь файл цілком, включаючи частини, які не зазнали змін.

Усе це повторно надсилається на кожній ітерації, через що витрати зростають за формулою розмір контенту × кількість локалей × кількість ітерацій, а будь-які невідповідності форматування чи ключів доводиться виправляти вручну.

Що Intlayer робить натомість

Перевага Intlayer полягає у виконанні цієї роботи за межами агента завдяки конвеєру (pipeline), створеному спеціально для перекладу:

• Фільтрує наявні переклади для обмеження використання токенів. Вже перекладені ключі у вашому 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. Його не можна використовувати як ключ Anthropic API у параметрі ai.apiKey. Для самого перекладу intlayer fill застосовує ваш обліковий запис Intlayer (включно з безкоштовним тарифом) або ваш власний ключ провайдера, налаштований у секції ai.

Підсумок