@intlayer/docs 9.5.2 → 9.5.4-canary.0

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

package/frequent_questions/vi/claude_code_token_consumption.md

@@ -0,0 +1,152 @@
+---
+createdAt: 2026-09-13
+updatedAt: 2026-09-13
+title: Cách giới hạn mức tiêu thụ token của Claude Code khi tạo bản dịch
+description: Tại sao dịch thuật bằng Claude Code gây lãng phí token, những gì Intlayer thực hiện thay thế (lọc các khóa đã dịch, chia nhỏ JSON, dịch markdown theo từng khối) và cách tái sử dụng gói đăng ký Claude với claude setup-token.
+keywords:
+  - claude code
+  - tokens
+  - tiêu thụ token
+  - setup-token
+  - i18n
+  - quốc tế hóa
+  - dịch thuật
+  - fill
+  - mcp
+  - agent
+slugs:
+  - frequent-questions
+  - claude-code-token-consumption
+author: aymericzip
+---
+
+# Cách giới hạn mức tiêu thụ token của Claude Code khi tạo bản dịch
+
+## Mô tả vấn đề
+
+Yêu cầu Claude Code (hoặc bất kỳ agent lập trình nào) dịch nội dung là phương pháp tốn kém nhất. Trong mỗi lần chạy, agent phải:
+
+- Tải toàn bộ tệp JSON hoặc tệp nội dung vào ngữ cảnh, bao gồm cả những khóa đã được dịch.
+- Tìm kiếm các tệp liên quan để xác định vị trí và cấu trúc của nội dung.
+- Tìm ra những ngôn ngữ (locales) còn thiếu và cần được tạo.
+- Đọc lại các hướng dẫn tùy chỉnh của bạn mỗi lần ("chuyển đổi URL theo cách này", "giữ nguyên tên thương hiệu bằng tiếng Anh", "dùng văn phong thân mật").
+- Viết lại toàn bộ tệp, bao gồm cả những phần không hề thay đổi.
+
+Tất cả những dữ liệu đó đều được gửi lại ở mỗi lượt tương tác, khiến chi phí tăng theo công thức `kích thước nội dung × số lượng ngôn ngữ × số lượt tương tác`, và mọi sai lệch về định dạng hoặc khóa đều phải rà soát thủ công.
+
+## Những gì Intlayer thực hiện thay thế
+
+Lợi ích của Intlayer là xử lý công việc đó bên ngoài agent, thông qua một pipeline được xây dựng chuyên biệt cho việc dịch thuật:
+
+- **Lọc các bản dịch đã có** để giảm thiểu việc sử dụng token. Các khóa đã được dịch trong JSON sẽ được loại bỏ, chỉ các khóa còn thiếu mới được gửi đến mô hình.
+- **Dịch markdown theo từng khối.** Đối với tài liệu, [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/cli/doc-translate.md) và [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/cli/doc-review.md) so sánh từng khối với tài liệu gốc và bỏ qua các khối đã được dịch hoặc không thay đổi.
+- **Chia nhỏ JSON (chunking)** nếu tệp quá lớn để luôn nằm trong vùng tối ưu của cửa sổ ngữ cảnh.
+- **Làm phẳng và tái cấu trúc JSON** nhằm tối ưu hóa lượng token tiêu thụ.
+- **Chèn prompt tùy chỉnh** cho các quy tắc cụ thể về thương hiệu và câu từ (`applicationContext`, `--custom-instructions`), giúp bạn chỉ cần viết một lần thay vì lặp lại trong mỗi cuộc trò chuyện.
+- **Xác thực cấu trúc** để đảm bảo tính nhất quán và ngăn ngừa sai lệch khóa, đồng thời giữ nguyên định dạng (markdown, HTML, biến chèn, số nhiều).
+- **Áp dụng cơ chế thử lại (retry)** khi định dạng đầu ra không hợp lệ.
+- **Xếp hàng và xử lý song song các yêu cầu** giữa các tệp, khối dữ liệu và ngôn ngữ để tăng tốc độ.
+
+Không có bước nào trong số này đi qua ngữ cảnh của agent. Nguyên tắc cốt lõi: để agent quyết định **cần** quốc tế hóa nội dung nào, và để Intlayer đảm nhận công việc lặp đi lặp lại.
+
+## Giải pháp
+
+### 1. Ủy quyền việc trích xuất cho `intlayer extract`
+
+Thay vì yêu cầu agent viết lại từng component theo cách thủ công, hãy để agent chạy lệnh [`extract`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/cli/extract.md). Lệnh này sẽ chuyển các chuỗi văn bản cố định sang tệp `.content` ngay cạnh component mà không cần tải toàn bộ tệp vào ngữ cảnh của agent.
+
+```bash
+npx intlayer extract --file src/components/Header.tsx
+```
+
+### 2. Ủy quyền việc dịch thuật cho `intlayer fill`
+
+Tuyệt đối không yêu cầu agent dịch trực tiếp. Lệnh [`fill`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/cli/fill.md) áp dụng pipeline đã nêu: chỉ gửi các khóa còn thiếu, chia nhỏ chúng, xử lý song song các ngôn ngữ và ghi kết quả trở lại các tệp nội dung của bạn.
+
+```bash
+npx intlayer fill
+```
+
+Một số flag giúp giới hạn phạm vi thực thi:
+
+- `--git-diff` (hoặc `--uncommitted`) chỉ xử lý các từ điển bị thay đổi trong nhánh hiện tại.
+- `--file` hoặc `--keys` nhắm mục tiêu vào các tệp nội dung cụ thể.
+- `--output-locales fr es` giới hạn thực thi cho các ngôn ngữ bạn thực sự cần lúc này.
+- `--skip-metadata` bỏ qua bước tạo tiêu đề, mô tả và thẻ tag.
+- `--data-serialization toon` gửi dữ liệu gọn gàng hơn đến mô hình (tiết kiệm token, đầu ra có thể hơi khác biệt).
+
+```bash
+npx intlayer fill --git-diff --output-locales fr es --skip-metadata
+```
+
+### 3. Dịch markdown bằng `doc translate` và `doc review`
+
+Yêu cầu agent dịch tệp `.md` đồng nghĩa với việc dán toàn bộ tài liệu cho từng ngôn ngữ sau mỗi lần thay đổi. Ngược lại, các lệnh [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/cli/doc-translate.md) và [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/cli/doc-review.md) xử lý theo từng khối.
+
+Sử dụng `doc translate` khi tệp dịch chưa tồn tại. Lệnh sẽ chia nhỏ markdown, dịch song song và tạo các tệp đích:
+
+```bash
+npx intlayer doc translate --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+Sử dụng `doc review` khi tệp dịch đã tồn tại. Lệnh sẽ so sánh từng khối với tài liệu gốc, bỏ qua các khối đã được dịch hoặc không đổi, và chỉ gửi các khối có sự khác biệt:
+
+```bash
+npx intlayer doc review --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+Cả hai lệnh đều tiếp nhận các quy tắc của bạn một lần duy nhất, tránh việc phải lặp lại trong mọi prompt:
+
+```bash
+npx intlayer doc translate --custom-instructions "Do not translate URLs. Keep the markdown structure and the code blocks untouched."
+```
+
+Hai chế độ của `doc review` rất hữu ích khi agent cần tham gia vào quy trình mà không làm phát sinh lệnh gọi AI nào từ phía Intlayer:
+
+- `--mode report` ghi lại các khối cần chú ý kèm theo số dòng, giúp agent chỉ chỉnh sửa các khối đó.
+- `--mode synthesis` chỉ thông báo tài liệu nào đã cập nhật và tài liệu nào còn các khối cần chỉnh sửa.
+
+```bash
+npx intlayer doc review --mode report --locales fr
+```
+
+### 4. Để agent gọi CLI thông qua máy chủ MCP
+
+Với [máy chủ Intlayer MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/mcp_server.md), agent trả lời dựa trên tài liệu mới nhất và tự chạy `intlayer fill` hoặc `intlayer doc review` thay vì triển khai lại logic đó trong cuộc hội thoại.
+
+```bash
+claude mcp add intlayer npx -y @intlayer/mcp
+```
+
+Cài đặt [Agent Skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/agent_skills.md) với `npx intlayer init skills` cũng giúp ngăn agent phỏng đoán API của Intlayer và đọc lại tài liệu trong mỗi tác vụ.
+
+### 5. Tái sử dụng gói đăng ký Claude với `claude setup-token`
+
+Chạy cấu hình i18n trong phiên Claude Code tương tác sẽ lưu toàn bộ lịch sử trò chuyện trong ngữ cảnh. Hãy chuyển tác vụ nặng này sang một phiên headless ngắn gọn.
+
+Tạo token dài hạn từ gói đăng ký Claude của bạn:
+
+```bash
+claude setup-token
+```
+
+Lưu dưới dạng `CLAUDE_CODE_OAUTH_TOKEN` (trong tệp `.env` hoặc trong bí mật CI của bạn), sau đó tái sử dụng cho phiên chạy đơn lẻ thực thi các lệnh Intlayer:
+
+```bash
+CLAUDE_CODE_OAUTH_TOKEN=... claude -p "Run npx intlayer extract on src/components, then npx intlayer fill --uncommitted"
+```
+
+Phiên này chỉ mang theo prompt đó và kết quả đầu ra của lệnh, không bao gồm toàn bộ cuộc trò chuyện trước đây. Token tương tự cũng hoạt động trong [Claude Code GitHub Action](https://github.com/anthropics/claude-code-action) để chạy `intlayer fill` trên mỗi pull request.
+
+> Token được cấp bởi `claude setup-token` chỉ xác thực cho Claude Code. Token này không thể sử dụng làm khóa Anthropic API trong `ai.apiKey`. Đối với bản dịch, `intlayer fill` sử dụng [tài khoản Intlayer](https://app.intlayer.org) của bạn (đã bao gồm gói miễn phí) hoặc khóa nhà cung cấp riêng được cấu hình trong [`ai`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/configuration.md#ai-configuration).
+
+## Tóm tắt
+
+| Tác vụ                              | Người thực hiện          | Token trong ngữ cảnh của agent |
+| ----------------------------------- | ------------------------ | ------------------------------ |
+| Quyết định nội dung cần bản địa hóa | Claude Code              | Thấp                           |
+| Trích xuất chuỗi văn bản            | `intlayer extract`       | Không có                       |
+| Dịch nội dung                       | `intlayer fill`          | Không có                       |
+| Dịch tài liệu                       | `intlayer doc translate` | Không có                       |
+| Cập nhật tài liệu                   | `intlayer doc review`    | Không có                       |
+| Chạy các lệnh                       | Headless Claude Code     | Prompt + đầu ra của lệnh       |

package/frequent_questions/zh/claude_code_token_consumption.md

@@ -0,0 +1,152 @@
+---
+createdAt: 2026-09-13
+updatedAt: 2026-09-13
+title: 如何限制 Claude Code 生成翻译时的 Token 消耗
+description: 为什么使用 Claude Code 进行翻译会大量消耗 Token，Intlayer 如何取而代之（过滤已翻译的键、切分 JSON、逐块翻译 Markdown），以及如何通过 claude setup-token 复用 Claude 订阅。
+keywords:
+  - claude code
+  - tokens
+  - token 消耗
+  - setup-token
+  - i18n
+  - 国际化
+  - 翻译
+  - fill
+  - mcp
+  - agent
+slugs:
+  - frequent-questions
+  - claude-code-token-consumption
+author: aymericzip
+---
+
+# 如何限制 Claude Code 生成翻译时的 Token 消耗
+
+## 问题描述
+
+让 Claude Code（或任何编码 Agent）直接翻译内容是最昂贵的做法。每次执行时，Agent 都必须：
+
+- 将整个 JSON 或内容文件加载到上下文中，甚至包括已经翻译过的键。
+- 检索相关文件以确定内容的存放位置和结构。
+- 分析缺少哪些语言环境（Locales）并需要生成。
+- 每次都要重新阅读您的自定义指令（“按此规则转换 URL”，“保留英文品牌名称”，“使用非正式语气”等）。
+- 重写整个文件，包括未发生变动的部分。
+
+所有这些内容在每次对话轮次中都会被重新发送，导致成本随着 `内容大小 × 语言环境数量 × 对话轮次` 呈倍数增长，而且格式或键名出现的任何偏差都必须手动排查。
+
+## Intlayer 采取的替代方案
+
+Intlayer 的优势在于将这些工作移至 Agent 之外，通过专为翻译构建的流水线来完成：
+
+- **过滤已存在的翻译**以限制 Token 消耗。JSON 中已翻译的键会被剥离，仅将缺失的键发送给模型。
+- **逐块翻译 Markdown。** 对于文档，[`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/doc-translate.md) 与 [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/doc-review.md) 会将每个文本块与基础文档进行比对，直接跳过已翻译或未更改的块。
+- **超大 JSON 自动分块（Chunking）**，使其始终处于上下文窗口的最佳处理区间内。
+- **扁平化与重构 JSON** 以优化 Token 消耗。
+- **插入自定义 Prompt** 以适配品牌与术语规则（`applicationContext`, `--custom-instructions`），只需编写一次，无需在每次对话中反复传递。
+- **校验数据结构**以确保一致性并防止键名漂移，同时完整保留原始排版格式（Markdown、HTML、插值、复数等）。
+- **内置重试机制**以应对输出格式错误。
+- **请求排队与并行处理**跨文件、分块和语言环境，显著提高翻译速度。
+
+所有这些工作都不会占用 Agent 的上下文。黄金法则是：让 Agent 决定**需要国际化什么**，而让 Intlayer 处理繁重的重复性流水线。
+
+## 解决方案
+
+### 1. 将提取工作委托给 `intlayer extract`
+
+无需让 Agent 手动重写每个组件，直接运行 [`extract`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/extract.md) 命令即可。它会将硬编码字符串提取到组件同目录下的 `.content` 文件中，而不会将完整文件加载到 Agent 上下文中。
+
+```bash
+npx intlayer extract --file src/components/Header.tsx
+```
+
+### 2. 将翻译工作委托给 `intlayer fill`
+
+切勿让 Agent 直接进行翻译。[`fill`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/fill.md) 命令会自动应用上述流水线：只发送缺失的键、进行分块、并行处理各个语言环境，并将结果写回内容文件中。
+
+```bash
+npx intlayer fill
+```
+
+通过几个参数可以精简执行范围：
+
+- `--git-diff`（或 `--uncommitted`）仅处理当前分支中发生更改的字典。
+- `--file` 或 `--keys` 针对特定的内容文件。
+- `--output-locales fr es` 仅限制在当前实际需要的语言环境中。
+- `--skip-metadata` 跳过标题、描述和标签的生成。
+- `--data-serialization toon` 向模型发送更紧凑的数据格式（更少的 Token，输出略微不可控）。
+
+```bash
+npx intlayer fill --git-diff --output-locales fr es --skip-metadata
+```
+
+### 3. 使用 `doc translate` 与 `doc review` 翻译 Markdown
+
+让 Agent 翻译 `.md` 文件意味着每次修改都要在每个语言环境中粘贴整个文档。而 [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/doc-translate.md) 和 [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/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."
+```
+
+在需要 Agent 参与但无需 Intlayer 发起 AI 调用的场景下，`doc review` 的两种模式非常实用：
+
+- `--mode report` 输出需要关注的文本块及行号，让 Agent 仅修改这些特定块。
+- `--mode synthesis` 仅输出哪些文档是最新的，哪些文档仍有待编辑的块。
+
+```bash
+npx intlayer doc review --mode report --locales fr
+```
+
+### 4. 让 Agent 通过 MCP 服务调用 CLI
+
+借助 [Intlayer MCP 服务](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/mcp_server.md)，Agent 可以依据最新的文档回答，并自行执行 `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/zh/agent_skills.md)，还可以避免 Agent 盲目猜测 Intlayer API 或在每个任务中重复阅读文档。
+
+### 5. 通过 `claude setup-token` 复用 Claude 订阅
+
+在交互式 Claude Code 会话中运行国际化设置会将整个对话历史保留在上下文中。将繁重的工作移至简短的无头（Headless）会话中执行：
+
+从 Claude 订阅中生成长效 Token：
+
+```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"
+```
+
+该会话仅包含该 Prompt 和命令输出，无需携带冗长的对话上下文。同一个 Token 也可以在 [Claude Code GitHub Action](https://github.com/anthropics/claude-code-action) 中使用，从而在每次 Pull Request 时运行 `intlayer fill`。
+
+> 通过 `claude setup-token` 颁发的 Token 仅用于 Claude Code 认证。它不能在 `ai.apiKey` 中作为 Anthropic API Key 使用。对于翻译本身，`intlayer fill` 会使用您的 [Intlayer 账户](https://app.intlayer.org)（包含免费额度）或在 [`ai`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md#ai-configuration) 中配置的专属模型 Key。
+
+## 总结
+
+| 任务               | 执行者                   | Agent 上下文中的 Token 消耗 |
+| ------------------ | ------------------------ | --------------------------- |
+| 决定要本地化的内容 | Claude Code              | 低                          |
+| 提取文本字符串     | `intlayer extract`       | 无                          |
+| 翻译声明内容       | `intlayer fill`          | 无                          |
+| 翻译 Markdown 文档 | `intlayer doc translate` | 无                          |
+| 更新 Markdown 文档 | `intlayer doc review`    | 无                          |
+| 批量执行命令       | Headless Claude Code     | 仅 Prompt + 命令输出        |