@intlayer/docs 7.2.3 → 7.3.0

package/README.md

@@ -24,6 +24,8 @@
   <a href="https://github.com/aymericzip/intlayer/blob/main/LICENSE" target="_blank" rel="noopener noreferrer nofollow"><img src="https://img.shields.io/github/license/aymericzip/intlayer?style=for-the-badge&labelColor=000000&color=FFFFFF&logoColor=000000&cacheSeconds=86400" alt="license"/></a>
   <a href="https://github.com/aymericzip/intlayer/commits/main" target="_blank" rel="noopener noreferrer nofollow"><img src="https://img.shields.io/github/last-commit/aymericzip/intlayer?style=for-the-badge&labelColor=000000&color=FFFFFF&logoColor=000000&cacheSeconds=86400" alt="last commit"/>
   </a>
+  <a href="https://bountyhub.dev/bounties?repo=intlayer" target="_blank" rel="noopener noreferrer nofollow"><img src="https://img.shields.io/badge/Bounties-on%20BountyHub-yellow?style=for-the-badge&labelColor=000000&color=FFFFFF&logoColor=000000&cacheSeconds=86400" alt="Bounties on BountyHub"/>
+  </a>
 </p>
 
 ![Watch the video](https://github.com/aymericzip/intlayer/blob/main/docs/assets/demo_video.gif)

package/blog/ar/compiler_vs_declarative_i18n.md

@@ -0,0 +1,138 @@
+---
+createdAt: 2025-11-24
+updatedAt: 2025-11-24
+title: المترجم مقابل التدوين التصريحي في التدويل
+description: استكشاف المقايضات المعمارية بين التدويل "السحري" المعتمد على المترجم وإدارة المحتوى التصريحية الصريحة.
+keywords:
+  - Intlayer
+  - التدويل
+  - مدونة
+  - Next.js
+  - JavaScript
+  - React
+  - i18n
+  - المترجم
+  - تدويني
+slugs:
+  - compiler-vs-declarative-i18n
+  - blog
+  - i18n
+---
+
+# الحجج المؤيدة والمعارضة للتدويل المعتمد على المترجم
+
+إذا كنت تبني تطبيقات ويب لأكثر من عقد من الزمن، فأنت تعلم أن التدويل (i18n) كان دائمًا نقطة احتكاك. غالبًا ما تكون مهمة لا يرغب أحد في القيام بها — استخراج النصوص، إدارة ملفات JSON، والقلق بشأن قواعد الجمع والتعدد.
+
+مؤخرًا، ظهرت موجة جديدة من أدوات التدويل "المعتمدة على المترجم"، واعدة بجعل هذه المعاناة تختفي. العرض مغرٍ: **فقط اكتب النص في مكوناتك، ودع أداة البناء تتولى الباقي.** لا مفاتيح، لا استيرادات، فقط سحر.
+
+ولكن كما هو الحال مع جميع التجريدات في هندسة البرمجيات، يأتي السحر بثمن.
+
+في هذه التدوينة، سوف نستكشف التحول من المكتبات التصريحية إلى النهج المعتمد على المترجم، والديون المعمارية الخفية التي يقدمونها، ولماذا قد يكون الطريق "الممل" لا يزال أفضل طريقة للتطبيقات المهنية.
+
+## لمحة تاريخية عن الترجمة
+
+لفهم مكاننا الحالي، علينا أن ننظر إلى الوراء حيث بدأنا.
+
+حوالي عامي 2011–2012، كان مشهد JavaScript مختلفًا تمامًا. لم تكن أدوات التجميع كما نعرفها اليوم (Webpack، Vite) موجودة أو كانت في مراحلها الأولى. كنا نلصق السكريبتات معًا في المتصفح. في هذه الحقبة، وُلدت مكتبات مثل **i18next**.
+
+لقد حلوا المشكلة بالطريقة الوحيدة الممكنة في ذلك الوقت: **القواميس أثناء وقت التشغيل**. كنت تقوم بتحميل كائن JSON ضخم في الذاكرة، وكانت دالة تبحث عن المفاتيح أثناء التنفيذ. كان ذلك موثوقًا وصريحًا، ويعمل في كل مكان.
+
+تقدم سريعًا إلى اليوم. لدينا مترجمات قوية (SWC، أدوات تجميع مبنية على Rust) يمكنها تحليل أشجار البنية المجردة (AST) في غضون مللي ثانية. هذه القوة ولدت فكرة جديدة: _لماذا ندير المفاتيح يدويًا؟ لماذا لا يستطيع المترجم فقط رؤية النص "Hello World" واستبداله لنا؟_
+
+وهكذا وُلدت الترجمة المعتمدة على المترجم (Compiler-based i18n).
+
+## جاذبية المترجم (النهج "السحري")
+
+هناك سبب يجعل هذا النهج الجديد شائعًا. بالنسبة للمطور، تكون التجربة مذهلة.
+
+### 1. السرعة و"التدفق"
+
+عندما تكون في حالة تركيز، التوقف للتفكير في اسم متغير (`home_hero_title_v2`) يكسر تدفقك. مع نهج المترجم، تكتب `<p>Welcome back</p>` وتتابع العمل. الاحتكاك معدوم.
+
+### 2. مهمة إنقاذ التراث
+
+تخيل أنك ترث قاعدة كود ضخمة تحتوي على 5000 مكون وبدون أي ترجمات. تعديل هذا النظام ليعمل بنظام المفاتيح اليدوي هو كابوس يستمر لأشهر. أداة تعتمد على المترجم تعمل كاستراتيجية إنقاذ، حيث تستخرج آلاف السلاسل النصية فورًا دون الحاجة إلى لمس أي ملف يدويًا.
+
+### 3. عصر الذكاء الاصطناعي
+
+هذه فائدة حديثة لا ينبغي أن نتجاهلها. مساعدو البرمجة بالذكاء الاصطناعي (مثل Copilot أو ChatGPT) يولدون بشكل طبيعي JSX/HTML قياسي. هم لا يعرفون مخطط مفاتيح الترجمة الخاص بك.
+
+- **إعلاني:** عليك إعادة كتابة مخرجات الذكاء الاصطناعي لاستبدال النص بالمفاتيح.
+- **المترجم:** تقوم بنسخ ولصق كود الذكاء الاصطناعي، ويعمل مباشرة.
+
+## فحص الواقع: لماذا "السحر" خطير
+
+بينما يبدو "السحر" جذابًا، فإن التجريد يتسرب. الاعتماد على أداة بناء لفهم نية الإنسان يُدخل هشاشة معمارية.
+
+### 1. هشاشة الاستدلال (لعبة التخمين)
+
+يجب على المترجم أن يخمن ما هو المحتوى وما هو الكود.
+
+- هل يتم ترجمة `className="active"`؟ إنها سلسلة نصية.
+- هل يتم ترجمة `status="pending"`؟
+- هل يتم ترجمة `<MyComponent errorMessage="An error occurred" />`؟
+- هل يتم ترجمة معرف منتج مثل `"AX-99"`؟
+
+في النهاية، ستجد نفسك "تقاتل" المترجم، مضيفًا تعليقات محددة (مثل `// ignore-translation`) لمنعه من كسر منطق تطبيقك.
+
+### 2. الحد الصعب للبيانات الديناميكية
+
+يعتمد استخراج المترجم على **التحليل الثابت**. يجب أن يرى السلسلة النصية الحرفية في كودك لتوليد معرف ثابت.
+إذا أعاد API الخاص بك رمز خطأ مثل `server_error`، فلا يمكنك ترجمته باستخدام المترجم لأن المترجم لا يعرف بوجود هذه السلسلة أثناء وقت البناء. تُجبر على بناء نظام ثانوي "للتشغيل فقط" مخصص للبيانات الديناميكية.
+
+### 3. "انفجار القطع" وشلالات الشبكة
+
+للسماح بعملية tree-shaking، غالبًا ما تقوم أدوات المترجم بتقسيم الترجمات حسب المكون.
+
+- **النتيجة:** قد يؤدي عرض صفحة واحدة تحتوي على 50 مكونًا صغيرًا إلى تفعيل **50 طلب HTTP منفصل** لقطع ترجمة صغيرة. حتى مع HTTP/2، يخلق هذا شلالًا في الشبكة يجعل تطبيقك يبدو بطيئًا مقارنة بتحميل حزمة لغة واحدة محسّنة.
+
+### 4. العبء على أداء وقت التشغيل
+
+لجعل الترجمات تفاعلية (حتى يتم تحديثها فورًا عند تبديل اللغات)، غالبًا ما يقوم المترجم بحقن خطافات إدارة الحالة في _كل_ مكون.
+
+- **التكلفة:** إذا قمت بعرض قائمة تحتوي على 5000 عنصر، فأنت تقوم بتهيئة 5000 من خطافات `useState` و `useEffect` فقط للنصوص. هذا يستهلك الذاكرة ودورات وحدة المعالجة المركزية التي توفرها المكتبات التصريحية (التي تستخدم عادة مزود Context واحد).
+
+## الفخ: التقييد بالبائع
+
+هذا ربما يكون أخطر جانب في التدويل المعتمد على المترجم.
+
+في مكتبة تصريحية، يحتوي كود المصدر الخاص بك على نية صريحة. أنت تملك المفاتيح. إذا قمت بتغيير المكتبة، فقط تغير الاستيراد.
+
+في النهج المعتمد على المترجم، **كود المصدر الخاص بك هو مجرد نص إنجليزي.** "منطق الترجمة" موجود فقط داخل تكوين إضافة البناء.
+إذا توقف ذلك المكتبة عن الصيانة، أو إذا تجاوزتها، فأنت عالق. لا يمكنك "الإخراج" بسهولة لأنك لا تملك أي مفاتيح ترجمة في شفرتك المصدرية. سيتعين عليك إعادة كتابة تطبيقك بالكامل يدويًا للانتقال بعيدًا.
+
+## الجانب الآخر: مخاطر النهج التصريحي
+
+لكي نكون منصفين، الطريقة التصريحية التقليدية ليست مثالية أيضًا. لديها مجموعة من "المشاكل الذاتية".
+
+1.  **جحيم المساحات الاسمية:** غالبًا ما يتعين عليك إدارة ملفات JSON التي يجب تحميلها يدويًا (`common.json`، `dashboard.json`، `footer.json`). إذا نسيت واحدًا، سيرى المستخدم المفاتيح الخام.
+2.  **التحميل الزائد:** بدون تكوين دقيق، من السهل جدًا تحميل _جميع_ مفاتيح الترجمة الخاصة بك لـ _جميع_ الصفحات عند التحميل الأولي، مما يزيد من حجم الحزمة.
+3.  **انحراف التزامن:** من الشائع أن تبقى المفاتيح في ملف JSON لفترة طويلة بعد حذف المكون الذي يستخدمها. تنمو ملفات الترجمة الخاصة بك بلا حدود، مليئة بـ "مفاتيح الزومبي".
+
+## الحل الوسط مع Intlayer
+
+هنا تحاول أدوات مثل **Intlayer** الابتكار. يفهم Intlayer أنه بينما المترجمات قوية، فإن السحر الضمني خطير.
+
+يقدم Intlayer أمرًا فريدًا **`transform`**. بدلاً من القيام بالسحر فقط في خطوة البناء المخفية، يمكنه فعليًا **إعادة كتابة كود المكون الخاص بك**. يقوم بمسح نصك ويستبدله بإعلانات محتوى صريحة في قاعدة الكود الخاصة بك.
+
+هذا يمنحك أفضل ما في العالمين:
+
+1.  **الدقة:** تحتفظ بترجماتك قريبة من مكوناتك (محسنًا التجزئة وإزالة الشجر).
+2.  **الأمان:** تصبح الترجمة كودًا صريحًا، وليس سحرًا مخفيًا في وقت البناء.
+3.  **عدم القفل:** نظرًا لأن الكود يتم تحويله إلى هيكل إعلاني قياسي داخل مستودعك، فلن تخفي المنطق في إضافة webpack.
+
+## الخلاصة
+
+فأي منهما يجب أن تختار؟
+
+**إذا كنت مطورًا مبتدئًا، أو مؤسسًا منفردًا، أو تبني MVP:**
+النهج القائم على المترجم هو خيار صالح. يسمح لك بالتحرك بسرعة كبيرة. لا تحتاج إلى القلق بشأن هياكل الملفات أو المفاتيح. فقط تبني. الدين الفني هو مشكلة لـ "أنت في المستقبل".
+
+**إذا كنت تبني تطبيقًا احترافيًا على مستوى المؤسسات:**
+السحر عادةً ما يكون فكرة سيئة. تحتاج إلى السيطرة.
+
+- تحتاج إلى التعامل مع البيانات الديناميكية من الخلفيات.
+- تحتاج إلى ضمان الأداء على الأجهزة منخفضة المواصفات (تجنب انفجارات الـ hooks).
+- تحتاج إلى التأكد من أنك لست مقيدًا بأداة بناء معينة إلى الأبد.
+
+بالنسبة للتطبيقات الاحترافية، يظل **إدارة المحتوى التصريحية** (مثل Intlayer أو المكتبات المعروفة) المعيار الذهبي. فهي تفصل بين اهتماماتك، وتحافظ على نظافة هيكلك، وتضمن أن قدرة تطبيقك على التحدث بعدة لغات لا تعتمد على "صندوق أسود" يقوم المترجم بتخمين نواياك.

package/blog/ar/intlayer_with_next-i18next.md

@@ -176,7 +176,6 @@ export default config;
 ```plaintext fileName=".gitignore"
 # تجاهل الملفات التي تم إنشاؤها بواسطة Intlayer
 .intlayer
-intl
 ```
 
 يتم إعادة إنشاء هذه الملفات تلقائيًا أثناء عملية البناء ولا تحتاج إلى الالتزام بها في مستودعك.

package/blog/ar/intlayer_with_vue-i18n.md

@@ -166,7 +166,6 @@ export default config;
 ```plaintext fileName=".gitignore"
 # تجاهل الملفات التي تم إنشاؤها بواسطة Intlayer
 .intlayer
-intl
 ```
 
 يتم إعادة إنشاء هذه الملفات تلقائيًا أثناء عملية البناء ولا تحتاج إلى الالتزام بها في مستودعك.

package/blog/de/compiler_vs_declarative_i18n.md

@@ -0,0 +1,138 @@
+---
+createdAt: 2025-11-24
+updatedAt: 2025-11-24
+title: Compiler vs. deklarative i18n
+description: Untersuchung der architektonischen Kompromisse zwischen "magischer" compiler-basierter Internationalisierung und explizitem deklarativem Content-Management.
+keywords:
+  - Intlayer
+  - Internationalisierung
+  - Blog
+  - Next.js
+  - JavaScript
+  - React
+  - i18n
+  - Compiler
+  - Deklarativ
+slugs:
+  - compiler-vs-declarative-i18n
+  - blog
+  - i18n
+---
+
+# Pro und Contra compiler-basierte i18n
+
+Wenn Sie seit mehr als einem Jahrzehnt Webanwendungen entwickeln, wissen Sie, dass Internationalisierung (i18n) schon immer ein Reibungspunkt war. Es ist oft die Aufgabe, die niemand machen möchte – Strings extrahieren, JSON-Dateien verwalten und sich um Pluralisierungsregeln kümmern.
+
+In letzter Zeit ist eine neue Welle von "compiler-basierten" i18n-Tools aufgetaucht, die versprechen, diesen Schmerz verschwinden zu lassen. Das Versprechen ist verlockend: **Schreiben Sie einfach den Text in Ihre Komponenten, und lassen Sie das Build-Tool den Rest erledigen.** Keine Keys, keine Importe, einfach Magie.
+
+Aber wie bei allen Abstraktionen in der Softwareentwicklung hat Magie ihren Preis.
+
+In diesem Blogbeitrag werden wir den Wandel von deklarativen Bibliotheken hin zu compiler-basierten Ansätzen untersuchen, die versteckten architektonischen Schulden, die sie mit sich bringen, und warum der "langweilige" Weg für professionelle Anwendungen immer noch der beste sein könnte.
+
+## Eine kurze Geschichte der Übersetzung
+
+Um zu verstehen, wo wir stehen, müssen wir zurückblicken, wo wir angefangen haben.
+
+Um 2011–2012 sah die JavaScript-Landschaft ganz anders aus. Bundler, wie wir sie heute kennen (Webpack, Vite), existierten entweder noch nicht oder steckten noch in den Kinderschuhen. Wir klebten Skripte direkt im Browser zusammen. In dieser Zeit entstanden Bibliotheken wie **i18next**.
+
+Sie lösten das Problem auf die damals einzig mögliche Weise: **Runtime-Wörterbücher**. Man lud ein riesiges JSON-Objekt in den Speicher, und eine Funktion suchte die Schlüssel zur Laufzeit nach. Es war zuverlässig, explizit und funktionierte überall.
+
+Spulen wir bis heute vor. Wir haben leistungsstarke Compiler (SWC, Rust-basierte Bundler), die Abstract Syntax Trees (AST) in Millisekunden parsen können. Diese Leistung brachte eine neue Idee hervor: _Warum verwalten wir Schlüssel manuell? Warum kann der Compiler nicht einfach den Text "Hello World" sehen und für uns austauschen?_
+
+So wurde das compiler-basierte i18n geboren.
+
+## Der Reiz des Compilers (Der "Magische" Ansatz)
+
+Es gibt einen Grund, warum dieser neue Ansatz im Trend liegt. Für einen Entwickler fühlt sich die Erfahrung unglaublich an.
+
+### 1. Geschwindigkeit und "Flow"
+
+Wenn man im Flow ist, unterbricht das Nachdenken über einen Variablennamen (`home_hero_title_v2`) den Arbeitsfluss. Mit einem Compiler-Ansatz tippt man einfach `<p>Welcome back</p>` und macht weiter. Die Reibung ist null.
+
+### 2. Die Rettungsmission für Altbestände
+
+Stellen Sie sich vor, Sie erben eine riesige Codebasis mit 5.000 Komponenten und null Übersetzungen. Diese manuell mit einem schlüsselbasierten System nachzurüsten, ist ein monatelanger Albtraum. Ein compilerbasiertes Tool fungiert als Rettungsstrategie, indem es sofort Tausende von Strings extrahiert, ohne dass Sie eine einzige Datei manuell anfassen müssen.
+
+### 3. Das KI-Zeitalter
+
+Dies ist ein moderner Vorteil, den wir nicht übersehen sollten. KI-Coding-Assistenten (wie Copilot oder ChatGPT) erzeugen natürlicherweise standardmäßiges JSX/HTML. Sie kennen Ihr spezifisches Übersetzungsschlüsselschema nicht.
+
+- **Deklarativ:** Sie müssen die Ausgabe der KI umschreiben, um Text durch Schlüssel zu ersetzen.
+- **Compiler:** Sie kopieren den Code der KI einfach und es funktioniert sofort.
+
+## Die Realität: Warum "Magie" gefährlich ist
+
+Obwohl die "Magie" verlockend ist, gibt es Undichtigkeiten in der Abstraktion. Sich auf ein Build-Tool zu verlassen, das menschliche Absichten versteht, führt zu architektonischer Fragilität.
+
+### 1. Heuristische Fragilität (Das Ratespiel)
+
+Der Compiler muss erraten, was Inhalt und was Code ist.
+
+- Wird `className="active"` übersetzt? Es ist ein String.
+- Wird `status="pending"` übersetzt?
+- Wird `<MyComponent errorMessage="An error occurred" />` übersetzt?
+- Wird eine Produkt-ID wie `"AX-99"` übersetzt?
+
+Sie enden unweigerlich damit, gegen den Compiler "anzukämpfen" und fügen spezifische Kommentare hinzu (wie `// ignore-translation`), um zu verhindern, dass er Ihre Anwendungslogik bricht.
+
+### 2. Die harte Grenze bei dynamischen Daten
+
+Die Compiler-Extraktion basiert auf **statischer Analyse**. Sie muss den Literalstring in Ihrem Code sehen, um eine stabile ID zu generieren.
+Wenn Ihre API einen Fehlercode-String wie `server_error` zurückgibt, können Sie ihn nicht mit einem Compiler übersetzen, da der Compiler diesen String zur Build-Zeit nicht kennt. Sie sind gezwungen, ein sekundäres "nur zur Laufzeit" System nur für dynamische Daten zu erstellen.
+
+### 3. "Chunk-Explosion" und Netzwerk-Wasserfälle
+
+Um Tree-Shaking zu ermöglichen, teilen Compiler-Tools Übersetzungen oft pro Komponente auf.
+
+- **Die Folge:** Eine einzelne Seitenansicht mit 50 kleinen Komponenten könnte **50 separate HTTP-Anfragen** für winzige Übersetzungsfragmente auslösen. Selbst mit HTTP/2 erzeugt dies eine Netzwerk-Wasserfallstruktur, die Ihre Anwendung im Vergleich zum Laden eines einzigen, optimierten Sprachpakets träge erscheinen lässt.
+
+### 4. Laufzeit-Performance-Overhead
+
+Um Übersetzungen reaktiv zu machen (damit sie sich sofort aktualisieren, wenn Sie die Sprache wechseln), injiziert der Compiler häufig Zustandsverwaltungs-Hooks in _jede_ Komponente.
+
+- **Die Kosten:** Wenn Sie eine Liste mit 5.000 Elementen rendern, initialisieren Sie 5.000 `useState`- und `useEffect`-Hooks ausschließlich für Text. Dies verbraucht Speicher und CPU-Zyklen, die deklarative Bibliotheken (die typischerweise einen einzigen Context-Provider verwenden) einsparen.
+
+## Die Falle: Vendor Lock-in
+
+Dies ist wohl der gefährlichste Aspekt von compiler-basierter i18n.
+
+In einer deklarativen Bibliothek enthält Ihr Quellcode eine explizite Absicht. Sie besitzen die Keys. Wenn Sie die Bibliothek wechseln, ändern Sie einfach den Import.
+
+In einem compiler-basierten Ansatz ist **Ihr Quellcode nur englischer Text.** Die „Übersetzungslogik“ existiert nur in der Konfiguration des Build-Plugins.
+Wenn diese Bibliothek nicht mehr gepflegt wird oder wenn Sie darüber hinauswachsen, sind Sie festgefahren. Sie können nicht einfach „aussteigen“, weil Sie keine Übersetzungsschlüssel in Ihrem Quellcode haben. Sie müssten Ihre gesamte Anwendung manuell neu schreiben, um zu migrieren.
+
+## Die andere Seite: Risiken des deklarativen Ansatzes
+
+Um fair zu sein, ist der traditionelle deklarative Weg auch nicht perfekt. Er hat seine eigenen „Fußangeln“.
+
+1.  **Namespace-Hölle:** Sie müssen oft manuell verwalten, welche JSON-Dateien geladen werden (`common.json`, `dashboard.json`, `footer.json`). Wenn Sie eine vergessen, sieht der Benutzer rohe Schlüssel.
+2.  **Übermäßiges Laden:** Ohne sorgfältige Konfiguration ist es sehr einfach, versehentlich _alle_ Ihre Übersetzungsschlüssel für _alle_ Seiten beim ersten Laden zu laden, was Ihre Bundle-Größe aufbläht.
+3.  **Synchronisationsabweichung:** Es ist üblich, dass Schlüssel lange nach der Löschung der sie verwendenden Komponente in der JSON-Datei verbleiben. Ihre Übersetzungsdateien wachsen unendlich und sind mit „Zombie-Schlüsseln“ gefüllt.
+
+## Der Mittelweg mit Intlayer
+
+Hier versuchen Werkzeuge wie **Intlayer** zu innovieren. Intlayer versteht, dass Compiler zwar mächtig sind, implizite Magie jedoch gefährlich ist.
+
+Intlayer bietet einen einzigartigen **`transform`-Befehl** an. Anstatt nur Magie im versteckten Build-Schritt auszuführen, kann es tatsächlich **Ihren Komponenten-Code umschreiben**. Es scannt Ihren Text und ersetzt ihn durch explizite Inhaltsdeklarationen in Ihrem Codebase.
+
+Das bietet Ihnen das Beste aus beiden Welten:
+
+1.  **Granularität:** Sie halten Ihre Übersetzungen nah an Ihren Komponenten (verbessert Modularität und Tree-Shaking).
+2.  **Sicherheit:** Die Übersetzung wird zu explizitem Code, nicht zu versteckter Build-Zeit-Magie.
+3.  **Keine Bindung:** Da der Code in eine standardisierte deklarative Struktur innerhalb Ihres Repositories umgewandelt wird, verstecken Sie keine Logik in einem Webpack-Plugin.
+
+## Fazit
+
+Welche Methode sollten Sie also wählen?
+
+**Wenn Sie ein Junior-Entwickler, ein Solo-Gründer oder ein MVP-Ersteller sind:**  
+Der compilerbasierte Ansatz ist eine gültige Wahl. Er ermöglicht es Ihnen, unglaublich schnell voranzukommen. Sie müssen sich nicht um Dateistrukturen oder Schlüssel kümmern. Sie bauen einfach. Die technische Schuld ist ein Problem für das „zukünftige Sie“.
+
+**Wenn Sie eine professionelle, unternehmensgerechte Anwendung entwickeln:**  
+Magie ist im Allgemeinen eine schlechte Idee. Sie brauchen Kontrolle.
+
+- Sie müssen dynamische Daten von Backends verarbeiten.
+- Sie müssen die Leistung auf Geräten mit geringer Leistung sicherstellen (Vermeidung von Hook-Explosionen).
+- Sie müssen sicherstellen, dass Sie nicht für immer an ein bestimmtes Build-Tool gebunden sind.
+
+Für professionelle Anwendungen bleibt **Deklaratives Content Management** (wie Intlayer oder etablierte Bibliotheken) der Goldstandard. Es trennt Ihre Anliegen, hält Ihre Architektur sauber und stellt sicher, dass die Mehrsprachigkeitsfähigkeit Ihrer Anwendung nicht von einem „Black-Box“-Compiler abhängt, der Ihre Absichten errät.

package/blog/de/intlayer_with_next-i18next.md

@@ -177,7 +177,6 @@ Schließen Sie generierte Dateien von der Versionskontrolle aus:
 ```plaintext fileName=".gitignore"
 # Dateien ignorieren, die von Intlayer generiert werden
 .intlayer
-intl
 ```
 
 Diese Dateien werden während des Build-Prozesses automatisch neu generiert und müssen nicht in Ihr Repository eingecheckt werden.

package/blog/de/intlayer_with_vue-i18n.md

@@ -166,7 +166,6 @@ Schließen Sie generierte Dateien von der Versionskontrolle aus:
 ```plaintext fileName=".gitignore"
 # Ignoriere von Intlayer generierte Dateien
 .intlayer
-intl
 ```
 
 Diese Dateien werden während des Build-Prozesses automatisch neu generiert und müssen nicht in Ihr Repository übernommen werden.

package/blog/en/compiler_vs_declarative_i18n.md

@@ -0,0 +1,138 @@
+---
+createdAt: 2025-11-24
+updatedAt: 2025-11-24
+title: Compiler vs. Declarative i18n
+description: Exploring the architectural trade-offs between "magic" compiler-based internationalization and explicit declarative content management.
+keywords:
+  - Intlayer
+  - Internationalization
+  - Blog
+  - Next.js
+  - JavaScript
+  - React
+  - i18n
+  - Compiler
+  - Declarative
+slugs:
+  - compiler-vs-declarative-i18n
+  - blog
+  - i18n
+---
+
+# The Case for and Against Compiler-Based i18n
+
+If you have been building web applications for more than a decade, you know that Internationalization (i18n) has always been a friction point. It is often the task no one wants to do—extracting strings, managing JSON files, and worrying about pluralization rules.
+
+Recently, a new wave of "Compiler-based" i18n tools has emerged, promising to make this pain disappear. The pitch is seductive: **Just write text in your components, and let the build tool handle the rest.** No keys, no imports, just magic.
+
+But as with all abstractions in software engineering, magic comes with a price.
+
+In this blog post, we will explore the shift from declarative libraries to compiler-based approaches, the hidden architectural debts they introduce, and why the "boring" way might still be the best way for professional applications.
+
+## A Brief History of Translation
+
+To understand where we are, we have to look back at where we started.
+
+Around 2011–2012, the JavaScript landscape was vastly different. Bundlers as we know them (Webpack, Vite) didn't exist or were in their infancy. We were glueing scripts together in the browser. In this era, libraries like **i18next** were born.
+
+They solved the problem the only way possible at the time: **Runtime Dictionaries**. You loaded a massive JSON object into memory, and a function looked up keys on the fly. It was reliable, explicit, and worked everywhere.
+
+Fast forward to today. We have powerful compilers (SWC, Rust-based bundlers) that can parse Abstract Syntax Trees (AST) in milliseconds. This power gave birth to a new idea: _Why are we manually managing keys? Why can't the compiler just see the text "Hello World" and swap it out for us?_
+
+Thus, Compiler-based i18n was born.
+
+## The Allure of the Compiler (The "Magic" Approach)
+
+There is a reason this new approach is trending. For a developer, the experience feels incredible.
+
+### 1. Speed and "Flow"
+
+When you are in the zone, stopping to think of a variable name (`home_hero_title_v2`) breaks your flow. With a compiler approach, you type `<p>Welcome back</p>` and keep moving. The friction is zero.
+
+### 2. The Legacy Rescue Mission
+
+Imagine inheriting a massive codebase with 5,000 components and zero translations. Retrofitting this with a manual key-based system is a months-long nightmare. A compiler-based tool acts as a rescue strategy, instantly extracting thousands of strings without you needing to touch a single file manually.
+
+### 3. The AI Era
+
+This is a modern benefit we shouldn't overlook. AI coding assistants (like Copilot or ChatGPT) naturally generate standard JSX/HTML. They don't know your specific translation key schema.
+
+- **Declarative:** You have to rewrite the AI's output to replace text with keys.
+- **Compiler:** You copy-paste the AI's code, and it just works.
+
+## The Reality Check: Why "Magic" is Dangerous
+
+While the "magic" is appealing, the abstraction leaks. Relying on a build tool to understand human intent introduces architectural fragility.
+
+### 1. Heuristic Fragility (The Guessing Game)
+
+The compiler has to guess what is content and what is code.
+
+- Does `className="active"` get translated? It's a string.
+- Does `status="pending"` get translated?
+- Does `<MyComponent errorMessage="An error occurred" />` get translated?
+- Does a product ID like `"AX-99"` get translated?
+
+You inevitably end up "fighting" the compiler, adding specific comments (like `// ignore-translation`) to prevent it from breaking your application logic.
+
+### 2. The Dynamic Data Hard Limit
+
+Compiler extraction relies on **static analysis**. It must see the literal string in your code to generate a stable ID.
+If your API returns an error code string like `server_error`, you cannot translate it with a compiler because the compiler doesn't know that string exists at build time. You are forced to build a secondary "runtime-only" system just for dynamic data.
+
+### 3. "Chunk Explosion" and Network Waterfalls
+
+To allow for tree-shaking, compiler tools often split translations per component.
+
+- **The Consequence:** A single page view with 50 small components might trigger **50 separate HTTP requests** for tiny translation fragments. Even with HTTP/2, this creates a network waterfall that makes your application feel sluggish compared to loading a single, optimized language bundle.
+
+### 4. Runtime Performance Overhead
+
+To make translations reactive (so they update instantly when you switch languages), the compiler often injects state management hooks into _every_ component.
+
+- **The Cost:** If you render a list of 5,000 items, you are initializing 5,000 `useState` and `useEffect` hooks solely for text. This eats up memory and CPU cycles that declarative libraries (which typically use a single Context provider) save.
+
+## The Trap: Vendor Lock-in
+
+This is arguably the most dangerous aspect of compiler-based i18n.
+
+In a declarative library, your source code contains explicit intent. You own the keys. If you switch libraries, you just change the import.
+
+In a compiler-based approach, **your source code is just English text.** The "translation logic" only exists inside the build plugin's configuration.
+If that library stops being maintained, or if you outgrow it, you are stuck. You cannot "eject" easily because you have zero translation keys in your source code. You would have to manually rewrite your entire application to migrate away.
+
+## The Other Side: Risks of the Declarative Approach
+
+To be fair, the traditional declarative way isn't perfect either. It has its own set of "footguns."
+
+1.  **Namespace Hell:** You often have to manually manage which JSON files to load (`common.json`, `dashboard.json`, `footer.json`). If you forget one, the user sees raw keys.
+2.  **Over-fetching:** Without careful configuration, it is very easy to accidentally load _all_ your translation keys for _all_ pages on the initial load, bloating your bundle size.
+3.  **Sync Drift:** It is common for keys to remain in the JSON file long after the component using them has been deleted. Your translation files grow indefinitely, filled with "zombie keys."
+
+## The Intlayer Middle Ground
+
+This is where tools like **Intlayer** are trying to innovate. Intlayer understands that while compilers are powerful, implicit magic is dangerous.
+
+Intlayer offers a unique **`transform` command**. Instead of just doing magic in the hidden build step, it can actually **rewrite your component code**. It scans your text and replaces it with explicit content declarations in your codebase.
+
+This gives you the best of both worlds:
+
+1.  **Granularity:** You keep your translations close to your components (improving modularity and tree-shaking).
+2.  **Safety:** The translation becomes explicit code, not hidden build-time magic.
+3.  **No Lock-in:** Since the code is transformed into a standard declarative structure within your repo, you aren't hiding logic in a webpack plugin.
+
+## Conclusion
+
+So, which should you choose?
+
+**If you are a Junior Developer, a Solo Founder, or building an MVP:**
+The compiler-based approach is a valid choice. It allows you to move incredibly fast. You don't need to worry about file structures or keys. You just build. The technical debt is a problem for "Future You."
+
+**If you are building a Professional, Enterprise-Grade Application:**
+Magic is generally a bad idea. You need control.
+
+- You need to handle dynamic data from backends.
+- You need to ensure performance on low-end devices (avoiding hook explosions).
+- You need to ensure you aren't locked into a specific build tool forever.
+
+For professional apps, **Declarative Content Management** (like Intlayer or established libraries) remains the gold standard. It separates your concerns, keeps your architecture clean, and ensures that your application's ability to speak multiple languages isn't dependent on a "black box" compiler guessing your intentions.

package/blog/en/i18n_using_next-i18next.md

@@ -1061,7 +1061,7 @@ Intlayer will allows your to:
   Intlayer provide test functions to that can be integrated in your CI/CD pipeline, or in your unit tests. Learn more about [testing your translations](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/testing.md).
 
 - **Automate your translations**,
-  Intlayer provide a CLI and a VSCode extension to automate your translations. It can be integrated in your CI/CD pipeline. Learn more about [automating your translations](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_cli.md).
+  Intlayer provide a CLI and a VSCode extension to automate your translations. It can be integrated in your CI/CD pipeline. Learn more about [automating your translations](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/index.md).
   You can use your **own API key, and the AI provider of your choice**. It also provide context aware translations, see [fill content](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/autoFill.md).
 
 - **Connect external content**

package/blog/en/i18n_using_next-intl.md

@@ -745,7 +745,7 @@ Intlayer will allows your to:
   Intlayer provide test functions to that can be integrated in your CI/CD pipeline, or in your unit tests. Learn more about [testing your translations](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/testing.md).
 
 - **Automate your translations**,
-  Intlayer provide a CLI and a VSCode extension to automate your translations. It can be integrated in your CI/CD pipeline. Learn more about [automating your translations](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_cli.md).
+  Intlayer provide a CLI and a VSCode extension to automate your translations. It can be integrated in your CI/CD pipeline. Learn more about [automating your translations](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/index.md).
   You can use your **own API key, and the AI provider of your choice**. It also provide context aware translations, see [fill content](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/autoFill.md).
 
 - **Connect external content**

package/blog/en/intlayer_with_i18next.md

@@ -218,7 +218,7 @@ npx intlayer fill
 This will fill your translations with the AI provider you have configured.
 
 > See all the available AI providers in the [Intlayer AI configuration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md#ai-configuration).
-> See all the available commands in the [Intlayer CLI documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_cli.md).
+> See all the available commands in the [Intlayer CLI documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/index.md).
 
 ---
 

package/blog/en/intlayer_with_next-i18next.md

@@ -218,7 +218,7 @@ npx intlayer fill
 This will fill your translations with the AI provider you have configured.
 
 > See all the available AI providers in the [Intlayer AI configuration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md#ai-configuration).
-> See all the available commands in the [Intlayer CLI documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_cli.md).
+> See all the available commands in the [Intlayer CLI documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/index.md).
 
 ---
 
@@ -229,7 +229,6 @@ Exclude generated files from version control:
 ```plaintext fileName=".gitignore"
 # Ignore files generated by Intlayer
 .intlayer
-intl
 ```
 
 These files are automatically regenerated during the build process and don't need to be committed to your repository.

package/blog/en/intlayer_with_next-intl.md

@@ -203,7 +203,7 @@ npx intlayer fill
 This will fill your translations with the AI provider you have configured.
 
 > See all the available AI providers in the [Intlayer AI configuration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md#ai-configuration).
-> See all the available commands in the [Intlayer CLI documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_cli.md).
+> See all the available commands in the [Intlayer CLI documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/index.md).
 
 ---
 

package/blog/en/intlayer_with_react-i18next.md

@@ -214,7 +214,7 @@ npx intlayer fill
 This will fill your translations with the AI provider you have configured.
 
 > See all the available AI providers in the [Intlayer AI configuration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md#ai-configuration).
-> See all the available commands in the [Intlayer CLI documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_cli.md).
+> See all the available commands in the [Intlayer CLI documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/index.md).
 
 ## Git Configuration
 

package/blog/en/intlayer_with_react-intl.md

@@ -212,7 +212,7 @@ npx intlayer fill
 This will fill your translations with the AI provider you have configured.
 
 > See all the available AI providers in the [Intlayer AI configuration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md#ai-configuration).
-> See all the available commands in the [Intlayer CLI documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_cli.md).
+> See all the available commands in the [Intlayer CLI documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/index.md).
 
 ---
 

package/blog/en/intlayer_with_vue-i18n.md

@@ -216,7 +216,7 @@ npx intlayer fill
 This will fill your translations with the AI provider you have configured.
 
 > See all the available AI providers in the [Intlayer AI configuration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md#ai-configuration).
-> See all the available commands in the [Intlayer CLI documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_cli.md).
+> See all the available commands in the [Intlayer CLI documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/index.md).
 
 ---
 
@@ -227,7 +227,6 @@ Exclude generated files from version control:
 ```plaintext fileName=".gitignore"
 # Ignore files generated by Intlayer
 .intlayer
-intl
 ```
 
 These files are automatically regenerated during the build process and don't need to be committed to your repository.