@intlayer/docs 9.5.2 → 9.5.3

package/frequent_questions/ar/claude_code_token_consumption.md

@@ -0,0 +1,152 @@
+---
+createdAt: 2026-09-13
+updatedAt: 2026-09-13
+title: كيفية تقليل استهلاك رموز Claude Code (Tokens) لتوليد الترجمات
+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 (Tokens) لتوليد الترجمات
+
+## وصف المشكلة
+
+يُعد الطلب من Claude Code (أو أي وكيل برمجي) ترجمة محتواك الطريقة الأكثر تكلفة على الإطلاق. ففي كل تشغيل، يضطر الوكيل إلى:
+
+- تحميل ملف JSON أو ملف المحتوى كاملاً في سياقه، حتى المفاتيح المترجمة بالفعل.
+- البحث في الملفات المرتبطة لمعرفة مكان المحتوى وطريقة تنظيمه.
+- استنتاج اللغات الناقصة التي ينبغي توليدها.
+- إعادة قراءة تعليماتك المخصصة في كل مرة ("تحويل الروابط بهذا الشكل"، "الإبقاء على اسم العلامة التجارية بالإنجليزية"، "استخدام الصيغة غير الرسمية").
+- إعادة كتابة الملف بأكمله، بما في ذلك الأجزاء التي لم تتغير.
+
+يتم إعادة إرسال كل هذا مع كل جولة محادثة، مما يؤدي إلى تضخم التكلفة وفق معادلة `حجم المحتوى × عدد اللغات × عدد الجولات`، بالإضافة إلى ضرورة اكتشاف أي خلل في التنسيق أو المفاتيح يدوياً.
+
+## ماذا يقدم Intlayer بدلاً من ذلك
+
+تكمن فائدة Intlayer في إنجاز هذا العمل خارج سياق الوكيل، عبر خط معالجة مبني خصيصاً للترجمة:
+
+- **تصفية الترجمات الموجودة مسبقاً** للحد من استهلاك الرموز (Tokens). يتم استبعاد المفاتيح المترجمة بالفعل في ملف JSON، وإرسال المفاتيح الناقصة فقط إلى النموذج.
+- **ترجمة ملفات markdown كتلة بكتلة.** بالنسبة للتوثيق، يقارن الأمران [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/cli/doc-translate.md) و [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/cli/doc-review.md) كل كتلة مع المستند الأساسي ويتجاوزان الكتل المترجمة مسبقاً أو غير المعدلة.
+- **تقسيم ملفات JSON إلى أجزاء (Chunks)** إذا كانت كبيرة جداً، لضمان البقاء في النطاق الأمثل لنافذة السياق.
+- **تسطيح وإعادة بناء ملفات JSON** لتحسين استهلاك الرموز.
+- **إدراج مطالبات مخصصة** للقواعد المحددة لعلامتك التجارية وصياغتك (`applicationContext`، `--custom-instructions`)، لتكتبها مرة واحدة بدلاً من تكرارها في كل محادثة.
+- **التحقق من صحة البنية** لضمان الاتساق ومنع انحراف المفاتيح، مع الحفاظ على التنسيق الأصلي (markdown، HTML، الإدراجات، صيغ الجمع).
+- **إدارة إعادة المحاولة (Retry)** في حال كان الناتج غير منسق بشكل سليم.
+- **جدولة الطلبات ومعالجتها بالتوازي** عبر الملفات والكتل واللغات لزيادة سرعة التنفيذ.
+
+لا يمر أي من هذا عبر سياق الوكيل. القاعدة الأساسية: دع الوكيل يقرر **ماذا** ينبغي تدويله، ودع Intlayer يتكفل بالمهام المتكررة.
+
+## الحل
+
+### 1. إسناد الاستخراج إلى `intlayer extract`
+
+بدلاً من مطالبة الوكيل بإعادة كتابة كل مكوّن يدوياً، دعه ينفذ الأمر [`extract`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/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/ar/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/ar/cli/doc-translate.md) و [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/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
+
+باستخدام [خادم Intlayer MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/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/ar/agent_skills.md) عبر `npx intlayer init skills` يمنع الوكيل من تخمين واجهة برمجة تطبيقات 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/ar/configuration.md#ai-configuration).
+
+## الملخص
+
+| المهمة                | المسؤول عنها             | الرموز (Tokens) في سياق الوكيل |
+| --------------------- | ------------------------ | ------------------------------ |
+| تحديد ما ينبغي تعريبه | Claude Code              | منخفض                          |
+| استخراج النصوص        | `intlayer extract`       | لا شيء                         |
+| ترجمة المحتوى         | `intlayer fill`          | لا شيء                         |
+| ترجمة التوثيق         | `intlayer doc translate` | لا شيء                         |
+| تحديث التوثيق         | `intlayer doc review`    | لا شيء                         |
+| تشغيل الأوامر         | Headless Claude Code     | الموجه + مخرجات الأمر          |

package/frequent_questions/de/claude_code_token_consumption.md

@@ -0,0 +1,152 @@
+---
+createdAt: 2026-09-13
+updatedAt: 2026-09-13
+title: Wie man den Token-Verbrauch von Claude Code bei Übersetzungen begrenzt
+description: Warum das Übersetzen mit Claude Code Tokens verbrennt, was Intlayer stattdessen tut (bereits übersetzte Schlüssel filtern, JSON aufteilen, Markdown blockweise übersetzen) und wie Sie Ihr Claude-Abonnement mit claude setup-token wiederverwenden.
+keywords:
+  - claude code
+  - tokens
+  - token-verbrauch
+  - setup-token
+  - i18n
+  - internationalisierung
+  - übersetzung
+  - fill
+  - mcp
+  - agent
+slugs:
+  - frequent-questions
+  - claude-code-token-consumption
+author: aymericzip
+---
+
+# Wie man den Token-Verbrauch von Claude Code bei Übersetzungen begrenzt
+
+## Problembeschreibung
+
+Claude Code (oder jeden anderen Programmier-Agenten) mit der Übersetzung Ihrer Inhalte zu beauftragen, ist der teuerste Weg. Bei jedem Durchlauf muss der Agent:
+
+- Die gesamte JSON- oder Inhaltsdatei in seinen Kontext laden, selbst die Schlüssel, die bereits übersetzt sind.
+- Die zugehörigen Dateien durchsuchen, um herauszufinden, wo sich der Inhalt befindet und wie er strukturiert ist.
+- Ermitteln, welche Locales fehlen und generiert werden müssen.
+- Ihre benutzerdefinierten Anweisungen jedes Mal erneut lesen ("URLs auf diese Weise anpassen", "Markennamen auf Englisch belassen", "Du-Form verwenden").
+- Die gesamte Datei neu schreiben, einschließlich der Teile, die sich nicht geändert haben.
+
+All das wird bei jedem Durchlauf erneut übermittelt, sodass die Kosten mit `Größe des Inhalts × Anzahl der Locales × Anzahl der Durchläufe` ansteigen, und jede Abweichung bei Formatierung oder Schlüsseln muss manuell überprüft werden.
+
+## Was Intlayer stattdessen tut
+
+Der Vorteil von Intlayer besteht darin, diese Arbeit außerhalb des Agenten mit einer speziell für Übersetzungen entwickelten Pipeline zu erledigen:
+
+- **Filtert bestehende Übersetzungen**, um den Token-Verbrauch zu begrenzen. Bereits übersetzte Schlüssel in Ihrem JSON werden entfernt und nur die fehlenden an das Modell gesendet.
+- **Übersetzt Markdown blockweise.** Für die Dokumentation vergleichen [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/cli/doc-translate.md) und [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/cli/doc-review.md) jeden Block mit dem Basisdokument und überspringen Blöcke, die bereits übersetzt oder unverändert sind.
+- **Teilt Ihr JSON in Chunks auf**, falls es zu groß ist, um im optimalen Bereich des Kontextfensters zu bleiben.
+- **Flacht Ihr JSON ab und rekonstruiert es**, um den Token-Verbrauch zu optimieren.
+- **Fügt benutzerdefinierte Prompts ein** für spezifische Regeln bezüglich Marke und Wording (`applicationContext`, `--custom-instructions`), sodass Sie diese einmal schreiben, anstatt sie in jeder Konversation zu wiederholen.
+- **Validiert die Struktur**, um Konsistenz zu gewährleisten und Schlüssel-Drift zu verhindern, und bewahrt Formatierungen (Markdown, HTML, Einfügungen, Pluralformen).
+- **Implementiert Wiederholungsversuche (Retry-Management)**, wenn die Ausgabe fehlerhaft ist.
+- **Reiht Anfragen ein und parallelisiert sie** über Dateien, Abschnitte und Locales hinweg, um die Geschwindigkeit zu maximieren.
+
+Nichts davon belastet den Kontext des Agenten. Die Faustregel: Lassen Sie den Agenten entscheiden, **was** internationalisiert werden soll, und überlassen Sie Intlayer die wiederkehrende Arbeit.
+
+## Lösung
+
+### 1. Extraktion an `intlayer extract` delegieren
+
+Anstatt den Agenten jede Komponente manuell umschreiben zu lassen, lassen Sie ihn den Befehl [`extract`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/cli/extract.md) ausführen. Dieser verschiebt hartcodierte Zeichenketten in eine `.content`-Datei neben der Komponente, ohne die gesamte Datei in den Kontext des Agenten zu laden.
+
+```bash
+npx intlayer extract --file src/components/Header.tsx
+```
+
+### 2. Übersetzung an `intlayer fill` delegieren
+
+Bitten Sie den Agenten niemals direkt zu übersetzen. Der Befehl [`fill`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/cli/fill.md) wendet die oben beschriebene Pipeline an: Er sendet nur die fehlenden Schlüssel, teilt sie auf, verarbeitet die Locales parallel und schreibt das Ergebnis direkt in Ihre Inhaltsdateien zurück.
+
+```bash
+npx intlayer fill
+```
+
+Einige Flags halten den Durchlauf schlank:
+
+- `--git-diff` (oder `--uncommitted`) verarbeitet nur die im aktuellen Branch geänderten Wörterbücher.
+- `--file` oder `--keys` zielt auf bestimmte Inhaltsdateien ab.
+- `--output-locales fr es` beschränkt den Durchlauf auf die Locales, die Sie aktuell wirklich benötigen.
+- `--skip-metadata` überspringt die Generierung von Titel, Beschreibung und Tags.
+- `--data-serialization toon` sendet eine kompaktere Nutzlast an das Modell (weniger Tokens, leicht weniger vorhersehbare Ausgabe).
+
+```bash
+npx intlayer fill --git-diff --output-locales fr es --skip-metadata
+```
+
+### 3. Markdown mit `doc translate` und `doc review` übersetzen
+
+Einen Agenten mit der Übersetzung einer `.md`-Datei zu beauftragen bedeutet, das gesamte Dokument für jedes Locale bei jeder Änderung einzufügen. Die Befehle [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/cli/doc-translate.md) und [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/cli/doc-review.md) arbeiten stattdessen blockweise.
+
+Verwenden Sie `doc translate`, wenn die übersetzte Datei noch nicht existiert. Der Befehl teilt das Markdown auf, übersetzt es parallel und erstellt die Zieldateien:
+
+```bash
+npx intlayer doc translate --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+Verwenden Sie `doc review`, wenn die übersetzte Datei bereits existiert. Der Befehl vergleicht jeden Block mit dem Basisdokument, überspringt Blöcke, die bereits übersetzt oder unverändert sind, und sendet nur die abweichenden Blöcke:
+
+```bash
+npx intlayer doc review --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+Beide Befehle übernehmen Ihre Regeln einmalig, anstatt sie in jedem Prompt wiederholen zu müssen:
+
+```bash
+npx intlayer doc translate --custom-instructions "Do not translate URLs. Keep the markdown structure and the code blocks untouched."
+```
+
+Zwei Modi von `doc review` sind nützlich, wenn der Agent ohne KI-Aufrufe seitens Intlayer eingebunden bleiben soll:
+
+- `--mode report` gibt die Blöcke aus, die Aufmerksamkeit erfordern, samt Zeilennummern, sodass der Agent nur diese Blöcke bearbeitet.
+- `--mode synthesis` gibt lediglich an, welche Dokumente aktuell sind und welche noch bearbeitbare Blöcke enthalten.
+
+```bash
+npx intlayer doc review --mode report --locales fr
+```
+
+### 4. Den Agenten die CLI über den MCP-Server aufrufen lassen
+
+Mit dem [Intlayer MCP-Server](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/mcp_server.md) antwortet der Agent auf Basis der aktuellen Dokumentation und führt `intlayer fill` oder `intlayer doc review` selbst aus, anstatt die Logik in der Konversation neu zu implementieren.
+
+```bash
+claude mcp add intlayer npx -y @intlayer/mcp
+```
+
+Die Installation der [Agent Skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/agent_skills.md) mit `npx intlayer init skills` verhindert zudem, dass der Agent die Intlayer-API erraten und die Dokumentation bei jeder Aufgabe neu lesen muss.
+
+### 5. Das Claude-Abonnement mit `claude setup-token` wiederverwenden
+
+Das Einrichten von i18n in Ihrer interaktiven Claude Code-Sitzung behält den gesamten Konversationsverlauf im Kontext. Verlagern Sie diese arbeitsintensive Aufgabe stattdessen in eine kurze Headless-Sitzung.
+
+Generieren Sie ein langlebiges Token aus Ihrem Claude-Abonnement:
+
+```bash
+claude setup-token
+```
+
+Speichern Sie es als `CLAUDE_CODE_OAUTH_TOKEN` (in einer `.env`-Datei oder in Ihren CI-Secrets) und nutzen Sie es für eine einmalige Sitzung, die die Intlayer-Befehle ausführt:
+
+```bash
+CLAUDE_CODE_OAUTH_TOKEN=... claude -p "Run npx intlayer extract on src/components, then npx intlayer fill --uncommitted"
+```
+
+Die Sitzung enthält lediglich diesen Prompt und die Ausgabe des Befehls, nicht Ihre gesamte Konversation. Dasselbe Token funktioniert auch in der [Claude Code GitHub Action](https://github.com/anthropics/claude-code-action), um `intlayer fill` bei jedem Pull Request auszuführen.
+
+> Das von `claude setup-token` ausgegebene Token authentifiziert ausschließlich Claude Code. Es kann nicht als Anthropic-API-Schlüssel in `ai.apiKey` verwendet werden. Für die eigentliche Übersetzung nutzt `intlayer fill` Ihr [Intlayer-Konto](https://app.intlayer.org) (kostenloser Tarif enthalten) oder Ihren eigenen in [`ai`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/configuration.md#ai-configuration) konfigurierten Provider-Schlüssel.
+
+## Zusammenfassung
+
+| Aufgabe                           | Wer führt sie aus        | Tokens im Kontext des Agenten |
+| --------------------------------- | ------------------------ | ----------------------------- |
+| Entscheiden, was lokalisiert wird | Claude Code              | Gering                        |
+| Zeichenketten extrahieren         | `intlayer extract`       | Keine                         |
+| Inhalte übersetzen                | `intlayer fill`          | Keine                         |
+| Dokumentation übersetzen          | `intlayer doc translate` | Keine                         |
+| Dokumentation aktualisieren       | `intlayer doc review`    | Keine                         |
+| Befehle ausführen                 | Headless Claude Code     | Prompt + Befehlsausgabe       |

package/frequent_questions/en/claude_code_token_consumption.md

@@ -0,0 +1,152 @@
+---
+createdAt: 2026-09-13
+updatedAt: 2026-09-13
+title: How to limit Claude Code token consumption to generate translations
+description: Why translating with Claude Code burns tokens, what Intlayer does instead (filters translated keys, chunks JSON, translates markdown block by block), and how to reuse your Claude subscription with claude setup-token.
+keywords:
+  - claude code
+  - tokens
+  - token consumption
+  - setup-token
+  - i18n
+  - internationalization
+  - translation
+  - fill
+  - mcp
+  - agent
+slugs:
+  - frequent-questions
+  - claude-code-token-consumption
+author: aymericzip
+---
+
+# How to limit Claude Code token consumption to generate translations
+
+## Problem Description
+
+Asking Claude Code (or any coding agent) to translate your content is the most expensive way to do it. For each run, the agent has to:
+
+- Load the complete JSON or content file into its context, even the keys that are already translated.
+- Search the related files to figure out where the content lives and how it is structured.
+- Work out which locales are missing and should be generated.
+- Re-read your custom instructions every time ("transform URLs this way", "keep the brand name in English", "use the informal form").
+- Rewrite the whole file, including the parts that did not change.
+
+All of that is re-sent on every turn, so the cost grows with `size of the content × number of locales × number of turns`, and any drift in formatting or keys has to be caught by hand.
+
+## What Intlayer does instead
+
+The interest of Intlayer is to do that work outside the agent, with a pipeline built for translation:
+
+- **Filters existing translations** to limit token usage. Keys already translated in your JSON are stripped out, and only the missing ones are sent to the model.
+- **Translates markdown block by block.** For documentation, [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/doc-translate.md) and [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/doc-review.md) compare each block with the base document and skip the blocks that are already translated or unchanged.
+- **Chunks your JSON** if it is too large, to stay in the best part of the context window.
+- **Flattens and reconstructs your JSON** to optimize token consumption.
+- **Inserts custom prompts** for specific rules regarding your brand and wording (`applicationContext`, `--custom-instructions`), so you write them once instead of repeating them in every conversation.
+- **Validates the structure** to ensure consistency and prevent key drift, and preserves formatting (markdown, HTML, insertions, plurals).
+- **Implements retry management** when the output is malformed.
+- **Queues and parallelizes requests** across files, chunks and locales to increase speed.
+
+None of that goes through the agent's context. The rule of thumb: let the agent decide **what** to internationalize, and let Intlayer do the repetitive work.
+
+## Solution
+
+### 1. Delegate extraction to `intlayer extract`
+
+Instead of asking the agent to rewrite each component by hand, let it run the [`extract`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/extract.md) command. It moves hard-coded strings into a `.content` file next to the component without loading the whole file into the agent's context.
+
+```bash
+npx intlayer extract --file src/components/Header.tsx
+```
+
+### 2. Delegate translation to `intlayer fill`
+
+Never ask the agent to translate. The [`fill`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/fill.md) command applies the pipeline above: it only sends the missing keys, chunks them, runs the locales in parallel and writes the result back into your content files.
+
+```bash
+npx intlayer fill
+```
+
+A few flags keep the run small:
+
+- `--git-diff` (or `--uncommitted`) only processes the dictionaries changed in the current branch.
+- `--file` or `--keys` targets specific content files.
+- `--output-locales fr es` limits the run to the locales you actually need now.
+- `--skip-metadata` skips title, description and tags generation.
+- `--data-serialization toon` sends a more compact payload to the model (fewer tokens, slightly less consistent output).
+
+```bash
+npx intlayer fill --git-diff --output-locales fr es --skip-metadata
+```
+
+### 3. Translate markdown with `doc translate` and `doc review`
+
+Asking an agent to translate a `.md` file means pasting the whole document, for every locale, on every change. The [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/doc-translate.md) and [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/doc-review.md) commands work block by block instead.
+
+Use `doc translate` when the translated file does not exist yet. It chunks the markdown, translates it in parallel and writes the target files:
+
+```bash
+npx intlayer doc translate --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+Use `doc review` when the translated file already exists. It compares each block with the base document, skips the blocks that are already translated or unchanged, and only sends the diverging ones:
+
+```bash
+npx intlayer doc review --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+Both commands accept your rules once, instead of you repeating them in every prompt:
+
+```bash
+npx intlayer doc translate --custom-instructions "Do not translate URLs. Keep the markdown structure and the code blocks untouched."
+```
+
+Two modes of `doc review` are useful when the agent still needs to be in the loop, without any AI call from Intlayer:
+
+- `--mode report` logs the blocks that need attention, with line numbers, so the agent only touches those blocks.
+- `--mode synthesis` only logs which documents are up to date and which still have blocks to edit.
+
+```bash
+npx intlayer doc review --mode report --locales fr
+```
+
+### 4. Let the agent call the CLI through the MCP server
+
+With the [Intlayer MCP server](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/mcp_server.md), the agent answers from the current documentation and runs `intlayer fill` or `intlayer doc review` itself instead of re-implementing it in the conversation.
+
+```bash
+claude mcp add intlayer npx -y @intlayer/mcp
+```
+
+Installing the [Agent Skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/agent_skills.md) with `npx intlayer init skills` also stops the agent from guessing the Intlayer API and re-reading the docs on every task.
+
+### 5. Reuse your Claude subscription with `claude setup-token`
+
+Running the i18n setup in your interactive Claude Code session keeps the whole conversation history in context. Move the heavy lifting to a short headless session instead.
+
+Generate a long-lived token from your Claude subscription:
+
+```bash
+claude setup-token
+```
+
+Store it as `CLAUDE_CODE_OAUTH_TOKEN` (in a `.env` file or your CI secrets), then reuse it for a one-shot session that runs the Intlayer commands:
+
+```bash
+CLAUDE_CODE_OAUTH_TOKEN=... claude -p "Run npx intlayer extract on src/components, then npx intlayer fill --uncommitted"
+```
+
+The session only carries that prompt and the command output, not your whole conversation. The same token works in the [Claude Code GitHub Action](https://github.com/anthropics/claude-code-action) to run `intlayer fill` on every pull request.
+
+> The token issued by `claude setup-token` authenticates Claude Code only. It cannot be used as an Anthropic API key in `ai.apiKey`. For the translation itself, `intlayer fill` uses your [Intlayer account](https://app.intlayer.org) (free tier included) or your own provider key configured in [`ai`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md#ai-configuration).
+
+## Summary
+
+| Task                    | Who does it              | Tokens in the agent context |
+| ----------------------- | ------------------------ | --------------------------- |
+| Decide what to localize | Claude Code              | Low                         |
+| Extract strings         | `intlayer extract`       | None                        |
+| Translate content       | `intlayer fill`          | None                        |
+| Translate documentation | `intlayer doc translate` | None                        |
+| Update documentation    | `intlayer doc review`    | None                        |
+| Run the commands        | Headless Claude Code     | Prompt + command output     |

package/frequent_questions/en-GB/claude_code_token_consumption.md

@@ -0,0 +1,152 @@
+---
+createdAt: 2026-09-13
+updatedAt: 2026-09-13
+title: How to limit Claude Code token consumption to generate translations
+description: Why translating with Claude Code burns tokens, what Intlayer does instead (filters translated keys, chunks JSON, translates markdown block by block), and how to reuse your Claude subscription with claude setup-token.
+keywords:
+  - claude code
+  - tokens
+  - token consumption
+  - setup-token
+  - i18n
+  - internationalisation
+  - translation
+  - fill
+  - mcp
+  - agent
+slugs:
+  - frequent-questions
+  - claude-code-token-consumption
+author: aymericzip
+---
+
+# How to limit Claude Code token consumption to generate translations
+
+## Problem Description
+
+Asking Claude Code (or any coding agent) to translate your content is the most expensive way to do it. For each run, the agent has to:
+
+- Load the complete JSON or content file into its context, even the keys that are already translated.
+- Search the related files to figure out where the content lives and how it is structured.
+- Work out which locales are missing and should be generated.
+- Re-read your custom instructions every time ("transform URLs this way", "keep the brand name in English", "use the informal form").
+- Rewrite the whole file, including the parts that did not change.
+
+All of that is re-sent on every turn, so the cost grows with `size of the content × number of locales × number of turns`, and any drift in formatting or keys has to be caught by hand.
+
+## What Intlayer does instead
+
+The interest of Intlayer is to do that work outside the agent, with a pipeline built for translation:
+
+- **Filters existing translations** to limit token usage. Keys already translated in your JSON are stripped out, and only the missing ones are sent to the model.
+- **Translates markdown block by block.** For documentation, [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/doc-translate.md) and [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/doc-review.md) compare each block with the base document and skip the blocks that are already translated or unchanged.
+- **Chunks your JSON** if it is too large, to stay in the best part of the context window.
+- **Flattens and reconstructs your JSON** to optimise token consumption.
+- **Inserts custom prompts** for specific rules regarding your brand and wording (`applicationContext`, `--custom-instructions`), so you write them once instead of repeating them in every conversation.
+- **Validates the structure** to ensure consistency and prevent key drift, and preserves formatting (markdown, HTML, insertions, plurals).
+- **Implements retry management** when the output is malformed.
+- **Queues and parallelises requests** across files, chunks and locales to increase speed.
+
+None of that goes through the agent's context. The rule of thumb: let the agent decide **what** to internationalise, and let Intlayer do the repetitive work.
+
+## Solution
+
+### 1. Delegate extraction to `intlayer extract`
+
+Instead of asking the agent to rewrite each component by hand, let it run the [`extract`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/extract.md) command. It moves hard-coded strings into a `.content` file next to the component without loading the whole file into the agent's context.
+
+```bash
+npx intlayer extract --file src/components/Header.tsx
+```
+
+### 2. Delegate translation to `intlayer fill`
+
+Never ask the agent to translate. The [`fill`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/fill.md) command applies the pipeline above: it only sends the missing keys, chunks them, runs the locales in parallel and writes the result back into your content files.
+
+```bash
+npx intlayer fill
+```
+
+A few flags keep the run small:
+
+- `--git-diff` (or `--uncommitted`) only processes the dictionaries changed in the current branch.
+- `--file` or `--keys` targets specific content files.
+- `--output-locales fr es` limits the run to the locales you actually need now.
+- `--skip-metadata` skips title, description and tags generation.
+- `--data-serialization toon` sends a more compact payload to the model (fewer tokens, slightly less consistent output).
+
+```bash
+npx intlayer fill --git-diff --output-locales fr es --skip-metadata
+```
+
+### 3. Translate markdown with `doc translate` and `doc review`
+
+Asking an agent to translate a `.md` file means pasting the whole document, for every locale, on every change. The [`doc translate`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/doc-translate.md) and [`doc review`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/doc-review.md) commands work block by block instead.
+
+Use `doc translate` when the translated file does not exist yet. It chunks the markdown, translates it in parallel and writes the target files:
+
+```bash
+npx intlayer doc translate --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+Use `doc review` when the translated file already exists. It compares each block with the base document, skips the blocks that are already translated or unchanged, and only sends the diverging ones:
+
+```bash
+npx intlayer doc review --doc-pattern "docs/**/*.md" --base-locale en --locales fr es
+```
+
+Both commands accept your rules once, instead of you repeating them in every prompt:
+
+```bash
+npx intlayer doc translate --custom-instructions "Do not translate URLs. Keep the markdown structure and the code blocks untouched."
+```
+
+Two modes of `doc review` are useful when the agent still needs to be in the loop, without any AI call from Intlayer:
+
+- `--mode report` logs the blocks that need attention, with line numbers, so the agent only touches those blocks.
+- `--mode synthesis` only logs which documents are up to date and which still have blocks to edit.
+
+```bash
+npx intlayer doc review --mode report --locales fr
+```
+
+### 4. Let the agent call the CLI through the MCP server
+
+With the [Intlayer MCP server](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/mcp_server.md), the agent answers from the current documentation and runs `intlayer fill` or `intlayer doc review` itself instead of re-implementing it in the conversation.
+
+```bash
+claude mcp add intlayer npx -y @intlayer/mcp
+```
+
+Installing the [Agent Skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/agent_skills.md) with `npx intlayer init skills` also stops the agent from guessing the Intlayer API and re-reading the docs on every task.
+
+### 5. Reuse your Claude subscription with `claude setup-token`
+
+Running the i18n setup in your interactive Claude Code session keeps the whole conversation history in context. Move the heavy lifting to a short headless session instead.
+
+Generate a long-lived token from your Claude subscription:
+
+```bash
+claude setup-token
+```
+
+Store it as `CLAUDE_CODE_OAUTH_TOKEN` (in a `.env` file or your CI secrets), then reuse it for a one-shot session that runs the Intlayer commands:
+
+```bash
+CLAUDE_CODE_OAUTH_TOKEN=... claude -p "Run npx intlayer extract on src/components, then npx intlayer fill --uncommitted"
+```
+
+The session only carries that prompt and the command output, not your whole conversation. The same token works in the [Claude Code GitHub Action](https://github.com/anthropics/claude-code-action) to run `intlayer fill` on every pull request.
+
+> The token issued by `claude setup-token` authenticates Claude Code only. It cannot be used as an Anthropic API key in `ai.apiKey`. For the translation itself, `intlayer fill` uses your [Intlayer account](https://app.intlayer.org) (free tier included) or your own provider key configured in [`ai`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md#ai-configuration).
+
+## Summary
+
+| Task                    | Who does it              | Tokens in the agent context |
+| ----------------------- | ------------------------ | --------------------------- |
+| Decide what to localise | Claude Code              | Low                         |
+| Extract strings         | `intlayer extract`       | None                        |
+| Translate content       | `intlayer fill`          | None                        |
+| Translate documentation | `intlayer doc translate` | None                        |
+| Update documentation    | `intlayer doc review`    | None                        |
+| Run the commands        | Headless Claude Code     | Prompt + command output     |