@intlayer/docs 9.0.0-canary.2 → 9.0.0-canary.3

package/docs/tr/plugins/sync-json.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-03-13
-updatedAt: 2025-12-13
+updatedAt: 2026-06-21
 title: JSON Senkronizasyon Eklentisi
 description: Intlayer sözlüklerini üçüncü taraf i18n JSON dosyalarıyla (i18next, next-intl, react-intl, vue-i18n ve daha fazlası) senkronize edin. Mevcut i18n yapınızı koruyarak Intlayer ile mesajlarınızı yönetin, çevirin ve test edin.
 keywords:
@@ -24,6 +24,9 @@ slugs:
   - sync-json
 youtubeVideo: https://www.youtube.com/watch?v=MpGMxniDHNg
 history:
+  - version: 9.0.0
+    date: 2026-06-21
+    changes: "next-intl / react-intl tek dosya düzenleri için splitKeys seçeneği eklendi (üst düzey ad alanı anahtarı başına bir sözlük)"
   - version: 7.5.0
     date: 2025-12-13
     changes: "ICU ve i18next format desteği eklendi"
@@ -62,7 +65,63 @@ pnpm add -D @intlayer/sync-json-plugin
 npm i -D @intlayer/sync-json-plugin
 ```
 
-## Hızlı başlangıç
+## Plugins
+
+Bu paket iki eklenti sağlar:
+
+- `loadJSON`: JSON dosyalarını Intlayer sözlüklerine yükler.
+  - Bu eklenti, bir kaynaktan JSON dosyalarını yüklemek için kullanılır ve Intlayer sözlüklerine yüklenecektir. Tüm kod tabanını tarayabilir ve belirli JSON dosyalarını arayabilir.
+    Bu eklenti şu durumlarda kullanılabilir:
+    - JSON'larınızın belirli bir konumda yüklenmesini zorunlu kılan bir i18n kütüphanesi kullanıyorsanız (örn: `next-intl`, `i18next`, `react-intl`, `vue-i18n`, vb.), ancak içerik bildirimlerinizi kod tabanınızda istediğiniz yere yerleştirmek istiyorsanız.
+    - Mesajlarınızı uzak bir kaynaktan (örn: bir CMS, bir API, vb.) almak ve mesajlarınızı JSON dosyalarında saklamak istiyorsanız da kullanılabilir.
+
+  > Arka planda, bu eklenti tüm kod tabanını tarayacak ve belirli JSON dosyalarını arayacak ve bunları Intlayer sözlüklerine yükleyecektir.
+  > Bu eklentinin çıktıyı ve çevirileri JSON dosyalarına geri yazmayacağını unutmayın.
+
+- `syncJSON`: JSON dosyalarını Intlayer sözlükleriyle senkronize eder.
+  - Bu eklenti, JSON dosyalarını Intlayer sözlükleriyle senkronize etmek için kullanılır. Verilen konumu tarayabilir ve belirli JSON dosyaları için desene uyan JSON'u yükleyebilir. Bu eklenti, başka bir i18n kütüphanesi kullanırken Intlayer'ın faydalarından yararlanmak istiyorsanız kullanışlıdır.
+
+## Her iki eklentiyi de kullanma
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadJSON, syncJSON } from "@intlayer/sync-json-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  // Mevcut JSON dosyalarınızı Intlayer sözlükleriyle senkronize tutun
+  plugins: [
+    /**
+     * src dizinindeki {key}.i18n.json desenine uyan tüm JSON dosyalarını yükleyecektir
+     */
+    loadJSON({
+      source: ({ key }) => `./src/**/${key}.i18n.json`,
+      locale: Locales.ENGLISH,
+      priority: 1, // Bu JSON dosyalarının `./locales/en/${key}.json` adresindeki dosyalara göre öncelikli olmasını sağlar
+      format: "intlayer", // JSON içeriğinin formatı
+    }),
+    /**
+     * Çıktıyı ve çevirileri locales dizinindeki JSON dosyalarına yükleyecek ve yazacaktır
+     */
+    syncJSON({
+      format: "i18next",
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      priority: 0,
+      format: "i18next",
+    }),
+  ],
+};
+
+export default config;
+```
+
+## `syncJSON` plugin
+
+### Hızlı başlangıç
 
 Eklentiyi `intlayer.config.ts` dosyanıza ekleyin ve mevcut JSON yapınıza işaret edin.
 
@@ -81,6 +140,7 @@ const config: IntlayerConfig = {
     syncJSON({
       // Yerel başına, ad alanı başına düzen (örneğin, next-intl, ad alanları ile i18next)
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      format: "icu",
     }),
   ],
 };
@@ -91,14 +151,27 @@ export default config;
 Alternatif: her yerel için tek dosya (i18next/react-intl yapılandırmalarında yaygın):
 
 ```ts fileName="intlayer.config.ts"
-plugins: [
-  syncJSON({
-    source: ({ locale }) => `./locales/${locale}.json`,
-  }),
-];
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  plugins: [
+    syncJSON({
+      format: "i18next",
+      source: ({ locale }) => `./locales/${locale}.json`,
+      format: "i18next",
+    }),
+  ],
+};
+
+export default config;
 ```
 
-### Nasıl çalışır
+#### Nasıl çalışır
 
 - Okuma: eklenti, `source` yapıcınızdan JSON dosyalarını keşfeder ve bunları Intlayer sözlükleri olarak yükler.
 - Yazma: derlemeler ve doldurmalar sonrası, yerelleştirilmiş JSON'u aynı yollara yazar (biçimlendirme sorunlarını önlemek için sonuna yeni satır ekleyerek).
@@ -112,6 +185,7 @@ syncJSON({
   location?: string, // isteğe bağlı etiket, varsayılan: "plugin"
   priority?: number, // isteğe bağlı öncelik, çakışma çözümü için, varsayılan: 0
   format?: 'intlayer' | 'icu' | 'i18next', // isteğe bağlı formatlayıcı, Intlayer runtime uyumluluğu için kullanılır
+  splitKeys?: boolean, // isteğe bağlı, tek bir dosyayı üst düzey anahtar başına bir sözlüğe böler (otomatik algılanır)
 });
 ```
 
@@ -136,18 +210,49 @@ syncJSON({
 }),
 ```
 
-## Birden fazla JSON kaynağı ve öncelik
+#### `splitKeys` (boolean)
+
+**İlk düzey anahtarları ad alanları olan** tek bir JSON dosyasının, tüm dosyayı tutan tek bir sözlük yerine, üst düzey anahtar başına bir sözlük haline gelip gelmeyeceğini kontrol eder.
+
+Bu, `next-intl` ve `react-intl` gibi kütüphanelerin ad alanı modeline uyar; burada bir `messages/{locale}.json` dosyası, ilk düzey anahtarlarıyla birden çok ad alanını gruplandırır ve her biri bağımsız olarak ele alınır (örneğin, `useTranslations('Hero')` `Hero` sözlüğüne çözümlenir).
+
+- `undefined` (varsayılan): **otomatik algılanır** — `source` deseninde `{key}` segmenti yoksa dosya bölünür (bir dosya her ad alanını tutar), aksi takdirde tek bir sözlük olarak kalır (anahtar başına bir dosya).
+- `true`: her üst düzey anahtarı her zaman kendi sözlüğüne böler.
+- `false`: asla bölmez; tüm dosya tek bir sözlük haline gelir.
+
+Tek bir `messages/{locale}.json` dosyası verildiğinde:
+
+```json fileName="messages/en.json"
+{
+  "Hero": { "title": "Full-stack developer" },
+  "Nav": { "work": "Work", "about": "About" },
+  "About": { "lead": "I build apps end to end." }
+}
+```
+
+```ts fileName="intlayer.config.ts"
+syncJSON({
+  format: "icu",
+  source: ({ locale }) => `./messages/${locale}.json`,
+  // splitKeys: true, // desenin `{key}` segmenti olmadığı için ima edilir
+}),
+```
+
+Bu, üç sözlük (`Hero`, `Nav` ve `About`) üretir, böylece `useTranslations('Hero')` (next-intl) doğru şekilde çözümlenir. Geri yazma işleminde, tüm ad alanları aynı yerel başına dosyada yeniden birleştirilir.
+
+> `source` içinde açık `{key}` segmentini koruduğunuzda (örneğin, `./locales/${locale}/${key}.json`), her dosya zaten bir ad alanıdır, bu nedenle bölme varsayılan olarak devre dışıdır.
+
+### Multiple JSON sources and priority
 
 Farklı JSON kaynaklarını senkronize etmek için birden fazla `syncJSON` eklentisi ekleyebilirsiniz. Bu, projenizde birden fazla i18n kütüphanesi veya farklı JSON yapıları olduğunda faydalıdır.
 
-### Öncelik sistemi
+#### Öncelik sistemi
 
 Birden fazla eklenti aynı sözlük anahtarını hedeflediğinde, `priority` parametresi hangi eklentinin öncelikli olduğunu belirler:
 
 - Daha yüksek öncelik numaraları, daha düşük olanlara karşı kazanır
-
 - `.content` dosyalarının varsayılan önceliği `0`'dır
-- Eklentilerin içerik dosyalarının varsayılan önceliği `-1`'dir
+- Eklentilerin varsayılan önceliği `0`'dır
 - Aynı önceliğe sahip eklentiler, yapılandırmada göründükleri sırayla işlenir
 
 ```ts fileName="intlayer.config.ts"
@@ -190,73 +295,140 @@ const config: IntlayerConfig = {
 export default config;
 ```
 
-### Çakışma çözümü
+## Load JSON plugin
 
-Aynı çeviri anahtarı birden fazla JSON kaynağında mevcutsa:
+### Hızlı başlangıç
 
-1. En yüksek önceliğe sahip eklenti nihai değeri belirler
-2. Daha düşük öncelikli kaynaklar, eksik anahtarlar için yedek olarak kullanılır
-3. Bu, eski çevirileri korumanıza ve yeni yapılara kademeli olarak geçiş yapmanıza olanak tanır
+Mevcut JSON dosyalarını Intlayer sözlükleri olarak almak için eklentiyi `intlayer.config.ts` dosyanıza ekleyin. Bu eklenti salt okunurdur (diske yazma yapmaz):
 
-## Entegrasyonlar
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadJSON } from "@intlayer/sync-json-plugin";
 
-Aşağıda yaygın eşlemeler bulunmaktadır. Çalışma zamanınızı değiştirmeyin; sadece eklentiyi ekleyin.
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
 
-### i18next
+  plugins: [
+    // Kaynak ağacınızın herhangi bir yerinde bulunan JSON mesajlarını alın
+    loadJSON({
+      source: ({ key }) => `./src/**/${key}.i18n.json`,
+      // Eklenti örneği başına tek bir yerel yükleyin (yapılandırma varsayılan yereline ayarlanır)
+      locale: Locales.ENGLISH,
+      priority: 0,
+    }),
+  ],
+};
 
-Tipik dosya düzeni: `./public/locales/{locale}/{namespace}.json` veya `./locales/{locale}/{namespace}.json`.
+export default config;
+```
+
+Alternatif: yerel başına düzen, yine salt okunur (yalnızca seçilen yerel yüklenir):
 
 ```ts fileName="intlayer.config.ts"
-import { syncJSON } from "@intlayer/sync-json-plugin";
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadJSON } from "@intlayer/sync-json-plugin";
 
-export default {
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
   plugins: [
-    syncJSON({
-      format: "i18next",
+    loadJSON({
+      // Bu desenden yalnızca Locales.FRENCH için dosyalar yüklenecektir
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      locale: Locales.FRENCH,
     }),
   ],
 };
+
+export default config;
 ```
 
-### next-intl
+### Nasıl çalışır
+
+- Keşfet: `source` yapıcınızdan bir glob oluşturur ve eşleşen JSON dosyalarını toplar.
+- Al: her JSON dosyasını sağlanan `locale` ile bir Intlayer sözlüğü olarak yükler.
+- Salt okunur: çıktı dosyalarını yazmaz veya biçimlendirmez; gidiş-dönüş senkronizasyonuna ihtiyacınız varsa `syncJSON` kullanın.
+- Otomatik doldurmaya hazır: `fill` deseni tanımlar, böylece `intlayer content fill` eksik anahtarları CLI aracılığıyla doldurabilir.
 
-Her yerel için JSON mesajları (genellikle `./messages/{locale}.json`) veya her ad alanı için.
+### API
 
-```ts fileName="intlayer.config.ts"
-plugins: [
-  syncJSON({
-    source: ({ locale, key }) => `./messages/${locale}/${key}.json`,
-  }),
-];
+```ts
+loadJSON({
+  // JSON'unuza giden yolları oluşturun. Yapınızda yerel segment yoksa `locale` isteğe bağlıdır
+  source: ({ key, locale }) => string,
+
+  // Bu eklenti örneği tarafından yüklenen sözlükler için hedef yerel
+  // configuration.internationalization.defaultLocale varsayılanına ayarlanır
+  locale?: Locale,
+
+  // Kaynağı tanımlamak için isteğe bağlı etiket
+  location?: string, // varsayılan: "plugin"
+
+  // Diğer kaynaklara karşı çakışma çözümü için kullanılan öncelik
+  priority?: number, // varsayılan: 0
+
+  // JSON içeriği için isteğe bağlı formatlayıcı
+  format?: 'intlayer' | 'icu' | 'i18next', // varsayılan: 'intlayer'
+
+  // Tek bir dosyayı üst düzey anahtar başına bir sözlüğe böler (otomatik algılanır)
+  splitKeys?: boolean,
+});
 ```
 
-Ayrıca bakınız: `docs/tr/intlayer_with_next-intl.md`.
+#### `format` ('intlayer' | 'icu' | 'i18next')
+
+JSON dosyalarını yüklerken sözlük içeriği için kullanılacak formatlayıcıyı belirtir. Bu, çeşitli i18n kütüphaneleriyle uyumlu farklı mesaj formatlama sözdizimlerini kullanmanıza olanak tanır.
 
-### react-intl
+- `'intlayer'`: Varsayılan Intlayer formatlayıcısı (varsayılan).
+- `'icu'`: ICU mesaj formatlamasını kullanır (react-intl, vue-i18n gibi kütüphanelerle uyumlu).
+- `'i18next'`: i18next mesaj formatlamasını kullanır (i18next, next-i18next, Solid-i18next ile uyumlu).
 
-Her yerel için tek JSON yaygındır:
+**Örnek:**
 
-```ts fileName="intlayer.config.ts"
-plugins: [
-  syncJSON({
-    source: ({ locale }) => `./locales/${locale}.json`,
-  }),
-];
+```ts
+loadJSON({
+  source: ({ key }) => `./src/**/${key}.i18n.json`,
+  locale: Locales.ENGLISH,
+  format: "icu", // Uyumluluk için ICU formatlaması kullan
+}),
 ```
 
-### vue-i18n
+#### `splitKeys` (boolean)
 
-Her yerel için ya da her ad alanı için tek bir dosya olabilir:
+[`syncJSON`](#splitkeys-boolean) ile aynı davranış: tek bir JSON dosyası, ilk düzey anahtarlarıyla birden çok ad alanını gruplandırdığında, her üst düzey anahtar kendi sözlüğü haline gelir.
 
-```ts fileName="intlayer.config.ts"
-plugins: [
-  syncJSON({
-    source: ({ key, locale }) => `./src/locales/${locale}/${key}.json`,
-  }),
-];
+- `undefined` (varsayılan): **otomatik algılanır** — `source` deseninde `{key}` segmenti yoksa bölünür, aksi takdirde tek bir sözlük olur.
+- `true` / `false`: bölmeyi zorlar veya devre dışı bırakır.
+
+```ts
+loadJSON({
+  source: ({ locale }) => `./messages/${locale}.json`,
+  format: "icu",
+  // splitKeys otomatik etkinleştirildi: `Hero`, `Nav`, `About`, … her biri bir sözlük haline gelir
+}),
 ```
 
+### Behavior and conventions
+
+- `source` maskeniz bir yerel yer tutucusu içeriyorsa, yalnızca seçilen `locale` için dosyalar alınır.
+- Maskenizde `{key}` segmenti yoksa, dosyanın her üst düzey anahtarı varsayılan olarak kendi sözlüğü haline gelir (bkz. [`splitKeys`](#splitkeys-boolean)). Bunun yerine tüm dosyayı tek bir `index` sözlüğü olarak yüklemek için `splitKeys: false` olarak ayarlayın.
+- Anahtarlar, `source` yapıcınızdaki `{key}` yer tutucusunun yerine geçirilerek dosya yollarından türetilir.
+- Eklenti yalnızca keşfedilen dosyaları kullanır ve eksik yerelleri veya anahtarları uydurmaz.
+- `fill` yolu, `source`'unuzdan çıkarılır ve CLI aracılığıyla eksik değerleri güncellemek için kullanılır.
+
+## Conflict resolution
+
+Aynı çeviri anahtarı birden fazla JSON kaynağında mevcutsa:
+
+1. En yüksek önceliğe sahip eklenti nihai değeri belirler
+2. Daha düşük öncelikli kaynaklar, eksik anahtarlar için yedek olarak kullanılır
+3. Bu, eski çevirileri korumanıza ve yeni yapılara kademeli olarak geçiş yapmanıza olanak tanır
+
 ## CLI
 
 Eşzamanlanmış JSON dosyaları diğer `.content` dosyaları gibi kabul edilecektir. Bu, tüm intlayer komutlarının eşzamanlanmış JSON dosyaları için de kullanılabilir olduğu anlamına gelir. Şunları içerir:

package/docs/uk/plugins/sync-json.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-03-13
-updatedAt: 2025-12-13
+updatedAt: 2026-06-21
 title: Плагін Sync JSON
 description: Синхронізуйте словники Intlayer із зовнішніми i18n JSON-файлами (i18next, next-intl, react-intl, vue-i18n та ін.). Залишайте ваш існуючий i18n-стек і використовуйте Intlayer для керування, перекладу та тестування повідомлень.
 keywords:
@@ -24,6 +24,9 @@ slugs:
   - sync-json
 youtubeVideo: https://www.youtube.com/watch?v=MpGMxniDHNg
 history:
+  - version: 9.0.0
+    date: 2026-06-21
+    changes: "Додано опцію splitKeys (один словник на ключ простору імен верхнього рівня) для макетів next-intl / react-intl з одним файлом"
   - version: 7.5.0
     date: 2025-12-13
     changes: "Додано підтримку форматів ICU та i18next"
@@ -182,6 +185,7 @@ syncJSON({
   location?: string, // необов'язковий ярлик, за замовчуванням: "plugin"
   priority?: number, // необов'язковий пріоритет для вирішення конфліктів, за замовчуванням: 0
   format?: 'intlayer' | 'icu' | 'i18next', // необов'язковий форматтер, використовується для сумісності з intlayer runtime
+  splitKeys?: boolean, // необов'язково, розділяє один файл на один словник для кожного ключа простору імен верхнього рівня (автоматично визначається)
 });
 ```
 
@@ -205,6 +209,38 @@ syncJSON({
 }),
 ```
 
+#### `splitKeys` (boolean)
+
+Контролює, чи повинен один JSON-файл, **ключі першого рівня якого є просторами імен**, стати одним словником на ключ верхнього рівня, замість одного словника, що містить весь файл.
+
+Це відповідає моделі просторів імен таких бібліотек, як `next-intl` та `react-intl`, де один файл `messages/{locale}.json` групує кілька просторів імен за ключами першого рівня, кожен з яких адресується незалежно (наприклад, `useTranslations('Hero')` розв'язується до словника `Hero`).
+
+- `undefined` (за замовчуванням): **автоматично визначається** — файл розділяється, коли шаблон `source` не має сегмента `{key}` (один файл містить кожен простір імен), і залишається як єдиний словник в іншому випадку (один файл на ключ).
+- `true`: завжди розділяти кожен ключ верхнього рівня на окремий словник.
+- `false`: ніколи не розділяти; весь файл стає єдиним словником.
+
+Дано один файл `messages/{locale}.json`:
+
+```json fileName="messages/en.json"
+{
+  "Hero": { "title": "Full-stack developer" },
+  "Nav": { "work": "Work", "about": "About" },
+  "About": { "lead": "I build apps end to end." }
+}
+```
+
+```ts fileName="intlayer.config.ts"
+syncJSON({
+  format: "icu",
+  source: ({ locale }) => `./messages/${locale}.json`,
+  // splitKeys: true, // мається на увазі, оскільки шаблон не має сегмента `{key}`
+}),
+```
+
+Це створює три словники — `Hero`, `Nav` та `About` — тому `useTranslations('Hero')` (next-intl) розв'язується коректно. При зворотному записі всі простори імен знову збираються в той самий файл для кожної локалі.
+
+> Коли ви зберігаєте явний сегмент `{key}` у вашому `source` (наприклад, `./locales/${locale}/${key}.json`), кожен файл вже є одним простором імен, тому розділення за замовчуванням вимкнено.
+
 ### Кілька джерел JSON та пріоритет
 
 Ви можете додавати кілька плагінів `syncJSON` для синхронізації різних джерел JSON. Це корисно, коли у вашому проєкті використовується декілька i18n бібліотек або різні структури JSON.
@@ -337,6 +373,9 @@ loadJSON({
 
   // Необов'язковий форматувач для JSON-вмісту
   format?: 'intlayer' | 'icu' | 'i18next', // за замовчуванням: 'intlayer'
+
+  // Розділяє один файл на один словник для кожного ключа верхнього рівня (автоматично визначається)
+  splitKeys?: boolean,
 });
 ```
 
@@ -358,10 +397,25 @@ loadJSON({
 }),
 ```
 
+#### `splitKeys` (boolean)
+
+Така ж поведінка, як і в [`syncJSON`](#splitkeys-boolean): коли один JSON-файл групує кілька просторів імен за ключами першого рівня, кожен ключ верхнього рівня стає окремим словником.
+
+- `undefined` (за замовчуванням): **автоматично визначається** — розділяється, коли шаблон `source` не має сегмента `{key}`, інакше — єдиний словник.
+- `true` / `false`: примусово ввімкнути або вимкнути розділення.
+
+```ts
+loadJSON({
+  source: ({ locale }) => `./messages/${locale}.json`,
+  format: "icu",
+  // splitKeys auto-enabled: `Hero`, `Nav`, `About`, … each become a dictionary
+}),
+```
+
 ### Поведінка та конвенції
 
 - Якщо ваша маска `source` містить плейсхолдер локалі, імпортуються лише файли для обраної `locale`.
-- Якщо в масці немає сегмента `{key}`, ключ словника, "index".
+- Якщо в масці немає сегмента `{key}`, кожен ключ верхнього рівня файлу за замовчуванням стає окремим словником (див. [`splitKeys`](#splitkeys-boolean)). Встановіть `splitKeys: false`, щоб замість цього завантажити весь файл як єдиний словник `index`.
 - Ключі виводяться зі шляхів файлів шляхом підстановки плейсхолдера `{key}` у вашому source builder.
 - Плагін використовує лише виявлені файли і не створює відсутні локалі чи ключі.
 - Шлях `fill` виводиться з вашого `source` і використовується для оновлення відсутніх значень через CLI, якщо ви погодитесь.