@intlayer/docs 9.3.3 → 9.4.0

package/docs/pt/configuration.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-13
-updatedAt: 2026-08-06
+updatedAt: 2026-08-22
 title: Configuração (Configuration)
 description: Saiba como configurar o Intlayer para a sua aplicação. Entenda as várias configurações e opções disponíveis para personalizar o Intlayer conforme as suas necessidades.
 keywords:
@@ -14,6 +14,9 @@ slugs:
   - concept
   - configuration
 history:
+  - version: 9.3.3
+    date: 2026-08-22
+    changes: "Ativar os analytics por predefinição quando `@intlayer/analytics` está instalado"
   - version: 9.1.3
     date: 2026-08-06
     changes: "Tornar `routing.enableProxy` de três estados: não definido (auto), `true`, `false`"
@@ -380,8 +383,8 @@ const config: IntlayerConfig = {
   analytics: {
     /**
      * Se a recolha de analytics está ativada (visualizações de página, exposições de conteúdo, eventos A/B).
-     * Requer que `editor.clientId` esteja definido para a atribuição.
-     * Padrão: false
+     * Requer que `@intlayer/analytics` esteja instalado e que `editor.clientId` esteja definido para a atribuição.
+     * Padrão: true
      */
     enabled: true,
 
@@ -735,19 +738,17 @@ Define as definições para o editor visual integrado, incluindo a porta do serv
 | `liveSyncPort`               | A porta do servidor de live sync.                                                                                                                                      | `number`                          | `4000`                              | `4000`                                                                                          |                                                                                                                                                                                                                                                   |
 | `liveSyncURL`                | O URL do servidor de live sync.                                                                                                                                        | `string`                          | `'http://localhost:{liveSyncPort}'` | `'https://example.com'`                                                                         | Aponta para o localhost por padrão; pode ser alterado para um servidor de live sync remoto.                                                                                                                                                       |
 
----
-
 ### Configuração de Analytics
 
 Define as definições relacionadas com os analytics do Intlayer: a recolha do conteúdo que é efetivamente mostrado aos utilizadores (visualizações de página, exposições de conteúdo) e o suporte a testes A/B de conteúdo.
 
-Os analytics são estritamente opt-in: nada é recolhido a menos que `analytics.enabled` esteja explicitamente definido como `true` **e** uma chave de projeto (`editor.clientId`) esteja configurada para a atribuição. Quando desativado (padrão), toda a integração de analytics é eliminada do bundle da sua aplicação (dead-code elimination).
+Os analytics são de exclusão (opt-out): estão ativados por predefinição e começam a recolher assim que o pacote `@intlayer/analytics` estiver instalado **e** uma chave de projeto (`editor.clientId`) estiver configurada para a atribuição. Defina `analytics.enabled` como `false` — ou não instale o pacote — e toda a integração de analytics é eliminada do bundle da sua aplicação (dead-code elimination).
 
-| Campo           | Descrição                                                                                    | Tipo      | Padrão  | Exemplo | Nota                                                                                                                                                 |
-| --------------- | -------------------------------------------------------------------------------------------- | --------- | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `enabled`       | Ativa a recolha de analytics (visualizações de página, exposições de conteúdo, eventos A/B). | `boolean` | `false` | `true`  | Requer que `editor.clientId` esteja definido para a atribuição; caso contrário, os analytics permanecem desativados mesmo que `enabled` seja `true`. |
-| `flushInterval` | Milissegundos entre os envios automáticos em lote para o backend.                            | `number`  | `20000` | `10000` |                                                                                                                                                      |
-| `sampleRate`    | Fração de sessões a registar, de `0` (nenhuma) a `1` (todas).                                | `number`  | `1`     | `0.5`   | A amostragem é determinística por sessão, pelo que uma sessão registada reporta todos os seus eventos (sem funis parciais).                          |
+| Campo           | Descrição                                                                                    | Tipo      | Padrão  | Exemplo | Nota                                                                                                                                                                                              |
+| --------------- | -------------------------------------------------------------------------------------------- | --------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `enabled`       | Ativa a recolha de analytics (visualizações de página, exposições de conteúdo, eventos A/B). | `boolean` | `true`  | `false` | Requer que `@intlayer/analytics` esteja instalado e que `editor.clientId` esteja definido para a atribuição; caso contrário, os analytics permanecem desativados mesmo que `enabled` seja `true`. |
+| `flushInterval` | Milissegundos entre os envios automáticos em lote para o backend.                            | `number`  | `20000` | `10000` |                                                                                                                                                                                                   |
+| `sampleRate`    | Fração de sessões a registar, de `0` (nenhuma) a `1` (todas).                                | `number`  | `1`     | `0.5`   | A amostragem é determinística por sessão, pelo que uma sessão registada reporta todos os seus eventos (sem funis parciais).                                                                       |
 
 ---
 
@@ -986,6 +987,13 @@ Configurações relacionadas a caminhos internos e resultados de saída do Intla
 
 ### Configuração do Dicionário
 
+Configurações que controlam operações de dicionário, incluindo comportamento de preenchimento automático e geração de conteúdo.
+
+Esta configuração de dicionário serve dois propósitos principais:
+
+1. **Valores Padrão**: Defina valores padrão ao criar arquivos de declaração de conteúdo
+2. **Comportamento de Fallback**: Forneça valores de fallback quando campos específicos não forem definidos, permitindo que você defina o comportamento da operação de dicionário globalmente
+
 Parâmetros que controlam as operações do dicionário, incluindo o comportamento de preenchimento automático (auto-fill) e geração de conteúdo.
 
 | Campo                       | Descrição                                                                                                                                              | Tipo                                                                                                            | Padrão       | Exemplo                                                                                     | Nota                                                                                                                                                                                                                                                                                                                                                                                                    |
@@ -1027,8 +1035,6 @@ Definições para personalizar a saída de logs do Intlayer.
 | `mode`   | Indica o modo do logger.                | `'default'` &#124; <br/> `'verbose'` &#124; <br/> `'disabled'` | `'default'`     | `'verbose'`        | • `'verbose'`: regista mais informações para depuração.<br/>• `'disabled'`: desativa o logger completamente. |
 | `prefix` | O prefixo para as mensagens de registo. | `string`                                                       | `'[intlayer] '` | `'[meu prefixo] '` |                                                                                                              |
 
----
-
 ### Configuração de IA
 
 Configurações que controlam as funcionalidades de IA do Intlayer, incluindo provedor, modelo e chave de API.
@@ -1068,8 +1074,6 @@ O Intlayer suporta múltiplos provedores de IA para máxima flexibilidade. Os pr
 | `baseURL`            | O URL base para a API de IA.                                                                                                          | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                             | Nenhum      | `'https://api.openai.com/v1'` <br/> `'http://localhost:5000'` | Pode apontar para um endpoint de API de IA local ou personalizado.                                                                                                                                    |
 | `dataSerialization`  | Formato de serialização de dados para as funcionalidades de IA.                                                                       | `'json'` &#124; <br/> `'toon'`                                                                                                                                                                                                                                                                                                                                                                                                                       | `undefined` | `'toon'`                                                      | • `'json'`: padrão, fiável; consome mais tokens.<br/>• `'toon'`: menos tokens, menos consistente.<br/>• Parâmetros adicionais são passados para o modelo como contexto (esforço de raciocínio, etc.). |
 
----
-
 ### Configuração de Build
 
 Parâmetros que controlam como o Intlayer otimiza e compila a internacionalização da sua aplicação.
@@ -1106,8 +1110,6 @@ Configurações que controlam o compilador do Intlayer, que extrai dicionários
 | `output`              | Define o caminho para os ficheiros de saída. Substitui `outputDir`. Suporta variáveis de template: `{{fileName}}`, <br/> `{{key}}`, <br/> `{{locale}}`, <br/> `{{extension}}`, <br/> `{{componentFileName}}`, <br/> `{{componentExtension}}`, <br/> `{{format}}`, <br/> `{{componentFormat}}`, <br/> `{{componentDirPath}}`. | `boolean` &#124; <br/> `FilePathPattern` &#124; <br/> `Partial<Record<Locale, boolean &#124; FilePathPattern>>` | `undefined` | `'./{{fileName}}{{extension}}'` <br/> `'/locales/{{locale}}/{{key}}.json'` <br/> `{ en: ({ key }) => './locales/en/${key}.json', fr: '...', es: false }` | • Caminhos `./` são resolvidos em relação ao diretório da componente.<br/>• Caminhos `/` em relação à raiz.<br/>• `{{locale}}` ativa a geração por idioma.<br/>• Suporta notação de objeto por idioma.                                                                                                   |
 | `noMetadata`          | Se `true`, o compilador omite os metadados do dicionário (chave, wrapper de conteúdo) da saída.                                                                                                                                                                                                                              | `boolean`                                                                                                       | `false`     | `false` → `{"key":"minha-chave","content":{"key":"valor"}}` <br/> `true` → `{"key":"valor"}`                                                             | • Útil para saídas i18next ou ICU MessageFormat JSON.<br/>• Funciona bem com o plugin `loadJSON`.                                                                                                                                                                                                        |
 
----
-
 ### Esquemas Personalizados
 
 | Campo     | Descrizione                                                                 | Tipo                        |

package/docs/pt/custom_domains.md

@@ -133,6 +133,38 @@ getMultilingualUrls("/about", { currentDomain: "intlayer.org" });
 
 Essas URLs absolutas estão prontas para usar em tags `<link rel="alternate" hreflang="...">` para SEO.
 
+## Inferência de Tipos
+
+`routing.domains` é serializado na augmentação de módulo gerada, então
+`getLocalizedUrl` e `getLocalizedPath` reduzem seu tipo de retorno para a URL exata
+que um locale roteado por domínio resolve — incluindo a supressão de prefixo.
+
+```ts
+// routing: { mode: 'prefix-no-default', domains: { en: 'intlayer.org', zh: 'intlayer.zh' } }
+
+getLocalizedUrl("/about", "zh");
+//     ^? "https://intlayer.zh/about" | "/about"
+
+getLocalizedPath("/about", "zh");
+//     ^? "/about"   (nunca uma origem, e sem prefixo /zh/)
+```
+
+O tipo de URL é a **union** dos dois valores que a função pode retornar: a
+URL absoluta no domínio do locale e a relativa que retorna quando a
+página sendo renderizada já está nesse domínio. `getLocalizedPath` não tem tal
+ambiguidade - nunca emite uma origem - então permanece um literal único.
+
+Locales que compartilham um domínio mantêm seu prefixo normal no tipo também:
+
+```ts
+getLocalizedUrl("/about", "fr");
+//     ^? "https://intlayer.org/fr/about" | "/fr/about"
+```
+
+> Regenere os tipos (`npx intlayer build`, ou qualquer execução do dev server) após
+> alterar `routing.domains` - a redução vem do
+> `__RoutingRegistry` gerado, não do arquivo de configuração em si.
+
 ## Comportamento do Proxy
 
 ### Next.js
@@ -165,6 +197,8 @@ GET intlayer.zh/about
 
 O plugin Vite `intlayerProxy` aplica a mesma lógica durante o desenvolvimento:
 
+> Desde Intlayer v9, `intlayerProxy()` é empacotado diretamente no plugin `intlayer()` e ativado por padrão através da opção `routing.enableProxy` (`true` por padrão). Registrá-lo separadamente como mostrado abaixo agora é opcional — é mantido para compatibilidade com versões anteriores e para setups que precisam controlar a ordem dos plugins. Defina `routing.enableProxy: false` para desativar. Consulte as [notas de lançamento da v9](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/releases/v9.md).
+
 ```typescript fileName="vite.config.ts"
 import { defineConfig } from "vite";
 import { intlayer } from "vite-intlayer";

package/docs/pt/custom_url_rewrites.md

@@ -248,7 +248,7 @@ Para garantir que a barra de endereço do navegador reflita sempre a URL localiz
 
 <Tabs group='framework'>
   <Tab label="Next.js" value="nextjs">
-  
+
     ```tsx
     'use client';
 
@@ -263,7 +263,7 @@ Para garantir que a barra de endereço do navegador reflita sempre a URL localiz
   </Tab>
 
   <Tab label="React Router" value="reactrouter">
-  
+
     ```tsx
     'use client';
 
@@ -279,7 +279,7 @@ Para garantir que a barra de endereço do navegador reflita sempre a URL localiz
   </Tab>
 
   <Tab label="Vue" value="vue">
-  
+
     ```vue
     <script setup>
     import { useRewriteURL } from "vue-intlayer";
@@ -291,7 +291,7 @@ Para garantir que a barra de endereço do navegador reflita sempre a URL localiz
 
   </Tab>
   <Tab label="Solid" value="solid">
-  
+
     ```tsx
     import { useRewriteURL } from "solid-intlayer";
 
@@ -303,7 +303,7 @@ Para garantir que a barra de endereço do navegador reflita sempre a URL localiz
 
   </Tab>
   <Tab label="Svelte" value="svelte">
-  
+
     ```svelte
     <script>
     import { useRewriteURL } from "svelte-intlayer";
@@ -340,6 +340,8 @@ export function middleware(request: NextRequest) {
 
 Para SolidJS, Vue e Svelte, o plugin Vite `intlayerProxy` gerencia as reescritas durante o desenvolvimento.
 
+> Desde Intlayer v9, `intlayerProxy()` é agrupado diretamente no plugin `intlayer()` e ativado por padrão através da opção `routing.enableProxy` (`true` por padrão). Registrá-lo separadamente como mostrado abaixo agora é opcional — é mantido para compatibilidade retroativa e para configurações que precisam controlar a ordem dos plugins. Defina `routing.enableProxy: false` para desativar. Consulte as [notas de versão v9](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/releases/v9.md).
+
 ```typescript fileName="vite.config.ts"
 import { defineConfig } from "vite";
 import { intlayer } from "vite-intlayer";

package/docs/pt/dictionary/html.md

@@ -248,7 +248,7 @@ Você pode configurar a renderização de HTML globalmente para toda a sua aplic
 
 <Tabs group="framework">
   <Tab label="React / Next.js" value="react">
-  
+
     ```tsx fileName="AppProvider.tsx"
     import { HTMLProvider } from "react-intlayer/html";
 
@@ -285,7 +285,7 @@ Você pode configurar a renderização de HTML globalmente para toda a sua aplic
 
   </Tab>
   <Tab label="Vue" value="vue">
-  
+
     ```typescript fileName="main.ts"
     import { createApp, h } from "vue";
     import { intlayer } from "vue-intlayer";
@@ -330,7 +330,7 @@ Você pode configurar a renderização de HTML globalmente para toda a sua aplic
 
   </Tab>
   <Tab label="Svelte" value="svelte">
-   
+
     ```svelte fileName="App.svelte"
     <script lang="ts">
       import { HTMLProvider } from "svelte-intlayer/html";
@@ -346,9 +346,11 @@ Você pode configurar a renderização de HTML globalmente para toda a sua aplic
     </HTMLProvider>
     ```
 
+> Importar seu renderer HTML dinamicamente é uma boa forma de reduzir o tamanho do bundle da sua aplicação.
+
   </Tab>
   <Tab label="Preact" value="preact">
-   
+
     ```tsx fileName="AppProvider.tsx"
     import { HTMLProvider } from "preact-intlayer/html";
 
@@ -384,7 +386,7 @@ Você pode configurar a renderização de HTML globalmente para toda a sua aplic
 
   </Tab>
   <Tab label="Solid" value="solid">
-   
+
     ```tsx fileName="AppProvider.tsx"
     import { HTMLProvider } from "solid-intlayer/html";
 
@@ -444,9 +446,9 @@ Você pode configurar a renderização de HTML globalmente para toda a sua aplic
     export const appConfig: ApplicationConfig = {
       providers: [
         createIntlayerHTMLProvider({
-          renderMarkdown: async (html) => {
-            const { renderMarkdown } = await import('angular-intlayer/html');
-            return renderMarkdown(html);
+          renderHTML: async (html) => {
+            const { renderHTML } = await import('angular-intlayer/html');
+            return renderHTML(html);
           },
         }),
       ],
@@ -503,9 +505,9 @@ Se precisar renderizar strings HTML brutas ou tiver mais controlo sobre o mapeam
 
   </Tab>
   <Tab label="Vue" value="vue">
-   
+
     #### Componente `<HTMLRenderer />`
-   
+
     ```vue
     <script setup>
     import { HTMLRenderer } from "vue-intlayer/html";
@@ -518,9 +520,9 @@ Se precisar renderizar strings HTML brutas ou tiver mais controlo sobre o mapeam
 
   </Tab>
   <Tab label="Svelte" value="svelte">
-  
+
     #### Componente `<HTMLRenderer />`
-   
+
     ```svelte
     <script lang="ts">
     import { HTMLRenderer } from "svelte-intlayer/html";
@@ -552,9 +554,9 @@ Se precisar renderizar strings HTML brutas ou tiver mais controlo sobre o mapeam
 
   </Tab>
   <Tab label="Preact" value="preact">
-   
+
     #### Componente `<HTMLRenderer />`
-   
+
     ```tsx
     import { HTMLRenderer } from "preact-intlayer/html";
 
@@ -583,9 +585,9 @@ Se precisar renderizar strings HTML brutas ou tiver mais controlo sobre o mapeam
 
   </Tab>
   <Tab label="Solid" value="solid">
-   
+
     #### Componente `<HTMLRenderer />`
-   
+
     ```tsx
     import { HTMLRenderer } from "solid-intlayer/html";
 
@@ -618,13 +620,13 @@ Se precisar renderizar strings HTML brutas ou tiver mais controlo sobre o mapeam
     Renderize uma string HTML utilizando o serviço.
 
     ```typescript
-    import { IntlayerHTMLService } from "angular-intlayer";
+    import { IntlayerHTMLService } from "angular-intlayer/html";
 
     export class MyComponent {
       constructor(private markdownService: IntlayerHTMLService) {}
 
       renderHTML(html: string) {
-        return this.markdownService.renderMarkdown(html);
+        return this.markdownService.renderHTML(html);
       }
     }
     ```

package/docs/pt/dictionary/insertion.md

@@ -100,20 +100,6 @@ Para configurar conteúdo de inserção no seu projeto Intlayer, crie um módulo
   </Tab>
 </Tabs>
 
-```json5 fileName="**/*.content.json" contentDeclarationFormat="json"
-{
-  "$schema": "https://intlayer.org/schema.json",
-  "key": "my_key",
-  "content": {
-    "myInsertion": {
-      "nodeType": "insertion",
-      "insertion": "Hello, my name is {{name}} and I am {{age}} years old!",
-    },
-    "myInsertion2": "Hello, my name is {{name}} and I am {{age}} years old!", // Since intlayer v8, insertion function is not required anymore. The content will be automatically decorated.
-  },
-}
-```
-
 ## Usando Conteúdo de Inserção com React Intlayer
 
 Para utilizar conteúdo de inserção dentro de um componente React, importe e use o hook `useIntlayer` do pacote `react-intlayer`. Este hook recupera o conteúdo para a chave especificada e permite que você passe um objeto que mapeia cada placeholder no seu conteúdo para o valor que deseja exibir.

package/docs/pt/dictionary/markdown.md

@@ -492,7 +492,7 @@ Estes utilitários renderizam **apenas strings Markdown brutas** e são independ
 
 <Tabs group="framework">
   <Tab label="React" value="react">
-  
+
     #### Componente `<MarkdownRenderer />`
 
     Renderiza uma string Markdown com opções específicas.
@@ -531,7 +531,7 @@ Estes utilitários renderizam **apenas strings Markdown brutas** e são independ
 
   </Tab>
   <Tab label="Next.js" value="nextjs">
-  
+
     #### Componente `<MarkdownRenderer />`
 
     Renderiza uma string Markdown com opções específicas.
@@ -957,21 +957,38 @@ O `MarkdownProvider` (ou o seu equivalente do framework) configura o pipeline de
   </Tab>
   <Tab label="Angular" value="angular">
 
-    ```typescript fileName="app.module.ts"
-    import { NgModule } from '@angular/core';
-    import { IntlayerMarkdownModule } from 'angular-intlayer/markdown';
+    ```typescript fileName="app.config.ts"
+    import { createIntlayerMarkdownProvider } from "angular-intlayer/markdown";
+
+    export const appConfig: ApplicationConfig = {
+      providers: [
+        createIntlayerMarkdownProvider({
+          components: {
+            h1: { class: "text-2xl font-bold" },
+          },
+        }),
+      ],
+    };
+    ```
+
+
+    > O MDX é suportado — qualquer nome de componente usado dentro do seu Markdown (ex: `<MyCustomJSXComponent />`) é resolvido com base no mapa de `components`.
+
+    Você também pode usar seu próprio renderizador de markdown:
+
+    ```typescript fileName="app.config.ts"
+    import { createIntlayerMarkdownProvider } from "angular-intlayer/markdown";
 
-    @NgModule({
-      imports: [
-        IntlayerMarkdownModule.forRoot({
+    export const appConfig: ApplicationConfig = {
+      providers: [
+        createIntlayerMarkdownProvider({
           renderMarkdown: async (md) => {
             const { renderMarkdown } = await import('angular-intlayer/markdown');
             return renderMarkdown(md);
-          }
-        })
-      ]
-    })
-    export class AppModule {}
+          },
+        }),
+      ],
+    };
     ```
 
     > Importar dinamicamente o seu renderizador de Markdown é uma ótima maneira de reduzir o tamanho do bundle da sua aplicação.
@@ -1047,7 +1064,7 @@ const MyComponent = () => {
 ```
 
   </Tab>
- 
+
   <Tab label="Vue" value="vue">
 
 Vue tem um componente `<Suspense>` integrado. Envolva o componente que renderiza o conteúdo Markdown em um limite `<Suspense>`.