@intlayer/docs 9.5.2 → 9.5.4-canary.0

package/frequent_questions/hi/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 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 या सामग्री फ़ाइल को अपने संदर्भ (context) में लोड करना पड़ता है।
+- सामग्री कहाँ स्थित है और इसकी संरचना कैसी है, यह समझने के लिए संबंधित फ़ाइलों को खोजना पड़ता है।
+- यह पता लगाना पड़ता है कि कौन से लोकेल अनुपलब्ध हैं और उन्हें उत्पन्न करने की आवश्यकता है।
+- आपके कस्टम निर्देशों को हर बार फिर से पढ़ना पड़ता है ("URL को इस तरह बदलें", "ब्रांड नाम अंग्रेजी में रखें", "अनौपचारिक रूप का उपयोग करें")।
+- उन हिस्सों सहित पूरी फ़ाइल को फिर से लिखना पड़ता है जिनमें कोई बदलाव नहीं हुआ था।
+
+यह सब प्रत्येक संवाद चक्र में फिर से भेजा जाता है, जिससे लागत `सामग्री का आकार × लोकेल की संख्या × चक्रों की संख्या` के अनुपात में बढ़ती है, और फ़ॉर्मेटिंग या कुंजियों में किसी भी अंतर को मैन्युअल रूप से ठीक करना पड़ता है।
+
+## Intlayer इसके बजाय क्या करता है
+
+Intlayer की सबसे बड़ी विशेषता यह है कि यह कार्य अनुवाद के लिए विशेष रूप से निर्मित पाइपलाइन के साथ एजेंट के बाहर किया जाता है:
+
+- **मौजूदा अनुवादों को फ़िल्टर करता है** ताकि टोकन का उपयोग सीमित रहे। आपके JSON में पहले से अनुवादित कुंजियों को हटा दिया जाता है, और केवल अनुपलब्ध कुंजियों को मॉडल को भेजा जाता है।
+- **Markdown का ब्लॉक-दर-ब्लॉक अनुवाद करता है।** प्रलेखन के लिए, [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/hi/cli/doc-translate.md) और [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/hi/cli/doc-review.md) प्रत्येक ब्लॉक की तुलना मूल दस्तावेज़ से करते हैं और उन ब्लॉकों को छोड़ देते हैं जो पहले से अनुवादित या अपरिवर्तित हैं।
+- **यदि आपका JSON बहुत बड़ा है तो उसके टुकड़े (chunking) करता है**, ताकि संदर्भ विंडो के सबसे उपयुक्त भाग में रहा जा सके।
+- **टोकन खपत को अनुकूलित करने के लिए आपके JSON को समतल (flatten) और पुनर्गठित करता है**।
+- **कस्टम प्रॉम्प्ट सम्मिलित करता है** आपके ब्रांड और शब्दावली से संबंधित विशिष्ट नियमों के लिए (`applicationContext`, `--custom-instructions`), जिससे आप उन्हें हर बातचीत में दोहराने के बजाय केवल एक बार लिखते हैं।
+- **संरचना को मान्य करता है** ताकि निरंतरता सुनिश्चित हो सके और कुंजियों का भटकाव रुके, साथ ही फ़ॉर्मेटिंग (markdown, HTML, इंसर्शन, बहुवचन) सुरक्षित रहे।
+- **पुनः प्रयास प्रबंधन (retry)** लागू करता है यदि आउटपुट का प्रारूप अमान्य हो।
+- **गति बढ़ाने के लिए फ़ाइलों, टुकड़ों और लोकेल में अनुरोधों को कतारबद्ध और समानांतर करता है**।
+
+इनमें से कुछ भी एजेंट के संदर्भ से होकर नहीं गुजरता। मुख्य नियम: एजेंट को यह तय करने दें कि **क्या** अंतर्राष्ट्रीयकृत करना है, और दोहराए जाने वाले कार्य को Intlayer पर छोड़ दें।
+
+## समाधान
+
+### 1. निष्कर्षण को `intlayer extract` को सौंपें
+
+एजेंट को प्रत्येक घटक को हाथ से फिर से लिखने के लिए कहने के बजाय, उसे [`extract`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/hi/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/hi/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` के साथ markdown का अनुवाद करें
+
+किसी एजेंट से `.md` फ़ाइल का अनुवाद करने के लिए कहने का अर्थ है प्रत्येक परिवर्तन पर, प्रत्येक लोकेल के लिए पूरा दस्तावेज़ चिपकाना। इसके विपरीत [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/hi/cli/doc-translate.md) और [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/hi/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 से किसी भी AI कॉल के बिना प्रक्रिया में शामिल रहने की आवश्यकता होती है:
+
+- `--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/hi/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/hi/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"
+```
+
+यह सत्र केवल उस प्रॉम्प्ट और कमांड आउटपुट को वहन करेगा, न कि आपकी पूरी बातचीत को। यही टोकन प्रत्येक पुल अनुरोध पर `intlayer fill` चलाने के लिए [Claude Code GitHub Action](https://github.com/anthropics/claude-code-action) में काम करता है।
+
+> `claude setup-token` द्वारा जारी टोकन केवल Claude Code को प्रमाणित करता है। इसका उपयोग `ai.apiKey` में Anthropic API कुंजी के रूप में नहीं किया जा सकता है। अनुवाद के लिए, `intlayer fill` आपके [Intlayer खाते](https://app.intlayer.org) (मुफ्त स्तर शामिल) या [`ai`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/hi/configuration.md#ai-configuration) में कॉन्फ़िगर की गई आपकी अपनी प्रदाता कुंजी का उपयोग करता है।
+
+## सारांश
+
+| कार्य                              | कौन करता है              | एजेंट संदर्भ में टोकन    |
+| ---------------------------------- | ------------------------ | ------------------------ |
+| क्या स्थानीयकृत करना है यह तय करना | Claude Code              | कम                       |
+| स्ट्रिंग्स निकालना                 | `intlayer extract`       | कोई नहीं                 |
+| सामग्री का अनुवाद करना             | `intlayer fill`          | कोई नहीं                 |
+| प्रलेखन का अनुवाद करना             | `intlayer doc translate` | कोई नहीं                 |
+| प्रलेखन अद्यतन करना                | `intlayer doc review`    | कोई नहीं                 |
+| कमांड चलाना                        | हेडलेस Claude Code       | प्रॉम्प्ट + कमांड आउटपुट |

package/frequent_questions/id/claude_code_token_consumption.md

@@ -0,0 +1,152 @@
+---
+createdAt: 2026-09-13
+updatedAt: 2026-09-13
+title: Cara membatasi konsumsi token Claude Code untuk menghasilkan terjemahan
+description: Mengapa menerjemahkan dengan Claude Code menghabiskan banyak token, apa yang dilakukan Intlayer sebagai gantinya (memfilter kunci yang diterjemahkan, memotong JSON, menerjemahkan markdown blok demi blok), dan cara menggunakan kembali langganan Claude Anda dengan claude setup-token.
+keywords:
+  - claude code
+  - tokens
+  - konsumsi token
+  - setup-token
+  - i18n
+  - internasionalisasi
+  - terjemahan
+  - fill
+  - mcp
+  - agen
+slugs:
+  - frequent-questions
+  - claude-code-token-consumption
+author: aymericzip
+---
+
+# Cara membatasi konsumsi token Claude Code untuk menghasilkan terjemahan
+
+## Deskripsi Masalah
+
+Meminta Claude Code (atau agen pengodean apa pun) untuk menerjemahkan konten Anda adalah metode yang paling boros biaya. Untuk setiap eksekusi, agen harus:
+
+- Memuat seluruh file JSON atau file konten ke dalam konteksnya, bahkan kunci yang sudah diterjemahkan.
+- Mencari file terkait untuk memahami letak konten dan bagaimana strukturnya disusun.
+- Menentukan locale mana yang belum ada dan perlu dibuat.
+- Membaca ulang instruksi khusus Anda setiap saat ("ubah URL dengan cara ini", "biarkan nama merek dalam bahasa Inggris", "gunakan nada santai").
+- Menulis ulang seluruh file, termasuk bagian yang tidak mengalami perubahan.
+
+Semua itu dikirim ulang pada setiap giliran percakapan, sehingga biaya melonjak seiring `ukuran konten × jumlah locale × jumlah giliran`, dan setiap inkonsistensi format maupun kunci harus diperiksa secara manual.
+
+## Apa yang dilakukan Intlayer sebagai gantinya
+
+Kelebihan Intlayer adalah menjalankan pekerjaan tersebut di luar agen melalui alur kerja (pipeline) yang dirancang khusus untuk penerjemahan:
+
+- **Memfilter terjemahan yang sudah ada** untuk menekan penggunaan token. Kunci yang sudah diterjemahkan di dalam JSON Anda akan disaring, dan hanya kunci yang belum ada yang dikirim ke model.
+- **Menerjemahkan markdown blok demi blok.** Untuk dokumentasi, [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/cli/doc-translate.md) dan [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/cli/doc-review.md) membandingkan setiap blok dengan dokumen dasar dan melewati blok yang sudah diterjemahkan atau tidak berubah.
+- **Memotong JSON (chunking)** jika ukurannya terlalu besar agar tetap berada di rentang konteks yang optimal.
+- **Meratakan dan menyusun ulang JSON** guna mengoptimalkan konsumsi token.
+- **Menyisipkan prompt khusus** untuk aturan tertentu terkait merek dan terminologi Anda (`applicationContext`, `--custom-instructions`), sehingga Anda hanya menuliskannya satu kali tanpa perlu mengulanginya di setiap percakapan.
+- **Memvalidasi struktur** untuk menjamin konsistensi dan mencegah pergeseran kunci, serta mempertahankan format (markdown, HTML, tag sisipan, bentuk jamak).
+- **Menerapkan manajemen percobaan ulang (retry)** apabila format output tidak valid.
+- **Mengantrekan dan memparalelkan permintaan** lintas file, potongan teks, dan locale untuk meningkatkan kecepatan.
+
+Semua proses ini tidak melewati konteks agen. Aturan praktisnya: biarkan agen memutuskan **apa** yang perlu diinternasionalisasi, dan biarkan Intlayer menangani pekerjaan berulang tersebut.
+
+## Solusi
+
+### 1. Delegasikan ekstraksi ke `intlayer extract`
+
+Alih-alih meminta agen menulis ulang setiap komponen secara manual, biarkan agen menjalankan perintah [`extract`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/cli/extract.md). Perintah ini memindahkan string statis ke dalam file `.content` di samping komponen tanpa memuat seluruh file ke dalam konteks agen.
+
+```bash
+npx intlayer extract --file src/components/Header.tsx
+```
+
+### 2. Delegasikan penerjemahan ke `intlayer fill`
+
+Jangan pernah meminta agen untuk menerjemahkan secara langsung. Perintah [`fill`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/cli/fill.md) menerapkan alur kerja di atas: hanya mengirimkan kunci yang belum diterjemahkan, membaginya ke dalam beberapa potongan, memproses locale secara paralel, dan menuliskan hasilnya kembali ke file konten Anda.
+
+```bash
+npx intlayer fill
+```
+
+Beberapa opsi flag membantu mempersempit ruang lingkup eksekusi:
+
+- `--git-diff` (atau `--uncommitted`) hanya memproses kamus yang dimodifikasi pada branch saat ini.
+- `--file` atau `--keys` menargetkan file konten tertentu.
+- `--output-locales fr es` membatasi eksekusi hanya untuk locale yang benar-benar Anda butuhkan saat ini.
+- `--skip-metadata` melewati pembuatan judul, deskripsi, dan tag.
+- `--data-serialization toon` mengirimkan payload yang lebih ringkas ke model (mengurangi token, hasil sedikit kurang konsisten).
+
+```bash
+npx intlayer fill --git-diff --output-locales fr es --skip-metadata
+```
+
+### 3. Terjemahkan markdown dengan `doc translate` dan `doc review`
+
+Meminta agen menerjemahkan file `.md` berarti menempelkan seluruh dokumen, untuk setiap locale, pada setiap perubahan. Sebaliknya, perintah [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/cli/doc-translate.md) dan [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/cli/doc-review.md) bekerja blok demi blok.
+
+Gunakan `doc translate` ketika file hasil terjemahan belum ada. Perintah ini memotong markdown, menerjemahkannya secara paralel, dan menulis file tujuan:
+
+```bash
+npx intlayer doc translate --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+Gunakan `doc review` ketika file terjemahan sudah ada. Perintah ini membandingkan setiap blok dengan dokumen dasar, melewati blok yang sudah diterjemahkan atau tidak berubah, dan hanya mengirimkan blok yang berbeda:
+
+```bash
+npx intlayer doc review --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+Kedua perintah ini menerima aturan Anda satu kali saja, sehingga Anda tidak perlu mengulanginya di setiap prompt:
+
+```bash
+npx intlayer doc translate --custom-instructions "Do not translate URLs. Keep the markdown structure and the code blocks untouched."
+```
+
+Dua mode pada `doc review` sangat berguna saat agen tetap harus dilibatkan tanpa memicu panggilan AI dari Intlayer:
+
+- `--mode report` mencatat blok-blok yang memerlukan penyesuaian lengkap dengan nomor baris, sehingga agen hanya mengubah blok tersebut.
+- `--mode synthesis` hanya melaporkan dokumen mana yang sudah diperbarui dan dokumen mana yang masih memiliki blok untuk diedit.
+
+```bash
+npx intlayer doc review --mode report --locales fr
+```
+
+### 4. Biarkan agen memanggil CLI melalui server MCP
+
+Dengan [server MCP Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/mcp_server.md), agen menjawab berdasarkan dokumentasi terbaru dan menjalankan `intlayer fill` atau `intlayer doc review` secara langsung alih-alih mengimplementasikan kembali logika tersebut di dalam percakapan.
+
+```bash
+claude mcp add intlayer npx -y @intlayer/mcp
+```
+
+Memasang [Agent Skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/agent_skills.md) melalui `npx intlayer init skills` juga mencegah agen menebak-nebak API Intlayer dan membaca ulang dokumentasi di setiap tugas.
+
+### 5. Gunakan kembali langganan Claude Anda dengan `claude setup-token`
+
+Menjalankan penyiapan i18n di dalam sesi Claude Code interaktif akan menumpuk seluruh riwayat percakapan dalam konteks. Alihkan tugas berat tersebut ke sesi headless yang singkat.
+
+Buat token berdurasi panjang dari langganan Claude Anda:
+
+```bash
+claude setup-token
+```
+
+Simpan token ini sebagai `CLAUDE_CODE_OAUTH_TOKEN` (di dalam file `.env` atau secret CI Anda), lalu gunakan kembali untuk sesi sekali jalan yang mengeksekusi perintah Intlayer:
+
+```bash
+CLAUDE_CODE_OAUTH_TOKEN=... claude -p "Run npx intlayer extract on src/components, then npx intlayer fill --uncommitted"
+```
+
+Sesi tersebut hanya memuat prompt dan output perintah tanpa menyertakan riwayat percakapan sebelumnya. Token yang sama juga berfungsi pada [Claude Code GitHub Action](https://github.com/anthropics/claude-code-action) untuk menjalankan `intlayer fill` di setiap pull request.
+
+> Token yang dibuat oleh `claude setup-token` hanya mengautentikasi Claude Code. Token ini tidak dapat digunakan sebagai kunci API Anthropic di `ai.apiKey`. Untuk proses penerjemahannya sendiri, `intlayer fill` menggunakan [akun Intlayer](https://app.intlayer.org) Anda (termasuk paket gratis) atau kunci penyedia Anda sendiri yang dikonfigurasi pada [`ai`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/configuration.md#ai-configuration).
+
+## Ringkasan
+
+| Tugas                                 | Pelaksana                | Token dalam konteks agen |
+| ------------------------------------- | ------------------------ | ------------------------ |
+| Menentukan apa yang akan dilokalisasi | Claude Code              | Rendah                   |
+| Mengekstrak string                    | `intlayer extract`       | Tidak ada                |
+| Menerjemahkan konten                  | `intlayer fill`          | Tidak ada                |
+| Menerjemahkan dokumentasi             | `intlayer doc translate` | Tidak ada                |
+| Memperbarui dokumentasi               | `intlayer doc review`    | Tidak ada                |
+| Menjalankan perintah                  | Headless Claude Code     | Prompt + output perintah |

package/frequent_questions/it/claude_code_token_consumption.md

@@ -0,0 +1,152 @@
+---
+createdAt: 2026-09-13
+updatedAt: 2026-09-13
+title: Come limitare il consumo di token di Claude Code per generare traduzioni
+description: Perché tradurre con Claude Code spreca token, cosa fa invece Intlayer (filtra le chiavi già tradotte, suddivide il JSON in blocchi, traduce il markdown blocco per blocco) e come riutilizzare il tuo abbonamento Claude con claude setup-token.
+keywords:
+  - claude code
+  - token
+  - consumo di token
+  - setup-token
+  - i18n
+  - internazionalizzazione
+  - traduzione
+  - fill
+  - mcp
+  - agent
+slugs:
+  - frequent-questions
+  - claude-code-token-consumption
+author: aymericzip
+---
+
+# Come limitare il consumo di token di Claude Code per generare traduzioni
+
+## Descrizione del problema
+
+Chiedere a Claude Code (o a qualsiasi agente di sviluppo) di tradurre i tuoi contenuti è il modo più costoso in assoluto. A ogni esecuzione, l'agente deve:
+
+- Caricare l'intero file JSON o di contenuto nel suo contesto, comprese le chiavi già tradotte.
+- Cercare nei file correlati per capire dove si trova il contenuto e come è strutturato.
+- Individuare quali locale mancano e devono essere generate.
+- Rileggere ogni volta le tue istruzioni personalizzate ("trasforma gli URL in questo modo", "mantieni il nome del brand in inglese", "usa una forma informale").
+- Riscrivere l'intero file, incluse le parti rimaste invariate.
+
+Tutto questo viene reinviato a ogni iterazione, quindi il costo cresce in base a `dimensione del contenuto × numero di locale × numero di iterazioni`, e ogni minima divergenza di formattazione o di chiavi deve essere controllata manualmente.
+
+## Cosa fa invece Intlayer
+
+Il vantaggio di Intlayer è svolgere questo lavoro al di fuori dell'agente, grazie a una pipeline progettata specificamente per la traduzione:
+
+- **Filtra le traduzioni esistenti** per limitare l'uso dei token. Le chiavi già tradotte nel tuo JSON vengono escluse, inviando al modello solo quelle mancanti.
+- **Traduce il markdown blocco per blocco.** Per la documentazione, [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/cli/doc-translate.md) e [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/cli/doc-review.md) confrontano ogni blocco con il documento base e saltano i blocchi già tradotti o invariati.
+- **Suddivide il tuo JSON in chunk** se è troppo grande, per operare nella parte migliore della finestra di contesto.
+- **Appiattisce e ricostruisce il tuo JSON** per ottimizzare il consumo di token.
+- **Inserisce prompt personalizzati** per regole specifiche sul tuo brand e stile (`applicationContext`, `--custom-instructions`), così da scriverli una sola volta invece di ripeterli in ogni conversazione.
+- **Valida la struttura** per assicurare coerenza, prevenire la deviazione delle chiavi e preservare la formattazione (markdown, HTML, inserimenti, plurali).
+- **Implementa la gestione dei tentativi (retry)** quando l'output è malformato.
+- **Accoda e parallelizza le richieste** tra file, blocchi e locale per massimizzare la velocità.
+
+Niente di tutto questo passa attraverso il contesto dell'agente. La regola d'oro: lascia che l'agente decida **cosa** internazionalizzare, e lascia a Intlayer il lavoro ripetitivo.
+
+## Soluzione
+
+### 1. Delegare l'estrazione a `intlayer extract`
+
+Invece di chiedere all'agente di riscrivere ogni componente a mano, fagli eseguire il comando [`extract`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/cli/extract.md). Questo sposta le stringhe hardcoded in un file `.content` accanto al componente senza caricare l'intero file nel contesto dell'agente.
+
+```bash
+npx intlayer extract --file src/components/Header.tsx
+```
+
+### 2. Delegare la traduzione a `intlayer fill`
+
+Non chiedere mai all'agente di tradurre direttamente. Il comando [`fill`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/cli/fill.md) applica la pipeline sopra descritta: invia solo le chiavi mancanti, le suddivide, elabora le locale in parallelo e riscrive il risultato direttamente nei file di contenuto.
+
+```bash
+npx intlayer fill
+```
+
+Alcuni flag consentono di contenere l'elaborazione:
+
+- `--git-diff` (o `--uncommitted`) elabora solo i dizionari modificati nel branch corrente.
+- `--file` o `--keys` punta a file di contenuto specifici.
+- `--output-locales fr es` limita l'esecuzione alle sole locale necessarie al momento.
+- `--skip-metadata` ignora la generazione di titolo, descrizione e tag.
+- `--data-serialization toon` invia un payload più compatto al modello (meno token, output leggermente meno prevedibile).
+
+```bash
+npx intlayer fill --git-diff --output-locales fr es --skip-metadata
+```
+
+### 3. Tradurre il markdown con `doc translate` e `doc review`
+
+Chiedere a un agente di tradurre un file `.md` comporta l'inclusione dell'intero documento, per ogni locale, a ogni modifica. I comandi [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/cli/doc-translate.md) e [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/cli/doc-review.md) lavorano invece blocco per blocco.
+
+Usa `doc translate` quando il file tradotto non esiste ancora. Suddivide il markdown, lo traduce in parallelo e crea i file di destinazione:
+
+```bash
+npx intlayer doc translate --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+Usa `doc review` quando il file tradotto esiste già. Confronta ogni blocco con il documento base, salta i blocchi già tradotti o invariati e invia solo quelli divergenti:
+
+```bash
+npx intlayer doc review --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+Entrambi i comandi accettano le tue regole una volta sola, senza doverle ripetere in ogni prompt:
+
+```bash
+npx intlayer doc translate --custom-instructions "Do not translate URLs. Keep the markdown structure and the code blocks untouched."
+```
+
+Due modalità di `doc review` sono utili quando l'agente deve rimanere coinvolto nel flusso, senza alcuna chiamata AI da parte di Intlayer:
+
+- `--mode report` segnala i blocchi che richiedono attenzione, completi di numero di riga, in modo che l'agente modifichi solo quei blocchi.
+- `--mode synthesis` riporta unicamente quali documenti sono aggiornati e quali presentano ancora blocchi da modificare.
+
+```bash
+npx intlayer doc review --mode report --locales fr
+```
+
+### 4. Far chiamare la CLI all'agente tramite il server MCP
+
+Grazie al [server MCP di Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/mcp_server.md), l'agente risponde basandosi sulla documentazione aggiornata ed esegue autonomamente `intlayer fill` o `intlayer doc review`, invece di dover reimplementare la logica nella conversazione.
+
+```bash
+claude mcp add intlayer npx -y @intlayer/mcp
+```
+
+Installare le [Agent Skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/agent_skills.md) con `npx intlayer init skills` evita inoltre che l'agente debba indovinare l'API di Intlayer e rileggere la documentazione a ogni task.
+
+### 5. Riutilizzare l'abbonamento Claude con `claude setup-token`
+
+Eseguire la configurazione di i18n nella sessione interattiva di Claude Code mantiene l'intera cronologia della conversazione nel contesto. Sposta invece questo carico di lavoro su una breve sessione headless.
+
+Genera un token a lunga durata dal tuo abbonamento Claude:
+
+```bash
+claude setup-token
+```
+
+Salvalo come `CLAUDE_CODE_OAUTH_TOKEN` (in un file `.env` o nei secret della tua CI), quindi riutilizzalo per una sessione mirata che esegua i comandi Intlayer:
+
+```bash
+CLAUDE_CODE_OAUTH_TOKEN=... claude -p "Run npx intlayer extract on src/components, then npx intlayer fill --uncommitted"
+```
+
+La sessione conterrà solo quel prompt e l'output del comando, evitando tutta la cronologia precedente. Lo stesso token funziona nella [Claude Code GitHub Action](https://github.com/anthropics/claude-code-action) per eseguire `intlayer fill` su ogni pull request.
+
+> Il token generato da `claude setup-token` autentica unicamente Claude Code. Non può essere usato come chiave API Anthropic in `ai.apiKey`. Per la traduzione vera e propria, `intlayer fill` usa il tuo [account Intlayer](https://app.intlayer.org) (piano gratuito incluso) o la tua chiave fornitore configurata in [`ai`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/configuration.md#ai-configuration).
+
+## Riepilogo
+
+| Attività                     | Chi la esegue                    | Token nel contesto dell'agente |
+| ---------------------------- | -------------------------------- | ------------------------------ |
+| Decidere cosa localizzare    | Claude Code                      | Basso                          |
+| Estrarre le stringhe         | `intlayer extract`               | Nessuno                        |
+| Tradurre i contenuti         | `intlayer fill`                  | Nessuno                        |
+| Tradurre la documentazione   | `intlayer doc translate`         | Nessuno                        |
+| Aggiornare la documentazione | `intlayer doc review`            | Nessuno                        |
+| Eseguire i comandi           | Claude Code in modalità headless | Prompt + output del comando    |

package/frequent_questions/ja/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 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内の既に翻訳されているキーは除外され、不足しているキーのみがモデルに送信されます。
+- **Markdownをブロック単位で翻訳します。** ドキュメントの場合、[`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/cli/doc-translate.md) および [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/cli/doc-review.md) は各ブロックをベースドキュメントと比較し、すでに翻訳されているブロックや変更のないブロックをスキップします。
+- **JSONが大きすぎる場合はチャンクに分割**し、コンテキストウィンドウの最適な範囲を維持します。
+- **JSONをフラット化して再構築**し、トークン消費を最適化します。
+- **カスタムプロンプトを挿入**してブランドや表現に関するルール（`applicationContext`, `--custom-instructions`）を適用できるため、会話ごとに繰り返すことなく一度だけ記述すれば済みます。
+- **構造を検証**して一貫性を担保し、キーのずれを防ぎながら、フォーマット（Markdown、HTML、挿入タグ、複数形など）を保持します。
+- **リトライ管理**を実装し、出力が不正な場合に自動で再試行します。
+- **リクエストをキューイングして並列化**し、ファイル、チャンク、ロケールをまたいで処理速度を向上させます。
+
+これらの処理はエージェントのコンテキストを経由しません。基本原則として、エージェントには**何を**国際化するかを判断させ、定型的な反復作業はIntlayerに任せます。
+
+## 解決策
+
+### 1. 抽出を `intlayer extract` に任せる
+
+エージェントに各コンポーネントを手動で書き直させる代わりに、[`extract`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/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/ja/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/ja/cli/doc-translate.md) および [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/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."
+```
+
+IntlayerからのAI呼び出しを発生させずにエージェントをワークフローに参加させたい場合、`doc review` の以下の2つのモードが役立ちます。
+
+- `--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/ja/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/ja/agent_skills.md) を導入すると、エージェントがIntlayerのAPIを推測したり、タスクごとにドキュメントを読み直したりする無駄も防げます。
+
+### 5. `claude setup-token` でClaudeのサブスクリプションを再利用する
+
+対話型のClaude Codeセッション内でi18nのセットアップを実行すると、会話履歴全体がコンテキストに保持され続けます。負荷の大きい処理は、短時間のヘッドレスセッションに切り替えて実行しましょう。
+
+お使いの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) でも動作し、Pull Requestごとに `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/ja/configuration.md#ai-configuration) で設定したプロバイダーのAPIキーが使用されます。
+
+## まとめ
+
+| タスク                 | 担当者                   | エージェントコンテキスト内のトークン |
+| ---------------------- | ------------------------ | ------------------------------------ |
+| ローカライズ対象の決定 | Claude Code              | 少量                                 |
+| 文字列の抽出           | `intlayer extract`       | なし                                 |
+| コンテンツの翻訳       | `intlayer fill`          | なし                                 |
+| ドキュメントの翻訳     | `intlayer doc translate` | なし                                 |
+| ドキュメントの更新     | `intlayer doc review`    | なし                                 |
+| コマンドの実行         | ヘッドレスClaude Code    | プロンプト + コマンド出力            |