@intlayer/docs 9.5.2 → 9.5.4-canary.0

package/frequent_questions/ko/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 청크 분할, 마크다운 블록 단위 번역), claude setup-token으로 Claude 구독을 재사용하는 방법을 알아봅니다.
+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의 핵심 가치는 번역 전용 파이프라인을 통해 에이전트 외부에서 이 작업을 수행한다는 점입니다.
+
+- **기존 번역 필터링**으로 토큰 사용량을 제한합니다. JSON에서 이미 번역된 키는 제거되고, 누락된 키만 모델로 전달됩니다.
+- **마크다운을 블록 단위로 번역합니다.** 문서의 경우 [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/doc-translate.md) 및 [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/doc-review.md)가 각 블록을 기본 문서와 비교하여 이미 번역되었거나 변경되지 않은 블록을 건너뜁니다.
+- **JSON이 너무 큰 경우 청크로 분할**하여 컨텍스트 윈도우의 최적 구간에 머무릅니다.
+- **JSON 평탄화 및 재구성**을 통해 토큰 소비를 최적화합니다.
+- **커스텀 프롬프트 삽입**을 지원하여 브랜드와 용어에 대한 특정 규칙(`applicationContext`, `--custom-instructions`)을 매 대화마다 반복하지 않고 한 번만 작성할 수 있습니다.
+- **구조 유효성 검사**를 수행하여 일관성을 보장하고 키 누락을 방지하며, 서식(마크다운, HTML, 삽입 태그, 복수형)을 보존합니다.
+- **재시도(retry) 관리**를 구현하여 출력이 잘못된 형식일 때 자동으로 복구합니다.
+- **요청 큐잉 및 병렬화**를 통해 파일, 청크, 로케일 전반의 처리 속도를 극대화합니다.
+
+이 중 어느 것도 에이전트의 컨텍스트를 거치지 않습니다. 기본 원칙은 에이전트가 **무엇을** 국제화할지 결정하게 하고, 반복적인 작업은 Intlayer에 맡기는 것입니다.
+
+## 해결 방법
+
+### 1. 추출 작업을 `intlayer extract`에 위임
+
+에이전트에게 각 컴포넌트를 수작업으로 다시 작성하도록 요청하는 대신 [`extract`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/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/ko/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. `doc translate` 및 `doc review`로 마크다운 번역
+
+에이전트에게 `.md` 파일 번역을 요청하면 수정할 때마다 각 로케일별 전체 문서를 붙여넣어야 합니다. 반면 [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/doc-translate.md) 및 [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/doc-review.md) 명령은 블록 단위로 동작합니다.
+
+번역 대상 파일이 아직 존재하지 않는 경우 `doc translate`를 사용하세요. 마크다운을 청크로 나누고 병렬로 번역하여 대상 파일을 생성합니다.
+
+```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."
+```
+
+Intlayer 측의 AI 호출 없이 에이전트가 검토 흐름에 참여해야 할 때는 `doc review`의 두 가지 모드가 유용합니다.
+
+- `--mode report`: 주의가 필요한 블록을 줄 번호와 함께 출력하여 에이전트가 해당 블록만 수정할 수 있도록 합니다.
+- `--mode synthesis`: 최신 상태인 문서와 아직 편집할 블록이 남아있는 문서의 목록만 출력합니다.
+
+```bash
+npx intlayer doc review --mode report --locales fr
+```
+
+### 4. 에이전트가 MCP 서버를 통해 CLI를 호출하도록 설정
+
+[Intlayer MCP 서버](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/mcp_server.md)를 사용하면 에이전트가 최신 문서를 기반으로 응답하며, 대화 내에서 직접 번역 로직을 구현하는 대신 `intlayer fill` 또는 `intlayer doc review`를 직접 실행합니다.
+
+```bash
+claude mcp add intlayer npx -y @intlayer/mcp
+```
+
+`npx intlayer init skills`로 [Agent Skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/agent_skills.md)를 설치하면 에이전트가 Intlayer API를 임의로 추측하거나 작업마다 문서를 다시 읽는 낭비도 방지할 수 있습니다.
+
+### 5. `claude setup-token`으로 Claude 구독 재사용
+
+대화형 Claude Code 세션에서 i18n 설정을 실행하면 전체 대화 내역이 컨텍스트에 누적됩니다. 부담이 큰 작업은 짧은 헤드리스(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`을 실행할 수 있습니다.
+
+> `claude setup-token`으로 발급된 토큰은 Claude Code 전용 인증 토큰입니다. `ai.apiKey`의 Anthropic API 키로는 사용할 수 없습니다. 번역 자체에는 [Intlayer 계정](https://app.intlayer.org)(무료 티어 포함)이나 [`ai`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/configuration.md#ai-configuration)에 설정한 자체 제공업체 API 키가 사용됩니다.
+
+## 요약
+
+| 작업             | 담당                     | 에이전트 컨텍스트 내 토큰 |
+| ---------------- | ------------------------ | ------------------------- |
+| 현지화 대상 결정 | Claude Code              | 낮음                      |
+| 문자열 추출      | `intlayer extract`       | 없음                      |
+| 콘텐츠 번역      | `intlayer fill`          | 없음                      |
+| 문서 번역        | `intlayer doc translate` | 없음                      |
+| 문서 업데이트    | `intlayer doc review`    | 없음                      |
+| 명령 실행        | 헤드리스 Claude Code     | 프롬프트 + 명령 출력      |

package/frequent_questions/pl/claude_code_token_consumption.md

@@ -0,0 +1,152 @@
+---
+createdAt: 2026-09-13
+updatedAt: 2026-09-13
+title: Jak ograniczyć zużycie tokenów Claude Code podczas generowania tłumaczeń
+description: Dlaczego tłumaczenie z Claude Code zużywa nadmierną liczbę tokenów, co zamiast tego robi Intlayer (filtruje przetłumaczone klucze, dzieli JSON na fragmenty, tłumaczy markdown blok po bloku) oraz jak ponownie wykorzystać subskrypcję Claude za pomocą claude setup-token.
+keywords:
+  - claude code
+  - tokens
+  - zużycie tokenów
+  - setup-token
+  - i18n
+  - internacjonalizacja
+  - tłumaczenie
+  - fill
+  - mcp
+  - agent
+slugs:
+  - frequent-questions
+  - claude-code-token-consumption
+author: aymericzip
+---
+
+# Jak ograniczyć zużycie tokenów Claude Code podczas generowania tłumaczeń
+
+## Opis problemu
+
+Zlecanie tłumaczenia treści narzędziu Claude Code (lub jakiemukolwiek innemu agentowi programistycznemu) jest najbardziej kosztownym podejściem. Przy każdym uruchomieniu agent musi:
+
+- Załadować cały plik JSON lub plik zawartości do swojego kontekstu, w tym klucze, które zostały już przetłumaczone.
+- Przeszukać powiązane pliki, aby ustalić, gdzie znajduje się treść i jak jest zorganizowana.
+- Określić, których wersji językowych (locales) brakuje i które należy wygenerować.
+- Za każdym razem ponownie odczytywać niestandardowe instrukcje ("przekształcaj adresy URL w ten sposób", "pozostaw nazwę marki po angielsku", "stosuj formę nieformalną").
+- Przepisać cały plik od nowa, łącznie z fragmentami, które w ogóle się nie zmieniły.
+
+Wszystkie te informacje są przesyłane ponownie w każdej turze konwersacji, przez co koszt rośnie według wzoru `rozmiar treści × liczba wersji językowych × liczba tur`, a wszelkie rozbieżności w formatowaniu lub kluczach trzeba wychwytywać ręcznie.
+
+## Co zamiast tego robi Intlayer
+
+Zaletą Intlayer jest wykonywanie tej pracy poza agentem, za pośrednictwem potoku stworzonego specjalnie do zadań tłumaczeniowych:
+
+- **Filtruje istniejące tłumaczenia**, aby ograniczyć zużycie tokenów. Klucze już przetłumaczone w pliku JSON są pomijane, a do modelu trafiają wyłącznie brakujące wpisy.
+- **Tłumaczy markdown blok po bloku.** W przypadku dokumentacji polecenia [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/cli/doc-translate.md) oraz [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/cli/doc-review.md) porównują każdy blok z dokumentem bazowym i pomijają bloki przetłumaczone lub niezmienione.
+- **Dzieli plik JSON na mniejsze fragmenty (chunking)**, jeśli jest zbyt duży, aby operować w optymalnej części okna kontekstu.
+- **Spłaszcza i rekonstruuje JSON**, optymalizując zużycie tokenów.
+- **Wstawia niestandardowe prompty** dla określonych zasad dotyczących marki i słownictwa (`applicationContext`, `--custom-instructions`), dzięki czemu definiujesz je raz, zamiast powtarzać w każdej rozmowie.
+- **Weryfikuje strukturę**, zapewniając spójność, zapobiegając rozbieżnościom kluczy i zachowując formatowanie (markdown, HTML, wstawki, formy mnogie).
+- **Zapewnia obsługę ponownych prób (retry)** w przypadku nieprawidłowego formatu odpowiedzi.
+- **Kolejkuje i zrównolegla żądania** pomiędzy plikami, fragmentami i językami, znacznie zwiększając szybkość działania.
+
+Żaden z tych procesów nie obciąża kontekstu agenta. Złota zasada: pozwól agentowi decydować, **co** zinternacjonalizować, a powtarzalną pracę powierz Intlayer.
+
+## Rozwiązanie
+
+### 1. Przekaż ekstrakcję poleceniu `intlayer extract`
+
+Zamiast prosić agenta o ręczne przepisywanie każdego komponentu, uruchom polecenie [`extract`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/cli/extract.md). Przenosi ono zahardkodowane ciągi znaków do pliku `.content` obok komponentu, bez ładowania całego pliku do kontekstu agenta.
+
+```bash
+npx intlayer extract --file src/components/Header.tsx
+```
+
+### 2. Przekaż tłumaczenie poleceniu `intlayer fill`
+
+Nigdy nie zlecaj tłumaczenia bezpośrednio agentowi. Polecenie [`fill`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/cli/fill.md) stosuje wyżej opisany proces: wysyła wyłącznie brakujące klucze, dzieli je na części, przetwarza języki równolegle i zapisuje wynik z powrotem w plikach zawartości.
+
+```bash
+npx intlayer fill
+```
+
+Kilka flag pozwala utrzymać oszczędny zakres operacji:
+
+- `--git-diff` (lub `--uncommitted`) przetwarza tylko słowniki zmodyfikowane w bieżącej gałęzi.
+- `--file` lub `--keys` wskazuje konkretne pliki zawartości.
+- `--output-locales fr es` ogranicza wykonanie do języków, których faktycznie potrzebujesz w danym momencie.
+- `--skip-metadata` pomija generowanie tytułów, opisów i tagów.
+- `--data-serialization toon` przesyła bardziej zwarty ładunek danych do modelu (mniej tokenów, nieco mniej przewidywalny wynik).
+
+```bash
+npx intlayer fill --git-diff --output-locales fr es --skip-metadata
+```
+
+### 3. Tłumacz markdown za pomocą `doc translate` i `doc review`
+
+Zlecenie agentowi przetłumaczenia pliku `.md` wiąże się z wklejaniem całego dokumentu dla każdego języka przy każdej zmianie. Z kolei polecenia [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/cli/doc-translate.md) i [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/cli/doc-review.md) operują blok po bloku.
+
+Używaj `doc translate`, gdy przetłumaczony plik jeszcze nie istnieje. Dzieli on markdown na części, tłumaczy je równolegle i generuje pliki docelowe:
+
+```bash
+npx intlayer doc translate --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+Używaj `doc review`, gdy przetłumaczony plik już istnieje. Porównuje on każdy blok z dokumentem bazowym, pomija bloki przetłumaczone lub bez zmian i wysyła wyłącznie te różniące się:
+
+```bash
+npx intlayer doc review --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+Oba polecenia przyjmują Twoje wytyczne raz, bez potrzeby powtarzania ich w każdym monicie:
+
+```bash
+npx intlayer doc translate --custom-instructions "Do not translate URLs. Keep the markdown structure and the code blocks untouched."
+```
+
+Dwa tryby `doc review` są przydatne, gdy agent musi uczestniczyć w procesie bez wykonywania wywołań AI przez Intlayer:
+
+- `--mode report` raportuje bloki wymagające uwagi wraz z numerami linii, dzięki czemu agent modyfikuje tylko te konkretne fragmenty.
+- `--mode synthesis` informuje wyłącznie o tym, które dokumenty są aktualne, a które nadal zawierają bloki do edycji.
+
+```bash
+npx intlayer doc review --mode report --locales fr
+```
+
+### 4. Pozwól agentowi wywoływać CLI za pośrednictwem serwera MCP
+
+Dzięki [serwerowi MCP Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/mcp_server.md) agent odpowiada na podstawie aktualnej dokumentacji i samodzielnie uruchamia `intlayer fill` lub `intlayer doc review`, zamiast odtwarzać logikę w rozmowie.
+
+```bash
+claude mcp add intlayer npx -y @intlayer/mcp
+```
+
+Zainstalowanie [Agent Skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/agent_skills.md) za pomocą `npx intlayer init skills` zapobiega ponadto zgadywaniu API Intlayer przez agenta i ponownemu czytaniu dokumentacji przy każdym zadaniu.
+
+### 5. Wykorzystaj ponownie subskrypcję Claude dzięki `claude setup-token`
+
+Wykonywanie konfiguracji i18n w interaktywnej sesji Claude Code utrzymuje całą historię rozmowy w oknie kontekstu. Przenieś to obciążenie do krótkiej sesji w trybie headless.
+
+Wygeneruj długoterminowy token w ramach swojej subskrypcji Claude:
+
+```bash
+claude setup-token
+```
+
+Zapisz go jako `CLAUDE_CODE_OAUTH_TOKEN` (w pliku `.env` lub w zmiennych CI), a następnie użyj go w jednorazowej sesji uruchamiającej polecenia Intlayer:
+
+```bash
+CLAUDE_CODE_OAUTH_TOKEN=... claude -p "Run npx intlayer extract on src/components, then npx intlayer fill --uncommitted"
+```
+
+Sesja obejmie wyłącznie ten prompt oraz wynik polecenia, bez obciążania wcześniejszą historią. Ten sam token działa w akcji [Claude Code GitHub Action](https://github.com/anthropics/claude-code-action), umożliwiając uruchamianie `intlayer fill` przy każdym pull requeście.
+
+> Token wygenerowany przez `claude setup-token` uwierzytelnia wyłącznie Claude Code. Nie można go używać jako klucza Anthropic API w parametrze `ai.apiKey`. Do samego tłumaczenia `intlayer fill` wykorzystuje Twoje [konto Intlayer](https://app.intlayer.org) (w tym darmowy plan) lub własny klucz dostawcy skonfigurowany w sekcji [`ai`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/configuration.md#ai-configuration).
+
+## Podsumowanie
+
+| Zadanie                   | Kto wykonuje             | Tokeny w kontekście agenta |
+| ------------------------- | ------------------------ | -------------------------- |
+| Decyzja o lokalizacji     | Claude Code              | Niskie                     |
+| Ekstrakcja ciągów znaków  | `intlayer extract`       | Brak                       |
+| Tłumaczenie zawartości    | `intlayer fill`          | Brak                       |
+| Tłumaczenie dokumentacji  | `intlayer doc translate` | Brak                       |
+| Aktualizacja dokumentacji | `intlayer doc review`    | Brak                       |
+| Uruchamianie poleceń      | Headless Claude Code     | Prompt + wynik polecenia   |

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     | Промпт + вывод команды    |