@intlayer/docs 7.2.3 → 7.3.0

package/blog/hi/intlayer_with_next-i18next.md

@@ -176,7 +176,6 @@ export default config;
 ```plaintext fileName=".gitignore"
 # Intlayer द्वारा जनरेट की गई फ़ाइलों को अनदेखा करें
 .intlayer
-intl
 ```
 
 ये फ़ाइलें बिल्ड प्रक्रिया के दौरान स्वचालित रूप से पुनः उत्पन्न होती हैं और इन्हें आपके रिपॉजिटरी में कमिट करने की आवश्यकता नहीं है।

package/blog/hi/intlayer_with_vue-i18n.md

@@ -166,7 +166,6 @@ export default config;
 ```plaintext fileName=".gitignore"
 # Intlayer द्वारा जनरेट की गई फ़ाइलों को अनदेखा करें
 .intlayer
-intl
 ```
 
 ये फ़ाइलें बिल्ड प्रक्रिया के दौरान स्वचालित रूप से पुनः उत्पन्न होती हैं और इन्हें आपके रिपॉजिटरी में कमिट करने की आवश्यकता नहीं है।

package/blog/id/compiler_vs_declarative_i18n.md

@@ -0,0 +1,138 @@
+---
+createdAt: 2025-11-24
+updatedAt: 2025-11-24
+title: Compiler vs. Deklaratif i18n
+description: Menjelajahi pertukaran arsitektural antara internasionalisasi berbasis compiler "ajaib" dan manajemen konten deklaratif yang eksplisit.
+keywords:
+  - Intlayer
+  - Internasionalisasi
+  - Blog
+  - Next.js
+  - JavaScript
+  - React
+  - i18n
+  - Compiler
+  - Deklaratif
+slugs:
+  - compiler-vs-declarative-i18n
+  - blog
+  - i18n
+---
+
+# Argumen Mendukung dan Menentang i18n Berbasis Compiler
+
+Jika Anda telah membangun aplikasi web selama lebih dari satu dekade, Anda tahu bahwa Internasionalisasi (i18n) selalu menjadi titik gesekan. Ini sering menjadi tugas yang tidak ada yang ingin lakukan—mengekstrak string, mengelola file JSON, dan memikirkan aturan pluralisasi.
+
+Baru-baru ini, gelombang baru alat i18n "berbasis Compiler" telah muncul, menjanjikan untuk menghilangkan rasa sakit ini. Janjinya menggoda: **Cukup tulis teks di komponen Anda, dan biarkan alat build yang mengurus sisanya.** Tidak perlu kunci, tidak perlu impor, hanya keajaiban.
+
+Namun seperti semua abstraksi dalam rekayasa perangkat lunak, keajaiban datang dengan harga.
+
+Dalam posting blog ini, kita akan mengeksplorasi pergeseran dari perpustakaan deklaratif ke pendekatan berbasis compiler, utang arsitektural tersembunyi yang mereka perkenalkan, dan mengapa cara "membosankan" mungkin masih menjadi cara terbaik untuk aplikasi profesional.
+
+## Sejarah Singkat Terjemahan
+
+Untuk memahami di mana kita berada, kita harus melihat kembali dari mana kita memulai.
+
+Sekitar tahun 2011–2012, lanskap JavaScript sangat berbeda. Bundler seperti yang kita kenal sekarang (Webpack, Vite) belum ada atau masih dalam tahap awal. Kita menggabungkan skrip langsung di browser. Pada era ini, perpustakaan seperti **i18next** lahir.
+
+Mereka memecahkan masalah dengan satu-satunya cara yang mungkin saat itu: **Kamus Runtime**. Anda memuat objek JSON besar ke dalam memori, dan sebuah fungsi mencari kunci secara langsung saat runtime. Ini dapat diandalkan, eksplisit, dan bekerja di mana saja.
+
+Maju ke hari ini. Kita memiliki compiler yang kuat (SWC, bundler berbasis Rust) yang dapat mengurai Abstract Syntax Trees (AST) dalam hitungan milidetik. Kekuatan ini melahirkan ide baru: _Mengapa kita harus mengelola kunci secara manual? Mengapa compiler tidak langsung melihat teks "Hello World" dan menggantinya untuk kita?_
+
+Dengan demikian, i18n berbasis Compiler lahir.
+
+## Daya Tarik Compiler (Pendekatan "Ajaib")
+
+Ada alasan mengapa pendekatan baru ini sedang tren. Bagi seorang developer, pengalamannya terasa luar biasa.
+
+### 1. Kecepatan dan "Aliran"
+
+Saat Anda sedang fokus, berhenti untuk memikirkan nama variabel (`home_hero_title_v2`) akan memutus aliran kerja Anda. Dengan pendekatan compiler, Anda mengetik `<p>Welcome back</p>` dan terus melanjutkan. Hambatannya nol.
+
+### 2. Misi Penyelamatan Warisan
+
+Bayangkan mewarisi codebase besar dengan 5.000 komponen dan tanpa terjemahan sama sekali. Memasang sistem berbasis kunci manual pada ini adalah mimpi buruk yang memakan waktu berbulan-bulan. Alat berbasis compiler bertindak sebagai strategi penyelamatan, langsung mengekstrak ribuan string tanpa Anda perlu menyentuh satu file pun secara manual.
+
+### 3. Era AI
+
+Ini adalah manfaat modern yang tidak boleh kita abaikan. Asisten pengkodean AI (seperti Copilot atau ChatGPT) secara alami menghasilkan JSX/HTML standar. Mereka tidak mengetahui skema kunci terjemahan spesifik Anda.
+
+- **Deklaratif:** Anda harus menulis ulang output AI untuk mengganti teks dengan kunci.
+- **Compiler:** Anda cukup menyalin-tempel kode AI, dan itu langsung bekerja.
+
+## Pemeriksaan Realitas: Mengapa "Ajaib" Itu Berbahaya
+
+Meskipun "ajaib" itu menarik, abstraksi tersebut bisa bocor. Mengandalkan alat build untuk memahami niat manusia memperkenalkan kerentanan arsitektural.
+
+### 1. Kerentanan Heuristik (Permainan Tebak-tebakan)
+
+Compiler harus menebak mana yang konten dan mana yang kode.
+
+- Apakah `className="active"` diterjemahkan? Itu adalah string.
+- Apakah `status="pending"` diterjemahkan?
+- Apakah `<MyComponent errorMessage="An error occurred" />` diterjemahkan?
+- Apakah ID produk seperti `"AX-99"` diterjemahkan?
+
+Anda pada akhirnya harus "berjuang" dengan compiler, menambahkan komentar khusus (seperti `// ignore-translation`) untuk mencegahnya merusak logika aplikasi Anda.
+
+### 2. Batas Keras Data Dinamis
+
+Ekstraksi compiler bergantung pada **analisis statis**. Compiler harus melihat string literal dalam kode Anda untuk menghasilkan ID yang stabil.
+Jika API Anda mengembalikan string kode error seperti `server_error`, Anda tidak bisa menerjemahkannya dengan compiler karena compiler tidak mengetahui string tersebut ada saat build time. Anda terpaksa membangun sistem "runtime-only" sekunder hanya untuk data dinamis.
+
+### 3. "Ledakan Chunk" dan Air Terjun Jaringan
+
+Untuk memungkinkan tree-shaking, alat compiler sering membagi terjemahan per komponen.
+
+- **Konsekuensinya:** Satu tampilan halaman dengan 50 komponen kecil mungkin memicu **50 permintaan HTTP terpisah** untuk fragmen terjemahan kecil. Bahkan dengan HTTP/2, ini menciptakan waterfall jaringan yang membuat aplikasi Anda terasa lambat dibandingkan memuat satu bundel bahasa yang dioptimalkan.
+
+### 4. Beban Kinerja Runtime
+
+Untuk membuat terjemahan bersifat reaktif (sehingga mereka langsung diperbarui saat Anda mengganti bahasa), compiler sering menyuntikkan hooks manajemen state ke _setiap_ komponen.
+
+- **Biayanya:** Jika Anda merender daftar dengan 5.000 item, Anda menginisialisasi 5.000 hook `useState` dan `useEffect` hanya untuk teks. Ini menghabiskan memori dan siklus CPU yang sebenarnya bisa dihemat oleh pustaka deklaratif (yang biasanya menggunakan satu penyedia Context).
+
+## Perangkap: Vendor Lock-in
+
+Ini mungkin aspek paling berbahaya dari i18n berbasis compiler.
+
+Dalam pustaka deklaratif, kode sumber Anda mengandung maksud yang eksplisit. Anda memiliki kunci-kuncinya. Jika Anda mengganti pustaka, Anda hanya perlu mengubah impor.
+
+Dalam pendekatan berbasis compiler, **kode sumber Anda hanyalah teks bahasa Inggris.** "Logika terjemahan" hanya ada di dalam konfigurasi plugin build.
+Jika perpustakaan itu berhenti dipelihara, atau jika Anda merasa sudah tidak cocok lagi, Anda akan terjebak. Anda tidak bisa dengan mudah "eject" karena Anda tidak memiliki kunci terjemahan sama sekali di kode sumber Anda. Anda harus menulis ulang seluruh aplikasi secara manual untuk bermigrasi.
+
+## Sisi Lain: Risiko dari Pendekatan Deklaratif
+
+Untuk adilnya, cara deklaratif tradisional juga tidak sempurna. Ia memiliki serangkaian "jebakan" tersendiri.
+
+1.  **Namespace Hell:** Anda sering harus mengelola secara manual file JSON mana yang akan dimuat (`common.json`, `dashboard.json`, `footer.json`). Jika Anda lupa satu, pengguna akan melihat kunci mentah.
+2.  **Over-fetching:** Tanpa konfigurasi yang hati-hati, sangat mudah secara tidak sengaja memuat _semua_ kunci terjemahan Anda untuk _semua_ halaman pada pemuatan awal, yang membuat ukuran bundle membengkak.
+3.  **Sync Drift:** Umum terjadi kunci tetap ada di file JSON jauh setelah komponen yang menggunakannya dihapus. File terjemahan Anda tumbuh tanpa batas, dipenuhi dengan "kunci zombie."
+
+## Jalan Tengah Intlayer
+
+Di sinilah alat seperti **Intlayer** mencoba berinovasi. Intlayer memahami bahwa meskipun compiler itu kuat, sihir implisit itu berbahaya.
+
+Intlayer menawarkan **perintah `transform`** yang unik. Alih-alih hanya melakukan sihir di langkah build tersembunyi, ia sebenarnya dapat **menulis ulang kode komponen Anda**. Ia memindai teks Anda dan menggantinya dengan deklarasi konten eksplisit di dalam codebase Anda.
+
+Ini memberi Anda yang terbaik dari kedua dunia:
+
+1.  **Granularitas:** Anda menjaga terjemahan tetap dekat dengan komponen Anda (meningkatkan modularitas dan tree-shaking).
+2.  **Keamanan:** Terjemahan menjadi kode eksplisit, bukan sihir tersembunyi saat build-time.
+3.  **Tanpa Lock-in:** Karena kode diubah menjadi struktur deklaratif standar dalam repo Anda, Anda tidak menyembunyikan logika dalam plugin webpack.
+
+## Kesimpulan
+
+Jadi, mana yang harus Anda pilih?
+
+**Jika Anda seorang Junior Developer, Solo Founder, atau sedang membangun MVP:**
+Pendekatan berbasis compiler adalah pilihan yang valid. Ini memungkinkan Anda bergerak sangat cepat. Anda tidak perlu khawatir tentang struktur file atau kunci. Anda hanya membangun. Hutang teknis adalah masalah untuk "Anda di Masa Depan."
+
+**Jika Anda membangun Aplikasi Profesional, Tingkat Enterprise:**
+Sihir umumnya adalah ide buruk. Anda membutuhkan kontrol.
+
+- Anda perlu menangani data dinamis dari backend.
+- Anda perlu memastikan performa pada perangkat kelas bawah (menghindari ledakan hook).
+- Anda perlu memastikan Anda tidak terkunci pada alat build tertentu selamanya.
+
+Untuk aplikasi profesional, **Manajemen Konten Deklaratif** (seperti Intlayer atau pustaka yang sudah mapan) tetap menjadi standar emas. Ini memisahkan kekhawatiran Anda, menjaga arsitektur Anda tetap bersih, dan memastikan kemampuan aplikasi Anda untuk berbicara dalam berbagai bahasa tidak bergantung pada compiler "kotak hitam" yang menebak niat Anda.

package/blog/id/intlayer_with_next-i18next.md

@@ -176,7 +176,6 @@ Kecualikan file yang dihasilkan dari kontrol versi:
 ```plaintext fileName=".gitignore"
 # Abaikan file yang dihasilkan oleh Intlayer
 .intlayer
-intl
 ```
 
 File-file ini secara otomatis dihasilkan ulang selama proses build dan tidak perlu dikomit ke repositori Anda.

package/blog/id/intlayer_with_vue-i18n.md

@@ -166,7 +166,6 @@ Kecualikan file yang dihasilkan dari kontrol versi:
 ```plaintext fileName=".gitignore"
 # Abaikan file yang dihasilkan oleh Intlayer
 .intlayer
-intl
 ```
 
 File-file ini secara otomatis dibuat ulang selama proses build dan tidak perlu dikomit ke repositori Anda.

package/blog/it/compiler_vs_declarative_i18n.md

@@ -0,0 +1,138 @@
+---
+createdAt: 2025-11-24
+updatedAt: 2025-11-24
+title: Compilatore vs. i18n Dichiarativo
+description: Esplorazione dei compromessi architetturali tra l'internazionalizzazione "magica" basata su compilatore e la gestione esplicita e dichiarativa dei contenuti.
+keywords:
+  - Intlayer
+  - Internazionalizzazione
+  - Blog
+  - Next.js
+  - JavaScript
+  - React
+  - i18n
+  - Compilatore
+  - Dichiarativo
+slugs:
+  - compiler-vs-declarative-i18n
+  - blog
+  - i18n
+---
+
+# Argomenti a favore e contro l'i18n basata su compilatore
+
+Se sviluppi applicazioni web da più di un decennio, sai che l'Internazionalizzazione (i18n) è sempre stata un punto critico. Spesso è il compito che nessuno vuole fare: estrarre stringhe, gestire file JSON e preoccuparsi delle regole di pluralizzazione.
+
+Recentemente, è emersa una nuova ondata di strumenti i18n "basati su compilatore", promettendo di far sparire questo fastidio. Il messaggio è seducente: **Basta scrivere il testo nei tuoi componenti e lasciare che lo strumento di build gestisca il resto.** Niente chiavi, niente importazioni, solo magia.
+
+Ma come per tutte le astrazioni nell'ingegneria del software, la magia ha un prezzo.
+
+In questo post del blog, esploreremo il passaggio dalle librerie dichiarative agli approcci basati su compilatore, i debiti architetturali nascosti che introducono e perché il modo "noioso" potrebbe ancora essere il migliore per applicazioni professionali.
+
+## Una breve storia della traduzione
+
+Per capire dove siamo, dobbiamo guardare indietro a dove siamo partiti.
+
+Intorno al 2011–2012, il panorama JavaScript era molto diverso. I bundler come li conosciamo oggi (Webpack, Vite) non esistevano o erano alle prime armi. Incollavamo gli script direttamente nel browser. In quell'epoca nacquero librerie come **i18next**.
+
+Risolvevano il problema nel modo unico possibile all'epoca: **Dizionari a runtime**. Caricavi un enorme oggetto JSON in memoria, e una funzione cercava le chiavi al volo. Era affidabile, esplicito e funzionava ovunque.
+
+Avanzando fino a oggi, abbiamo potenti compilatori (SWC, bundler basati su Rust) che possono analizzare Abstract Syntax Trees (AST) in millisecondi. Questa potenza ha dato vita a una nuova idea: _Perché gestiamo manualmente le chiavi? Perché il compilatore non può semplicemente vedere il testo "Hello World" e sostituirlo per noi?_
+
+Così è nato l'i18n basato su compilatore.
+
+## Il Fascino del Compilatore (L'Approccio "Magico")
+
+C'è un motivo per cui questo nuovo approccio è di tendenza. Per uno sviluppatore, l'esperienza è incredibile.
+
+### 1. Velocità e "Flow"
+
+Quando sei nel flusso, fermarti a pensare a un nome di variabile (`home_hero_title_v2`) interrompe il tuo flusso. Con un approccio basato sul compilatore, digiti `<p>Welcome back</p>` e continui. L'attrito è zero.
+
+### 2. La Missione di Salvataggio del Legacy
+
+Immagina di ereditare una codebase enorme con 5.000 componenti e zero traduzioni. Retrofitare questo con un sistema manuale basato su chiavi è un incubo che dura mesi. Uno strumento basato su compilatore agisce come una strategia di salvataggio, estraendo istantaneamente migliaia di stringhe senza che tu debba toccare manualmente un singolo file.
+
+### 3. L'Era dell'AI
+
+Questo è un vantaggio moderno che non dovremmo trascurare. Gli assistenti di codifica AI (come Copilot o ChatGPT) generano naturalmente JSX/HTML standard. Non conoscono il tuo schema specifico di chiavi di traduzione.
+
+- **Dichiarativo:** Devi riscrivere l'output dell'AI per sostituire il testo con le chiavi.
+- **Compilatore:** Copi e incolli il codice dell'AI, e funziona semplicemente.
+
+## Il Controllo della Realtà: Perché la "Magia" è Pericolosa
+
+Sebbene la "magia" sia attraente, l'astrazione perde colpi. Affidarsi a uno strumento di build per comprendere l'intento umano introduce fragilità architetturali.
+
+### 1. Fragilità Euristica (Il Gioco delle Ipotesi)
+
+Il compilatore deve indovinare cosa è contenuto e cosa è codice.
+
+- `className="active"` viene tradotto? È una stringa.
+- `status="pending"` viene tradotto?
+- `<MyComponent errorMessage="An error occurred" />` viene tradotto?
+- Un ID prodotto come `"AX-99"` viene tradotto?
+
+Inevitabilmente finisci per "combattere" con il compilatore, aggiungendo commenti specifici (come `// ignore-translation`) per evitare che rompa la logica della tua applicazione.
+
+### 2. Il Limite Rigido dei Dati Dinamici
+
+L'estrazione del compilatore si basa sull'**analisi statica**. Deve vedere la stringa letterale nel tuo codice per generare un ID stabile.
+Se la tua API restituisce una stringa di codice errore come `server_error`, non puoi tradurla con un compilatore perché il compilatore non conosce quella stringa al momento della build. Sei costretto a costruire un sistema secondario "solo a runtime" solo per i dati dinamici.
+
+### 3. "Esplosione di Chunk" e Cascate di Rete
+
+Per consentire il tree-shaking, gli strumenti del compilatore spesso suddividono le traduzioni per componente.
+
+- **La conseguenza:** Una singola visualizzazione di pagina con 50 piccoli componenti potrebbe generare **50 richieste HTTP separate** per minuscoli frammenti di traduzione. Anche con HTTP/2, questo crea un effetto "network waterfall" che rende la tua applicazione lenta rispetto al caricamento di un singolo bundle linguistico ottimizzato.
+
+### 4. Sovraccarico delle Prestazioni a Runtime
+
+Per rendere le traduzioni reattive (in modo che si aggiornino istantaneamente quando cambi lingua), il compilatore spesso inietta hook di gestione dello stato in _ogni_ componente.
+
+- **Il costo:** Se renderizzi una lista di 5.000 elementi, stai inizializzando 5.000 hook `useState` e `useEffect` solo per il testo. Questo consuma memoria e cicli CPU che le librerie dichiarative (che tipicamente usano un singolo provider Context) risparmiano.
+
+## La trappola: Vendor Lock-in
+
+Questo è probabilmente l'aspetto più pericoloso dell'i18n basato su compilatori.
+
+In una libreria dichiarativa, il tuo codice sorgente contiene un intento esplicito. Possiedi le chiavi. Se cambi libreria, devi solo modificare l'import.
+
+In un approccio basato su compilatori, **il tuo codice sorgente è solo testo in inglese.** La "logica di traduzione" esiste solo all'interno della configurazione del plugin di build.
+Se quella libreria smette di essere mantenuta, o se la superi, rimani bloccato. Non puoi "espellere" facilmente perché non hai chiavi di traduzione nel tuo codice sorgente. Dovresti riscrivere manualmente l'intera applicazione per migrare.
+
+## L'altro lato: rischi dell'approccio dichiarativo
+
+Per essere onesti, il modo dichiarativo tradizionale non è perfetto nemmeno. Ha i suoi "tranelli".
+
+1.  **Inferno dei namespace:** Spesso devi gestire manualmente quali file JSON caricare (`common.json`, `dashboard.json`, `footer.json`). Se ne dimentichi uno, l'utente vede le chiavi raw.
+2.  **Over-fetching:** Senza una configurazione attenta, è molto facile caricare accidentalmente _tutte_ le tue chiavi di traduzione per _tutte_ le pagine al caricamento iniziale, gonfiando la dimensione del bundle.
+3.  **Deriva di sincronizzazione:** È comune che le chiavi rimangano nel file JSON molto tempo dopo che il componente che le utilizzava è stato eliminato. I tuoi file di traduzione crescono indefinitamente, pieni di "chiavi zombie".
+
+## La via di mezzo di Intlayer
+
+È qui che strumenti come **Intlayer** cercano di innovare. Intlayer comprende che, sebbene i compilatori siano potenti, la magia implicita è pericolosa.
+
+Intlayer offre un comando unico **`transform`**. Invece di fare solo magia nel passaggio di build nascosto, può effettivamente **riscrivere il codice del tuo componente**. Scansiona il tuo testo e lo sostituisce con dichiarazioni di contenuto esplicite nel tuo codebase.
+
+Questo ti offre il meglio di entrambi i mondi:
+
+1.  **Granularità:** Mantieni le tue traduzioni vicine ai tuoi componenti (migliorando modularità e tree-shaking).
+2.  **Sicurezza:** La traduzione diventa codice esplicito, non una magia nascosta al momento della build.
+3.  **Nessun Lock-in:** Poiché il codice viene trasformato in una struttura dichiarativa standard all'interno del tuo repository, non stai nascondendo la logica in un plugin di webpack.
+
+## Conclusione
+
+Quindi, quale dovresti scegliere?
+
+**Se sei uno Sviluppatore Junior, un Fondatore Solitario o stai costruendo un MVP:**
+L'approccio basato sul compilatore è una scelta valida. Ti permette di muoverti incredibilmente velocemente. Non devi preoccuparti delle strutture dei file o delle chiavi. Devi solo costruire. Il debito tecnico è un problema per il "Te Futuro".
+
+**Se stai costruendo un'Applicazione Professionale di livello Enterprise:**
+La magia è generalmente una cattiva idea. Hai bisogno di controllo.
+
+- Devi gestire dati dinamici provenienti dai backend.
+- Devi garantire le prestazioni su dispositivi di fascia bassa (evitando esplosioni di hook).
+- Devi assicurarti di non rimanere vincolato per sempre a uno specifico strumento di build.
+
+Per le applicazioni professionali, la **Gestione Contenuti Dichiarativa** (come Intlayer o librerie consolidate) rimane lo standard d'eccellenza. Essa separa le tue preoccupazioni, mantiene pulita l'architettura e garantisce che la capacità della tua applicazione di supportare più lingue non dipenda da un compilatore "scatola nera" che indovina le tue intenzioni.

package/blog/it/intlayer_with_next-i18next.md

@@ -176,7 +176,6 @@ Escludi i file generati dal controllo di versione:
 ```plaintext fileName=".gitignore"
 # Ignora i file generati da Intlayer
 .intlayer
-intl
 ```
 
 Questi file vengono rigenerati automaticamente durante il processo di build e non devono essere aggiunti al tuo repository.

package/blog/it/intlayer_with_vue-i18n.md

@@ -166,7 +166,6 @@ Escludi i file generati dal controllo di versione:
 ```plaintext fileName=".gitignore"
 # Ignora i file generati da Intlayer
 .intlayer
-intl
 ```
 
 Questi file vengono rigenerati automaticamente durante il processo di build e non devono essere aggiunti al tuo repository.

package/blog/ja/compiler_vs_declarative_i18n.md

@@ -0,0 +1,138 @@
+---
+createdAt: 2025-11-24
+updatedAt: 2025-11-24
+title: コンパイラー型 vs 宣言型 i18n
+description: 「マジック」なコンパイラー型国際化と明示的な宣言型コンテンツ管理のアーキテクチャ上のトレードオフを探る。
+keywords:
+  - Intlayer
+  - 国際化
+  - ブログ
+  - Next.js
+  - JavaScript
+  - React
+  - i18n
+  - コンパイラー
+  - 宣言型
+slugs:
+  - compiler-vs-declarative-i18n
+  - blog
+  - i18n
+---
+
+# コンパイラー型i18nの賛否
+
+もし10年以上ウェブアプリケーションを開発してきたなら、国際化（i18n）が常に摩擦点であったことをご存知でしょう。文字列の抽出、JSONファイルの管理、複数形ルールの扱いなど、誰もやりたがらない作業であることが多いのです。
+
+最近、「コンパイラー型」i18nツールの新しい波が登場し、この苦痛を解消すると約束しています。魅力的な提案はこうです：**コンポーネント内にテキストを書くだけで、ビルドツールが残りを処理してくれる。** キーもインポートも不要、ただのマジックです。
+
+しかし、ソフトウェア工学におけるすべての抽象化と同様に、マジックには代償が伴います。
+
+このブログ記事では、宣言型ライブラリからコンパイラー型アプローチへの移行、彼らがもたらす隠れたアーキテクチャ的負債、そしてなぜ「退屈な」方法がプロフェッショナルなアプリケーションにとって依然として最良の方法であるかを探ります。
+
+## 翻訳の簡単な歴史
+
+今の状況を理解するためには、出発点を振り返る必要があります。
+
+2011年から2012年頃、JavaScriptの状況は大きく異なっていました。現在私たちが知っているようなバンドラー（WebpackやVite）は存在しなかったか、まだ初期段階にありました。ブラウザ上でスクリプトをつなぎ合わせていた時代です。この時代に、**i18next**のようなライブラリが誕生しました。
+
+彼らは当時可能な唯一の方法で問題を解決しました：**ランタイム辞書**です。巨大なJSONオブジェクトをメモリに読み込み、関数がその場でキーを検索する仕組みでした。これは信頼性が高く、明示的で、どこでも動作しました。
+
+そして現在に至ります。私たちはミリ秒単位で抽象構文木（AST）を解析できる強力なコンパイラ（SWCやRustベースのバンドラー）を持っています。この力が新しいアイデアを生み出しました：_なぜ私たちは手動でキーを管理しているのか？なぜコンパイラが「Hello World」というテキストを見て、それを置き換えてくれないのか？_
+
+こうして、コンパイラベースのi18nが誕生しました。
+
+## コンパイラの魅力（「マジック」アプローチ）
+
+この新しいアプローチがトレンドになっている理由があります。開発者にとって、その体験は驚くべきものです。
+
+### 1. スピードと「フロー」
+
+集中しているときに、変数名（`home_hero_title_v2`）を考えるために立ち止まると、フローが途切れてしまいます。コンパイラアプローチでは、`<p>Welcome back</p>` とタイプしてそのまま進めます。摩擦はゼロです。
+
+### 2. レガシー救出ミッション
+
+5,000のコンポーネントがある巨大なコードベースを引き継ぎ、翻訳が一切ないと想像してください。手動のキー管理システムでこれを後付けするのは数ヶ月に及ぶ悪夢です。コンパイラベースのツールは救出戦略として機能し、手動でファイルに触れることなく数千の文字列を瞬時に抽出します。
+
+### 3. AI時代
+
+これは見逃せない現代的な利点です。AIコーディングアシスタント（CopilotやChatGPTのようなもの）は、標準的なJSX/HTMLを自然に生成します。彼らはあなたの特定の翻訳キーのスキーマを知りません。
+
+- **宣言的（Declarative）:** AIの出力をテキストからキーに置き換えるために書き直す必要があります。
+- **コンパイラ（Compiler）:** AIのコードをコピー＆ペーストするだけで、そのまま動作します。
+
+## 現実の確認：なぜ「マジック」は危険なのか
+
+「マジック」は魅力的ですが、その抽象化は漏れが生じます。ビルドツールに人間の意図を理解させることに依存すると、アーキテクチャの脆弱性が生まれます。
+
+### 1. ヒューリスティックの脆弱性（推測ゲーム）
+
+コンパイラは何がコンテンツで何がコードかを推測しなければなりません。
+
+- `className="active"` は翻訳されますか？これは文字列です。
+- `status="pending"` は翻訳されますか？
+- `<MyComponent errorMessage="An error occurred" />` は翻訳されますか？
+- `"AX-99"` のような製品IDは翻訳されますか？
+
+最終的には、コンパイラと「戦う」ことになり、アプリケーションのロジックを壊さないように特定のコメント（例：`// ignore-translation`）を追加することになります。
+
+### 2. 動的データのハードリミット
+
+コンパイラの抽出は**静的解析**に依存しています。安定したIDを生成するためには、コード内にリテラル文字列が存在している必要があります。  
+もしAPIが `server_error` のようなエラーコード文字列を返す場合、コンパイラはビルド時にその文字列の存在を認識できないため、翻訳できません。動的データ用に「ランタイム専用」の二次的なシステムを構築せざるを得ません。
+
+### 3. 「チャンク爆発」とネットワークウォーターフォール
+
+ツリーシェイキングを可能にするために、コンパイラツールはしばしばコンポーネントごとに翻訳を分割します。
+
+- **結果:** 50個の小さなコンポーネントがある単一のページビューで、**50回の別々のHTTPリクエスト**が小さな翻訳断片に対して発生する可能性があります。HTTP/2を使用していても、これはネットワークのウォーターフォールを生み出し、単一の最適化された言語バンドルを読み込む場合と比べて、アプリケーションの動作が遅く感じられます。
+
+### 4. ランタイムのパフォーマンスオーバーヘッド
+
+翻訳をリアクティブに（言語を切り替えたときに即座に更新されるように）するために、コンパイラはしばしば*すべての*コンポーネントに状態管理フックを注入します。
+
+- **コスト:** もし5,000件のアイテムのリストをレンダリングすると、テキストのためだけに5,000個の `useState` と `useEffect` フックを初期化することになります。これは、宣言的ライブラリ（通常は単一のContextプロバイダーを使用）が節約するメモリとCPUサイクルを消費します。
+
+## トラップ：ベンダーロックイン
+
+これはおそらく、コンパイラベースのi18nで最も危険な側面です。
+
+宣言的ライブラリでは、ソースコードに明確な意図が含まれています。キーはあなたが所有しています。ライブラリを切り替える場合は、インポートを変更するだけです。
+
+コンパイラベースのアプローチでは、**ソースコードは単なる英語のテキストです。** 「翻訳ロジック」はビルドプラグインの設定内にのみ存在します。
+もしそのライブラリのメンテナンスが停止したり、ライブラリの機能を超えてしまった場合、あなたは行き詰まります。ソースコードに翻訳キーが一切存在しないため、「イジェクト」することは簡単ではありません。移行するには、アプリケーション全体を手動で書き直す必要があります。
+
+## もう一方の側面：宣言的アプローチのリスク
+
+公平を期すために言うと、従来の宣言的な方法も完璧ではありません。独自の「落とし穴」が存在します。
+
+1.  **ネームスペース地獄:** どのJSONファイルを読み込むか（`common.json`、`dashboard.json`、`footer.json`など）を手動で管理する必要がよくあります。もし一つでも忘れると、ユーザーは生のキーを目にすることになります。
+2.  **過剰フェッチ:** 注意深く設定しないと、初回ロード時にすべてのページのすべての翻訳キーを誤って読み込んでしまい、バンドルサイズが膨れ上がることが非常に簡単に起こります。
+3.  **同期のズレ（Sync Drift）：** コンポーネントが削除された後も、そのコンポーネントで使われていたキーがJSONファイルに残り続けることがよくあります。翻訳ファイルは無限に増え続け、「ゾンビキー」で溢れてしまいます。
+
+## Intlayerの中間的アプローチ
+
+ここで、**Intlayer**のようなツールが革新を試みています。Intlayerは、コンパイラが強力である一方で、暗黙のマジックは危険であることを理解しています。
+
+Intlayerは独自の**`transform`コマンド**を提供します。隠れたビルドステップで単にマジックを行うのではなく、実際に**コンポーネントのコードを書き換える**ことができます。テキストをスキャンし、コードベース内で明示的なコンテンツ宣言に置き換えます。
+
+これにより、両方の利点を得られます：
+
+1.  **粒度（Granularity）：** 翻訳をコンポーネントの近くに保持できるため（モジュール性とツリーシェイキングが向上します）。
+2.  **安全性:** 翻訳は隠れたビルド時のマジックではなく、明示的なコードになります。
+3.  **ロックインなし:** コードがリポジトリ内で標準的な宣言的構造に変換されるため、webpackプラグイン内にロジックを隠すことはありません。
+
+## 結論
+
+では、どちらを選ぶべきでしょうか？
+
+**もしあなたがジュニア開発者、ソロ創業者、またはMVPを構築している場合：**  
+コンパイラベースのアプローチは有効な選択肢です。非常に速く開発を進めることができます。ファイル構造やキーについて心配する必要はありません。ただビルドすれば良いのです。技術的負債は「未来のあなた」の問題です。
+
+**もしあなたがプロフェッショナルなエンタープライズグレードのアプリケーションを構築している場合：**  
+マジックは一般的に悪い考えです。コントロールが必要です。
+
+- バックエンドからの動的データを扱う必要があります。
+- 低スペックデバイスでのパフォーマンスを確保する必要があります（フックの爆発を避けるため）。
+- 特定のビルドツールに永遠にロックインされないようにする必要があります。
+
+プロフェッショナルなアプリケーションの場合、**宣言的コンテンツ管理**（Intlayerや確立されたライブラリのようなもの）が依然としてゴールドスタンダードです。これにより関心事が分離され、アーキテクチャがクリーンに保たれ、アプリケーションが複数言語を扱う能力が「ブラックボックス」コンパイラの推測に依存しないことが保証されます。

package/blog/ja/intlayer_with_next-i18next.md

@@ -176,7 +176,6 @@ export default config;
 ```plaintext fileName=".gitignore"
 # Intlayerによって生成されたファイルを無視する
 .intlayer
-intl
 ```
 
 これらのファイルはビルドプロセス中に自動的に再生成されるため、リポジトリにコミットする必要はありません。

package/blog/ja/intlayer_with_vue-i18n.md

@@ -166,7 +166,6 @@ export default config;
 ```plaintext fileName=".gitignore"
 # Intlayer によって生成されたファイルを無視する
 .intlayer
-intl
 ```
 
 これらのファイルはビルドプロセス中に自動的に再生成されるため、リポジトリにコミットする必要はありません。

package/blog/ko/compiler_vs_declarative_i18n.md

@@ -0,0 +1,138 @@
+---
+createdAt: 2025-11-24
+updatedAt: 2025-11-24
+title: 컴파일러 기반 i18n 대 선언적 i18n
+description: "매직" 컴파일러 기반 국제화와 명시적 선언적 콘텐츠 관리 간의 아키텍처적 트레이드오프 탐구.
+keywords:
+  - Intlayer
+  - 국제화
+  - 블로그
+  - Next.js
+  - JavaScript
+  - React
+  - i18n
+  - 컴파일러
+  - 선언적
+slugs:
+  - compiler-vs-declarative-i18n
+  - blog
+  - i18n
+---
+
+# 컴파일러 기반 i18n에 대한 찬반 논쟁
+
+10년 이상 웹 애플리케이션을 개발해왔다면, 국제화(i18n)가 항상 마찰 지점이었음을 알 것입니다. 문자열 추출, JSON 파일 관리, 복수형 규칙 처리 등 아무도 하고 싶어 하지 않는 작업인 경우가 많습니다.
+
+최근에 "컴파일러 기반" i18n 도구의 새로운 물결이 등장하여 이 고통을 사라지게 하겠다고 약속하고 있습니다. 그 제안은 매력적입니다: **컴포넌트에 텍스트만 작성하면 빌드 도구가 나머지를 처리해줍니다.** 키도, 임포트도 없이, 그저 마법처럼요.
+
+하지만 소프트웨어 공학의 모든 추상화가 그렇듯, 마법에는 대가가 따릅니다.
+
+이 블로그 글에서는 선언적 라이브러리에서 컴파일러 기반 접근법으로의 전환, 그들이 도입하는 숨겨진 아키텍처 부채, 그리고 왜 "지루한" 방식이 여전히 전문 애플리케이션에 가장 좋은 방법일 수 있는지 탐구할 것입니다.
+
+## 번역의 간략한 역사
+
+우리가 현재 어디에 있는지 이해하려면, 우리가 어디서 시작했는지 돌아봐야 합니다.
+
+2011년에서 2012년경, JavaScript 환경은 지금과 매우 달랐습니다. 우리가 알고 있는 번들러들(Webpack, Vite)은 존재하지 않았거나 초기 단계에 불과했습니다. 우리는 브라우저에서 스크립트를 붙여서 사용하고 있었습니다. 이 시기에 **i18next**와 같은 라이브러리가 탄생했습니다.
+
+이들은 당시 가능한 유일한 방법으로 문제를 해결했습니다: **런타임 사전(Runtime Dictionaries)**. 거대한 JSON 객체를 메모리에 로드하고, 함수가 실행 중에 키를 찾아내는 방식이었습니다. 이는 신뢰할 수 있고 명확하며 어디서나 작동했습니다.
+
+오늘날로 빠르게 넘어가 보면, 우리는 밀리초 단위로 추상 구문 트리(AST)를 파싱할 수 있는 강력한 컴파일러들(SWC, Rust 기반 번들러)을 갖추고 있습니다. 이 강력한 기술은 새로운 아이디어를 탄생시켰습니다: _왜 우리가 수동으로 키를 관리해야 할까? 컴파일러가 "Hello World"라는 텍스트를 보고 바로 교체해주면 안 될까?_
+
+이렇게 해서 컴파일러 기반 i18n이 탄생했습니다.
+
+## 컴파일러의 매력 (일명 "마법" 접근법)
+
+이 새로운 접근법이 유행하는 데는 이유가 있습니다. 개발자 입장에서 경험이 놀랍도록 좋기 때문입니다.
+
+### 1. 속도와 "흐름"
+
+작업에 몰입해 있을 때 변수 이름(`home_hero_title_v2`)을 생각하느라 멈추면 흐름이 끊깁니다. 컴파일러 접근법에서는 `<p>Welcome back</p>`를 입력하고 계속 진행할 수 있습니다. 마찰이 전혀 없습니다.
+
+### 2. 레거시 구조 구출 작전
+
+5,000개의 컴포넌트가 있지만 번역이 전혀 없는 거대한 코드베이스를 상속받았다고 상상해 보세요. 수동 키 기반 시스템으로 이를 개조하는 것은 몇 달이 걸리는 악몽 같은 작업입니다. 컴파일러 기반 도구는 구출 전략으로 작동하여, 단 한 파일도 수동으로 건드리지 않고 수천 개의 문자열을 즉시 추출합니다.
+
+### 3. AI 시대
+
+이것은 우리가 간과해서는 안 될 현대적인 이점입니다. AI 코딩 어시스턴트(예: Copilot 또는 ChatGPT)는 자연스럽게 표준 JSX/HTML을 생성합니다. 이들은 여러분의 특정 번역 키 스키마를 알지 못합니다.
+
+- **선언적 방식(Declarative):** AI의 출력을 텍스트에서 키로 교체하기 위해 다시 작성해야 합니다.
+- **컴파일러 방식(Compiler):** AI의 코드를 복사-붙여넣기만 하면 바로 작동합니다.
+
+## 현실 점검: 왜 "마법"이 위험한가
+
+"마법"은 매력적이지만, 추상화가 새어나갑니다. 빌드 도구가 인간의 의도를 이해하도록 의존하는 것은 아키텍처적 취약성을 초래합니다.
+
+### 1. 휴리스틱 취약성 (추측 게임)
+
+컴파일러는 무엇이 콘텐츠이고 무엇이 코드인지 추측해야 합니다.
+
+- `className="active"`는 번역되나요? 이것은 문자열입니다.
+- `status="pending"`는 번역되나요?
+- `<MyComponent errorMessage="An error occurred" />`가 번역되나요?
+- `"AX-99"`와 같은 제품 ID가 번역되나요?
+
+결국 컴파일러와 "싸우게" 되며, 애플리케이션 로직이 깨지지 않도록 특정 주석(예: `// ignore-translation`)을 추가하게 됩니다.
+
+### 2. 동적 데이터의 한계
+
+컴파일러 추출은 **정적 분석**에 의존합니다. 안정적인 ID를 생성하려면 코드 내에 리터럴 문자열이 보여야 합니다.
+API가 `server_error`와 같은 에러 코드 문자열을 반환하면, 컴파일러가 빌드 시점에 해당 문자열이 존재하는지 알지 못하기 때문에 번역할 수 없습니다. 동적 데이터 전용의 별도 "런타임 전용" 시스템을 구축해야만 합니다.
+
+### 3. "청크 폭발"과 네트워크 워터폴
+
+트리 쉐이킹을 허용하기 위해, 컴파일러 도구는 종종 컴포넌트별로 번역을 분할합니다.
+
+- **결과:** 50개의 작은 컴포넌트가 있는 단일 페이지 뷰는 작은 번역 조각에 대해 **50개의 별도 HTTP 요청**을 발생시킬 수 있습니다. HTTP/2를 사용하더라도, 이는 네트워크 워터폴을 생성하여 단일 최적화된 언어 번들을 로드하는 것보다 애플리케이션이 느리게 느껴지게 만듭니다.
+
+### 4. 런타임 성능 오버헤드
+
+번역을 반응형으로 만들어(언어를 전환할 때 즉시 업데이트되도록) 컴파일러는 종종 _모든_ 컴포넌트에 상태 관리 훅을 주입합니다.
+
+- **비용:** 5,000개의 아이템 리스트를 렌더링하면, 텍스트를 위해 5,000개의 `useState`와 `useEffect` 훅을 초기화하게 됩니다. 이는 선언형 라이브러리(일반적으로 단일 Context 프로바이더를 사용하는)가 절약하는 메모리와 CPU 사이클을 낭비하는 셈입니다.
+
+## 함정: 공급업체 종속성 (Vendor Lock-in)
+
+이는 컴파일러 기반 i18n에서 가장 위험한 측면이라고 할 수 있습니다.
+
+선언형 라이브러리에서는 소스 코드에 명확한 의도가 포함되어 있습니다. 키를 직접 소유합니다. 라이브러리를 변경할 때는 단순히 import만 바꾸면 됩니다.
+
+컴파일러 기반 접근법에서는 **소스 코드가 단지 영어 텍스트일 뿐입니다.** "번역 로직"은 빌드 플러그인의 설정 안에만 존재합니다.
+만약 그 라이브러리가 더 이상 유지되지 않거나, 사용자가 그 라이브러리를 벗어나고 싶어도, 당신은 꼼짝할 수 없습니다. 소스 코드에 번역 키가 전혀 없기 때문에 쉽게 "eject"할 수 없습니다. 마이그레이션을 위해 애플리케이션 전체를 수동으로 다시 작성해야 할 것입니다.
+
+## 다른 측면: 선언적 접근 방식의 위험
+
+공정하게 말하면, 전통적인 선언적 방식도 완벽하지 않습니다. 자체적인 "함정"이 존재합니다.
+
+1.  **네임스페이스 지옥:** 어떤 JSON 파일을 로드할지 (`common.json`, `dashboard.json`, `footer.json`) 수동으로 관리해야 하는 경우가 많습니다. 하나라도 잊으면 사용자는 원시 키를 보게 됩니다.
+2.  **과도한 페칭:** 신중한 설정 없이 초기 로드 시 모든 페이지의 모든 번역 키를 실수로 불러와 번들 크기가 불필요하게 커질 수 있습니다.
+3.  **동기화 이탈(Sync Drift):** 컴포넌트가 삭제된 후에도 해당 키가 JSON 파일에 남아 있는 경우가 흔합니다. 이로 인해 번역 파일이 무한히 커지며 "좀비 키"로 가득 차게 됩니다.
+
+## Intlayer의 중간 지점
+
+이것이 바로 **Intlayer**와 같은 도구들이 혁신을 시도하는 부분입니다. Intlayer는 컴파일러가 강력하지만, 암묵적인 마법은 위험하다는 점을 이해합니다.
+
+Intlayer는 독특한 **`transform` 명령어**를 제공합니다. 숨겨진 빌드 단계에서 마법처럼 처리하는 대신, 실제로 **컴포넌트 코드를 재작성**할 수 있습니다. 텍스트를 스캔하여 코드베이스 내에서 명시적인 콘텐츠 선언으로 대체합니다.
+
+이로써 두 세계의 장점을 모두 누릴 수 있습니다:
+
+1.  **세분성(Granularity):** 번역을 컴포넌트 가까이에 유지하여 모듈화와 트리 쉐이킹(tree-shaking)을 개선합니다.
+2.  **안전성:** 번역이 숨겨진 빌드 타임 마법이 아니라 명시적인 코드가 됩니다.
+3.  **락인 방지:** 코드가 리포지토리 내에서 표준 선언적 구조로 변환되기 때문에 webpack 플러그인에 로직을 숨기지 않습니다.
+
+## 결론
+
+그렇다면 어떤 방식을 선택해야 할까요?
+
+**당신이 주니어 개발자이거나, 1인 창업자이거나, MVP를 만들고 있다면:**
+컴파일러 기반 접근법도 유효한 선택입니다. 매우 빠르게 개발할 수 있습니다. 파일 구조나 키에 대해 걱정할 필요가 없습니다. 그냥 개발하면 됩니다. 기술 부채는 "미래의 당신"이 해결할 문제입니다.
+
+**당신이 전문적이고 엔터프라이즈급 애플리케이션을 개발 중이라면:**
+마법 같은 접근법은 일반적으로 좋지 않습니다. 제어가 필요합니다.
+
+- 백엔드에서 오는 동적 데이터를 처리해야 합니다.
+- 저사양 기기에서의 성능을 보장해야 합니다 (hook 폭발 방지).
+- 특정 빌드 도구에 영원히 종속되지 않도록 해야 합니다.
+
+전문적인 애플리케이션의 경우, **선언적 콘텐츠 관리**(Intlayer나 검증된 라이브러리와 같은)는 여전히 최고의 표준입니다. 이는 관심사를 분리하고 아키텍처를 깔끔하게 유지하며, 애플리케이션이 여러 언어를 지원하는 능력이 "블랙박스" 컴파일러가 의도를 추측하는 것에 의존하지 않도록 보장합니다.