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

package/blog/ru/next-i18next_vs_next-intl_vs_intlayer.md

@@ -61,14 +61,6 @@ author: aymericzip
 
 ---
 
-## Сравнение функций бок о бок (с фокусом на Next.js)
-
-| Функция | `next-intlayer` (Intlayer) | `next-intl` | `next-i18next` |
-
-> Значки обновляются автоматически. Снимки будут меняться со временем.
-
----
-
 ## Сравнение функций бок о бок (с акцентом на Next.js)
 
 | Функция                                                   | `next-intlayer` (Intlayer)                                                                                                                          | `next-intl`                                                                                                                     | `next-i18next`                                                                                                                  |
@@ -290,34 +282,6 @@ Next.js предоставляет встроенную поддержку ин
 
 ---
 
-## DX, инструменты и сопровождение
-
-<Columns>
-  <Column>
-
-**next-intl**
-
-- Обычно используется вместе с внешними платформами локализации и редакционными рабочими процессами.
-
-  </Column>
-  <Column>
-
-**next-i18next**
-
-- Обычно используется вместе с внешними платформами локализации и редакционными рабочими процессами.
-
-  </Column>
-  <Column>
-
-**intlayer**
-
-- Поставляется с **бесплатным Визуальным Редактором** и **опциональной CMS** (дружелюбной к Git или внешней), а также с **расширением для VSCode** и **переводами с помощью ИИ**, использующими ваши собственные ключи провайдера.
-
-  </Column>
-</Columns>
-
-**Почему это важно:** Снижает операционные затраты и сокращает цикл взаимодействия между разработчиками и авторами контента.
-
 ## Интеграция с платформами локализации (TMS)
 
 Крупные организации часто используют Системы Управления Переводами (TMS), такие как **Crowdin**, **Phrase**, **Lokalise**, **Localizely** или **Localazy**.
@@ -1187,6 +1151,127 @@ export default robots;
 
 ---
 
+### Middleware для маршрутизации локалей
+
+<Tabs defaultTab="next-intl" group='techno'>
+  <Tab label="next-i18next" value="next-i18next">
+
+Добавьте middleware для обработки определения локали и маршрутизации:
+
+```ts fileName="src/middleware.ts"
+import { NextResponse, type NextRequest } from "next/server";
+import { defaultLocale, locales } from "@/i18n.config";
+
+const PUBLIC_FILE = /\.[^/]+$/; // исключить файлы с расширениями
+
+export function middleware(request: NextRequest) {
+  const { pathname } = request.nextUrl;
+
+  if (
+    pathname.startsWith("/_next") ||
+    pathname.startsWith("/api") ||
+    pathname.startsWith("/static") ||
+    PUBLIC_FILE.test(pathname)
+  ) {
+    return;
+  }
+
+  const hasLocale = locales.some(
+    (l) => pathname === "/" + l || pathname.startsWith("/" + l + "/")
+  );
+  if (!hasLocale) {
+    const locale = defaultLocale;
+    const url = request.nextUrl.clone();
+    url.pathname = "/" + locale + (pathname === "/" ? "" : pathname);
+    return NextResponse.redirect(url);
+  }
+}
+
+export const config = {
+  matcher: [
+    // Совпадение всех путей, кроме начинающихся с этих и файлов с расширениями
+    "/((?!api|_next|static|.*\\..*).*)",
+  ],
+};
+```
+
+  </Tab>
+  <Tab label="next-intl" value="next-intl">
+
+Добавьте middleware для обработки определения локали и маршрутизации:
+
+```ts fileName="src/middleware.ts"
+import createMiddleware from "next-intl/middleware";
+import { locales, defaultLocale } from "@/i18n";
+
+export default createMiddleware({
+  locales: [...locales],
+  defaultLocale,
+  localeDetection: true,
+});
+
+export const config = {
+  // Пропустить API, Next внутренние компоненты и статические ассеты
+  matcher: ["/((?!api|_next|.*\\..*).*)"],
+};
+```
+
+  </Tab>
+  <Tab label="intlayer" value="intlayer">
+
+Intlayer предоставляет встроенную обработку middleware через конфигурацию пакета `next-intlayer`.
+
+```ts fileName="src/middleware.ts"
+import { intlayerProxy } from "next-intlayer/proxy";
+
+export const middleware = intlayerProxy();
+
+// применяет этот middleware только к файлам в директории app
+export const config = {
+  matcher: "/((?!api|_next|static|.*\\..*).*)",
+};
+```
+
+Конфигурация middleware централизована в файле `intlayer.config.ts`.
+
+  </Tab>
+</Tabs>
+
+### Контрольный список настройки и лучшие практики
+
+<Tabs defaultTab="next-intl" group='techno'>
+  <Tab label="next-i18next" value="next-i18next">
+
+- Убедитесь, что `lang` и `dir` установлены на корневом `<html>` в `src/app/[locale]/layout.tsx`.
+- Разделите переводы на пространства имен (например `common.json`, `about.json`) в `src/locales/<locale>/`.
+- Загружайте только требуемые пространства имен в клиентских компонентах с помощью `useTranslation('<ns>')` и обозначив область `I18nProvider` теми же пространствами имен.
+- Держите страницы статичными когда возможно: экспортируйте `export const dynamic = 'force-static'` на страницах; установите `dynamicParams = false` и реализуйте `generateStaticParams`.
+- Используйте синхронные серверные компоненты, вложенные под клиентские границы, передавая предварительно вычисленные строки или функцию `t` и `locale`.
+- Для SEO установите `alternates.languages` в метаданных, укажите локализованные URLs в `sitemap.ts` и запретите дублирующиеся локализованные маршруты в `robots.ts`.
+- Предпочитайте форматеры, зависящие от локали (например `Intl.NumberFormat(locale)`) и мемоизируйте их на клиенте, если используется React < 19.
+
+  </Tab>
+  <Tab label="next-intl" value="next-intl">
+
+- **Установите html `lang` и `dir`**: В `src/app/[locale]/layout.tsx` вычислите `dir` через `getLocaleDirection(locale)` и установите `<html lang={locale} dir={dir}>`.
+- **Разделите сообщения по пространствам имен**: Организуйте JSON по локали и пространству имен (например `common.json`, `about.json`).
+- **Минимизируйте полезную нагрузку клиента**: На страницах отправляйте только требуемые пространства имен в `NextIntlClientProvider` (например `pick(messages, ['common', 'about'])`).
+- **Предпочитайте статичные страницы**: Экспортируйте `export const dynamic = 'force-static'` и генерируйте статичные параметры для всех `locales`.
+- **Синхронные серверные компоненты**: Держите серверные компоненты синхронными, передавая предварительно вычисленные строки (переведенные метки, отформатированные числа) вместо асинхронных вызовов или функций, которые нельзя сериализовать.
+
+  </Tab>
+  <Tab label="intlayer" value="intlayer">
+
+- **Модульное содержимое**: Разместите словари содержимого рядом с компонентами, используя файлы `.content.{ts|js|json}`.
+- **Безопасность типов**: Используйте интеграцию TypeScript для проверки содержимого во время компиляции.
+- **Оптимизация на этапе сборки**: Используйте инструменты сборки Intlayer для автоматического tree-shaking и оптимизации пакета.
+- **Встроенные инструменты**: Используйте встроенную маршрутизацию, помощники SEO и поддержку визуального редактора.
+
+  </Tab>
+</Tabs>
+
+---
+
 ## И победитель…
 
 Это не просто. У каждого варианта есть свои компромиссы. Вот как я это вижу:

package/blog/ru/rag_powered_documentation_assistant.md

@@ -313,3 +313,16 @@ RAG, один из самых простых и мощных способов с
 </Step>
 
 </Steps>
+## Заключение
+
+RAG — один из самых простых и мощных способов сделать LLM практичными. Комбинируя **поиск + генерацию**, вы можете превратить статичную документацию в **умного помощника** и одновременно получить постоянный поток информации о продукте.
+
+Для меня этот проект показал, что RAG — это не просто технический трюк. Это способ преобразовать документацию в:
+
+- интерактивную систему поддержки
+- канал обратной связи
+- инструмент стратегии продукта
+
+👉 [Попробуйте демо здесь](https://intlayer.org/doc/why) 👉 [Посмотрите шаблон кода на GitHub](https://github.com/aymericzip/smart_doc_RAG)
+
+И если вы тоже экспериментируете с RAG, я бы с удовольствием узнал, как вы его используете.

package/blog/ru/react-i18next_vs_react-intl_vs_intlayer.md

@@ -137,6 +137,14 @@ author: aymericzip
 
 ---
 
+## Взаимодействие с `react-intl` и `react-i18next`
+
+`intlayer` также может помочь управлять вашими пространствами имен `react-intl` и `react-i18next`.
+
+Используя `intlayer`, вы можете объявлять свой контент в формате вашей любимой библиотеки i18n, и intlayer будет генерировать ваши пространства имен в выбранном вами месте (пример: `/messages/{{locale}}/{{namespace}}.json`).
+
+---
+
 ## Практические заметки по миграции (react-intl / react-i18next → Intlayer)
 
 - **Мигрируйте постепенно**: начните с одной функции или маршрута; в период перехода сохраняйте старые каталоги параллельно.

package/blog/ru/vue-i18n_vs_intlayer.md

@@ -249,6 +249,14 @@ const { greeting } = useIntlayer("component-example");
 
 ---
 
+## Interoperability with vue-i18n
+
+`intlayer` also может помочь управлять вашими `vue-i18n` namespaces.
+
+Using `intlayer`, you can declare your content in the format of your favorite i18n library, and intlayer will generate your namespaces in the location of your choice (example: `/messages/{{locale}}/{{namespace}}.json`).
+
+---
+
 ## Практические заметки по миграции (vue-i18n → Intlayer)
 
 - **Начинайте по функциям**: Переносите по одному маршруту/виду/компоненту за раз в локальные словари Intlayer.

package/blog/tr/intlayer_with_i18next.md

@@ -34,6 +34,10 @@ author: aymericzip
 
 <iframe title="i18next JSON çevirilerinizi Intlayer kullanarak nasıl otomatikleştirirsiniz" class="m-auto aspect-16/9 w-full overflow-hidden rounded-lg border-0" allow="autoplay; gyroscope;" loading="lazy" width="1080" height="auto" src="https://www.youtube.com/embed/MpGMxniDHNg?autoplay=0&amp;origin=https://intlayer.org&amp;controls=0&amp;rel=1"/>
 
+## İçindekiler
+
+<TOC/>
+
 ## Intlayer nedir?
 
 **Intlayer**, geleneksel i18n çözümlerinin eksikliklerini gidermek için tasarlanmış yenilikçi, açık kaynaklı bir uluslararasılaştırma kütüphanesidir. JavaScript uygulamalarında içerik yönetimi için modern bir yaklaşım sunar.
@@ -65,24 +69,40 @@ Bu rehber, Intlayer'ın üstün içerik beyan sistemi avantajlarından yararlan
 
 Gerekli paketleri yükleyin:
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> `--interactive` bayrağı isteğe bağlıdır. Bir yapay zeka aracısıysanız `intlayer-cli init` kullanın.
+
+> Bu komut ortamınızı algılayacak ve gerekli paketleri yükleyecektir. Örneğin:
+
 ```bash packageManager="npm"
 npm install intlayer @intlayer/sync-json-plugin --save-dev
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer @intlayer/sync-json-plugin --save-dev
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer @intlayer/sync-json-plugin --dev
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer @intlayer/sync-json-plugin --dev
-bun x intlayer init
 ```
 
 **Paket açıklamaları:**

package/blog/tr/intlayer_with_next-i18next.md

@@ -34,17 +34,6 @@ author: aymericzip
 
 <TOC/>
 
-## next-i18next nedir?
-
-**next-i18next**, Next.js uygulamaları için en popüler uluslararasılaştırma (i18n) çerçevelerinden biridir. Güçlü **i18next** ekosistemi üzerine inşa edilmiştir ve Next.js projelerinde çevirilerin yönetimi, yerelleştirme ve dil değiştirme için kapsamlı bir çözüm sunar.
-
-Ancak, next-i18next bazı zorluklarla birlikte gelir:
-
-- **Karmaşık yapılandırma**: next-i18next kurulumu, birden fazla yapılandırma dosyası gerektirir ve sunucu tarafı ile istemci tarafı i18n örneklerinin dikkatli kurulmasını gerektirir.
-- **Dağınık çeviriler**: Çeviri dosyaları genellikle bileşenlerden ayrı dizinlerde saklanır, bu da tutarlılığı korumayı zorlaştırır.
-- **Manuel isim alanı yönetimi**: Geliştiricilerin isim alanlarını manuel olarak yönetmesi ve çeviri kaynaklarının doğru şekilde yüklenmesini sağlaması gerekir.
-  /// **Sınırlı tür güvenliği**: TypeScript desteği ek yapılandırma gerektirir ve çeviriler için otomatik tür oluşturma sağlamaz.
-
 ## Intlayer Nedir?
 
 **Intlayer**, geleneksel i18n çözümlerinin eksikliklerini gidermek için tasarlanmış yenilikçi, açık kaynaklı bir uluslararasılaştırma kütüphanesidir. Next.js uygulamalarında içerik yönetimi için modern bir yaklaşım sunar.
@@ -73,24 +62,40 @@ Bu rehber, Intlayer'ın üstün içerik beyan sistemi avantajlarından yararlan
 
 Tercih ettiğiniz paket yöneticisini kullanarak gerekli paketleri yükleyin:
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> `--interactive` bayrağı isteğe bağlıdır. Bir yapay zeka aracısıysanız `intlayer-cli init` kullanın.
+
+> Bu komut ortamınızı algılayacak ve gerekli paketleri yükleyecektir. Örneğin:
+
 ```bash packageManager="npm"
 npm install intlayer @intlayer/sync-json-plugin --save-dev
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer @intlayer/sync-json-plugin --save-dev
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer @intlayer/sync-json-plugin --dev
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer @intlayer/sync-json-plugin --dev
-bun x intlayer init
 ```
 
 **Paket açıklamaları:**

package/blog/tr/intlayer_with_next-intl.md

@@ -29,6 +29,10 @@ author: aymericzip
 
 <iframe title="Intlayer kullanarak next-intl JSON çevirilerinizi nasıl otomatikleştirirsiniz" class="m-auto aspect-16/9 w-full overflow-hidden rounded-lg border-0" allow="autoplay; gyroscope;" loading="lazy" width="1080" height="auto" src="https://www.youtube.com/embed/MpGMxniDHNg?autoplay=0&amp;origin=https://intlayer.org&amp;controls=0&amp;rel=1"/>
 
+# İçindekiler Tablosu
+
+<TOC/>
+
 ## Intlayer nedir?
 
 **Intlayer**, geleneksel i18n çözümlerinin eksikliklerini gidermek için tasarlanmış yenilikçi, açık kaynaklı bir uluslararasılaştırma kütüphanesidir. Next.js uygulamalarında içerik yönetimi için modern bir yaklaşım sunar.
@@ -60,24 +64,40 @@ Bu rehber, Intlayer'ın üstün içerik beyan sistemi avantajlarından yararlan
 
 Gerekli paketleri yükleyin:
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> `--interactive` bayrağı isteğe bağlıdır. Bir yapay zeka aracısıysanız `intlayer-cli init` kullanın.
+
+> Bu komut ortamınızı algılayacak ve gerekli paketleri yükleyecektir. Örneğin:
+
 ```bash packageManager="npm"
 npm install intlayer @intlayer/sync-json-plugin --save-dev
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer @intlayer/sync-json-plugin --save-dev
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer @intlayer/sync-json-plugin --dev
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer @intlayer/sync-json-plugin --dev
-bun x intlayer init
 ```
 
 **Paket açıklamaları:**

package/blog/tr/intlayer_with_react-i18next.md

@@ -63,24 +63,40 @@ Bu rehber, Intlayer'ın üstün içerik beyan sistemi kullanılırken react-i18n
 
 Gerekli paketleri yükleyin:
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> `--interactive` bayrağı isteğe bağlıdır. Bir yapay zeka aracısıysanız `intlayer-cli init` kullanın.
+
+> Bu komut ortamınızı algılayacak ve gerekli paketleri yükleyecektir. Örneğin:
+
 ```bash packageManager="npm"
 npm install intlayer @intlayer/sync-json-plugin --save-dev
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer @intlayer/sync-json-plugin --save-dev
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer @intlayer/sync-json-plugin --dev
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer @intlayer/sync-json-plugin --dev
-bun x intlayer init
 ```
 
 **Paket açıklamaları:**

package/blog/tr/intlayer_with_react-intl.md

@@ -62,24 +62,40 @@ Bu rehber, react-intl ile uyumluluğu korurken Intlayer'ın üstün içerik beya
 
 Gerekli paketleri yükleyin:
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> `--interactive` bayrağı isteğe bağlıdır. Bir yapay zeka aracısıysanız `intlayer-cli init` kullanın.
+
+> Bu komut ortamınızı algılayacak ve gerekli paketleri yükleyecektir. Örneğin:
+
 ```bash packageManager="npm"
 npm install intlayer @intlayer/sync-json-plugin --save-dev
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer @intlayer/sync-json-plugin --save-dev
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer @intlayer/sync-json-plugin --dev
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer @intlayer/sync-json-plugin --dev
-bun x intlayer init
 ```
 
 **Paket açıklamaları:**

package/blog/tr/intlayer_with_vue-i18n.md

@@ -63,24 +63,40 @@ Bu rehber, Intlayer'ın üstün içerik beyan sistemi avantajlarından yararlan
 
 Tercih ettiğiniz paket yöneticisini kullanarak gerekli paketleri yükleyin:
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> `--interactive` bayrağı isteğe bağlıdır. Bir yapay zeka aracısıysanız `intlayer-cli init` kullanın.
+
+> Bu komut ortamınızı algılayacak ve gerekli paketleri yükleyecektir. Örneğin:
+
 ```bash packageManager="npm"
 npm install intlayer @intlayer/sync-json-plugin --save-dev
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer @intlayer/sync-json-plugin --save-dev
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer @intlayer/sync-json-plugin --dev
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer @intlayer/sync-json-plugin --dev
-bun x intlayer init
 ```
 
 **Paket açıklamaları:**