@intlayer/docs 7.2.3 → 7.3.0-canary.0

package/blog/ko/intlayer_with_next-i18next.md

@@ -176,7 +176,6 @@ export default config;
 ```plaintext fileName=".gitignore"
 # Intlayer에서 생성된 파일 무시
 .intlayer
-intl
 ```
 
 이 파일들은 빌드 과정에서 자동으로 다시 생성되므로 저장소에 커밋할 필요가 없습니다.

package/blog/ko/intlayer_with_vue-i18n.md

@@ -166,7 +166,6 @@ export default config;
 ```plaintext fileName=".gitignore"
 # Intlayer에서 생성된 파일 무시
 .intlayer
-intl
 ```
 
 이 파일들은 빌드 과정에서 자동으로 다시 생성되므로 저장소에 커밋할 필요가 없습니다.

package/blog/pl/compiler_vs_declarative_i18n.md

@@ -0,0 +1,138 @@
+---
+createdAt: 2025-11-24
+updatedAt: 2025-11-24
+title: Kompilator kontra deklaratywne i18n
+description: Eksploracja kompromisów architektonicznych między "magiczna" internacjonalizacją opartą na kompilatorze a explicytnym, deklaratywnym zarządzaniem treścią.
+keywords:
+  - Intlayer
+  - Internacjonalizacja
+  - Blog
+  - Next.js
+  - JavaScript
+  - React
+  - i18n
+  - Kompilator
+  - Deklaratywne
+slugs:
+  - compiler-vs-declarative-i18n
+  - blog
+  - i18n
+---
+
+# Argumenty za i przeciw internacjonalizacji opartej na kompilatorze
+
+Jeśli tworzysz aplikacje webowe od ponad dekady, wiesz, że internacjonalizacja (i18n) zawsze była punktem zapalnym. Często jest to zadanie, którego nikt nie chce wykonywać — wyciąganie stringów, zarządzanie plikami JSON i martwienie się o zasady pluralizacji.
+
+Ostatnio pojawiła się nowa fala narzędzi i18n opartych na "kompilatorze", obiecujących, że ta uciążliwość zniknie. Przekaz jest kuszący: **Po prostu pisz tekst w swoich komponentach, a narzędzie budujące zajmie się resztą.** Bez kluczy, bez importów, po prostu magia.
+
+Ale jak to bywa ze wszystkimi abstrakcjami w inżynierii oprogramowania, magia ma swoją cenę.
+
+W tym wpisie na blogu przyjrzymy się przejściu od bibliotek deklaratywnych do podejść opartych na kompilatorze, ukrytym długom architektonicznym, które one wprowadzają, oraz dlaczego "nudny" sposób może nadal być najlepszym rozwiązaniem dla profesjonalnych aplikacji.
+
+## Krótka historia tłumaczeń
+
+Aby zrozumieć, gdzie jesteśmy, musimy spojrzeć wstecz, skąd zaczęliśmy.
+
+Około 2011–2012 krajobraz JavaScript wyglądał zupełnie inaczej. Bundlery takie jak znamy je dziś (Webpack, Vite) nie istniały lub były we wczesnym stadium rozwoju. Sklejaliśmy skrypty bezpośrednio w przeglądarce. W tym okresie powstały biblioteki takie jak **i18next**.
+
+Rozwiązały one problem w jedyny możliwy wtedy sposób: **Słowniki w czasie wykonywania (Runtime Dictionaries)**. Ładowało się ogromny obiekt JSON do pamięci, a funkcja wyszukiwała klucze na bieżąco. Było to niezawodne, jawne i działało wszędzie.
+
+Przenieśmy się do dziś. Mamy potężne kompilatory (SWC, bundlery oparte na Rust), które potrafią analizować Abstrakcyjne Drzewa Składniowe (AST) w ciągu milisekund. Ta moc dała początek nowemu pomysłowi: _Dlaczego ręcznie zarządzamy kluczami? Dlaczego kompilator nie może po prostu zobaczyć tekstu "Hello World" i zamienić go za nas?_
+
+Tak narodziło się i18n oparte na kompilatorze.
+
+## Urok Kompilatora (Podejście „Magiczne”)
+
+Istnieje powód, dla którego to nowe podejście zyskuje na popularności. Dla dewelopera doświadczenie jest niesamowite.
+
+### 1. Szybkość i „Flow”
+
+Kiedy jesteś w strefie, zatrzymanie się, by wymyślić nazwę zmiennej (`home_hero_title_v2`), przerywa twój flow. Przy podejściu kompilatorowym wpisujesz `<p>Welcome back</p>` i idziesz dalej. Tarcie jest zerowe.
+
+### 2. Misja Ratunkowa dla Dziedzictwa
+
+Wyobraź sobie, że dziedziczysz ogromną bazę kodu z 5000 komponentów i zerowymi tłumaczeniami. Dopasowanie tego do ręcznego systemu opartego na kluczach to koszmar trwający miesiące. Narzędzie oparte na kompilatorze działa jako strategia ratunkowa, natychmiast wyciągając tysiące stringów bez konieczności ręcznego dotykania choćby jednego pliku.
+
+### 3. Era AI
+
+To nowoczesna korzyść, której nie powinniśmy pomijać. Asystenci kodowania AI (tacy jak Copilot czy ChatGPT) naturalnie generują standardowy JSX/HTML. Nie znają twojego specyficznego schematu kluczy tłumaczeń.
+
+- **Deklaratywne:** Musisz przepisać wynik AI, aby zastąpić tekst kluczami.
+- **Kompilator:** Kopiujesz i wklejasz kod AI i po prostu działa.
+
+## Sprawdzenie Rzeczywistości: Dlaczego „Magia” jest Niebezpieczna
+
+Chociaż „magia” jest kusząca, abstrakcja przecieka. Poleganie na narzędziu budującym, które ma rozumieć intencje człowieka, wprowadza architektoniczną kruchość.
+
+### 1. Kruchość Heurystyczna (Gra w Zgadywanie)
+
+Kompilator musi zgadnąć, co jest treścią, a co kodem.
+
+- Czy `className="active"` jest tłumaczone? To jest string.
+- Czy `status="pending"` jest tłumaczone?
+- Czy `<MyComponent errorMessage="An error occurred" />` jest tłumaczone?
+- Czy identyfikator produktu taki jak `"AX-99"` jest tłumaczony?
+
+Nieuchronnie kończysz na „walce” z kompilatorem, dodając specyficzne komentarze (np. `// ignore-translation`), aby zapobiec złamaniu logiki twojej aplikacji.
+
+### 2. Twardy Limit Danych Dynamicznych
+
+Ekstrakcja przez kompilator opiera się na **analizie statycznej**. Musi zobaczyć dosłowny ciąg znaków w twoim kodzie, aby wygenerować stabilny identyfikator.
+Jeśli twoje API zwraca kod błędu w postaci ciągu znaków, np. `server_error`, nie możesz go przetłumaczyć za pomocą kompilatora, ponieważ kompilator nie wie o istnieniu tego ciągu w czasie budowania. Jesteś zmuszony do stworzenia drugiego systemu działającego tylko w czasie wykonywania, przeznaczonego wyłącznie dla danych dynamicznych.
+
+### 3. „Eksplozja Fragmentów” i Kaskady Sieciowe
+
+Aby umożliwić tree-shaking, narzędzia kompilatora często dzielą tłumaczenia na poszczególne komponenty.
+
+- **Konsekwencja:** Pojedyncze wyświetlenie strony z 50 małymi komponentami może wywołać **50 oddzielnych żądań HTTP** dla drobnych fragmentów tłumaczeń. Nawet przy HTTP/2 tworzy to efekt wodospadu sieciowego, który sprawia, że Twoja aplikacja działa wolniej w porównaniu do załadowania pojedynczego, zoptymalizowanego pakietu językowego.
+
+### 4. Obciążenie wydajności w czasie wykonywania
+
+Aby tłumaczenia były reaktywne (tak, aby aktualizowały się natychmiast po zmianie języka), kompilator często wstrzykuje hooki zarządzania stanem do _każdego_ komponentu.
+
+- **Koszt:** Jeśli renderujesz listę 5 000 elementów, inicjujesz 5 000 hooków `useState` i `useEffect` wyłącznie dla tekstu. Zużywa to pamięć i cykle CPU, które biblioteki deklaratywne (zazwyczaj używające pojedynczego dostawcy Context) oszczędzają.
+
+## Pułapka: Vendor Lock-in
+
+To prawdopodobnie najniebezpieczniejszy aspekt i18n opartego na kompilatorze.
+
+W bibliotece deklaratywnej Twój kod źródłowy zawiera wyraźny zamiar. Posiadasz klucze. Jeśli zmienisz bibliotekę, wystarczy, że zmienisz import.
+
+W podejściu opartym na kompilatorze, **Twój kod źródłowy to tylko tekst w języku angielskim.** „Logika tłumaczenia” istnieje tylko w konfiguracji wtyczki build.
+Jeśli ta biblioteka przestanie być utrzymywana lub jeśli ją przerosniesz, utkniesz. Nie możesz łatwo „wyjść” z niej, ponieważ nie masz żadnych kluczy tłumaczeń w swoim kodzie źródłowym. Musiałbyś ręcznie przepisać całą aplikację, aby przejść na inne rozwiązanie.
+
+## Druga strona medalu: Ryzyka podejścia deklaratywnego
+
+Aby być sprawiedliwym, tradycyjny sposób deklaratywny też nie jest idealny. Ma swoje własne „pułapki”.
+
+1.  **Piekło przestrzeni nazw:** Często musisz ręcznie zarządzać, które pliki JSON załadować (`common.json`, `dashboard.json`, `footer.json`). Jeśli zapomnisz o jednym, użytkownik zobaczy surowe klucze.
+2.  **Nadmierne pobieranie:** Bez ostrożnej konfiguracji bardzo łatwo jest przypadkowo załadować _wszystkie_ klucze tłumaczeń dla _wszystkich_ stron podczas początkowego ładowania, co powoduje nadmierne powiększenie rozmiaru paczki.
+3.  **Sync Drift:** Często zdarza się, że klucze pozostają w pliku JSON długo po usunięciu komponentu, który ich używał. Twoje pliki tłumaczeń rosną w nieskończoność, wypełnione „zombie kluczami”.
+
+## Środkowa Droga Intlayer
+
+To właśnie tutaj narzędzia takie jak **Intlayer** próbują wprowadzać innowacje. Intlayer rozumie, że chociaż kompilatory są potężne, to ukryta magia jest niebezpieczna.
+
+Intlayer oferuje unikalne polecenie **`transform`**. Zamiast po prostu wykonywać magię w ukrytym kroku budowania, może faktycznie **przepisać kod twojego komponentu**. Skanuje twój tekst i zastępuje go jawnie zadeklarowaną zawartością w twojej bazie kodu.
+
+Daje to najlepsze z obu światów:
+
+1.  **Szczegółowość:** Trzymasz tłumaczenia blisko swoich komponentów (poprawiając modularność i tree-shaking).
+2.  **Bezpieczeństwo:** Tłumaczenie staje się jawnie zapisanym kodem, a nie ukrytą magią podczas kompilacji.
+3.  **Brak uzależnienia:** Ponieważ kod jest przekształcany do standardowej, deklaratywnej struktury w Twoim repozytorium, nie ukrywasz logiki w wtyczce webpack.
+
+## Podsumowanie
+
+Więc, którą opcję powinieneś wybrać?
+
+**Jeśli jesteś Junior Developerem, Samodzielnym Założycielem lub tworzysz MVP:**
+Podejście oparte na kompilatorze jest dobrym wyborem. Pozwala Ci działać niesamowicie szybko. Nie musisz martwić się strukturą plików ani kluczami. Po prostu budujesz. Dług techniczny to problem dla „Przyszłego Ciebie”.
+
+**Jeśli tworzysz profesjonalną aplikację klasy enterprise:**
+Magia zazwyczaj jest złym pomysłem. Potrzebujesz kontroli.
+
+- Musisz obsługiwać dynamiczne dane z backendów.
+- Musisz zapewnić wydajność na urządzeniach o niskich parametrach (unikając eksplozji hooków).
+- Musisz upewnić się, że nie jesteś na stałe związany z konkretnym narzędziem do budowania.
+
+W przypadku profesjonalnych aplikacji, **Deklaratywne Zarządzanie Treścią** (takie jak Intlayer lub uznane biblioteki) pozostaje złotym standardem. Oddziela Twoje obszary odpowiedzialności, utrzymuje czystą architekturę i zapewnia, że zdolność Twojej aplikacji do obsługi wielu języków nie zależy od „czarnej skrzynki” kompilatora, która zgaduje Twoje intencje.

package/blog/pl/intlayer_with_next-i18next.md

@@ -187,7 +187,6 @@ Wyklucz generowane pliki z kontroli wersji:
 ```plaintext fileName=".gitignore"
 # Ignoruj pliki generowane przez Intlayer
 .intlayer
-intl
 ```
 
 Te pliki są automatycznie generowane podczas procesu budowania i nie muszą być zatwierdzane do Twojego repozytorium.

package/blog/pl/intlayer_with_vue-i18n.md

@@ -166,7 +166,6 @@ Wyklucz generowane pliki z kontroli wersji:
 ```plaintext fileName=".gitignore"
 # Ignoruj pliki generowane przez Intlayer
 .intlayer
-intl
 ```
 
 Te pliki są automatycznie generowane podczas procesu budowania i nie muszą być zatwierdzane do Twojego repozytorium.

package/blog/pt/compiler_vs_declarative_i18n.md

@@ -0,0 +1,138 @@
+---
+createdAt: 2025-11-24
+updatedAt: 2025-11-24
+title: Compilador vs. i18n Declarativo
+description: Explorando as trocas arquitetônicas entre a internacionalização "mágica" baseada em compilador e o gerenciamento explícito de conteúdo declarativo.
+keywords:
+  - Intlayer
+  - Internacionalização
+  - Blog
+  - Next.js
+  - JavaScript
+  - React
+  - i18n
+  - Compilador
+  - Declarativo
+slugs:
+  - compiler-vs-declarative-i18n
+  - blog
+  - i18n
+---
+
+# O Caso a Favor e Contra a i18n Baseada em Compilador
+
+Se você tem construído aplicações web por mais de uma década, sabe que a Internacionalização (i18n) sempre foi um ponto de atrito. Frequentemente é a tarefa que ninguém quer fazer — extrair strings, gerenciar arquivos JSON e se preocupar com regras de pluralização.
+
+Recentemente, uma nova onda de ferramentas de i18n "baseadas em compilador" surgiu, prometendo fazer essa dor desaparecer. A proposta é sedutora: **Basta escrever o texto nos seus componentes e deixar a ferramenta de build cuidar do resto.** Sem chaves, sem imports, apenas magia.
+
+Mas, como em todas as abstrações na engenharia de software, magia tem um preço.
+
+Neste post do blog, exploraremos a mudança das bibliotecas declarativas para abordagens baseadas em compilador, as dívidas arquitetônicas ocultas que elas introduzem e por que o jeito "chato" pode ainda ser o melhor para aplicações profissionais.
+
+## Uma Breve História da Tradução
+
+Para entender onde estamos, precisamos olhar para onde começamos.
+
+Por volta de 2011–2012, o cenário do JavaScript era muito diferente. Bundlers como os conhecemos hoje (Webpack, Vite) não existiam ou estavam em sua infância. Estávamos juntando scripts diretamente no navegador. Nessa época, bibliotecas como **i18next** nasceram.
+
+Elas resolveram o problema da única forma possível na época: **Dicionários em tempo de execução**. Você carregava um enorme objeto JSON na memória, e uma função buscava as chaves dinamicamente. Era confiável, explícito e funcionava em qualquer lugar.
+
+Avançando para hoje. Temos compiladores poderosos (SWC, bundlers baseados em Rust) que conseguem analisar Árvores de Sintaxe Abstrata (AST) em milissegundos. Esse poder deu origem a uma nova ideia: _Por que gerenciar chaves manualmente? Por que o compilador não pode simplesmente ver o texto "Hello World" e substituí-lo para nós?_
+
+Assim, nasceu o i18n baseado em compilador.
+
+## O Encanto do Compilador (A Abordagem "Mágica")
+
+Há uma razão pela qual essa nova abordagem está em alta. Para um desenvolvedor, a experiência é incrível.
+
+### 1. Velocidade e "Flow"
+
+Quando você está concentrado, parar para pensar em um nome de variável (`home_hero_title_v2`) quebra seu fluxo. Com a abordagem do compilador, você digita `<p>Welcome back</p>` e continua. O atrito é zero.
+
+### 2. A Missão de Resgate do Legado
+
+Imagine herdar uma base de código enorme com 5.000 componentes e zero traduções. Adaptar isso para um sistema manual baseado em chaves é um pesadelo que dura meses. Uma ferramenta baseada em compilador atua como uma estratégia de resgate, extraindo instantaneamente milhares de strings sem que você precise tocar manualmente em um único arquivo.
+
+### 3. A Era da IA
+
+Este é um benefício moderno que não devemos ignorar. Assistentes de codificação com IA (como Copilot ou ChatGPT) geram naturalmente JSX/HTML padrão. Eles não conhecem seu esquema específico de chaves de tradução.
+
+- **Declarativo:** Você precisa reescrever a saída da IA para substituir o texto por chaves.
+- **Compilador:** Você copia e cola o código da IA, e ele simplesmente funciona.
+
+## A Verificação da Realidade: Por que a "Magia" é Perigosa
+
+Embora a "magia" seja atraente, a abstração apresenta vazamentos. Confiar em uma ferramenta de build para entender a intenção humana introduz fragilidade arquitetural.
+
+### 1. Fragilidade Heurística (O Jogo de Adivinhação)
+
+O compilador precisa adivinhar o que é conteúdo e o que é código.
+
+- `className="active"` é traduzido? É uma string.
+- `status="pending"` é traduzido?
+- O `<MyComponent errorMessage="An error occurred" />` é traduzido?
+- Um ID de produto como `"AX-99"` é traduzido?
+
+Inevitavelmente, você acaba "lutando" contra o compilador, adicionando comentários específicos (como `// ignore-translation`) para evitar que ele quebre a lógica da sua aplicação.
+
+### 2. O Limite Rígido dos Dados Dinâmicos
+
+A extração pelo compilador depende de **análise estática**. Ele precisa ver a string literal no seu código para gerar um ID estável.
+Se sua API retorna uma string de código de erro como `server_error`, você não pode traduzi-la com um compilador porque ele não sabe que essa string existe em tempo de build. Você é forçado a construir um sistema secundário "apenas em tempo de execução" só para dados dinâmicos.
+
+### 3. "Explosão de Chunks" e Cascatas de Rede
+
+Para permitir tree-shaking, as ferramentas de compilação frequentemente dividem as traduções por componente.
+
+- **A Consequência:** Uma única visualização de página com 50 pequenos componentes pode disparar **50 requisições HTTP separadas** para pequenos fragmentos de tradução. Mesmo com HTTP/2, isso cria um efeito cascata na rede que faz sua aplicação parecer lenta em comparação ao carregamento de um único pacote de idioma otimizado.
+
+### 4. Sobrecarga de Performance em Tempo de Execução
+
+Para tornar as traduções reativas (para que atualizem instantaneamente quando você troca de idioma), o compilador frequentemente injeta hooks de gerenciamento de estado em _cada_ componente.
+
+- **O Custo:** Se você renderizar uma lista de 5.000 itens, estará inicializando 5.000 hooks `useState` e `useEffect` apenas para texto. Isso consome memória e ciclos de CPU que bibliotecas declarativas (que normalmente usam um único provedor Context) economizam.
+
+## A Armadilha: Vendor Lock-in
+
+Este é, sem dúvida, o aspecto mais perigoso da i18n baseada em compilador.
+
+Em uma biblioteca declarativa, seu código-fonte contém a intenção explícita. Você possui as chaves. Se trocar de biblioteca, basta alterar a importação.
+
+Em uma abordagem baseada em compilador, **seu código-fonte é apenas texto em inglês.** A "lógica de tradução" existe apenas dentro da configuração do plugin de build.
+Se essa biblioteca deixar de ser mantida, ou se você ultrapassar suas limitações, ficará preso. Você não pode "ejetar" facilmente porque não há nenhuma chave de tradução no seu código-fonte. Você teria que reescrever manualmente toda a sua aplicação para migrar para outra solução.
+
+## O Outro Lado: Riscos da Abordagem Declarativa
+
+Para ser justo, a forma tradicional declarativa também não é perfeita. Ela tem seu próprio conjunto de "armadilhas".
+
+1.  **Inferno dos Namespaces:** Frequentemente, você precisa gerenciar manualmente quais arquivos JSON carregar (`common.json`, `dashboard.json`, `footer.json`). Se esquecer algum, o usuário verá as chaves brutas.
+2.  **Carregamento Excessivo:** Sem uma configuração cuidadosa, é muito fácil carregar acidentalmente _todas_ as suas chaves de tradução para _todas_ as páginas no carregamento inicial, inchando o tamanho do seu bundle.
+3.  **Descompasso de Sincronização:** É comum que chaves permaneçam no arquivo JSON muito tempo depois do componente que as utiliza ter sido deletado. Seus arquivos de tradução crescem indefinidamente, cheios de "chaves zumbi".
+
+## O Meio-Termo do Intlayer
+
+É aqui que ferramentas como o **Intlayer** estão tentando inovar. O Intlayer entende que, embora compiladores sejam poderosos, magia implícita é perigosa.
+
+O Intlayer oferece um comando único chamado **`transform`**. Em vez de apenas fazer mágica na etapa oculta de build, ele pode realmente **reescrever o código do seu componente**. Ele escaneia seu texto e o substitui por declarações explícitas de conteúdo na sua base de código.
+
+Isso lhe dá o melhor dos dois mundos:
+
+1.  **Granularidade:** Você mantém suas traduções próximas aos seus componentes (melhorando modularidade e tree-shaking).
+2.  **Segurança:** A tradução torna-se código explícito, não uma mágica oculta em tempo de build.
+3.  **Sem Aprisionamento:** Como o código é transformado em uma estrutura declarativa padrão dentro do seu repositório, você não está escondendo lógica em um plugin do webpack.
+
+## Conclusão
+
+Então, qual você deve escolher?
+
+**Se você é um Desenvolvedor Júnior, um Fundador Solo ou está construindo um MVP:**
+A abordagem baseada em compilador é uma escolha válida. Ela permite que você avance incrivelmente rápido. Você não precisa se preocupar com estruturas de arquivos ou chaves. Você simplesmente constrói. A dívida técnica é um problema para o "Você do Futuro".
+
+**Se você está construindo uma Aplicação Profissional, de Nível Empresarial:**
+Mágica geralmente é uma má ideia. Você precisa de controle.
+
+- Você precisa lidar com dados dinâmicos provenientes de backends.
+- Você precisa garantir desempenho em dispositivos de baixo custo (evitando explosões de hooks).
+- Você precisa garantir que não fique preso a uma ferramenta de build específica para sempre.
+
+Para aplicativos profissionais, **Gerenciamento Declarativo de Conteúdo** (como Intlayer ou bibliotecas consolidadas) continua sendo o padrão ouro. Ele separa suas preocupações, mantém sua arquitetura limpa e garante que a capacidade do seu aplicativo de falar múltiplos idiomas não dependa de um compilador "caixa preta" tentando adivinhar suas intenções.

package/blog/pt/intlayer_with_next-i18next.md

@@ -176,7 +176,6 @@ Exclua arquivos gerados do controle de versão:
 ```plaintext fileName=".gitignore"
 # Ignorar arquivos gerados pelo Intlayer
 .intlayer
-intl
 ```
 
 Esses arquivos são automaticamente regenerados durante o processo de build e não precisam ser commitados no seu repositório.

package/blog/pt/intlayer_with_vue-i18n.md

@@ -166,7 +166,6 @@ Exclua arquivos gerados do controle de versão:
 ```plaintext fileName=".gitignore"
 # Ignorar arquivos gerados pelo Intlayer
 .intlayer
-intl
 ```
 
 Esses arquivos são automaticamente regenerados durante o processo de build e não precisam ser comitados no seu repositório.

package/blog/ru/compiler_vs_declarative_i18n.md

@@ -0,0 +1,138 @@
+---
+createdAt: 2025-11-24
+updatedAt: 2025-11-24
+title: Компилятор против декларативного i18n
+description: Исследование архитектурных компромиссов между «магической» интернационализацией на основе компилятора и явным декларативным управлением контентом.
+keywords:
+  - Intlayer
+  - Интернационализация
+  - Блог
+  - Next.js
+  - JavaScript
+  - React
+  - i18n
+  - Компилятор
+  - Декларативный
+slugs:
+  - compiler-vs-declarative-i18n
+  - blog
+  - i18n
+---
+
+# Аргументы за и против интернационализации на основе компилятора
+
+Если вы разрабатываете веб-приложения более десяти лет, вы знаете, что интернационализация (i18n) всегда была источником сложностей. Это часто та задача, которую никто не хочет выполнять — извлечение строк, управление JSON-файлами и заботы о правилах множественного числа.
+
+В последнее время появилась новая волна инструментов i18n на основе «компилятора», обещающих избавить от этих проблем. Обещание звучит заманчиво: **Просто пишите текст в своих компонентах, а остальное пусть сделает инструмент сборки.** Без ключей, без импортов, просто магия.
+
+Но, как и во всех абстракциях в программной инженерии, магия имеет свою цену.
+
+В этом блоге мы рассмотрим переход от декларативных библиотек к подходам на основе компилятора, скрытые архитектурные долги, которые они вносят, и почему «скучный» способ может оставаться лучшим для профессиональных приложений.
+
+## Краткая история перевода
+
+Чтобы понять, где мы сейчас, нужно оглянуться назад и вспомнить, с чего мы начинали.
+
+Около 2011–2012 годов ландшафт JavaScript был кардинально другим. Такие бандлеры, как мы их знаем сегодня (Webpack, Vite), либо не существовали, либо только зарождались. Мы склеивали скрипты прямо в браузере. В эту эпоху появились библиотеки, такие как **i18next**.
+
+Они решили проблему единственным возможным на тот момент способом: **словарями во время выполнения**. Вы загружали огромный JSON-объект в память, и функция искала ключи на лету. Это было надежно, явно и работало везде.
+
+Перенесемся в настоящее. У нас есть мощные компиляторы (SWC, бандлеры на базе Rust), которые могут парсить абстрактные синтаксические деревья (AST) за миллисекунды. Эта мощь породила новую идею: _Зачем нам вручную управлять ключами? Почему компилятор просто не видит текст "Hello World" и не заменит его за нас?_
+
+Так родился 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. Жесткое ограничение динамических данных
+
+Извлечение компилятором основано на **статическом анализе**. Он должен видеть буквальную строку в вашем коде, чтобы сгенерировать стабильный ID.
+Если ваш API возвращает строку с кодом ошибки, например `server_error`, вы не сможете перевести её с помощью компилятора, потому что компилятор не знает о существовании этой строки во время сборки. Вам придется создавать вторичную систему "только во время выполнения" специально для динамических данных.
+
+### 3. "Взрыв чанков" и сетевые водопады
+
+Для поддержки tree-shaking инструменты компилятора часто разбивают переводы по компонентам.
+
+- **Последствие:** Один просмотр страницы с 50 небольшими компонентами может вызвать **50 отдельных HTTP-запросов** для маленьких фрагментов перевода. Даже с HTTP/2 это создает сетевой "водопад", из-за которого ваше приложение кажется медленным по сравнению с загрузкой одного оптимизированного языкового пакета.
+
+### 4. Нагрузка на производительность во время выполнения
+
+Чтобы сделать переводы реактивными (чтобы они обновлялись мгновенно при переключении языков), компилятор часто внедряет хуки управления состоянием в _каждый_ компонент.
+
+- **Стоимость:** Если вы рендерите список из 5000 элементов, вы инициализируете 5000 хуков `useState` и `useEffect` исключительно для текста. Это потребляет память и ресурсы процессора, которые декларативные библиотеки (которые обычно используют один провайдер Context) экономят.
+
+## Ловушка: Зависимость от поставщика
+
+Это, пожалуй, самый опасный аспект i18n на основе компилятора.
+
+В декларативной библиотеке ваш исходный код содержит явное намерение. Вы владеете ключами. Если вы меняете библиотеку, вы просто меняете импорт.
+
+В подходе на основе компилятора **ваш исходный код — это просто английский текст.** "Логика перевода" существует только внутри конфигурации плагина сборки.
+Если эта библиотека перестанет поддерживаться или вы перерастёте её, вы окажетесь в ловушке. Вы не сможете легко "выйти" из неё, потому что в вашем исходном коде нет ни одного ключа перевода. Вам придётся вручную переписать всё приложение, чтобы мигрировать на другую систему.
+
+## Другая сторона: риски декларативного подхода
+
+Честно говоря, традиционный декларативный способ тоже не идеален. У него есть свои "подводные камни".
+
+1.  **Ад namespace:** Часто приходится вручную управлять тем, какие JSON-файлы загружать (`common.json`, `dashboard.json`, `footer.json`). Если вы забудете один из них, пользователь увидит необработанные ключи.
+2.  **Перезагрузка:** Без тщательной настройки очень легко случайно загрузить _все_ ключи перевода для _всех_ страниц при первоначальной загрузке, что увеличивает размер вашего бандла.
+3.  **Синхронизационный дрейф:** Часто ключи остаются в JSON-файле задолго после того, как компонент, использующий их, был удалён. Ваши файлы перевода растут бесконечно, заполненные "зомби-ключами".
+
+## Средний путь Intlayer
+
+Именно здесь такие инструменты, как **Intlayer**, пытаются внести инновации. Intlayer понимает, что хотя компиляторы мощные, неявная магия опасна.
+
+Intlayer предлагает уникальную команду **`transform`**. Вместо того чтобы просто делать магию на скрытом этапе сборки, она фактически может **переписать ваш код компонента**. Она сканирует ваш текст и заменяет его явными декларациями контента в вашей кодовой базе.
+
+Это даёт вам лучшее из обоих миров:
+
+1.  **Гранулярность:** Вы держите переводы рядом с вашими компонентами (улучшая модульность и tree-shaking).
+2.  **Безопасность:** Перевод становится явным кодом, а не скрытой магией на этапе сборки.
+3.  **Отсутствие зависимости:** Поскольку код преобразуется в стандартную декларативную структуру внутри вашего репозитория, вы не скрываете логику в плагине webpack.
+
+## Заключение
+
+Итак, что же выбрать?
+
+**Если вы начинающий разработчик, соло-фаундер или создаёте MVP:**
+Подход на основе компилятора — это приемлемый выбор. Он позволяет двигаться невероятно быстро. Вам не нужно беспокоиться о структуре файлов или ключах. Вы просто создаёте. Технический долг — это проблема "будущего вас".
+
+**Если вы создаёте профессиональное корпоративное приложение:**
+Магия обычно — плохая идея. Вам нужен контроль.
+
+- Вам нужно обрабатывать динамические данные с бэкендов.
+- Вам нужно обеспечить производительность на устройствах с низкими характеристиками (избегая взрывов хуков).
+- Вам нужно гарантировать, что вы не будете навсегда привязаны к конкретному инструменту сборки.
+
+Для профессиональных приложений **Декларативное управление контентом** (например, Intlayer или проверенные библиотеки) остается золотым стандартом. Оно разделяет ваши задачи, сохраняет архитектуру чистой и гарантирует, что способность вашего приложения поддерживать несколько языков не зависит от "черного ящика" компилятора, который пытается угадать ваши намерения.

package/blog/ru/intlayer_with_next-i18next.md

@@ -176,7 +176,6 @@ export default config;
 ```plaintext fileName=".gitignore"
 # Игнорировать файлы, сгенерированные Intlayer
 .intlayer
-intl
 ```
 
 Эти файлы автоматически пересоздаются во время процесса сборки и не требуют коммита в ваш репозиторий.

package/blog/ru/intlayer_with_vue-i18n.md

@@ -166,7 +166,6 @@ export default config;
 ```plaintext fileName=".gitignore"
 # Игнорировать файлы, сгенерированные Intlayer
 .intlayer
-intl
 ```
 
 Эти файлы автоматически пересоздаются в процессе сборки и не требуют добавления в ваш репозиторий.

package/blog/tr/compiler_vs_declarative_i18n.md

@@ -0,0 +1,138 @@
+---
+createdAt: 2025-11-24
+updatedAt: 2025-11-24
+title: Derleyici Tabanlı ve Deklaratif i18n Karşılaştırması
+description: "Sihirli" derleyici tabanlı uluslararasılaştırma ile açık deklaratif içerik yönetimi arasındaki mimari ödünleşimleri keşfetmek.
+keywords:
+  - Intlayer
+  - Uluslararasılaştırma
+  - Blog
+  - Next.js
+  - JavaScript
+  - React
+  - i18n
+  - Derleyici
+  - Deklaratif
+slugs:
+  - compiler-vs-declarative-i18n
+  - blog
+  - i18n
+---
+
+# Derleyici Tabanlı i18n İçin ve Karşı Argümanlar
+
+On yıldan fazla süredir web uygulamaları geliştiriyorsanız, Uluslararasılaştırmanın (i18n) her zaman bir zorluk noktası olduğunu bilirsiniz. Genellikle kimsenin yapmak istemediği bir görevdir—metinleri çıkarmak, JSON dosyalarını yönetmek ve çoğul ek kurallarıyla uğraşmak.
+
+Son zamanlarda, bu acıyı ortadan kaldırmayı vaat eden yeni bir "Derleyici tabanlı" i18n araç dalgası ortaya çıktı. Teklif cazip: **Sadece bileşenlerinizde metni yazın, gerisini derleme aracı halletsin.** Anahtar yok, import yok, sadece sihir.
+
+Ancak yazılım mühendisliğindeki tüm soyutlamalarda olduğu gibi, sihrin de bir bedeli vardır.
+
+Bu blog yazısında, deklaratif kütüphanelerden derleyici tabanlı yaklaşımlara geçişi, getirdikleri gizli mimari borçları ve neden "sıkıcı" yolun profesyonel uygulamalar için hala en iyi yol olabileceğini inceleyeceğiz.
+
+## Çevirinin Kısa Tarihi
+
+Nerede olduğumuzu anlamak için, başladığımız yere bakmamız gerekiyor.
+
+2011–2012 yıllarında, JavaScript dünyası oldukça farklıydı. Bildiğimiz bundlerlar (Webpack, Vite) ya yoktu ya da çok erken aşamalardaydı. Tarayıcıda scriptleri birbirine yapıştırıyorduk. Bu dönemde, **i18next** gibi kütüphaneler doğdu.
+
+O zamanlar problemi çözmenin tek yolu vardı: **Çalışma Zamanı Sözlükleri**. Büyük bir JSON nesnesini belleğe yüklüyordunuz ve bir fonksiyon anahtarları anında arıyordu. Bu yöntem güvenilir, açık ve her yerde çalışıyordu.
+
+Bugüne hızlıca gelirsek. Milisaniyeler içinde Abstract Syntax Tree (AST) çözümleyebilen güçlü derleyicilerimiz var (SWC, Rust tabanlı bundlerlar). Bu güç yeni bir fikrin doğmasına yol açtı: _Neden anahtarları manuel olarak yönetiyoruz? Derleyici neden "Hello World" metnini görüp bizim için değiştirmesin?_
+
+Böylece, Derleyici tabanlı i18n doğdu.
+
+## Derleyicinin Cazibesi ("Sihirli" Yaklaşım)
+
+Bu yeni yaklaşımın popüler olmasının bir nedeni var. Bir geliştirici için deneyim inanılmazdır.
+
+### 1. Hız ve "Akış"
+
+İşin içindeyken, bir değişken adı (`home_hero_title_v2`) düşünmek için durmak akışınızı bozar. Derleyici yaklaşımıyla, `<p>Welcome back</p>` yazarsınız ve devam edersiniz. Sürtünme sıfırdır.
+
+### 2. Miras Kurtarma Görevi
+
+5.000 bileşenli ve hiç çevirisi olmayan devasa bir kod tabanını devraldığınızı hayal edin. Bunu manuel anahtar tabanlı bir sistemle sonradan uyarlamak aylar süren bir kabus olur. Derleyici tabanlı bir araç, tek bir dosyaya elle dokunmanıza gerek kalmadan binlerce metni anında çıkaran bir kurtarma stratejisi olarak görev yapar.
+
+### 3. Yapay Zeka Çağı
+
+Bu, göz ardı etmememiz gereken modern bir avantajdır. AI kodlama asistanları (Copilot veya ChatGPT gibi) doğal olarak standart JSX/HTML üretir. Özel çeviri anahtarı şemanızı bilmezler.
+
+- **Deklaratif:** AI'nın çıktısını, metni anahtarlarla değiştirmek için yeniden yazmanız gerekir.
+- **Derleyici:** AI'nın kodunu kopyalayıp yapıştırırsınız ve sadece çalışır.
+
+## Gerçeklik Kontrolü: Neden "Sihir" Tehlikelidir
+
+"Sihir" çekici olsa da, soyutlama sızar. İnsan niyetini anlaması için bir derleme aracına güvenmek mimari kırılganlık getirir.
+
+### 1. Sezgisel Kırılganlık (Tahmin Oyunu)
+
+Derleyici, içeriğin ne olduğunu ve kodun ne olduğunu tahmin etmek zorundadır.
+
+- `className="active"` çevrilir mi? Bu bir string.
+- `status="pending"` çevrilir mi?
+- `<MyComponent errorMessage="An error occurred" />` çevrilir mi?
+- `"AX-99"` gibi bir ürün kimliği çevrilir mi?
+
+Sonuç olarak, derleyiciyle "mücadele" etmek zorunda kalırsınız ve uygulama mantığınızı bozmasını önlemek için `// ignore-translation` gibi özel yorumlar eklersiniz.
+
+### 2. Dinamik Veri Sert Sınırı
+
+Derleyici çıkarımı **statik analiz**e dayanır. Kararlı bir ID oluşturmak için kodunuzda literal stringi görmesi gerekir.
+API'niz `server_error` gibi bir hata kodu stringi dönerse, derleyici bunu derleme zamanında bilmediği için çeviremezsiniz. Dinamik veriler için yalnızca çalışma zamanı "runtime-only" ikinci bir sistem kurmak zorunda kalırsınız.
+
+### 3. "Parça Patlaması" ve Ağ Şelaleleri
+
+Ağaç sarsma (tree-shaking) için, derleyici araçları genellikle çevirileri bileşen bazında böler.
+
+- **Sonuç:** 50 küçük bileşene sahip tek bir sayfa görüntülemesi, küçük çeviri parçaları için **50 ayrı HTTP isteği** tetikleyebilir. HTTP/2 olsa bile, bu durum tek, optimize edilmiş bir dil paketi yüklemeye kıyasla uygulamanızın yavaş hissetmesine neden olan bir ağ şelalesi oluşturur.
+
+### 4. Çalışma Zamanı Performans Yükü
+
+Çevirilerin reaktif olmasını sağlamak (yani dil değiştirdiğinizde anında güncellenmesi için), derleyici genellikle _her_ bileşene durum yönetimi (state management) hook'ları enjekte eder.
+
+- **Maliyet:** Eğer 5.000 öğeden oluşan bir liste render ederseniz, yalnızca metin için 5.000 `useState` ve `useEffect` hook'u başlatıyorsunuz demektir. Bu, deklaratif kütüphanelerin (genellikle tek bir Context sağlayıcı kullanan) tasarruf ettiği bellek ve CPU döngülerini tüketir.
+
+## Tuzak: Vendor Lock-in (Tedarikçi Bağımlılığı)
+
+Bu, derleyici tabanlı i18n'nin muhtemelen en tehlikeli yönüdür.
+
+Deklaratif bir kütüphanede, kaynak kodunuz açık niyet içerir. Anahtarlar size aittir. Kütüphane değiştirirseniz, sadece import'u değiştirirsiniz.
+
+Derleyici tabanlı bir yaklaşımda, **kaynak kodunuz sadece İngilizce metindir.** "Çeviri mantığı" sadece build eklentisinin yapılandırması içinde vardır.
+Eğer o kütüphane bakım dışı kalırsa veya ihtiyaçlarınızı karşılamaz hale gelirse, sıkışıp kalırsınız. Kaynak kodunuzda hiç çeviri anahtarı olmadığından kolayca "eject" yapamazsınız. Göç etmek için tüm uygulamanızı manuel olarak yeniden yazmanız gerekir.
+
+## Diğer Taraf: Deklaratif Yaklaşımın Riskleri
+
+Adil olmak gerekirse, geleneksel deklaratif yöntem de mükemmel değildir. Kendi "kendi ayağına sıkma" sorunları vardır.
+
+1.  **Namespace Cehennemi:** Hangi JSON dosyalarının yükleneceğini (`common.json`, `dashboard.json`, `footer.json`) genellikle manuel olarak yönetmeniz gerekir. Birini unutursanız, kullanıcı ham anahtarları görür.
+2.  **Aşırı Yükleme:** Dikkatli yapılandırma yapılmazsa, başlangıç yüklemesinde _tüm_ sayfalarınız için _tüm_ çeviri anahtarlarınızı yanlışlıkla yüklemek çok kolaydır ve bu da paket boyutunuzu şişirir.
+3.  **Senkronizasyon Kayması:** Bir bileşeni kullanan anahtarlar silindikten sonra bile JSON dosyasında kalması yaygındır. Çeviri dosyalarınız "zombi anahtarlarla" dolarak sonsuz şekilde büyür.
+
+## Intlayer Orta Yolu
+
+İşte **Intlayer** gibi araçların yenilik yapmaya çalıştığı yer burasıdır. Intlayer, derleyicilerin güçlü olduğunu ancak örtük sihrin tehlikeli olduğunu anlar.
+
+Intlayer benzersiz bir **`transform` komutu** sunar. Gizli derleme adımında sadece sihir yapmak yerine, aslında **bileşen kodunuzu yeniden yazabilir**. Metninizi tarar ve kod tabanınızda açık içerik beyanları ile değiştirir.
+
+Bu size her iki dünyanın en iyisini sunar:
+
+1.  **Detaylılık:** Çevirilerinizi bileşenlerinize yakın tutarsınız (modülerliği ve tree-shaking'i geliştirir).
+2.  **Güvenlik:** Çeviri, gizli derleme zamanı sihri değil, açık kod haline gelir.
+3.  **Kilitlenme Yok:** Kod, depo içinde standart bir deklaratif yapıya dönüştürüldüğünden, mantığı bir webpack eklentisinde gizlememiş olursunuz.
+
+## Sonuç
+
+Peki, hangisini seçmelisiniz?
+
+**Eğer Junior Geliştirici, Tek Kurucu ya da bir MVP geliştiriyorsanız:**
+Derleyici tabanlı yaklaşım geçerli bir seçimdir. Çok hızlı ilerlemenizi sağlar. Dosya yapıları veya anahtarlar hakkında endişelenmenize gerek yoktur. Sadece inşa edersiniz. Teknik borç "Gelecekteki Siz" için bir sorundur.
+
+**Eğer Profesyonel, Kurumsal Düzeyde Bir Uygulama Geliştiriyorsanız:**
+Sihir genellikle kötü bir fikirdir. Kontrole ihtiyacınız vardır.
+
+- Backendlerden dinamik verileri yönetmeniz gerekir.
+- Düşük donanımlı cihazlarda performansı garanti etmeniz gerekir (hook patlamalarını önleyerek).
+- Belirli bir derleme aracına sonsuza kadar bağımlı kalmadığınızdan emin olmanız gerekir.
+
+Profesyonel uygulamalar için, **Deklaratif İçerik Yönetimi** (Intlayer veya yerleşik kütüphaneler gibi) altın standart olmaya devam eder. Bu, endişelerinizi ayırır, mimarinizi temiz tutar ve uygulamanızın birden fazla dili konuşma yeteneğinin, niyetlerinizi tahmin eden "kara kutu" bir derleyiciye bağlı olmamasını sağlar.