@intlayer/docs 7.0.3 → 7.0.4

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

@@ -0,0 +1,244 @@
+---
+createdAt: 2025-03-13
+updatedAt: 2025-10-05
+title: Плагин синхронизации JSON
+description: Синхронизируйте словари Intlayer с JSON-файлами сторонних i18n (i18next, next-intl, react-intl, vue-i18n и другими). Сохраняйте существующую i18n, используя Intlayer для управления, перевода и тестирования ваших сообщений.
+keywords:
+  - Intlayer
+  - Синхронизация JSON
+  - i18next
+  - next-intl
+  - react-intl
+  - vue-i18n
+  - next-translate
+  - nuxt-i18n
+  - LinguiJS
+  - Polyglot.js
+  - Solid-i18next
+  - svelte-i18n
+  - i18n
+  - переводы
+slugs:
+  - doc
+  - plugin
+  - sync-json
+history:
+  - version: 6.1.6
+    date: 2025-10-05
+    changes: Начальная документация плагина синхронизации JSON
+---
+
+## Синхронизация JSON (мосты i18n)
+
+Используйте Intlayer в качестве дополнения к вашему существующему стеку i18n. Этот плагин поддерживает синхронизацию ваших JSON-сообщений со словарями Intlayer, чтобы вы могли:
+
+- Сохранять использование i18next, next-intl, react-intl, vue-i18n, next-translate, nuxt-i18n, Solid-i18next, svelte-i18n и других.
+- Управлять и переводить ваши сообщения с помощью Intlayer (CLI, CI, провайдеры, CMS), без необходимости рефакторинга вашего приложения.
+- Публиковать обучающие материалы и SEO-контент, ориентированный на каждую экосистему, предлагая Intlayer в качестве слоя управления JSON.
+
+Примечания и текущий охват:
+
+- Внешняя интеграция с CMS работает для переводов и классического текста.
+- Пока нет поддержки вставок, множественного числа/ICU или продвинутых функций времени выполнения других библиотек.
+- Визуальный редактор пока не поддерживается для вывода сторонних i18n.
+
+### Когда использовать этот плагин
+
+- Вы уже используете библиотеку i18n и храните сообщения в JSON-файлах.
+- Вы хотите использовать заполнение с помощью ИИ, тестирование в CI и управление контентом без изменения вашего runtime для рендеринга.
+
+## Установка
+
+```bash
+pnpm add -D @intlayer/sync-json-plugin
+# или
+npm i -D @intlayer/sync-json-plugin
+```
+
+## Быстрый старт
+
+Добавьте плагин в ваш `intlayer.config.ts` и укажите путь к вашей существующей структуре JSON.
+
+```ts fileName="intlayer.config.ts"
+import { defineConfig, Locales } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+export default defineConfig({
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  // Синхронизируйте ваши текущие JSON-файлы со словарями Intlayer
+  plugins: [
+    syncJSON({
+      // Макет по локалям и пространствам имён (например, next-intl, i18next с пространствами имён)
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+    }),
+  ],
+});
+```
+
+Альтернатива: один файл на локаль (распространено в настройках i18next/react-intl):
+
+```ts fileName="intlayer.config.ts"
+plugins: [
+  syncJSON({
+    source: ({ locale }) => `./locales/${locale}.json`,
+  }),
+];
+```
+
+### Как это работает
+
+- Чтение: плагин обнаруживает JSON-файлы с помощью вашего билдера `source` и загружает их как словари Intlayer.
+- Запись: после сборок и заполнения он записывает локализованные JSON обратно по тем же путям (с завершающим переводом строки, чтобы избежать проблем с форматированием).
+- Автозаполнение: плагин объявляет путь `autoFill` для каждого словаря. Запуск `intlayer fill` по умолчанию обновляет только отсутствующие переводы в ваших JSON-файлах.
+
+API:
+
+```ts
+syncJSON({
+  source: ({ key, locale }) => string, // обязательно
+  location?: string, // необязательная метка, по умолчанию: "plugin"
+  priority?: number, // необязательный приоритет для разрешения конфликтов, по умолчанию: 0
+});
+```
+
+## Несколько источников JSON и приоритет
+
+Вы можете добавить несколько плагинов `syncJSON` для синхронизации разных источников JSON. Это полезно, если в вашем проекте используются несколько библиотек i18n или разные структуры JSON.
+
+### Система приоритетов
+
+Когда несколько плагинов нацелены на один и тот же ключ словаря, параметр `priority` определяет, какой плагин имеет преимущество:
+
+- Побеждает плагин с более высоким числом приоритета
+- Приоритет по умолчанию для файлов `.content` равен `0`
+- Приоритет по умолчанию для файлов плагинов равен `-1`
+- Плагины с одинаковым приоритетом обрабатываются в порядке их появления в конфигурации
+
+```ts fileName="intlayer.config.ts"
+import { defineConfig, Locales } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+export default defineConfig({
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  plugins: [
+    // Основной источник JSON (наивысший приоритет)
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      location: "main-translations",
+      priority: 10,
+    }),
+
+    // Резервный источник JSON (низший приоритет)
+    syncJSON({
+      source: ({ locale }) => `./fallback-locales/${locale}.json`,
+      location: "fallback-translations",
+      priority: 5,
+    }),
+
+    // Источник устаревших JSON (самый низкий приоритет)
+    syncJSON({
+      source: ({ locale }) => `/my/other/app/legacy/${locale}/messages.json`,
+      location: "legacy-translations",
+      priority: 1,
+    }),
+  ],
+});
+```
+
+### Разрешение конфликтов
+
+Когда один и тот же ключ перевода присутствует в нескольких JSON-источниках:
+
+1. Плагин с наивысшим приоритетом определяет итоговое значение
+2. Источники с более низким приоритетом используются как резервные для отсутствующих ключей
+3. Это позволяет поддерживать устаревшие переводы, постепенно переходя на новые структуры
+
+## Интеграции
+
+Ниже приведены распространённые сопоставления. Не изменяйте ваше окружение выполнения; просто добавьте плагин.
+
+### i18next
+
+Типичная структура файлов: `./public/locales/{locale}/{namespace}.json` или `./locales/{locale}/{namespace}.json`.
+
+```ts fileName="intlayer.config.ts"
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+export default {
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+    }),
+  ],
+};
+```
+
+### next-intl
+
+JSON-сообщения для каждого локаля (часто `./messages/{locale}.json`) или по namespace.
+
+```ts fileName="intlayer.config.ts"
+plugins: [
+  syncJSON({
+    source: ({ locale, key }) => `./messages/${locale}/${key}.json`,
+  }),
+];
+```
+
+См. также: `docs/ru/intlayer_with_next-intl.md`.
+
+### react-intl
+
+Обычно используется один JSON на локаль:
+
+```ts fileName="intlayer.config.ts"
+plugins: [
+  syncJSON({
+    source: ({ locale }) => `./locales/${locale}.json`,
+  }),
+];
+```
+
+### vue-i18n
+
+Либо один файл на локаль, либо по пространствам имён:
+
+```ts fileName="intlayer.config.ts"
+plugins: [
+  syncJSON({
+    source: ({ key, locale }) => `./src/locales/${locale}/${key}.json`, // источник файлов локализации
+  }),
+];
+```
+
+## CLI
+
+Синхронизированные JSON-файлы будут рассматриваться как другие файлы с расширением `.content`. Это означает, что все команды intlayer будут доступны для синхронизированных JSON-файлов, включая:
+
+- `intlayer content test` для проверки отсутствующих переводов
+- `intlayer content list` для вывода списка синхронизированных JSON-файлов
+- `intlayer content fill` для заполнения отсутствующих переводов
+- `intlayer content push` для отправки синхронизированных JSON-файлов
+- `intlayer content pull` для загрузки синхронизированных JSON-файлов
+
+См. [Intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/intlayer_cli.md) для получения дополнительной информации.
+
+## Ограничения (текущие)
+
+- Нет поддержки вставок или множественного числа/ICU при работе с библиотеками третьих сторон.
+- Визуальный редактор пока недоступен для сред выполнения, не являющихся Intlayer.
+- Синхронизация только JSON; форматы каталогов, не являющиеся JSON, не поддерживаются.
+
+## Почему это важно
+
+- Мы можем рекомендовать проверенные решения i18n и позиционировать Intlayer как дополнение.
+- Мы используем их SEO/ключевые слова с помощью руководств, которые заканчиваются предложением использовать Intlayer для управления JSON.
+- Расширяет целевую аудиторию с «новых проектов» до «любых команд, уже использующих i18n».

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

@@ -0,0 +1,245 @@
+---
+createdAt: 2025-03-13
+updatedAt: 2025-10-05
+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:
+  - Intlayer
+  - JSON Senkronizasyonu
+  - i18next
+  - next-intl
+  - react-intl
+  - vue-i18n
+  - next-translate
+  - nuxt-i18n
+  - LinguiJS
+  - Polyglot.js
+  - Solid-i18next
+  - svelte-i18n
+  - i18n
+  - çeviriler
+slugs:
+  - doc
+  - plugin
+  - sync-json
+history:
+  - version: 6.1.6
+    date: 2025-10-05
+    changes: İlk JSON Senkronizasyon Eklentisi dokümantasyonu
+---
+
+# JSON Senkronizasyonu (i18n köprüleri)
+
+Intlayer'ı mevcut i18n yapınıza bir eklenti olarak kullanın. Bu eklenti, JSON mesajlarınızı Intlayer sözlükleriyle senkronize tutar, böylece:
+
+- i18next, next-intl, react-intl, vue-i18n, next-translate, nuxt-i18n, Solid-i18next, svelte-i18n vb. kullanmaya devam edebilirsiniz.
+- Uygulamanızı yeniden yapılandırmadan Intlayer (CLI, CI, sağlayıcılar, CMS) ile mesajlarınızı yönetip çevirebilirsiniz.
+- Her ekosistemi hedefleyen eğitimler ve SEO içerikleri sunabilir, aynı zamanda Intlayer'ı JSON yönetim katmanı olarak önerebilirsiniz.
+
+Notlar ve mevcut kapsam:
+
+- CMS'ye dışa aktarma, çeviriler ve klasik metinler için çalışır.
+- Henüz eklemeler, çoğullar/ICU veya diğer kütüphanelerin gelişmiş çalışma zamanı özellikleri desteklenmemektedir.
+- Görsel editör, üçüncü taraf i18n çıktıları için henüz desteklenmemektedir.
+
+### Bu eklenti ne zaman kullanılmalı
+
+- Zaten bir i18n kütüphanesi kullanıyor ve mesajları JSON dosyalarında saklıyorsunuz.
+- Rendering çalışma zamanınızı değiştirmeden AI destekli doldurma, CI'da test ve içerik operasyonları yapmak istiyorsunuz.
+
+## Kurulum
+
+```bash
+pnpm add -D @intlayer/sync-json-plugin
+# veya
+npm i -D @intlayer/sync-json-plugin
+```
+
+## Hızlı başlangıç
+
+Eklentiyi `intlayer.config.ts` dosyanıza ekleyin ve mevcut JSON yapınıza işaret edin.
+
+```ts fileName="intlayer.config.ts"
+import { defineConfig, Locales } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+export default defineConfig({
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  // Mevcut JSON dosyalarınızı Intlayer sözlükleriyle senkronize tutun
+  plugins: [
+    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`,
+    }),
+  ],
+});
+```
+
+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`,
+  }),
+];
+```
+
+### 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).
+- Otomatik doldurma: eklenti, her sözlük için bir `autoFill` yolu belirtir. `intlayer fill` komutunu çalıştırmak, JSON dosyalarınızdaki yalnızca eksik çevirileri varsayılan olarak günceller.
+
+API:
+
+```ts
+syncJSON({
+  source: ({ key, locale }) => string, // zorunlu
+  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
+});
+```
+
+## Birden fazla JSON kaynağı ve öncelik
+
+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
+
+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
+- Aynı önceliğe sahip eklentiler, yapılandırmada göründükleri sırayla işlenir
+
+```ts fileName="intlayer.config.ts"
+import { defineConfig, Locales } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+export default defineConfig({
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  plugins: [
+    // Birincil JSON kaynağı (en yüksek öncelik)
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      location: "main-translations",
+      priority: 10,
+    }),
+
+    // Yedek JSON kaynağı (daha düşük öncelik)
+    syncJSON({
+      source: ({ locale }) => `./fallback-locales/${locale}.json`,
+      location: "fallback-translations",
+      priority: 5,
+    }),
+
+    // Eski JSON kaynağı (en düşük öncelik)
+    syncJSON({
+      source: ({ locale }) => `/my/other/app/legacy/${locale}/messages.json`,
+      location: "legacy-translations",
+      priority: 1,
+    }),
+  ],
+});
+```
+
+### Çakışma çözümü
+
+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
+
+## Entegrasyonlar
+
+Aşağıda yaygın eşlemeler bulunmaktadır. Çalışma zamanınızı değiştirmeyin; sadece eklentiyi ekleyin.
+
+### i18next
+
+Tipik dosya düzeni: `./public/locales/{locale}/{namespace}.json` veya `./locales/{locale}/{namespace}.json`.
+
+```ts fileName="intlayer.config.ts"
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+export default {
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+    }),
+  ],
+};
+```
+
+### next-intl
+
+Her yerel için JSON mesajları (genellikle `./messages/{locale}.json`) veya her ad alanı için.
+
+```ts fileName="intlayer.config.ts"
+plugins: [
+  syncJSON({
+    source: ({ locale, key }) => `./messages/${locale}/${key}.json`,
+  }),
+];
+```
+
+Ayrıca bakınız: `docs/tr/intlayer_with_next-intl.md`.
+
+### react-intl
+
+Her yerel için tek JSON yaygındır:
+
+```ts fileName="intlayer.config.ts"
+plugins: [
+  syncJSON({
+    source: ({ locale }) => `./locales/${locale}.json`,
+  }),
+];
+```
+
+### vue-i18n
+
+Her yerel için ya da her ad alanı için tek bir dosya olabilir:
+
+```ts fileName="intlayer.config.ts"
+plugins: [
+  syncJSON({
+    source: ({ key, locale }) => `./src/locales/${locale}/${key}.json`,
+  }),
+];
+```
+
+## 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:
+
+- Eksik çevirilerin olup olmadığını test etmek için `intlayer content test`
+- Eşzamanlanmış JSON dosyalarını listelemek için `intlayer content list`
+- Eksik çevirileri doldurmak için `intlayer content fill`
+- Eşzamanlanmış JSON dosyalarını göndermek için `intlayer content push`
+- Eşzamanlanmış JSON dosyalarını çekmek için `intlayer content pull`
+
+Daha fazla detay için [Intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/intlayer_cli.md) sayfasına bakınız.
+
+## Sınırlamalar (mevcut)
+
+- Üçüncü taraf kütüphaneler hedeflendiğinde ekleme veya çoğul/ICU desteği yoktur.
+- Görsel editör henüz Intlayer dışı çalışma zamanları için mevcut değildir.
+- Sadece JSON senkronizasyonu; JSON olmayan katalog formatları desteklenmemektedir.
+
+## Neden bu önemli
+
+- Yerleşik i18n çözümlerini önerebilir ve Intlayer'ı bir eklenti olarak konumlandırabiliriz.
+- JSON yönetimi için Intlayer öneren eğitimlerle onların SEO/anahtar kelimelerinden faydalanırız.
+- Hedef kitlesini “yeni projeler”den “zaten i18n kullanan herhangi bir ekip”e genişletir.