@intlayer/docs 9.5.2 → 9.5.3

package/frequent_questions/pt/claude_code_token_consumption.md

@@ -0,0 +1,152 @@
+---
+createdAt: 2026-09-13
+updatedAt: 2026-09-13
+title: Como limitar o consumo de tokens do Claude Code para gerar traduções
+description: Por que traduzir com o Claude Code gasta tokens em excesso, o que o Intlayer faz em vez disso (filtra chaves traduzidas, divide JSON em blocos, traduz markdown bloco a bloco) e como reutilizar sua assinatura do Claude com claude setup-token.
+keywords:
+  - claude code
+  - tokens
+  - consumo de tokens
+  - setup-token
+  - i18n
+  - internacionalização
+  - tradução
+  - fill
+  - mcp
+  - agente
+slugs:
+  - frequent-questions
+  - claude-code-token-consumption
+author: aymericzip
+---
+
+# Como limitar o consumo de tokens do Claude Code para gerar traduções
+
+## Descrição do problema
+
+Pedir ao Claude Code (ou a qualquer agente de programação) para traduzir seu conteúdo é a forma mais cara de realizá-lo. Em cada execução, o agente precisa:
+
+- Carregar todo o arquivo JSON ou de conteúdo no seu contexto, até mesmo as chaves já traduzidas.
+- Buscar nos arquivos relacionados para identificar onde o conteúdo reside e como está estruturado.
+- Descobrir quais locales estão ausentes e precisam ser gerados.
+- Reler suas instruções personalizadas a cada execução ("transformar URLs desta maneira", "manter o nome da marca em inglês", "usar forma informal").
+- Reescrever todo o arquivo, inclusive as partes que não foram alteradas.
+
+Tudo isso é reenviado a cada interação, fazendo com que o custo cresça conforme `tamanho do conteúdo × número de locales × número de turnos`, e qualquer divergência de formatação ou de chaves precise ser corrigida manualmente.
+
+## O que o Intlayer faz em vez disso
+
+O diferencial do Intlayer é realizar esse trabalho fora do agente, através de um pipeline construído especificamente para tradução:
+
+- **Filtra traduções existentes** para limitar o uso de tokens. As chaves já traduzidas no seu JSON são ignoradas, enviando apenas as pendentes ao modelo.
+- **Traduz markdown bloco a bloco.** Para a documentação, [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/cli/doc-translate.md) e [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/cli/doc-review.md) comparam cada bloco com o documento base e ignoram blocos já traduzidos ou inalterados.
+- **Divide o seu JSON em partes (chunking)** se for muito grande, garantindo operação na melhor faixa da janela de contexto.
+- **Achata e reconstrói o seu JSON** para otimizar o consumo de tokens.
+- **Insere prompts personalizados** para regras específicas da sua marca e terminologia (`applicationContext`, `--custom-instructions`), permitindo que você as defina uma única vez em vez de repeti-las em cada conversa.
+- **Valida a estrutura** para assegurar consistência e evitar desvio de chaves, preservando a formatação (markdown, HTML, inserções, plurais).
+- **Implementa gestão de novas tentativas (retry)** caso a saída apresente formato inválido.
+- **Enfileira e paraleliza requisições** entre arquivos, blocos e locales para aumentar a velocidade.
+
+Nada disso transita pelo contexto do agente. A regra prática: deixe o agente decidir **o que** internacionalizar, e deixe o Intlayer cuidar do trabalho repetitivo.
+
+## Solução
+
+### 1. Delegar a extração para `intlayer extract`
+
+Em vez de pedir ao agente para reescrever cada componente manualmente, deixe-o executar o comando [`extract`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/cli/extract.md). Ele move strings fixas para um arquivo `.content` ao lado do componente sem carregar o arquivo completo no contexto do agente.
+
+```bash
+npx intlayer extract --file src/components/Header.tsx
+```
+
+### 2. Delegar a tradução para `intlayer fill`
+
+Nunca peça ao agente para traduzir. O comando [`fill`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/cli/fill.md) aplica o pipeline acima: envia apenas as chaves ausentes, as fragmenta, processa os locales em paralelo e grava o resultado de volta nos seus arquivos de conteúdo.
+
+```bash
+npx intlayer fill
+```
+
+Algumas flags mantêm a execução enxuta:
+
+- `--git-diff` (ou `--uncommitted`) processa apenas os dicionários alterados no branch atual.
+- `--file` ou `--keys` foca em arquivos de conteúdo específicos.
+- `--output-locales fr es` restringe a execução aos locales realmente necessários no momento.
+- `--skip-metadata` ignora a criação de título, descrição e tags.
+- `--data-serialization toon` envia uma carga útil mais compacta para o modelo (menos tokens, saída ligeiramente menos previsível).
+
+```bash
+npx intlayer fill --git-diff --output-locales fr es --skip-metadata
+```
+
+### 3. Traduzir markdown com `doc translate` e `doc review`
+
+Pedir a um agente para traduzir um arquivo `.md` significa colar todo o documento, para cada locale, a cada alteração. Os comandos [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/cli/doc-translate.md) e [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/cli/doc-review.md) operam bloco a bloco.
+
+Use `doc translate` quando o arquivo traduzido ainda não existir. Ele divide o markdown, traduz em paralelo e grava os arquivos de destino:
+
+```bash
+npx intlayer doc translate --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+Use `doc review` quando o arquivo traduzido já existir. Ele compara cada bloco com o documento base, ignora os blocos já traduzidos ou inalterados e envia apenas os divergentes:
+
+```bash
+npx intlayer doc review --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+Ambos os comandos aceitam suas regras uma única vez, sem a necessidade de repeti-las em cada prompt:
+
+```bash
+npx intlayer doc translate --custom-instructions "Do not translate URLs. Keep the markdown structure and the code blocks untouched."
+```
+
+Dois modos de `doc review` são úteis quando o agente precisa continuar no fluxo sem disparar chamadas de IA pelo Intlayer:
+
+- `--mode report` lista os blocos que exigem atenção com números de linha, permitindo que o agente edite apenas esses blocos.
+- `--mode synthesis` reporta apenas quais documentos estão em dia e quais contêm blocos pendentes de edição.
+
+```bash
+npx intlayer doc review --mode report --locales fr
+```
+
+### 4. Permitir que o agente chame a CLI através do servidor MCP
+
+Com o [servidor MCP do Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/mcp_server.md), o agente responde com base na documentação atualizada e executa `intlayer fill` ou `intlayer doc review` por conta própria em vez de reimplementar a lógica na conversa.
+
+```bash
+claude mcp add intlayer npx -y @intlayer/mcp
+```
+
+Instalar as [Agent Skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/agent_skills.md) com `npx intlayer init skills` também evita que o agente tente adivinhar a API do Intlayer e releia a documentação em cada tarefa.
+
+### 5. Reutilizar sua assinatura do Claude com `claude setup-token`
+
+Executar a configuração de i18n na sua sessão interativa do Claude Code mantém todo o histórico da conversa no contexto. Transfira esse trabalho pesado para uma sessão curta em modo headless.
+
+Gere um token de longa duração a partir da sua assinatura do Claude:
+
+```bash
+claude setup-token
+```
+
+Armazene-o como `CLAUDE_CODE_OAUTH_TOKEN` (em um arquivo `.env` ou nas variáveis secretas do seu CI) e reutilize-o para uma sessão pontual que execute os comandos do Intlayer:
+
+```bash
+CLAUDE_CODE_OAUTH_TOKEN=... claude -p "Run npx intlayer extract on src/components, then npx intlayer fill --uncommitted"
+```
+
+A sessão carregará apenas esse prompt e a saída do comando, sem o histórico da sua conversa. O mesmo token funciona na [Claude Code GitHub Action](https://github.com/anthropics/claude-code-action) para rodar `intlayer fill` em cada pull request.
+
+> O token gerado por `claude setup-token` autentica somente o Claude Code. Ele não pode ser usado como chave de API da Anthropic em `ai.apiKey`. Para a tradução em si, `intlayer fill` usa a sua [conta do Intlayer](https://app.intlayer.org) (plano gratuito incluso) ou a sua chave própria configurada em [`ai`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/configuration.md#ai-configuration).
+
+## Resumo
+
+| Tarefa                  | Quem executa                 | Tokens no contexto do agente |
+| ----------------------- | ---------------------------- | ---------------------------- |
+| Decidir o que localizar | Claude Code                  | Baixo                        |
+| Extrair strings         | `intlayer extract`           | Nenhum                       |
+| Traduzir conteúdo       | `intlayer fill`              | Nenhum                       |
+| Traduzir documentação   | `intlayer doc translate`     | Nenhum                       |
+| Atualizar documentação  | `intlayer doc review`        | Nenhum                       |
+| Executar os comandos    | Claude Code em modo headless | Prompt + saída do comando    |

package/frequent_questions/ru/claude_code_token_consumption.md

@@ -0,0 +1,152 @@
+---
+createdAt: 2026-09-13
+updatedAt: 2026-09-13
+title: Как ограничить расход токенов Claude Code при генерации переводов
+description: Почему перевод с помощью Claude Code сжигает токены, что делает Intlayer вместо этого (фильтрует переведенные ключи, делит JSON на блоки, переводит markdown по блокам) и как повторно использовать подписку Claude с помощью claude setup-token.
+keywords:
+  - claude code
+  - токены
+  - расход токенов
+  - setup-token
+  - i18n
+  - интернационализация
+  - перевод
+  - fill
+  - mcp
+  - агент
+slugs:
+  - frequent-questions
+  - claude-code-token-consumption
+author: aymericzip
+---
+
+# Как ограничить расход токенов Claude Code при генерации переводов
+
+## Описание проблемы
+
+Запрос к Claude Code (или любому другому агенту разработки) на перевод контента является самым дорогостоящим способом. При каждом запуске агент вынужден:
+
+- Загружать весь файл JSON или файл контента в свой контекст, включая уже переведенные ключи.
+- Искать связанные файлы, чтобы понять, где находится контент и как он структурирован.
+- Определять, какие локали отсутствуют и должны быть сгенерированы.
+- Каждый раз заново считывать ваши пользовательские инструкции ("преобразовывать URL определенным образом", "оставлять название бренда на английском", "использовать обращение на ты").
+- Переписывать весь файл целиком, включая части, которые не менялись.
+
+Все это повторно отправляется на каждой итерации, поэтому стоимость возрастает по формуле `размер контента × количество локалей × количество итераций`, а любые расхождения в форматировании или ключах приходится отслеживать вручную.
+
+## Что Intlayer делает вместо этого
+
+Преимущество Intlayer заключается в выполнении этой работы вне агента с помощью конвейера, созданного специально для перевода:
+
+- **Фильтрует существующие переводы** для ограничения расхода токенов. Уже переведенные ключи в вашем JSON удаляются, и модели отправляются только недостающие.
+- **Переводит markdown по блокам.** Для документации команды [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/cli/doc-translate.md) и [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/cli/doc-review.md) сравнивают каждый блок с исходным документом и пропускают уже переведенные или неизмененные блоки.
+- **Разбивает ваш JSON на части (chunking)**, если он слишком большой, чтобы оставаться в оптимальной части контекстного окна.
+- **Сглаживает и восстанавливает структуру JSON** для оптимизации расхода токенов.
+- **Вставляет пользовательские промпты** для специфических правил бренда и терминологии (`applicationContext`, `--custom-instructions`), позволяя написать их один раз вместо повторения в каждом диалоге.
+- **Проверяет структуру** для обеспечения согласованности и предотвращения расхождения ключей, сохраняя форматирование (markdown, HTML, вставки, множественные числа).
+- **Реализует повторные попытки (retry)** в случае некорректного формата ответа.
+- **Ставит в очередь и распараллеливает запросы** по файлам, фрагментам и локалям для максимальной скорости.
+
+Ничто из этого не проходит через контекст агента. Главное правило: пусть агент решает, **что** интернационализировать, а Intlayer выполняет повторяющуюся рутинную работу.
+
+## Решение
+
+### 1. Делегируйте извлечение команде `intlayer extract`
+
+Вместо того чтобы просить агента вручную переписывать каждый компонент, выполните команду [`extract`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/cli/extract.md). Она переносит жестко заданные строки в файл `.content` рядом с компонентом без загрузки всего исходного файла в контекст агента.
+
+```bash
+npx intlayer extract --file src/components/Header.tsx
+```
+
+### 2. Делегируйте перевод команде `intlayer fill`
+
+Никогда не поручайте агенту перевод напрямую. Команда [`fill`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/cli/fill.md) применяет описанный выше конвейер: она отправляет только недостающие ключи, разбивает их на части, обрабатывает локали параллельно и записывает результат обратно в ваши файлы контента.
+
+```bash
+npx intlayer fill
+```
+
+Несколько флагов позволяют оптимизировать запуск:
+
+- `--git-diff` (или `--uncommitted`) обрабатывает только словари, измененные в текущей ветке.
+- `--file` или `--keys` выбирает конкретные файлы контента.
+- `--output-locales fr es` ограничивает выполнение только теми локалями, которые необходимы прямо сейчас.
+- `--skip-metadata` пропускает создание заголовка, описания и тегов.
+- `--data-serialization toon` передает более компактные данные модели (меньше токенов, немного менее предсказуемый вывод).
+
+```bash
+npx intlayer fill --git-diff --output-locales fr es --skip-metadata
+```
+
+### 3. Переводите markdown с помощью `doc translate` и `doc review`
+
+Запрос агенту на перевод файла `.md` приводит к отправке всего документа для каждой локали при каждом изменении. Команды [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/cli/doc-translate.md) и [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/cli/doc-review.md) работают поблочно.
+
+Используйте `doc translate`, если переведенного файла еще не существует. Команда разбивает markdown, переводит его параллельно и создает целевые файлы:
+
+```bash
+npx intlayer doc translate --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+Используйте `doc review`, если переведенный файл уже существует. Команда сравнивает каждый блок с базовым документом, пропускает уже переведенные или неизмененные блоки и отправляет только отличающиеся:
+
+```bash
+npx intlayer doc review --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+Обе команды принимают ваши инструкции один раз, избавляя от необходимости повторять их в каждом промпте:
+
+```bash
+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` сообщает только о том, какие документы актуальны, а какие содержат блоки для редактирования.
+
+```bash
+npx intlayer doc review --mode report --locales fr
+```
+
+### 4. Позвольте агенту обращаться к CLI через сервер MCP
+
+Благодаря [серверу MCP Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/mcp_server.md) агент отвечает на основе актуальной документации и запускает `intlayer fill` или `intlayer doc review` самостоятельно вместо повторной реализации логики в диалоге.
+
+```bash
+claude mcp add intlayer npx -y @intlayer/mcp
+```
+
+Установка [Agent Skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/agent_skills.md) с помощью `npx intlayer init skills` также избавляет агента от необходимости угадывать API Intlayer и перечитывать документацию при каждой задаче.
+
+### 5. Повторно используйте подписку Claude с помощью `claude setup-token`
+
+Настройка i18n в интерактивной сессии Claude Code сохраняет всю историю разговора в контексте. Перенесите ресурсоемкие операции в короткую headless-сессию.
+
+Сгенерируйте долгоживущий токен из вашей подписки Claude:
+
+```bash
+claude setup-token
+```
+
+Сохраните его как `CLAUDE_CODE_OAUTH_TOKEN` (в файле `.env` или в секретах CI) и используйте для разовой сессии, запускающей команды Intlayer:
+
+```bash
+CLAUDE_CODE_OAUTH_TOKEN=... claude -p "Run npx intlayer extract on src/components, then npx intlayer fill --uncommitted"
+```
+
+Сессия будет содержать только этот промпт и вывод команды, исключая всю предыдущую переписку. Этот же токен работает в [Claude Code GitHub Action](https://github.com/anthropics/claude-code-action) для запуска `intlayer fill` при каждом pull request.
+
+> Токен, созданный командой `claude setup-token`, авторизует исключительно Claude Code. Его нельзя использовать в качестве ключа API Anthropic в параметре `ai.apiKey`. Для самого перевода `intlayer fill` задействует ваш [аккаунт Intlayer](https://app.intlayer.org) (включая бесплатный тариф) или ваш собственный ключ провайдера, настроенный в секции [`ai`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/configuration.md#ai-configuration).
+
+## Итоги
+
+| Задача                   | Кто выполняет            | Токены в контексте агента |
+| ------------------------ | ------------------------ | ------------------------- |
+| Решать, что локализовать | Claude Code              | Мало                      |
+| Извлекать строки         | `intlayer extract`       | Нет                       |
+| Переводить контент       | `intlayer fill`          | Нет                       |
+| Переводить документацию  | `intlayer doc translate` | Нет                       |
+| Обновлять документацию   | `intlayer doc review`    | Нет                       |
+| Выполнять команды        | Headless Claude Code     | Промпт + вывод команды    |

package/frequent_questions/tr/claude_code_token_consumption.md

@@ -0,0 +1,152 @@
+---
+createdAt: 2026-09-13
+updatedAt: 2026-09-13
+title: Çeviri üretirken Claude Code token tüketimi nasıl sınırlandırılır
+description: Claude Code ile çeviri yapmanın neden aşırı token harcadığı, Intlayer'ın bunun yerine ne yaptığı (çevrilmiş anahtarları filtreler, JSON'u parçalar, markdown'ı blok blok çevirir) ve claude setup-token ile Claude aboneliğinizi nasıl yeniden kullanabileceğiniz.
+keywords:
+  - claude code
+  - tokens
+  - token tüketimi
+  - setup-token
+  - i18n
+  - uluslararasılaştırma
+  - çeviri
+  - fill
+  - mcp
+  - ajan
+slugs:
+  - frequent-questions
+  - claude-code-token-consumption
+author: aymericzip
+---
+
+# Çeviri üretirken Claude Code token tüketimi nasıl sınırlandırılır
+
+## Sorun Açıklaması
+
+Claude Code'dan (veya herhangi bir kodlama ajanından) içeriğinizi çevirmesini istemek, bu işi yapmanın en maliyetli yoludur. Her çalıştırmada ajanın şunları yapması gerekir:
+
+- Zaten çevrilmiş anahtarlar dahil olmak üzere tüm JSON veya içerik dosyasını bağlamına yüklemek.
+- İçeriğin nerede bulunduğunu ve nasıl yapılandırıldığını anlamak için ilgili dosyaları aramak.
+- Hangi dillerin eksik olduğunu ve oluşturulması gerektiğini belirlemek.
+- Özel talimatlarınızı her seferinde yeniden okumak ("URL'leri şu şekilde dönüştür", "marka adını İngilizce bırak", "samimi bir dil kullan").
+- Değişmeyen kısımlar dahil olmak üzere tüm dosyayı baştan yazmak.
+
+Tüm bunlar her turda yeniden gönderilir, bu nedenle maliyet `içerik boyutu × dil sayısı × tur sayısı` formülüyle katlanarak artar ve biçimlendirme veya anahtarlardaki herhangi bir kaymanın manuel olarak düzeltilmesi gerekir.
+
+## Intlayer bunun yerine ne yapar
+
+Intlayer'ın temel avantajı, bu işi ajanın dışında, çeviri için özel olarak oluşturulmuş bir işlem hattıyla (pipeline) gerçekleştirmesidir:
+
+- **Mevcut çevirileri filtreler** ve token kullanımını sınırlar. JSON'unuzda zaten çevrilmiş olan anahtarlar ayıklanır ve modele yalnızca eksik olanlar gönderilir.
+- **Markdown'ı blok blok çevirir.** Belgeler için [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/cli/doc-translate.md) ve [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/cli/doc-review.md) komutları, her bloğu temel belgeyle karşılaştırır ve zaten çevrilmiş veya değişmemiş blokları atlar.
+- **JSON'unuz çok büyükse parçalara (chunk) ayırır**, böylece bağlam penceresinin en verimli aralığında kalınmasını sağlar.
+- **JSON'unuzu düzleştirir ve yeniden yapılandırır**, bu sayede token tüketimini optimize eder.
+- **Özel komut istemleri ekler**, böylece markanız ve terminolojinizle ilgili özel kuralları (`applicationContext`, `--custom-instructions`) her sohbette tekrarlamak yerine yalnızca bir kez tanımlarsınız.
+- **Yapıyı doğrular**, tutarlılığı garanti altına alır, anahtar kaymalarını önler ve biçimlendirmeyi (markdown, HTML, eklemeler, çoğullar) korur.
+- **Yeniden deneme (retry) yönetimi uygular**, böylece çıktı hatalı olduğunda süreci otomatik olarak toparlar.
+- **İstekleri sıraya alır ve paralelleştirir**, dosyalar, parçalar ve diller arasında işlem hızını artırır.
+
+Bunların hiçbiri ajanın bağlamından geçmez. Temel kural: neyin uluslararasılaştırılacağına ajanın karar vermesini sağlayın, tekrarlayan rutin işleri ise Intlayer'a bırakın.
+
+## Çözüm
+
+### 1. Ayıklama işlemini `intlayer extract` komutuna devredin
+
+Ajanın her bileşeni elle yeniden yazmasını istemek yerine [`extract`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/cli/extract.md) komutunu çalıştırmasını sağlayın. Bu komut, tüm dosyayı ajanın bağlamına yüklemeden sabit kodlanmış metinleri bileşenin yanındaki bir `.content` dosyasına taşır.
+
+```bash
+npx intlayer extract --file src/components/Header.tsx
+```
+
+### 2. Çeviri işlemini `intlayer fill` komutuna devredin
+
+Ajanın doğrudan çeviri yapmasını asla istemeyin. [`fill`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/cli/fill.md) komutu yukarıdaki işlem hattını uygular: yalnızca eksik anahtarları gönderir, bunları parçalara ayırır, dilleri paralel olarak çalıştırır ve sonucu içerik dosyalarınıza geri yazar.
+
+```bash
+npx intlayer fill
+```
+
+Birkaç bayrak işlemi sınırlandırmanızı sağlar:
+
+- `--git-diff` (veya `--uncommitted`) yalnızca geçerli daldaki değiştirilmiş sözlükleri işler.
+- `--file` veya `--keys` belirli içerik dosyalarını hedefler.
+- `--output-locales fr es` çalışmayı yalnızca şu anda gerçekten ihtiyacınız olan dillerle sınırlandırır.
+- `--skip-metadata` başlık, açıklama ve etiket oluşturmayı atlar.
+- `--data-serialization toon` modele daha kompakt bir veri yükü gönderir (daha az token, biraz daha az öngörülebilir çıktı).
+
+```bash
+npx intlayer fill --git-diff --output-locales fr es --skip-metadata
+```
+
+### 3. Markdown'ı `doc translate` ve `doc review` ile çevirin
+
+Bir ajandan `.md` dosyasını çevirmesini istemek, her değişiklikte ve her dil için tüm belgenin yapıştırılması anlamına gelir. Buna karşılık [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/cli/doc-translate.md) ve [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/cli/doc-review.md) komutları blok blok çalışır.
+
+Çevrilmiş dosya henüz mevcut olmadığında `doc translate` kullanın. Markdown'ı parçalara böler, paralel olarak çevirir ve hedef dosyaları yazar:
+
+```bash
+npx intlayer doc translate --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+Çevrilmiş dosya zaten mevcut olduğunda `doc review` kullanın. Her bloğu temel belgeyle karşılaştırır, zaten çevrilmiş veya değişmemiş blokları atlar ve yalnızca farklılık gösteren blokları gönderir:
+
+```bash
+npx intlayer doc review --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+Her iki komut da kurallarınızı her istemde tekrarlamak yerine tek bir seferde kabul eder:
+
+```bash
+npx intlayer doc translate --custom-instructions "Do not translate URLs. Keep the markdown structure and the code blocks untouched."
+```
+
+Intlayer tarafında herhangi bir yapay zeka çağrısı olmadan ajanın döngüde kalması gerektiğinde `doc review` komutunun iki modu oldukça kullanışlıdır:
+
+- `--mode report` müdahale gerektiren blokları satır numaralarıyla birlikte günlüğe kaydeder, böylece ajan yalnızca bu blokları düzenler.
+- `--mode synthesis` yalnızca hangi belgelerin güncel olduğunu ve hangilerinde düzenlenecek blok kaldığını raporlar.
+
+```bash
+npx intlayer doc review --mode report --locales fr
+```
+
+### 4. Ajanın CLI'ı MCP sunucusu üzerinden çağırmasını sağlayın
+
+[Intlayer MCP sunucusu](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/mcp_server.md) sayesinde ajan güncel belgelere dayanarak yanıt verir ve konuşma içinde mantığı yeniden üretmek yerine `intlayer fill` veya `intlayer doc review` komutlarını doğrudan kendisi çalıştırır.
+
+```bash
+claude mcp add intlayer npx -y @intlayer/mcp
+```
+
+`npx intlayer init skills` ile [Agent Skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/agent_skills.md) kurulumunu yapmak, ajanın Intlayer API'sini tahmin etmesini ve her görevde belgeleri tekrar okumasını da engeller.
+
+### 5. Claude aboneliğinizi `claude setup-token` ile yeniden kullanın
+
+Etkileşimli Claude Code oturumunuzda i18n kurulumunu çalıştırmak, tüm konuşma geçmişini bağlamda tutar. Bunun yerine yoğun iş yükünü kısa ve gözetimsiz (headless) bir oturuma taşıyın.
+
+Claude aboneliğinizden uzun ömürlü bir token oluşturun:
+
+```bash
+claude setup-token
+```
+
+Bunu `CLAUDE_CODE_OAUTH_TOKEN` olarak kaydedin (bir `.env` dosyasında veya CI sırlarınızda), ardından Intlayer komutlarını çalıştıran tek seferlik bir oturum için yeniden kullanın:
+
+```bash
+CLAUDE_CODE_OAUTH_TOKEN=... claude -p "Run npx intlayer extract on src/components, then npx intlayer fill --uncommitted"
+```
+
+Oturum, önceki konuşma geçmişinizi taşımadan yalnızca bu komut istemini ve komut çıktısını barındırır. Aynı token, her çekme isteğinde (Pull Request) `intlayer fill` çalıştırmak için [Claude Code GitHub Action](https://github.com/anthropics/claude-code-action) içinde de çalışır.
+
+> `claude setup-token` tarafından verilen token yalnızca Claude Code kimliğini doğrular. `ai.apiKey` içinde bir Anthropic API anahtarı olarak kullanılamaz. Çevirinin kendisi için `intlayer fill`, [Intlayer hesabınızı](https://app.intlayer.org) (ücretsiz plan dahildir) veya [`ai`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/configuration.md#ai-configuration) içinde yapılandırılan kendi sağlayıcı anahtarınızı kullanır.
+
+## Özet
+
+| Görev                                   | Kim yapar                | Ajan bağlamındaki tokenlar |
+| --------------------------------------- | ------------------------ | -------------------------- |
+| Neyin yerelleştirileceğine karar vermek | Claude Code              | Düşük                      |
+| Dizeleri ayıklamak                      | `intlayer extract`       | Yok                        |
+| İçeriği çevirmek                        | `intlayer fill`          | Yok                        |
+| Belgeleri çevirmek                      | `intlayer doc translate` | Yok                        |
+| Belgeleri güncellemek                   | `intlayer doc review`    | Yok                        |
+| Komutları çalıştırmak                   | Headless Claude Code     | İstem + komut çıktısı      |

package/frequent_questions/uk/claude_code_token_consumption.md

@@ -0,0 +1,152 @@
+---
+createdAt: 2026-09-13
+updatedAt: 2026-09-13
+title: Як обмежити споживання токенів Claude Code під час генерації перекладів
+description: Чому переклад за допомогою Claude Code спалює токени, що натомість робить Intlayer (фільтрує перекладені ключі, розбиває JSON на частини, перекладає markdown блок за блоком) та як повторно використати підписку Claude за допомогою claude setup-token.
+keywords:
+  - claude code
+  - tokens
+  - споживання токенів
+  - setup-token
+  - i18n
+  - інтернаціоналізація
+  - переклад
+  - fill
+  - mcp
+  - агент
+slugs:
+  - frequent-questions
+  - claude-code-token-consumption
+author: aymericzip
+---
+
+# Як обмежити споживання токенів Claude Code під час генерації перекладів
+
+## Опис проблеми
+
+Звернення до Claude Code (або будь-якого іншого кодинг-агента) для перекладу вашого контенту є найдорожчим способом. Під час кожного запуску агент змушений:
+
+- Завантажувати повний файл JSON або файл контенту у свій контекст, навіть ті ключі, які вже перекладені.
+- Шукати пов'язані файли, щоб зрозуміти, де розташований контент та як він структурований.
+- Визначати, які локалі відсутні та мають бути згенеровані.
+- Щоразу наново зчитувати ваші користувацькі інструкції ("перетворювати URL-адреси саме так", "залишати назву бренду англійською", "використовувати звернення на ти").
+- Переписувати весь файл цілком, включаючи частини, які не зазнали змін.
+
+Усе це повторно надсилається на кожній ітерації, через що витрати зростають за формулою `розмір контенту × кількість локалей × кількість ітерацій`, а будь-які невідповідності форматування чи ключів доводиться виправляти вручну.
+
+## Що Intlayer робить натомість
+
+Перевага Intlayer полягає у виконанні цієї роботи за межами агента завдяки конвеєру (pipeline), створеному спеціально для перекладу:
+
+- **Фільтрує наявні переклади** для обмеження використання токенів. Вже перекладені ключі у вашому JSON відсіюються, і до моделі надсилаються лише відсутні.
+- **Перекладає markdown блок за блоком.** Для документації команди [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/cli/doc-translate.md) та [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/cli/doc-review.md) порівнюють кожен блок із базовим документом та пропускають блоки, які вже перекладені або не змінилися.
+- **Розбиває JSON на частини (chunking)**, якщо він завеликий, щоб залишатися в оптимальній зоні контекстного вікна.
+- **Сплощує та реконструює ваш JSON** для оптимізації споживання токенів.
+- **Вставляє користувацькі промпти** для специфічних правил вашого бренду та термінології (`applicationContext`, `--custom-instructions`), що дозволяє описати їх один раз замість повторення в кожному діалозі.
+- **Перевіряє структуру** для гарантування узгодженості та запобігання відхиленню ключів, зберігаючи початкове форматування (markdown, HTML, вставки, множину).
+- **Забезпечує керування повторними спробами (retry)** у разі некоректного формату відповіді.
+- **Ставить у чергу та розпаралелює запити** між файлами, частинами та локалями для досягнення максимальної швидкості.
+
+Жоден із цих етапів не навантажує контекст агента. Головне правило: дозвольте агенту вирішувати, **що** потрібно інтернаціоналізувати, а рутинну повторювану роботу довірте Intlayer.
+
+## Рішення
+
+### 1. Делегуйте вилучення команді `intlayer extract`
+
+Замість того щоб просити агента вручну переписувати кожен компонент, доручіть йому виконати команду [`extract`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/cli/extract.md). Вона переносить захардкоджені рядки у файл `.content` поруч із компонентом без завантаження всього вихідного файлу в контекст агента.
+
+```bash
+npx intlayer extract --file src/components/Header.tsx
+```
+
+### 2. Делегуйте переклад команді `intlayer fill`
+
+Ніколи не просіть агента перекладати напряму. Команда [`fill`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/cli/fill.md) застосовує описаний вище конвеєр: вона надсилає лише відсутні ключі, розбиває їх на частини, обробляє локалі паралельно та записує результат назад у ваші файли контенту.
+
+```bash
+npx intlayer fill
+```
+
+Кілька прапорців дозволяють оптимізувати виконання:
+
+- `--git-diff` (або `--uncommitted`) обробляє лише словники, змінені в поточній гілці.
+- `--file` або `--keys` обирає конкретні файли контенту.
+- `--output-locales fr es` обмежує запуск лише тими локалями, які вам справді потрібні зараз.
+- `--skip-metadata` пропускає генерацію заголовка, опису та тегів.
+- `--data-serialization toon` передає моделі більш компактні дані (менше токенів, дещо менш передбачуваний результат).
+
+```bash
+npx intlayer fill --git-diff --output-locales fr es --skip-metadata
+```
+
+### 3. Перекладайте markdown за допомогою `doc translate` та `doc review`
+
+Запит до агента на переклад файлу `.md` змушує щоразу вставляти весь документ для кожної локалі при будь-якій зміні. Натомість команди [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/cli/doc-translate.md) та [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/cli/doc-review.md) працюють поблочно.
+
+Використовуйте `doc translate`, коли перекладеного файлу ще не існує. Команда ділить markdown на частини, перекладає його паралельно та створює цільові файли:
+
+```bash
+npx intlayer doc translate --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+Використовуйте `doc review`, коли перекладений файл уже існує. Команда порівнює кожен блок із базовим документом, пропускає блоки, які вже перекладені або не змінилися, і надсилає лише відмінні блоки:
+
+```bash
+npx intlayer doc review --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+Обидві команди приймають ваші правила один раз, позбавляючи потреби дублювати їх у кожному запиті:
+
+```bash
+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` повідомляє лише про те, які документи є актуальними, а в яких ще залишилися блоки для редагування.
+
+```bash
+npx intlayer doc review --mode report --locales fr
+```
+
+### 4. Дозвольте агенту викликати CLI через сервер MCP
+
+Завдяки [серверу MCP Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/mcp_server.md) агент відповідає на основі актуальної документації та самостійно виконує `intlayer fill` або `intlayer doc review`, замість повторної реалізації цієї логіки в діалозі.
+
+```bash
+claude mcp add intlayer npx -y @intlayer/mcp
+```
+
+Встановлення [Agent Skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/agent_skills.md) за допомогою `npx intlayer init skills` також позбавляє агента необхідності вгадувати API Intlayer та перечитувати документацію під час виконання кожного завдання.
+
+### 5. Повторно використовуйте підписку Claude за допомогою `claude setup-token`
+
+Налаштування i18n в інтерактивній сесії Claude Code зберігає всю історію розмови в контексті. Перенесіть це ресурсомістке навантаження у коротку headless-сесію.
+
+Згенеруйте довгоживучий токен із вашої підписки Claude:
+
+```bash
+claude setup-token
+```
+
+Збережіть його як `CLAUDE_CODE_OAUTH_TOKEN` (у файлі `.env` або у секретах CI), а потім використайте для одноразової сесії, яка виконує команди Intlayer:
+
+```bash
+CLAUDE_CODE_OAUTH_TOKEN=... claude -p "Run npx intlayer extract on src/components, then npx intlayer fill --uncommitted"
+```
+
+Ця сесія міститиме лише зазначений промпт та вивід команди, без перенесення всієї попередньої розмови. Цей самий токен працює в [Claude Code GitHub Action](https://github.com/anthropics/claude-code-action) для запуску `intlayer fill` під час кожного pull request.
+
+> Токен, згенерований через `claude setup-token`, автентифікує виключно Claude Code. Його не можна використовувати як ключ Anthropic API у параметрі `ai.apiKey`. Для самого перекладу `intlayer fill` застосовує ваш [обліковий запис Intlayer](https://app.intlayer.org) (включно з безкоштовним тарифом) або ваш власний ключ провайдера, налаштований у секції [`ai`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/configuration.md#ai-configuration).
+
+## Підсумок
+
+| Завдання                   | Хто виконує              | Токени в контексті агента |
+| -------------------------- | ------------------------ | ------------------------- |
+| Визначати, що локалізувати | Claude Code              | Низькі                    |
+| Вилучати рядки             | `intlayer extract`       | Немає                     |
+| Перекладати контент        | `intlayer fill`          | Немає                     |
+| Перекладати документацію   | `intlayer doc translate` | Немає                     |
+| Оновлювати документацію    | `intlayer doc review`    | Немає                     |
+| Виконувати команди         | Headless Claude Code     | Промпт + вивід команди    |