@intlayer/docs 9.0.0-canary.14 → 9.0.0-canary.16

package/docs/pt/live-sync.md

@@ -0,0 +1,174 @@
+---
+createdAt: 2026-07-08
+updatedAt: 2026-07-08
+title: Sincronização ao vivo | Reflita as alterações de conteúdo do CMS em tempo real
+description: Permita que sua aplicação reflita as alterações de conteúdo do CMS Intlayer em tempo de execução, sem necessidade de rebuild ou reimplantação.
+keywords:
+  - Sincronização ao vivo
+  - Live Sync
+  - CMS
+  - Editor Visual
+  - Internacionalização
+  - Documentação
+  - Intlayer
+  - Next.js
+  - Vite
+history:
+  - version: 9.0.0
+    date: 2026-07-08
+    changes: "Movido da documentação do CMS Intlayer para sua própria página"
+  - version: 6.0.1
+    date: 2025-09-22
+    changes: "Adiciona documentação sobre live sync"
+  - version: 6.0.0
+    date: 2025-09-04
+    changes: "Substitui o campo `hotReload` por `liveSync`"
+author: aymericzip
+---
+
+# Sincronização ao vivo
+
+A Sincronização ao Vivo permite que a sua aplicação reflita as alterações de conteúdo do CMS em tempo de execução. Não é necessário reconstruir ou reimplantar. Quando ativada, as atualizações são transmitidas para um servidor de Sincronização ao Vivo que atualiza os dicionários que a sua aplicação lê.
+
+## Tabela de conteúdos
+
+<TOC/>
+
+---
+
+## Ativar a sincronização ao vivo
+
+> A Sincronização ao Vivo requer uma conexão contínua com o servidor e está disponível no plano enterprise.
+
+Ative a Sincronização ao Vivo atualizando a sua configuração Intlayer:
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  // ... outras configurações
+  editor: {
+    /**
+     * Ativa o recarregamento a quente das configurações de localidade quando são detetadas alterações.
+     * Por exemplo, quando um dicionário é adicionado ou atualizado, a aplicação atualiza
+     * o conteúdo exibido na página.
+     *
+     * Como o recarregamento a quente requer uma conexão contínua com o servidor, está
+     * disponível apenas para clientes do plano `enterprise`.
+     *
+     * Padrão: false
+     */
+    liveSync: true,
+  },
+  dictionary: {
+    /**
+     * Controla como os dicionários são importados:
+     *
+     * - "live": Os dicionários são buscados dinamicamente usando a API de Sincronização ao Vivo.
+     *   Substitui useIntlayer por useDictionaryDynamic.
+     *
+     * Nota: O modo live usa a API de Sincronização ao Vivo para buscar os dicionários. Se a chamada da API
+     * falhar, os dicionários são importados dinamicamente.
+     * Nota: Apenas dicionários com conteúdo remoto e sinalizadores "live" usam o modo live.
+     * Outros usam o modo dinâmico para melhor desempenho.
+     */
+    importMode: "fetch",
+  },
+};
+
+export default config;
+```
+
+Inicie o servidor Live Sync para envolver sua aplicação:
+
+Exemplo usando Next.js:
+
+```json5 fileName="package.json"
+{
+  "scripts": {
+    // ... outros scripts
+    "build": "next build",
+    "dev": "next dev",
+    "start": "npx intlayer live --with 'next start'",
+  },
+}
+```
+
+Exemplo usando Vite:
+
+```json5 fileName="package.json"
+{
+  "scripts": {
+    // ... outros scripts
+    "build": "vite build",
+    "dev": "vite dev",
+    "start": "npx intlayer live --with 'vite start'",
+  },
+}
+```
+
+O servidor Live Sync envolve sua aplicação e aplica automaticamente o conteúdo atualizado assim que ele chega.
+
+Para receber notificações de alterações do CMS, o servidor Live Sync mantém uma conexão SSE com o backend. Quando o conteúdo muda no CMS, o backend encaminha a atualização para o servidor Live Sync, que grava os novos dicionários. Sua aplicação refletirá a atualização na próxima navegação ou recarregamento do navegador, sem necessidade de reconstrução.
+
+Fluxograma (CMS/Backend -> Servidor Live Sync -> Servidor de Aplicação -> Frontend):
+
+![Esquema Lógico do Live Sync](https://github.com/aymericzip/intlayer/blob/main/docs/assets/live_sync_logic_schema.svg)
+
+Como funciona:
+
+![Fluxo Live Sync CMS/Backend/Servidor Live Sync/Servidor de Aplicação/Frontend](https://github.com/aymericzip/intlayer/blob/main/docs/assets/live_sync_flow_scema.svg)
+
+## Fluxo de trabalho de desenvolvimento (local)
+
+- Em desenvolvimento, todos os dicionários remotos são buscados quando a aplicação inicia, para que você possa testar atualizações rapidamente.
+- Para testar o Live Sync localmente com Next.js, envolva seu servidor de desenvolvimento:
+
+```json5 fileName="package.json"
+{
+  "scripts": {
+    // ... outros scripts
+    "dev": "npx intlayer live --with 'next dev'",
+    // "dev": "npx intlayer live --with 'vite dev'", // Para Vite
+  },
+}
+```
+
+Habilite a otimização para que o Intlayer aplique as transformações de importação Live durante o desenvolvimento:
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  editor: {
+    applicationURL: "http://localhost:5173",
+    liveSyncURL: "http://localhost:4000",
+    liveSync: true,
+  },
+  dictionary: {
+    importMode: "fetch",
+  },
+  build: {
+    optimize: true,
+  },
+};
+
+export default config;
+```
+
+Esta configuração envolve seu servidor de desenvolvimento com o servidor Live Sync, busca dicionários remotos na inicialização e transmite atualizações do CMS via SSE. Atualize a página para ver as mudanças.
+
+## Notas e restrições
+
+- Adicione a origem do live sync à política de segurança do seu site (CSP). Certifique-se de que a URL do live sync esteja permitida em `connect-src` (e `frame-ancestors`, se relevante).
+- O Live Sync não funciona com saída estática. Para Next.js, a página deve ser dinâmica para receber atualizações em tempo de execução (por exemplo, use `generateStaticParams`, `generateMetadata`, `getServerSideProps` ou `getStaticProps` adequadamente para evitar restrições de somente estático).
+- No CMS, cada dicionário possui uma flag `live`. Apenas dicionários com `live=true` são buscados via API de sincronização ao vivo; os demais são importados dinamicamente e permanecem inalterados em tempo de execução.
+- A flag `live` é avaliada para cada dicionário no momento da compilação. Se o conteúdo remoto não foi marcado como `live=true` durante a compilação, você deve recompilar para habilitar a Sincronização ao Vivo para esse dicionário.
+- O servidor de sincronização ao vivo deve ter permissão para escrever em `.intlayer`. Em contêineres, assegure o acesso de escrita a `/.intlayer`.
+
+## Links úteis
+
+- [CMS Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_CMS.md)
+- [Editor Visual do Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_visual_editor.md)
+- [Referência de configuração](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/configuration.md)
+- [Guia de Auto-hospedagem](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/self_hosting.md)

package/docs/pt/releases/v9.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-06-14
-updatedAt: 2026-06-30
+updatedAt: 2026-07-08
 title: Novo Intlayer v9 - O que há de novo?
 description: Descubra o que há de novo no Intlayer v9. Apresentando pacotes de compatibilidade drop-in para bibliotecas i18n populares e suporte para Collections e Variants.
 keywords:
@@ -205,6 +205,49 @@ const product = useIntlayer("product-copy", {
 
 ---
 
+## `@intlayer/analytics`: rastreamento de exposição de conteúdo e testes A/B
+
+Um novo pacote opcional, [`@intlayer/analytics`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/analytics.md), mostra qual conteúdo é realmente exibido aos seus visitantes — e fecha o ciclo com **Collections & Variants**, permitindo testar conteúdo em A/B e medir conversões por variante.
+
+- **Rastreamento em nível de provider**: `IntlayerProvider` (React / Next.js / React Native) registra automaticamente eventos `page_view` no carregamento, na mudança de rota e na mudança de idioma.
+- **Rastreamento em nível de nó**: cada resolução de `useIntlayer` reporta um evento `content_exposure` — qual chave de dicionário, caminho de chave, idioma e, quando aplicável, qual **variante** A/B foi exibida. Exposições repetidas do mesmo nó dentro de uma janela de envio são combinadas em um único evento.
+- **Atribuição determinística de A/B**: `getVariant(experimentKey, variants)` atribui uma variante a cada sessão **sem ida e volta ao servidor**, portanto não há cintilação antes da primeira renderização.
+- **`useConversion()`**: atribui uma meta (cadastro, clique, compra…) à variante à qual a sessão foi exposta.
+- **Custo zero quando não instalado**: mesmo padrão tree-shakeable do `@intlayer/editor` — `import()` dinâmico envolto em `try/catch`, mais uma variável de ambiente em tempo de compilação (`INTLAYER_ANALYTICS_ENABLED`) que elimina completamente a integração do bundle para apps que não a ativam.
+- **Sem novo esquema de configuração**: reutiliza `editor.backendURL` (endpoint de ingestão / auto-hospedagem) e `editor.clientId` (chave do projeto, também o interruptor de ativação).
+- **Respeita a privacidade**: hash anônimo de sessão (SHA-256, sem armazenar ids brutos), sem armazenamento de IP, geolocalização aproximada apenas por país, requisições enviadas em lote a cada ~20 segundos.
+- **Painel**: uma nova página **Analytics** (exibida na barra lateral assim que um projeto é selecionado) mostra usuários ativos, usuários de hoje, usuários dos últimos 7/30/90 dias, um gráfico de evolução de visitantes e a divisão por idioma e localização.
+
+```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",
+        })
+      }
+    >
+      Get started
+    </button>
+  );
+};
+```
+
+```bash packageManager="npm"
+npm install @intlayer/analytics
+```
+
+Já disponível para React, Next.js e React Native (via `react-intlayer`); outras integrações de frameworks (Vue, Svelte, Angular, …) estão planejadas, seguindo o mesmo padrão de lançamento do `@intlayer/editor`. Consulte a [documentação do Analytics](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/analytics.md) para o guia completo.
+
+---
+
 ## Vite Plugin: Compilador Agrupado & Proxy
 
 O plugin Vite `intlayer()` agora agrupa o **compilador** e o **proxy de roteamento de localidade** diretamente, então a maioria dos projetos precisa apenas de um único plugin em `vite.config.ts`:
@@ -353,6 +396,7 @@ Se você estiver atualizando da v8, observe que a v9 não inclui breaking change
 
 - [Guia de Compat Adapter Packages](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/compat/index.md)
 - [Dicionários Dinâmicos - Collections & Variants](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dynamic_dictionaries/index.md)
+- [Analytics - Rastreamento de exposição de conteúdo e testes A/B](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/analytics.md)
 - [Referência de Configuração](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/configuration.md)
 - [SDK do CMS - Acesso programático com @intlayer/api](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_CMS.md)
 - [Guia de Auto-hospedagem](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/self_hosting.md)

package/docs/ru/cli/index.md

@@ -125,7 +125,7 @@ Intlayer принимает несколько форматов файлов к
 
 ### Аутентификация
 
-- **[Login](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/login.md)** - Аутентификация в Intlayer CMS и получение учетных данных для доступа
+- **[Login](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/cli/login.md)** - Аутентификация в Intlayer CMS и получение учетных данных для доступа
 
 ### Основные команды
 

package/docs/ru/configuration.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-13
-updatedAt: 2026-06-23
+updatedAt: 2026-07-11
 title: Конфигурация (Configuration)
 description: Узнайте, как настроить Intlayer для вашего приложения. Разберитесь в различных параметрах и опциях, доступных для настройки Intlayer в соответствии с вашими потребностями.
 keywords:
@@ -14,6 +14,9 @@ slugs:
   - concept
   - configuration
 history:
+  - version: 9.0.0
+    date: 2026-07-11
+    changes: "Добавлена конфигурация `analytics`"
   - version: 9.0.0
     date: 2026-06-24
     changes: "Add `enableProxy` option to the routing configuration"
@@ -355,6 +358,30 @@ const config: IntlayerConfig = {
     liveSync: true,
   },
 
+  /**
+   * Конфигурация аналитики (analytics).
+   */
+  analytics: {
+    /**
+     * Включён ли сбор аналитики (просмотры страниц, показы контента, события A/B).
+     * Требует, чтобы был задан `editor.clientId` для атрибуции.
+     * По умолчанию: false
+     */
+    enabled: true,
+
+    /**
+     * Миллисекунды между автоматическими пакетными отправками на бэкенд.
+     * По умолчанию: 20000
+     */
+    flushInterval: 20000,
+
+    /**
+     * Доля сессий для записи, от 0 (ни одной) до 1 (все).
+     * По умолчанию: 1
+     */
+    sampleRate: 1,
+  },
+
   /**
    * Настройки переводов и генерации с помощью ИИ.
    */
@@ -668,6 +695,20 @@ export default config;
 
 ---
 
+### Конфигурация аналитики (Analytics)
+
+Определяет настройки, связанные с аналитикой Intlayer: сбор данных о том, какой контент действительно показывается пользователям (просмотры страниц, показы контента), и поддержку A/B-тестирования контента.
+
+Аналитика строго опциональна (opt-in): ничего не собирается, если `analytics.enabled` явно не установлен в `true` **и** не настроен ключ проекта (`editor.clientId`) для атрибуции. При отключении (по умолчанию) вся интеграция аналитики удаляется из сборки вашего приложения (dead-code elimination).
+
+| Поле            | Описание                                                                   | Тип       | По умолчанию | Пример  | Примечание                                                                                                                        |
+| --------------- | -------------------------------------------------------------------------- | --------- | ------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `enabled`       | Включает сбор аналитики (просмотры страниц, показы контента, события A/B). | `boolean` | `false`      | `true`  | Требует, чтобы был задан `editor.clientId` для атрибуции; иначе аналитика остаётся отключённой, даже если `enabled` равно `true`. |
+| `flushInterval` | Миллисекунды между автоматическими пакетными отправками на бэкенд.         | `number`  | `20000`      | `10000` |                                                                                                                                   |
+| `sampleRate`    | Доля сессий для записи, от `0` (ни одной) до `1` (все).                    | `number`  | `1`          | `0.5`   | Выборка детерминирована для каждой сессии, поэтому записанная сессия сообщает обо всех своих событиях (без частичных воронок).    |
+
+---
+
 ### Конфигурация маршрутизации (Routing)
 
 Настройки, управляющие поведением маршрутизации, включая структуру URL, хранение языков и управление middleware.

package/docs/ru/intlayer_CMS.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-08-23
-updatedAt: 2026-06-30
+updatedAt: 2026-07-08
 title: Intlayer CMS | Внешнее управление контентом через Intlayer CMS
 description: Внешнее управление вашим контентом через Intlayer CMS для делегирования управления контентом вашей команде.
 keywords:
@@ -18,6 +18,9 @@ slugs:
   - cms
 youtubeVideo: https://www.youtube.com/watch?v=UDDTnirwi_4
 history:
+  - version: 9.0.0
+    date: 2026-07-08
+    changes: "Раздел «Живая синхронизация» перенесён на отдельную страницу (live-sync.md); здесь оставлено краткое введение со ссылкой"
   - version: 9.0.0
     date: 2026-06-30
     changes: "Добавлен раздел «Самостоятельное размещение»: начальная загрузка Docker Compose, инвентаризация сервисов, конфигурация SDK, необязательные функции и примечания по обновлению"
@@ -403,144 +406,7 @@ await pushDictionaries([{ key: "home", content: { title: "Home" } }]);
 
 Живая синхронизация позволяет вашему приложению отражать изменения контента CMS в режиме реального времени. Пересборка или повторный деплой не требуются. Когда функция включена, обновления передаются на сервер живой синхронизации, который обновляет словари, используемые вашим приложением.
 
-Включите живую синхронизацию, обновив конфигурацию Intlayer:
-
-```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
-import type { IntlayerConfig } from "intlayer";
-
-const config: IntlayerConfig = {
-  // ... другие настройки конфигурации
-  editor: {
-    /**
-     * Включает горячую перезагрузку конфигураций локалей при обнаружении изменений.
-     * Например, когда словарь добавляется или обновляется, приложение обновляет
-     * отображаемый на странице контент.
-     *
-     * Поскольку горячая перезагрузка требует постоянного подключения к серверу,
-     * она доступна только для клиентов с тарифным планом `enterprise`.
-     *
-     * По умолчанию: false
-     */
-    liveSync: true,
-  },
-  dictionary: {
-    /**
-     * Управляет способом импорта словарей:
-     *
-     * - "fetch": словари загружаются динамически с использованием Live Sync API.
-     *   Заменяет useIntlayer на useDictionaryDynamic.
-     *
-     * Примечание: Режим "fetch" использует Live Sync API для загрузки словарей. Если вызов API
-     * не удаётся, словари импортируются динамически.
-     * Примечание: Только словари с удалённым содержимым и флагом "live" используют режим "fetch".
-     * Остальные используют динамический режим для повышения производительности.
-     */
-    importMode: "fetch",
-  },
-};
-
-export default config;
-```
-
-Запустите сервер Live Sync, чтобы обернуть ваше приложение:
-
-Пример использования автономного сервера:
-
-```json5 fileName="package.json"
-{
-  "scripts": {
-    // ... other scripts
-    "live:start": "npx intlayer live",
-  },
-}
-```
-
-Вы также можете использовать сервер вашего приложения параллельно, используя аргумент `--process`.
-
-Пример с использованием Next.js:
-
-```json5 fileName="package.json"
-{
-  "scripts": {
-    // ... другие скрипты
-    "build": "next build",
-    "dev": "next dev",
-    "start": "npx intlayer live --with 'next start'",
-  },
-}
-```
-
-Пример с использованием Vite:
-
-```json5 fileName="package.json"
-{
-  "scripts": {
-    // ... другие скрипты
-    "build": "vite build",
-    "dev": "vite dev",
-    "start": "npx intlayer live --with 'vite start'",
-  },
-}
-```
-
-Сервер Live Sync оборачивает ваше приложение и автоматически применяет обновлённый контент по мере его поступления.
-
-Чтобы получать уведомления об изменениях из CMS, сервер Live Sync поддерживает SSE-соединение с бэкендом. Когда контент в CMS изменяется, бэкенд пересылает обновление серверу Live Sync, который записывает новые словари. Ваше приложение отобразит обновление при следующей навигации или перезагрузке браузера, пересборка не требуется.
-
-Блок-схема (CMS/Backend -> Live Sync Server -> Application Server -> Frontend):
-
-![Схема потока Live Sync CMS/Backend/Live Sync Server/Application Server/Frontend](https://github.com/aymericzip/intlayer/blob/main/docs/assets/live_sync_flow_scema.svg)
-
-Как это работает:
-
-![Схема логики Live Sync](https://github.com/aymericzip/intlayer/blob/main/docs/assets/live_sync_logic_schema.svg)
-
-### Рабочий процесс разработки (локально)
-
-- В процессе разработки все удалённые словари загружаются при запуске приложения, чтобы вы могли быстро тестировать обновления.
-- Чтобы протестировать Live Sync локально с Next.js, оберните ваш dev-сервер:
-
-```json5 fileName="package.json"
-{
-  "scripts": {
-    // ... другие скрипты
-    "dev": "npx intlayer live --with 'next dev'",
-    // "dev": "npx intlayer live --with 'vite dev'", // Для Vite
-  },
-}
-```
-
-Включите оптимизацию, чтобы Intlayer применял трансформации Live импорта во время разработки:
-
-```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
-import type { IntlayerConfig } from "intlayer";
-
-const config: IntlayerConfig = {
-  editor: {
-    applicationURL: "http://localhost:5173",
-    liveSyncURL: "http://localhost:4000",
-    liveSync: true,
-  },
-  dictionary: {
-    importMode: "fetch",
-  },
-  build: {
-    optimize: true, // default: process.env.NODE_ENV === 'production'
-  },
-};
-
-export default config;
-```
-
-Эта настройка оборачивает ваш dev-сервер сервером Live Sync, загружает удалённые словари при запуске и транслирует обновления из CMS через SSE. Обновите страницу, чтобы увидеть изменения.
-
-Примечания и ограничения:
-
-- Добавьте источник live sync в политику безопасности вашего сайта (CSP). Убедитесь, что URL live sync разрешён в `connect-src` (и в `frame-ancestors`, если это актуально).
-- Live Sync не работает со статическим выводом. Для Next.js страница должна быть динамической, чтобы получать обновления во время выполнения (например, используйте `generateStaticParams`, `generateMetadata`, `getServerSideProps` или `getStaticProps` соответствующим образом, чтобы избежать ограничений полностью статического вывода).
-- В CMS у каждого словаря есть флаг `live`. Только словари с `live=true` загружаются через API live sync; остальные импортируются динамически и остаются неизменными во время выполнения.
-- Флаг `live` оценивается для каждого словаря во время сборки. Если удалённый контент не был помечен как `live=true` во время сборки, необходимо выполнить повторную сборку, чтобы включить Live Sync для этого словаря.
-- Сервер live sync должен иметь возможность записывать в `.intlayer`. В контейнерах убедитесь, что есть права на запись в `/.intlayer`.
+Полное руководство по настройке (включение, запуск сервера Live Sync, рабочий процесс локальной разработки и ограничения) см. в [документации Live Sync](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/live-sync.md).
 
 ## Самостоятельное размещение (Self-Hosting)