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

package/blog/pt/rag_powered_documentation_assistant.md

@@ -57,43 +57,6 @@ Esse último ponto é crucial. Um sistema RAG não apenas responde perguntas, el
 
 Portanto, RAG não é apenas uma ferramenta de suporte. É também um **motor de descoberta de produto**.
 
-## Como funciona o pipeline RAG
-
-![RAG Pipeline](https://github.com/aymericzip/intlayer/blob/main/docs/assets/rag_flow.svg)
-
-Em um nível geral, aqui está a receita que usei:
-
-1.  **Dividir a documentação em partes** Grandes arquivos Markdown são divididos em partes. Dividir permite fornecer como contexto apenas as partes relevantes da documentação.
-2.  **Gerar embeddings** Cada parte é transformada em um vetor usando a API de embedding da OpenAI (text-embedding-3-large) ou um banco de dados vetorial (Chroma, Qdrant, Pinecone).
-3.  **Indexação e armazenamento** Os embeddings são armazenados em um arquivo JSON simples (para minha demonstração), mas em produção, provavelmente você usaria um banco de dados vetorial.
-4.  **Recuperação (R em RAG)** A consulta do usuário é transformada em embedding, a similaridade cosseno é calculada, e os chunks mais relevantes são recuperados.
-5.  **Aumento + Geração (AG em RAG)** Esses chunks são injetados no prompt para o ChatGPT, para que o modelo responda com o contexto real da documentação.
-6.  **Registro de consultas para feedback** Cada consulta do usuário é armazenada. Isso é ouro para entender pontos problemáticos, documentação faltante ou novas oportunidades.
-
-## Passo 1: Lendo a Documentação
-
-O primeiro passo foi simples: eu precisava de uma forma de escanear uma pasta docs/ para todos os arquivos .md. Usando Node.js e glob, eu busquei o conteúdo de cada arquivo Markdown para a memória.
-
-Isso mantém o pipeline flexível: em vez de Markdown, você poderia buscar documentos de um banco de dados, um CMS ou até mesmo uma API.
-
-## Passo 2: Dividindo a Documentação em Partes
-
-Por que dividir em partes? Porque os modelos de linguagem têm **limites de contexto**. Alimentá-los com um livro inteiro de documentação não funciona.
-
-Então, a ideia é quebrar o texto em partes gerenciáveis (por exemplo, 500 tokens cada) com sobreposição (por exemplo, 100 tokens). A sobreposição garante continuidade para que você não perca o significado nas fronteiras das partes.
-
-**Exemplo:**
-
-- Parte 1 → “…a velha biblioteca que muitos haviam esquecido. Suas prateleiras imponentes estavam cheias de livros…”
-- Parte 2 → “…as prateleiras estavam cheias de livros de todos os gêneros imagináveis, cada um sussurrando histórias…”
-
-A sobreposição garante que ambas as partes contenham contexto compartilhado, para que a recuperação permaneça coerente.
-
-Esse equilíbrio (tamanho do chunk vs sobreposição) é fundamental para a eficiência do RAG:
-
-- Muito pequeno → você obtém ruído.
-- Muito grande → você estoura o tamanho do contexto.
-
 ## Passo 3: Gerando Embeddings
 
 Uma vez que os documentos são divididos em chunks, geramos **embeddings**, vetores de alta dimensão que representam cada chunk.
@@ -112,164 +75,6 @@ Usei o modelo text-embedding-3-large da OpenAI, mas você pode usar qualquer mod
 
 Cada vetor é uma impressão digital matemática do texto, permitindo a busca por similaridade.
 
-## Passo 4: Indexando e Armazenando Embeddings
-
-Para evitar regenerar embeddings várias vezes, eu os armazenei em embeddings.json.
-
-Em produção, você provavelmente vai querer um banco de dados vetorial como:
-
-- Chroma
-- Qdrant
-- Pinecone
-- FAISS, Weaviate, Milvus, etc.
-
-Bancos de dados vetoriais lidam com indexação, escalabilidade e busca rápida. Mas para meu protótipo, um JSON local funcionou bem.
-
-## Passo 5: Recuperação com Similaridade Cosseno
-
-Quando um usuário faz uma pergunta:
-
-1. Gere um embedding para a consulta.
-2. Compare-o com todos os embeddings dos documentos usando **similaridade cosseno**.
-3. Mantenha apenas os N chunks mais similares.
-
-A similaridade cosseno mede o ângulo entre dois vetores. Uma correspondência perfeita tem pontuação **1.0**.
-
-Dessa forma, o sistema encontra as passagens do documento mais próximas da consulta.
-
-## Passo 6: Aumento + Geração
-
-Agora vem a mágica. Pegamos os chunks principais e os injetamos no **prompt do sistema** para o ChatGPT.
-
-Isso significa que o modelo responde como se esses trechos fizessem parte da conversa.
-
-O resultado: respostas precisas e **baseadas na documentação**.
-
-## Passo 7: Registro das Consultas dos Usuários
-
-Este é o superpoder oculto.
-
-Cada pergunta feita é armazenada. Com o tempo, você constrói um conjunto de dados de:
-
-- Perguntas mais frequentes (ótimo para FAQs)
-- Perguntas sem resposta (documentação ausente ou pouco clara)
-- Solicitações de funcionalidades disfarçadas de perguntas (“Integra com X?”)
-- Casos de uso emergentes que você não havia planejado
-
-Isso transforma seu assistente RAG em uma **ferramenta contínua de pesquisa com usuários**.
-
-## Quanto Custa?
-
-Uma objeção comum ao RAG é o custo. Na prática, é surpreendentemente barato:
-
-- Gerar embeddings para cerca de 200 documentos leva cerca de **5 minutos** e custa **1–2 euros**.
-- O recurso de busca na documentação é 100% gratuito.
-- Para consultas, usamos o gpt-4o-latest sem o modo “thinking”. No Intlayer, vemos cerca de **300 consultas de chat por mês**, e a fatura da API OpenAI raramente ultrapassa **10 dólares**.
-
-Além disso, você pode incluir o custo de hospedagem.
-
-## Detalhes da Implementação
-
-Stack:
-
-- Monorepo: workspace pnpm
-- Pacote de documentação: Node.js / TypeScript / API OpenAI
-- Frontend: Next.js / React / Tailwind CSS
-- Backend: rota API Node.js / API OpenAI
-
-O pacote `@smart-doc/docs` é um pacote TypeScript que lida com o processamento da documentação. Quando um arquivo markdown é adicionado ou modificado, o pacote inclui um script `build` que reconstrói a lista de documentação em cada idioma, gera embeddings e os armazena em um arquivo `embeddings.json`.
-
-Para o frontend, usamos uma aplicação Next.js que fornece:
-
-- Renderização de Markdown para HTML
-- Uma barra de pesquisa para encontrar documentação relevante
-- Uma interface de chatbot para fazer perguntas sobre a documentação
-
-Para realizar uma busca na documentação, a aplicação Next.js inclui uma rota de API que chama uma função do pacote `@smart-doc/docs` para recuperar fragmentos de documentação que correspondem à consulta. Usando esses fragmentos, podemos retornar uma lista de páginas de documentação relevantes para a busca do usuário.
-
-Para a funcionalidade do chatbot, seguimos o mesmo processo de busca, mas além disso, injetamos os fragmentos de documentação recuperados no prompt enviado ao ChatGPT.
-
-Aqui está um exemplo de um prompt enviado ao ChatGPT:
-
-Prompt do sistema:
-
-```txt
-Você é um assistente prestativo que pode responder perguntas sobre a documentação do Intlayer.
-
-Fragmentos relacionados:
-
------
-docName: "getting-started"
-docChunk: "1/3"
-docUrl: "https://example.com/docs/pt/getting-started"
----
-
-# Como começar
-
-...
-
------
-docName: "another-doc"
-docChunk: "1/5"
-docUrl: "https://example.com/docs/pt/another-doc"
----
-
-# Outro documento
-
-...
-```
-
-Consulta do usuário :
-
-```txt
-Como começar?
-```
-
-Usamos SSE para transmitir a resposta da rota da API.
-
-Como mencionado, usamos gpt-4-turbo sem o modo "thinking". As respostas são relevantes e a latência é baixa.
-Experimentamos com o gpt-5, mas a latência era muito alta (às vezes até 15 segundos para uma resposta). Mas revisaremos isso no futuro.
-
-👉 [Experimente a demonstração aqui](https://intlayer.org/doc/why) 👉 [Confira o modelo de código no GitHub](https://github.com/aymericzip/smart_doc_RAG)
-
-## Indo Além
-
-Este projeto é uma implementação mínima. Mas você pode estendê-lo de várias maneiras:
-
-- Servidor MCP → a função de pesquisa de documentação para um servidor MCP para conectar a documentação a qualquer assistente de IA
-
-- Bancos de Dados Vetoriais → escalar para milhões de pedaços de documentação
-- LangChain / LlamaIndex → frameworks prontos para pipelines RAG
-- Painéis de análise → visualizar consultas dos usuários e pontos problemáticos
-- Recuperação multi-fonte → buscar não apenas documentos, mas entradas de banco de dados, posts de blog, tickets, etc.
-- Melhoria no prompting → reclassificação, filtragem e busca híbrida (palavra-chave + semântica)
-
-## Limitações que Encontramos
-
-- A segmentação e sobreposição são empíricas. O equilíbrio correto (tamanho do pedaço, porcentagem de sobreposição, número de pedaços recuperados) requer iteração e testes.
-- Embeddings não são regenerados automaticamente quando os documentos mudam. Nosso sistema redefine os embeddings para um arquivo somente se o número de pedaços for diferente do que está armazenado.
-- Neste protótipo, os embeddings são armazenados em JSON. Isso funciona para demonstrações, mas polui o Git. Em produção, um banco de dados ou um armazenamento vetorial dedicado é melhor.
-
-## Por Que Isso Importa Além da Documentação
-
-A parte interessante não é apenas o chatbot. É o **ciclo de feedback**.
-
-Com RAG, você não apenas responde:
-
-- Você aprende o que confunde os usuários.
-- Você descobre quais recursos eles esperam.
-- Você adapta sua estratégia de produto com base em consultas reais.
-
-**Exemplo:**
-
-Imagine lançar um novo recurso e ver instantaneamente:
-
-- 50% das perguntas são sobre o mesmo passo de configuração pouco claro
-- Usuários pedem repetidamente por uma integração que você ainda não suporta
-- Pessoas buscam termos que revelam um novo caso de uso
-
-Isso é **inteligência de produto** diretamente dos seus usuários.
-
 ## Conclusão
 
 RAG é uma das formas mais simples e poderosas de tornar os LLMs práticos. Ao combinar **recuperação + geração**, você pode transformar documentos estáticos em um **assistente inteligente** e, ao mesmo tempo, obter um fluxo contínuo de insights sobre o produto.

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

@@ -137,6 +137,14 @@ Nós avaliamos:
 
 ---
 
+## Interoperabilidade com `react-intl` e `react-i18next`
+
+`intlayer` também pode ajudar a gerenciar seus namespaces `react-intl` e `react-i18next`.
+
+Usando `intlayer`, você pode declarar seu conteúdo no formato de sua biblioteca i18n favorita, e o intlayer gerará seus namespaces no local de sua escolha (exemplo: `/messages/{{locale}}/{{namespace}}.json`).
+
+---
+
 ## Notas práticas de migração (react-intl / react-i18next → Intlayer)
 
 - **Migre de forma incremental**: Comece com uma funcionalidade ou rota; mantenha os catálogos legados em paralelo durante a transição.

package/blog/pt/vue-i18n_vs_intlayer.md

@@ -249,6 +249,14 @@ Esta abordagem:
 
 ---
 
+## Interoperabilidade com vue-i18n
+
+`intlayer` também pode ajudar a gerenciar seus namespaces `vue-i18n`.
+
+Usando `intlayer`, você pode declarar seu conteúdo no formato de sua biblioteca i18n favorita, e intlayer gerará seus namespaces no local de sua escolha (exemplo: `/messages/{{locale}}/{{namespace}}.json`).
+
+---
+
 ## Notas práticas de migração (vue-i18n → Intlayer)
 
 - **Comece por funcionalidade**: Mova uma rota/visualização/componente de cada vez para os dicionários locais do Intlayer.

package/blog/ru/intlayer_with_i18next.md

@@ -34,6 +34,10 @@ author: aymericzip
 
 <iframe title="Как автоматизировать ваши JSON-переводы i18next с помощью Intlayer" 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"/>
 
+## Содержание
+
+<TOC/>
+
 ## Что такое Intlayer?
 
 **Intlayer**, это инновационная, открытая библиотека интернационализации, созданная для устранения недостатков традиционных решений i18n. Она предлагает современный подход к управлению контентом в JavaScript-приложениях.
@@ -65,24 +69,40 @@ author: aymericzip
 
 Установите необходимые пакеты:
 
+```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` не является обязательным. Используйте `intlayer-cli init`, если вы являетесь ИИ-агентом.
+
+> Эта команда определит вашу среду и установит необходимые пакеты. Например:
+
 ```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
 ```
 
 **Описание пакетов:**

package/blog/ru/intlayer_with_next-i18next.md

@@ -34,17 +34,6 @@ author: aymericzip
 
 <TOC/>
 
-## Что такое next-i18next?
-
-**next-i18next**, это один из самых популярных фреймворков для интернационализации (i18n) в приложениях Next.js. Построенный на мощной экосистеме **i18next**, он предоставляет комплексное решение для управления переводами, локализацией и переключением языков в проектах Next.js.
-
-Однако next-i18next имеет некоторые сложности:
-
-- **Сложная конфигурация**: Настройка next-i18next требует нескольких конфигурационных файлов и тщательной настройки экземпляров i18n на стороне сервера и клиента.
-- **Разрозненные переводы**: Файлы переводов обычно хранятся в отдельных директориях от компонентов, что затрудняет поддержание согласованности.
-- **Ручное управление пространствами имён**: Разработчикам необходимо вручную управлять пространствами имён и обеспечивать правильную загрузку ресурсов переводов.
-- **Ограниченная типобезопасность**: Поддержка TypeScript требует дополнительной настройки и не обеспечивает автоматическую генерацию типов для переводов.
-
 ## Что такое Intlayer?
 
 **Intlayer**, это инновационная, открытая библиотека интернационализации, разработанная для устранения недостатков традиционных решений i18n. Она предлагает современный подход к управлению контентом в приложениях Next.js.
@@ -73,24 +62,40 @@ author: aymericzip
 
 Установите необходимые пакеты с помощью предпочитаемого менеджера пакетов:
 
+```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` не является обязательным. Используйте `intlayer-cli init`, если вы являетесь ИИ-агентом.
+
+> Эта команда определит вашу среду и установит необходимые пакеты. Например:
+
 ```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
 ```
 
 **Объяснение пакетов:**

package/blog/ru/intlayer_with_next-intl.md

@@ -29,6 +29,10 @@ author: aymericzip
 
 <iframe title="Как автоматизировать перевод JSON для next-intl с помощью Intlayer" 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"/>
 
+# Оглавление
+
+<TOC/>
+
 ## Что такое Intlayer?
 
 **Intlayer**, это инновационная, открытая библиотека интернационализации, созданная для устранения недостатков традиционных решений i18n. Она предлагает современный подход к управлению контентом в приложениях Next.js.
@@ -59,24 +63,40 @@ author: aymericzip
 
 Установите необходимые пакеты:
 
+```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` не является обязательным. Используйте `intlayer-cli init`, если вы являетесь ИИ-агентом.
+
+> Эта команда определит вашу среду и установит необходимые пакеты. Например:
+
 ```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
 ```
 
 **Описание пакетов:**

package/blog/ru/intlayer_with_react-i18next.md

@@ -63,24 +63,40 @@ author: aymericzip
 
 Установите необходимые пакеты:
 
+```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` не является обязательным. Используйте `intlayer-cli init`, если вы являетесь ИИ-агентом.
+
+> Эта команда определит вашу среду и установит необходимые пакеты. Например:
+
 ```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
 ```
 
 **Описание пакетов:**

package/blog/ru/intlayer_with_react-intl.md

@@ -61,24 +61,40 @@ author: aymericzip
 
 Установите необходимые пакеты:
 
+```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` не является обязательным. Используйте `intlayer-cli init`, если вы являетесь ИИ-агентом.
+
+> Эта команда определит вашу среду и установит необходимые пакеты. Например:
+
 ```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
 ```
 
 **Описание пакетов:**

package/blog/ru/intlayer_with_vue-i18n.md

@@ -63,24 +63,40 @@ author: aymericzip
 
 Установите необходимые пакеты с помощью предпочитаемого менеджера пакетов:
 
+```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` не является обязательным. Используйте `intlayer-cli init`, если вы являетесь ИИ-агентом.
+
+> Эта команда определит вашу среду и установит необходимые пакеты. Например:
+
 ```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
 ```
 
 **Объяснение пакетов:**