@intlayer/docs 9.1.3 → 9.2.0

package/docs/tr/intlayer_with_vite+vue.md

@@ -30,9 +30,7 @@ history:
 author: aymericzip
 ---
 
-# Intlayer ile Vite and Vue çevirin | Uluslararasılaştırma (i18n)
-
-GitHub'da [Uygulama Şablonu](https://github.com/aymericzip/intlayer-vite-vue-template)'na bakın.
+# Intlayer kullanarak Vite ve Vue web sitenizi çevirme | Uluslararasılaştırma (i18n)
 
 ## İçindekiler
 

package/docs/tr/packages/intlayer/getMultilingualUrls.md

@@ -49,26 +49,12 @@ author: aymericzip
 
 ## Parametreler
 
-## Parametreler
+### Gerekli Parametreler
 
 - `url: string`
-  - **Açıklama**: Yerel ayarlarla öneklendirilecek orijinal URL dizesi.
-  - **Tür**: `string`
-
-- `locales: Locales[]`
-  - **Açıklama**: İsteğe bağlı desteklenen yerel ayarlar dizisi. Varsayılan olarak projede yapılandırılan yerel ayarları kullanır.
-  - **Tür**: `Locales[]`
-  - **Varsayılan**: `localesDefault`
-
-- `defaultLocale: Locales`
-  - **Açıklama**: Uygulamanın varsayılan yerel ayarı. Varsayılan olarak projede yapılandırılan varsayılan yerel ayarı kullanır.
-  - **Tür**: `Locales`
-  - **Varsayılan**: `defaultLocaleDefault`
-
-- `prefixDefault: boolean`
-  - **Açıklama**: Varsayılan yerel ayarı öneklendirip öneklendirmeyeceğinizi belirtir. Varsayılan olarak projede yapılandırılan değeri kullanır.
-  - **Tür**: `boolean`
-  - **Varsayılan**: `prefixDefaultDefault`
+  - **Description**: Locale'ler ile ön ek eklenecek orijinal URL string'i.
+  - **Type**: `string`
+  - **Required**: Yes
 
 ### İsteğe Bağlı Parametreler
 

package/docs/tr/packages/vite-intlayer/exports.md

@@ -48,3 +48,18 @@ import "vite-intlayer";
 | `intlayerProxy`      | Yerel tespiti ve yönlendirmeyi işlemek için geliştirme middleware eklentisi.          | -                                                                                                                      |
 | `intlayerMiddleware` | (**Kullanımdan Kaldırıldı**) `intlayerProxy` için takma ad.                           | -                                                                                                                      |
 | `intlayerPrune`      | Derleme sırasında kullanılmayan sözlükleri tree-shake yapmak ve budamak için eklenti. | [intlayerPrune](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/packages/vite-intlayer/intlayerPrune.md) |
+
+### Utilities
+
+| Export                       | Description                                                                                     | Related Doc                                                                                                            |
+| ---------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `createIntlayerProxyHandler` | Framework-agnostic Node.js `(req, res, next)` middleware'i locale-routing logic'i ile döndürür. | [intlayerProxy](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/packages/vite-intlayer/intlayerProxy.md) |
+
+### Türler
+
+| Export                       | Açıklama                                                                                                                              |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `IntlayerPluginOptions`      | `intlayer()` tarafından kabul edilen seçenekler. `GetConfigurationOptions` öğesini `compatCallers` ve `proxy` ile genişletir.         |
+| `IntlayerProxyPluginOptions` | `intlayerProxy()` ve `createIntlayerProxyHandler()` tarafından kabul edilen seçenekler. `ignore` ve `configOptions` öğelerini içerir. |
+| `IntlayerCompilerOptions`    | `intlayerCompiler()` tarafından kabul edilen seçenekler. `configOptions` ve `compilerConfig` öğelerini içerir.                        |
+| `CompatCallerConfig`         | `@intlayer/babel` öğesinden yeniden dışa aktarılan. Alan kullanımı analizi için compat-adapter çağrı deseni tanımlar.                 |

package/docs/tr/packages/vite-intlayer/intlayer.md

@@ -39,11 +39,126 @@ export default defineConfig({
 });
 ```
 
-## Açıklama
+## Seçenekler
 
-Eklenti şu görevleri yerine getirir:
+```ts
+import type { IntlayerPluginOptions } from "vite-intlayer";
+```
+
+`IntlayerPluginOptions`, `GetConfigurationOptions` (bkz. `@intlayer/config`) öğesini aşağıdaki ek alanlarla genişletir:
+
+| Seçenek         | Tür                             | Varsayılan  | Açıklama                                                                                                                                                                 |
+| --------------- | ------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `compatCallers` | `CompatCallerConfig[]`          | `[]`        | Compat-adapter paketleri için ek çağrı desenleri (örn. `@intlayer/react-i18next`). Derleme zamanında alan kullanımı analizine iletilir.                                  |
+| `proxy`         | `{ ignore?: (req) => boolean }` | `undefined` | Paketlenmiş yerel ayar yönlendirme proxy'sine iletilen seçenekler. Belirli yolları (örn. API rotaları) yerel ayar yönlendirmesinden hariç tutmak için `ignore` kullanın. |
+
+Diğer tüm seçenekler (`override`, `configFile`, …) doğrudan `getConfiguration()` öğesine iletilir.
+
+### Örnekler
+
+#### Yerel yönlendirmeden API rotalarını yoksay
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
+});
+```
+
+#### Özel bir config dosya yolu ile
+
+```ts
+export default defineConfig({
+  plugins: [
+    intlayer({
+      configFile: "./config/intlayer.config.ts",
+    }),
+  ],
+});
+```
+
+#### compat-adapter çağırıcıları ile
+
+```ts
+import { intlayer } from "vite-intlayer";
+import { reactI18nextCallerConfig } from "@intlayer/react-i18next/plugin";
+
+export default defineConfig({
+  plugins: [
+    intlayer({
+      compatCallers: [reactI18nextCallerConfig],
+    }),
+  ],
+});
+```
+
+## Eklentinin ne yaptığı
+
+### 1. Sözlük hazırlığı
+
+Build başlamadan önce (ve geliştirme ortamında saatte bir), `intlayer` tüm `.content.ts` dosyalarını `.intlayer/` klasöründe depolanan optimize edilmiş JSON sözlüklerine derlemek için `prepareIntlayer` işlevini çağırır.
+
+### 2. Module aliases
+
+Plugin, `import { myDict } from 'intlayer/dictionaries/my-dict'` ifadesinin diskte derlenen JSON dosyasına çözümlenmesi için Vite resolve aliases'lerini ekler. SSR buildleri, tüm `@intlayer/*` paketlerinin alias'lar uygulanarak birlikte paketlenmesini sağlamak için `ssr.noExternal` kullanır.
+
+### 3. Dev-server watcher
+
+Geliştirme modunda bir `chokidar` watcher başlatılır. Bir `.content.ts` dosyası değiştiğinde sözlükler yeniden derlenir ve Vite'in HMR güncellemeleri tarayıcıya yayınlar.
+
+### 4. Bundled locale-routing proxy (v9+)
+
+Intlayer v9'dan beri `intlayerProxy` middleware'i `intlayer()` içinde otomatik olarak kaydedilir. Şunları işler:
+
+- URL ön eki, çerezler ve `Accept-Language` başlığından yerel ayar algılaması.
+- Algılanan yerel ayar geçerli URL ile eşleşmediğinde 301 yönlendirmeleri.
+- Framework'ün doğru `[locale]` rota parametresini görmesi için iç URL yeniden yazmaları.
+
+Proxy, Intlayer yapılandırmanızda `routing.enableProxy` (varsayılan `true`) tarafından kontrol edilir. Tamamen devre dışı bırakmak için:
+
+```ts
+// intlayer.config.ts
+import { defineConfig } from "intlayer";
+
+export default defineConfig({
+  routing: { enableProxy: false },
+});
+```
+
+Ayrı bir `intlayerProxy()` çağrısı olmadan proxy davranışını özelleştirmek için ana eklentiye `proxy` seçeneklerini geçin:
+
+```ts
+intlayer({ proxy: { ignore: (req) => req.url?.startsWith("/api") } });
+```
+
+Tam yönlendirme davranışı referansı için [intlayerProxy belgelerine](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/packages/vite-intlayer/intlayerProxy.md) bakın.
+
+### 5. Bundled compiler (v9+)
+
+`compiler.enabled` değeri `true` **ve** Intlayer config dosyanızda `compiler.output` ayarlandığında, `intlayer()` otomatik olarak `intlayerCompiler` kaydeder. Compiler, bileşen dosyalarının içinde doğrudan yazılan satır içi içerik bildirimleri çıkarır ve bunları dönüştürme zamanında sözlüklere yazar. [intlayerCompiler dokumentasyonu](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/packages/vite-intlayer/intlayerCompiler.md) sayfasına bakın.
+
+### 6. Build optimisasyonları
+
+Bir üretim derlemesi sırasında eklenti şunları ekler:
+
+- **intlayerOptimize** – `useIntlayer('key')` → `useDictionary(hash)` yeniden yazılıp doğrudan JSON içe aktarımlarını enjekte eden Babel dönüşümü.
+- **intlayerPrune** – sözlük JSON'undan kullanılmayan içerik alanlarını kaldırır.
+- **intlayerMinify** – sözlük JSON'unu sıkıştırır ve isteğe bağlı olarak alan adlarını karıştırır.
+
+Bunlar geliştirme modunda etkin değildir.
+
+## Kullanım Dışı Bırakılan Takma Adlar
 
-1. **Sözlükleri Hazırlama**: Yapı veya geliştirme sürecinin başında sözlükleri optimize edilmiş dosyalara derler.
-2. **İzleme Modu**: Geliştirme modunda, sözlük dosyalarındaki değişiklikleri izler ve bunları otomatik olarak yeniden derler.
-3. **Aliaslar**: Uygulamanızda sözlüklere erişim için aliaslar sağlar.
-4. **Tree-shaking**: Kullanılmayan çevirilerin `intlayerPrune` eklentisi aracılığıyla tree-shaking ile kaldırılmasını destekler.
+| Kullanım Dışı Bırakılan Export | Değiştirme |
+| ------------------------------ | ---------- |
+| `intlayerPlugin`               | `intlayer` |
+| `intLayerPlugin`               | `intlayer` |

package/docs/tr/packages/vite-intlayer/intlayerPrune.md

@@ -30,16 +30,89 @@ author: aymericzip
 
 ## Kullanım
 
+### `intlayer()` kapsamında (önerilen)
+
+Intlayer yapılandırmanız aracılığıyla pruning'i etkinleştirin ve ana plugin her şeyi işler:
+
+```ts
+// intlayer.config.ts
+import { defineConfig } from "intlayer";
+
+export default defineConfig({
+  build: {
+    optimize: true, // pruning ve minify'ı etkinleştirir
+  },
+});
+```
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+### Standalone
+
+Plugin stack'ini manuel olarak oluşturuyorsanız, `intlayerPrune` ve `intlayerMinify` bir `PruneContext` nesnesini paylaşır ve bu nesne bir kez oluşturulup her ikisine de geçirilmelidir:
+
 ```ts
 // vite.config.ts
 import { defineConfig } from "vite";
-import { intlayer, intlayerPrune } from "vite-intlayer";
+import { intlayerPrune, intlayerMinify } from "vite-intlayer";
+import { createPruneContext } from "@intlayer/babel";
+import { getConfiguration } from "@intlayer/config/node";
+
+const intlayerConfig = getConfiguration();
+const pruneContext = createPruneContext();
 
 export default defineConfig({
-  plugins: [intlayer(), intlayerPrune()],
+  plugins: [
+    intlayerPrune(intlayerConfig, pruneContext),
+    intlayerMinify(intlayerConfig, pruneContext), // isteğe bağlı, aynı context'ten okur
+  ],
 });
 ```
 
-## Açıklama
+## Nasıl çalışır
+
+### 1. Kullanım analizi (buildStart)
+
+`buildStart` sırasında, `intlayerOptimize` eklentisi (aynı zamanda `intlayer()`'ın bir parçası) `build.filesList`'de listelenen her bileşen kaynak dosyasını tarar. Her `useIntlayer('key')` veya `getIntlayer('key')` çağrısı için, hangi alanların erişildiğini tam olarak kaydeder, örneğin:
+
+```ts
+const { title, description } = useIntlayer("myDict");
+// kaydeder: myDict → { title, description }
+```
+
+Bu, herhangi bir `transform` çağrısı çalışmadan önce `pruneContext.fieldUsageMap`'i oluşturur.
+
+### 2. JSON budama (transform, enforce: 'pre')
+
+Vite derlenmiş bir sözlük JSON dosyasını işlediğinde, `intlayerPrune` bunu Vite'nin yerleşik JSON → ESM dönüştürmesinden önce ele geçirir. `pruneContext`'ten alan kullanım haritasını okur ve kaydedilen kullanım setinde olmayan herhangi bir içerik alanını kaldırır.
+
+İki içerik şekli desteklenir:
+
+- **Statik sözlükler** — `{ nodeType: "translation", translation: { en: {...}, fr: {...} } }`. Alanlar `translation` içinde yerel başına budanır.
+- **Dinamik (yerel başına) sözlükler** — düz `{ fieldA: ..., fieldB: ... }`. Alanlar en üst düzeyde budanır.
+
+### 3. Edge cases
+
+Bir sözlüğün içerik yapısı tanınamazsa (örneğin, olağandışı iç içe bir şekil), `pruneContext.dictionariesWithEdgeCases` öğesine eklenir ve **değiştirilmez bırakılır**. Bir uyarı günlüğe kaydedilir. `intlayerMinify` bu sözlükleri de atlar.
+
+### 4. Field-rename map
+
+Budama başarılı olduğunda, `intlayerPrune` ayrıca `pruneContext.dictionaryKeyToFieldRenameMap` — orijinal alan adlarından kısa takma adlara eşleme yazar. `intlayerMinify` çıktı JSON'daki alanları yeniden adlandırmak için bu haritayı okur ve `intlayerOptimize`'ın Babel rename geçişi kaynak dosyalardaki property erişimlerini buna göre günceller.
+
+## Aktivasyon koşulları
+
+`intlayerPrune` **yalnızca** aşağıdakilerin hepsi doğru olduğunda etkin olur:
+
+1. Vite komutu `build` olur.
+2. `build.optimize` `true` olur (veya `undefined`, derlemeler için varsayılan olarak `true` olur).
+3. `build.purge` Intlayer yapılandırmanızda `true` olur.
 
-Eklenti, kaynak kodunuzu analiz ederek hangi sözlük anahtarlarının gerçekten kullanıldığını belirler. Ardından paketlenen sözlük dosyalarından kullanılmayan içeriği kaldırır. Bu, yalnızca belirli sayfalar veya bileşenlerde bir alt kümesi kullanılan birçok sözlüğe sahip büyük projeler için özellikle faydalıdır.
+`editor.enabled` `true` olduğunda otomatik olarak **devre dışı bırakılır** çünkü düzenleyici tam sözlük içeriğine ihtiyaç duyar.

package/docs/tr/self_hosting.md

@@ -80,6 +80,18 @@ Yığın çalışmaya başladıktan sonra **http://localhost:3000** adresini aç
 
 ---
 
+## İlk çalıştırma kurulumu
+
+Yeni bir instance'ta (boş veritabanı), dashboard'u açmak sizi **`/init`** sayfasına yönlendirir:
+
+1. İlk hesabı oluşturun. Kullanıcılar koleksiyonu boş olduğundan, bu hesap otomatik olarak **super admin** olarak yükseltilir.
+2. Bir doğrulama e-postası gönderilir (Resend aracılığıyla). E-posta doğrulaması **zorunludur** — bu nedenle `RESEND_API_KEY` başlamadan önce ayarlanmalıdır.
+3. E-postadaki bağlantıyı tıklayın, ardından oturum açın.
+
+Bir admin mevcut olduğunda, `/init` standart oturum açma sayfasına yönlendirilir.
+
+---
+
 ## Servisler
 
 | Servis      | Görüntü                                           | Ana Bilgisayar Bağlantı Noktası(ları) | Amaç                                                         |
@@ -97,9 +109,18 @@ Dahili bağlantı noktaları (mongo, redis) varsayılan olarak ana bilgisayara a
 
 ---
 
-## Ortam Değişkenleri
+## Ortam değişkenleri
 
-Yükleyici, kullanıma hazır bir `.env` dosyası oluşturur. Aşağıdaki tablo her değişkeni açıklar.
+### Gerekli
+
+| Variable               | Example                      | Description                                                                                                                                                          |
+| ---------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DB_ID`                | `intlayer`                   | MongoDB Atlas kullanıcısı                                                                                                                                            |
+| `DB_MDP`               | _(şifreniz)_                 | MongoDB Atlas şifresi                                                                                                                                                |
+| `DB_CLUSTER`           | `cluster0.xxxxx.mongodb.net` | MongoDB Atlas cluster host'u (`mongodb+srv://` URI'de kullanılır)                                                                                                    |
+| `BETTER_AUTH_SECRET`   | _(generated)_                | Session imzalama için 32-byte secret                                                                                                                                 |
+| `S3_SECRET_ACCESS_KEY` | _(generated)_                | Bundled MinIO için secret                                                                                                                                            |
+| `RESEND_API_KEY`       | _(your key)_                 | Resend aracılığıyla işlemsel e-posta. Global SMTP mailer'ı yapılandırmadığınız sürece ilk çalıştırma kurulumu için gereklidir (bkz. [Global mailer](#global-mailer)) |
 
 ### Gerekli (otomatik oluşturulur veya istenir)
 
@@ -141,6 +162,26 @@ Yükleyici, kullanıma hazır bir `.env` dosyası oluşturur. Aşağıdaki tablo
 
 ---
 
+### Global mailer
+
+Varsayılan olarak, tüm işlemsel e-postalar Resend üzerinden `RESEND_API_KEY` kullanılarak gönderilir. Self-hosted dağıtımlar bunun yerine **tüm** e-postaları — şifre sıfırlamaları ve magic linkler gibi organizasyon dışı e-postalar dahil — ortam değişkenleriyle yapılandırılmış global bir mailer üzerinden yönlendirebilir.
+
+Etkinleştirmek için `MAIL_PROVIDER` ayarlayın. Ayarlanmadığında, varsayılan Resend mailer kullanılır.
+
+| Değişken             | Örnek                          | Açıklama                                                                          |
+| -------------------- | ------------------------------ | --------------------------------------------------------------------------------- |
+| `MAIL_PROVIDER`      | `smtp`                         | Global transport: `smtp` veya `resend`. Varsayılanları kullanmak için ayarlamayın |
+| `MAIL_FROM`          | `Intlayer <no-reply@acme.com>` | Gönderen başlığı. Düz bir adres veya `Name <email>` formatını kabul eder          |
+| `MAIL_SMTP_HOST`     | `smtp.acme.com`                | SMTP host (`MAIL_PROVIDER=smtp` olduğunda gerekli)                                |
+| `MAIL_SMTP_PORT`     | `587`                          | SMTP port (varsayılan `587`)                                                      |
+| `MAIL_SMTP_SECURE`   | `false`                        | Implicit TLS. Port `465` için `true` olarak ayarlayın                             |
+| `MAIL_SMTP_USER`     | _(your user)_                  | SMTP kullanıcı adı (isteğe bağlı; kimliği doğrulanmamış relayler için atlayın)    |
+| `MAIL_SMTP_PASSWORD` | _(your password)_              | SMTP şifresi                                                                      |
+
+> Öncelik: bir organizasyonun kendi mailer'ı (**Organization** panosundan yapılandırılmış) global mailer'dan daha yüksek önceliğe sahiptir ve bu da varsayılan Resend anahtarından daha yüksek önceliğe sahiptir.
+
+---
+
 ## Intlayer projenizi bağlama
 
 Yığın çalışmaya başladıktan sonra, projenizi `intlayer.org` yerine kendi barındırılan backend ve kontrol paneline yönlendirin.
@@ -259,47 +300,11 @@ docker run --rm \
 
 ---
 
-## Ters Proxy Kullanımı (Nginx / Caddy)
-
-Üretim dağıtımları için, uygulama ve backend kapsayıcılarının önüne doğrudan açmak yerine bir ters proxy yerleştirin.
+## Sınırlamalar
 
-### Nginx örneği
-
-```nginx
-server {
-    listen 80;
-    server_name cms.example.com;
-
-    location / {
-        proxy_pass http://localhost:3000;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-    }
-}
-
-server {
-    listen 80;
-    server_name api.example.com;
-
-    location / {
-        proxy_pass http://localhost:3100;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-    }
-}
-```
-
-Aşağıdaki `.env` değişkenlerini genel alan adlarınızla eşleşecek şekilde güncelleyin:
-
-```sh
-BACKEND_URL=https://api.example.com
-APP_URL=https://cms.example.com
-DOMAIN=example.com
-VITE_BACKEND_URL=https://api.example.com
-VITE_DOMAIN=example.com
-```
-
-> `VITE_*` değişkenleri oluşturma zamanında kontrol paneli görüntüsüne gömülür. Görüntü oluşturulduktan sonra bunları değiştirirseniz, `app` görüntüsünü yeniden oluşturmanız (`docker compose build app`) veya çalışma zamanı yapılandırma enjeksiyonu kullanmanız gerekir.
+- **MongoDB harici (Atlas) olmalıdır.** Backend yalnızca `mongodb+srv://` üzerinden bağlanır (`DB_ID` / `DB_MDP` / `DB_CLUSTER` öğesinden oluşturulur), bu nedenle düz `mongodb://host:27017` — konteyner'ın kendi paketlenmiş `mongod` dahil — kullanılamaz. Bir MongoDB Atlas kümesi sağlayın.
+- **Özel alan adı yok.** Tüm tarayıcıya yönelik `VITE_*` URL'leri derleme zamanında uygulamaya satır içine alınır ve yayınlanan görüntü `localhost` değerleriyle gemi. Pano şu adreste erişilmelidir: `http://localhost:3000`; bunu genel bir alan adında sunmak, görüntüyü hedef URL'ler ile yeniden oluşturmayı gerektiriyor ve kutudan hemen çıkar desteklenmiyor.
+- **E-posta çalışan bir postacı gerektirir.** İlk çalıştırma kurulumu e-posta doğrulamasını uygular, bu nedenle `RESEND_API_KEY` veya bir [global SMTP postacısı](#global-mailer) (`MAIL_PROVIDER=smtp` + `MAIL_SMTP_*`) yapılandırılmalıdır. İlk yönetici oturum açtıktan sonra, her kuruluş panodan kendi SMTP veya Resend postacısını da yapılandırabilir.
 
 ---
 
@@ -324,14 +329,6 @@ docker compose build app
 docker compose up -d app
 ```
 
-### E-posta Gönderilmiyor
-
-Varsayılan olarak, tüm giden e-postalar Mailpit tarafından yakalanır. Gönderilen mesajları görmek için `http://localhost:8025` adresini açın. Gerçek e-posta göndermek için `.env` dosyasında `MAIL_PROVIDER=resend` ve `RESEND_API_KEY=<anahtarınız>` ayarlayın, ardından backend'i yeniden başlatın:
-
-```sh
-docker compose restart backend
-```
-
 ### MinIO Kovası Eksik
 
 Eğer `minio-init` tek seferlik servisi çalışmadıysa (veya MinIO hazır olmadan önce çalıştıysa), kovayı manuel olarak oluşturun:

package/docs/uk/analytics.md

@@ -0,0 +1,222 @@
+---
+createdAt: 2026-07-08
+updatedAt: 2026-07-08
+title: Intlayer Analytics | Відстеження показів контенту та проведення A/B-тестування
+description: Дізнайтеся, як @intlayer/analytics відстежує перегляди сторінок/локалей та покази контенту, і як використовувати це для проведення A/B-тестування вашого контенту в Intlayer.
+keywords:
+  - Аналітика (Analytics)
+  - A/B Тестування
+  - Аудиторія (Audience)
+  - Інтернаціоналізація
+  - Документація
+  - Intlayer
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - concept
+  - analytics
+history:
+  - version: 9.0.0
+    date: 2026-07-08
+    changes: "Init doc — пакет @intlayer/analytics, відстеження на рівні провайдера/вузла, A/B-тестування, дашборд"
+author: aymericzip
+---
+
+# Документація Intlayer Analytics
+
+`@intlayer/analytics` — це додатковий пакет, який показує, **який контент насправді бачать** ваші відвідувачі (яку сторінку, в якій локалі та який саме фрагмент перекладеного контенту), щоб ви могли розуміти свою аудиторію та **проводити A/B-тестування контенту**.
+
+## Зміст
+
+<TOC/>
+
+---
+
+## Що відстежується
+
+`@intlayer/analytics` об'єднує в пакети (batch) три типи анонімних подій:
+
+| Подія              | Де фіксується                             | Про що вона говорить                                                                                                                            |
+| ------------------ | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `page_view`        | На рівні провайдера (`IntlayerProvider`)  | Яку сторінку та локаль переглянув користувач (сесія) під час першого завантаження, зміни маршруту або зміни локалі.                             |
+| `content_exposure` | На рівні вузла (`useIntlayer` / плагіни)  | Який ключ словника / шлях до ключа було фактично вирішено (resolved) та показано — і, якщо це частина експерименту, який **варіант** (variant). |
+| `conversion`       | Скрізь, де викликається `useConversion()` | Досягнення мети (реєстрація, клік, покупка...), пов'язане з A/B-варіантом, який бачив користувач у цій сесії.                                   |
+
+Події збираються в пам'яті та надсилаються як **один пакетний запит приблизно кожні 20 секунд** — а не при кожному натисканні клавіші або рендерингу — тому аналітика ніколи не впливає на час першого рендерингу і не додає запити на кожну взаємодію.
+
+## Як це працює для A/B-тестування контенту
+
+Intlayer вже дозволяє вам оголошувати [Варіанти (Variants)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dynamic_dictionaries/index.md) контенту (наприклад, словник `hero-banner` з варіантами `control` та `black_friday`). `@intlayer/analytics` замикає цикл:
+
+1. `getVariant(experimentKey, variants)` детерміновано призначає кожну анонімну сесію варіанту — це чиста функція від ID сесії та ключа експерименту, тому призначення є **стабільним протягом усієї сесії** і не вимагає **запитів до сервера (server round-trips)** до першого рендерингу (без мерехтіння і зсувів макета).
+2. Кожна подія `content_exposure` містить показаний `variant`.
+3. `useConversion()` дозволяє пов'язати мету (наприклад, `"cta_click"`) з цим варіантом.
+4. Ендпоінт результатів експериментів у дашборді порівнює коефіцієнти конверсії (conversion rates) за варіантами, включаючи статистичну значущість (z-тест).
+
+## Встановлення
+
+`@intlayer/analytics` — це **однорангова (peer), необов'язкова** залежність. Вона ніколи автоматично не встановлюється фреймворками. Додайте її разом з `intlayer`:
+
+```bash packageManager="npm"
+npm install @intlayer/analytics
+```
+
+```bash packageManager="yarn"
+yarn add @intlayer/analytics
+```
+
+```bash packageManager="pnpm"
+pnpm add @intlayer/analytics
+```
+
+```bash packageManager="bun"
+bun add @intlayer/analytics
+```
+
+Якщо ви її не встановите, всі точки інтеграції будуть розв'язуватися у порожні операції (no-op) — див. [Нульові витрати, якщо не встановлено](#нульові-витрати-якщо-не-встановлено) нижче.
+
+## Налаштування
+
+Аналітика **повторно використовує існуючий блок конфігурації `editor`** — вам не потрібно заповнювати окрему схему конфігурації для `analytics`:
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  editor: {
+    backendURL: "https://back.intlayer.org", // Також використовується як кінцева точка для збору аналітики
+    clientId: "your-client-id", // Також використовується як ключ проекту аналітики
+    clientSecret: "your-client-secret",
+  },
+};
+
+export default config;
+```
+
+- `editor.backendURL` — базовий URL, на який надсилаються події аналітики (`POST {backendURL}/api/analytics/events`).
+- `editor.clientId` — публічний ключ проекту, що присвоюється кожній прийнятій події. Він також діє як **перемикач увімкнення**: аналітика залишається повністю вимкненою (і видаляється при tree-shaking, див. нижче), доки не налаштовано `clientId`.
+
+Якщо ви самостійно розміщуєте (self-host) Intlayer, аналітика автоматично вказує на ваш власний екземпляр, оскільки вона використовує спільний `editor.backendURL`.
+
+## Підтримка фреймворків
+
+Аналітика вбудована у спільний `IntlayerProvider` з `react-intlayer`, тому вона доступна вже сьогодні скрізь, де використовується цей провайдер:
+
+| Фреймворк                                                | Статус                                                                                                     |
+| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| React                                                    | ✅ Доступно                                                                                                |
+| Next.js (`next-intlayer`)                                | ✅ Доступно (через `react-intlayer`)                                                                       |
+| React Native / Expo (`react-native-intlayer`)            | ✅ Доступно (через `react-intlayer`)                                                                       |
+| Vue, Svelte, Angular, Solid, Preact, Lit, Astro, Vanilla | 🚧 Заплановано — той самий клієнт, прив'язки на рівні провайдера за зразком розгортання `@intlayer/editor` |
+
+## Використання
+
+### Автоматичне відстеження на рівні провайдера
+
+Жодних змін у коді не потрібно. Як тільки встановлено `@intlayer/analytics` та налаштовано `editor.clientId`, `IntlayerProvider` автоматично:
+
+- ініціалізує клієнт аналітики при монтуванні (mount),
+- записує `page_view` при початковому завантаженні,
+- записує `page_view` при кожній зміні локалі,
+- запускає цикл очищення (flush) з інтервалом ~20 с і надсилає всі події, що залишилися, при розмонтуванні / закритті вкладки (через `navigator.sendBeacon`, з відкатом (fallback) на `fetch(..., { keepalive: true })`).
+
+### Автоматичне відстеження на рівні вузла
+
+Щоразу, коли `useIntlayer` розв'язує фрагмент контенту для відображення, інтерпретатор повідомляє про подію `content_exposure` для цього точного `dictionaryKey` + шляху до ключа + локалі — знову ж таки, жодних змін у коді не потрібно. Повторні покази одного й того ж вузла в межах вікна очищення (flush window) об'єднуються в одну подію з лічильником (`count`), тому список, що перемальовується (re-render) 50 разів, не надсилає 50 подій.
+
+### Відстеження конверсій для A/B-тестування
+
+Використовуйте `useConversion()`, щоб пов'язати мету з варіантом, який бачила сесія:
+
+```tsx fileName="CTAButton.tsx" codeFormat="tsx"
+import { useConversion } from "react-intlayer";
+
+const CTAButton = () => {
+  const trackConversion = useConversion();
+
+  return (
+    <button
+      onClick={() =>
+        trackConversion({
+          experimentKey: "homepage-hero",
+          variant: "black_friday",
+          goal: "cta_click",
+        })
+      }
+    >
+      Почати
+    </button>
+  );
+};
+```
+
+### Розв'язання варіанту на стороні клієнта
+
+```tsx fileName="useHeroVariant.ts" codeFormat="tsx"
+import { getGlobalAnalyticsClient } from "@intlayer/analytics/client";
+
+const client = getGlobalAnalyticsClient();
+const variant = client?.getVariant("homepage-hero", [
+  "control",
+  "black_friday",
+]);
+```
+
+## Конфіденційність та продуктивність
+
+- **Анонімність за дизайном**: сесії ідентифікуються за id, що обертається (rotating id); сервер (backend) коли-небудь зберігає лише **SHA-256 хеш** цього id — ніколи сам id і ніколи IP-адресу.
+- **Приблизне місцезнаходження (Coarse location)**: лише код країни, отриманий із заголовків геолокації CDN (наприклад, `cf-ipcountry`, `x-vercel-ip-country`, ...) — IP не зчитується і не зберігається.
+- **URL виключають параметри пошуку** за замовчуванням, тому рядки запиту (query strings) ніколи не фіксуються.
+- **Семпліювання (Sampling)**: `sampleRate` дозволяє зберігати лише частину подій показу контенту в додатках з високим трафіком.
+- **Пакетна передача (Batched)**: один запит приблизно кожні 20 секунд (`flushInterval`) або раніше, якщо буфер заповнений (`maxBufferSize`) — ніколи не надсилається один запит на кожну подію.
+
+### Нульові витрати, якщо не встановлено
+
+`@intlayer/analytics` дотримується того ж патерну опціональних залежностей, що й `@intlayer/editor`:
+
+- кожна точка інтеграції завантажує пакет через **динамічний `import()`, обгорнутий у `try/catch`** — додаток, який ніколи не встановлює `@intlayer/analytics`, не збільшує розмір збірки (bundle size) і не витрачає ресурси під час виконання, а також ніколи не бачить помилок;
+- змінна середовища часу компіляції (`INTLAYER_ANALYTICS_ENABLED`), що автоматично встановлюється в `'false'` пакетом `@intlayer/config`, коли не налаштовано `editor.clientId`, дозволяє бандлерам **видаляти весь код інтеграції (dead-code-eliminate)**;
+- аналітика вимкнена всередині iframe попереднього перегляду редактора/CMS Intlayer, тому сесії в редакторі ніколи не враховуються як реальний трафік.
+
+## Дашборд: Сторінка Analytics
+
+Як тільки ваш проект збере події, сторінка **Analytics** у [дашборді Intlayer](https://app.intlayer.org/analytics) (видна в бічній панелі після вибору проекту) покаже:
+
+- **Активні користувачі** — унікальні відвідувачі за вибране ковзне вікно (7 / 30 / 90 днів).
+- **Користувачі сьогодні** та **користувачі за останні 7 днів**.
+- **Перегляди сторінок (Page views)** за вибране вікно.
+- **Графік динаміки** унікальних відвідувачів по днях.
+- Вкладки з розбивкою по **Локалях (Locales)** та **Місцезнаходженню (Location)**, що ранжують вашу аудиторію за локаллю та країною.
+
+## Довідник API бекенда (Backend API reference)
+
+Всі ендпоінти для читання вимагають автентифікації; прийом даних публічний і асоціюється за `clientId` у тілі запиту.
+
+| Метод  | Ендпоінт                                    | Опис                                                                                |
+| ------ | ------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `POST` | `/api/analytics/events`                     | Прийом пакету подій (публічний, асоціюється за `clientId` в тілі).                  |
+| `GET`  | `/api/analytics/overview`                   | Загальні показники сторінок/локалей для автентифікованого проекту.                  |
+| `GET`  | `/api/analytics/audience?days=30`           | Унікальні відвідувачі, перегляди сторінок, серії по днях, розбивка (локаль+країна). |
+| `GET`  | `/api/analytics/content-stats`              | Загальні покази контенту, згруповані за ключем словника / шляхом / локаллю.         |
+| `GET`  | `/api/analytics/experiments/:experimentKey` | Коефіцієнти конверсії за варіантами та статистична значущість для A/B-тесту.        |
+
+Ви також можете викликати їх програмно за допомогою [CMS SDK](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/intlayer_CMS.md):
+
+```ts fileName="analytics.ts"
+import { createIntlayerCMS } from "@intlayer/api";
+import { analyticsEndpoint } from "@intlayer/api/analytics";
+
+const cms = createIntlayerCMS();
+
+const { data: audience } = await analyticsEndpoint(cms).getAudience(30);
+```
+
+## Корисні посилання
+
+- [Динамічні словники - Колекції та варіанти](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dynamic_dictionaries/index.md)
+- [Intlayer CMS - CMS SDK](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/intlayer_CMS.md)
+- [Візуальний редактор Intlayer (Visual Editor)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/intlayer_visual_editor.md)
+- [Довідник з конфігурації (Configuration Reference)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/configuration.md)
+- [Посібник із самостійного хостингу (Self-Hosting)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/self_hosting.md)