@intlayer/docs 7.0.0-canary.2 → 7.0.0-canary.3

package/docs/pt/introduction.md

@@ -144,19 +144,6 @@ const MyComponent = () => {
 
 ## Principais Funcionalidades
 
-Intlayer oferece uma variedade de funcionalidades adaptadas para atender às necessidades do desenvolvimento web moderno. Abaixo estão as principais funcionalidades, com links para documentação detalhada de cada uma:
-
-- **Suporte à Internacionalização**: Amplie o alcance global da sua aplicação com suporte integrado para internacionalização.
-- **Editor Visual**: Melhore seu fluxo de desenvolvimento com plugins de editor projetados para Intlayer. Confira o [Guia do Editor Visual](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_visual_editor.md).
-  const { myTranslatedContent } = useIntlayer("component-key");
-
-  return <span>{myTranslatedContent}</span>;
-  };
-
-```
-
-## Principais Funcionalidades
-
 O Intlayer oferece uma variedade de funcionalidades adaptadas para atender às necessidades do desenvolvimento web moderno. Abaixo estão as principais funcionalidades, com links para documentação detalhada de cada uma:
 
 - **Suporte à Internacionalização**: Amplie o alcance global da sua aplicação com suporte integrado para internacionalização.
@@ -217,5 +204,3 @@ Cada guia de integração inclui as melhores práticas para usar os recursos do
 Valorizamos o poder do código aberto e do desenvolvimento orientado pela comunidade. Se desejar propor melhorias, adicionar um novo guia ou corrigir quaisquer problemas em nossa documentação, sinta-se à vontade para enviar um Pull Request ou abrir uma issue em nosso [repositório GitHub](https://github.com/aymericzip/intlayer/blob/main/docs/docs).
 
 **Pronto para traduzir sua aplicação de forma mais rápida e eficiente?** Mergulhe em nossa documentação para começar a usar o Intlayer hoje mesmo. Experimente uma abordagem robusta e simplificada para internacionalização que mantém seu conteúdo organizado e sua equipe mais produtiva.
-
----

package/docs/pt/releases/v7.md

@@ -0,0 +1,486 @@
+---
+createdAt: 2025-09-22
+updatedAt: 2025-09-23
+title: Nova Intlayer v7 - O que há de novo?
+description: Descubra as novidades da Intlayer v7. Grandes melhorias em desempenho, experiência do desenvolvedor e novos recursos para aprimorar seu fluxo de trabalho de internacionalização.
+keywords:
+  - Intlayer
+  - Localização
+  - Desenvolvimento
+  - Desempenho
+  - Experiência do Desenvolvedor
+  - Recursos
+  - React
+  - Next.js
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - releases
+  - v7
+---
+
+# Nova Intlayer v7 - O que há de novo?
+
+Bem-vindo à Intlayer v7! Esta grande versão traz melhorias significativas em desempenho, segurança de tipos e experiência do desenvolvedor. Abaixo estão os destaques, com notas de migração e exemplos práticos.
+
+## Destaques
+
+- Estratégia de cache para builds mais rápidos
+- Geração aprimorada de tipos TypeScript com tipos específicos por localidade
+- Otimização do pacote: Localidades como strings em vez de enum
+- Novos modos de roteamento: `prefix-no-default`, `prefix-all`, `no-prefix`, `search-params`
+- Armazenamento de localidade compatível com GDPR usando localStorage como padrão
+- Configuração flexível de armazenamento: cookies, localStorage, sessionStorage ou múltiplos
+- Pacote do Visual Editor 30% menor
+- Opções aprimoradas de configuração de middleware
+- Comportamento atualizado do comando fill para melhor gerenciamento de conteúdo
+- Estabilidade aprimorada com atualizações completas dos arquivos de declaração de conteúdo
+- Gerenciamento inteligente de tentativas para maior precisão na tradução
+- Paralelização para processamento de tradução mais rápido
+- Divisão inteligente para lidar com arquivos grandes dentro dos limites de contexto da IA
+
+---
+
+## Desempenho: Cache para builds mais rápidos
+
+Em vez de reconstruir as declarações de conteúdo com esbuild a cada build, a versão 7 implementa uma estratégia de cache que acelera o processo de build.
+
+```bash
+npx intlayer build
+```
+
+O novo sistema de cache:
+
+- Armazena declarações de conteúdo compiladas para evitar processamento redundante
+- Detecta alterações e reconstrói apenas os arquivos modificados
+- Reduz significativamente o tempo de build em projetos grandes
+
+---
+
+## TypeScript: Geração de tipos específicos por localidade
+
+Os tipos TypeScript agora são gerados por localidade, proporcionando tipagem mais forte e eliminando tipos união entre todas as localidades.
+
+**Comportamento na v6:**
+
+```tsx
+const content = getIntlayer("my-title-content", "en");
+// typeof content = { title: "My title" } | { title: "Mon titre" } | { title: "Mi título" }
+```
+
+**Comportamento na v7:**
+
+```tsx
+const content = getIntlayer("my-title-content", "en");
+// typeof content = { title: "Meu título" }
+```
+
+Benefícios:
+
+- Autocompletar mais preciso no seu IDE
+- Melhor segurança de tipos sem poluição entre localidades
+- Desempenho aprimorado ao reduzir a complexidade dos tipos
+
+---
+
+## Otimização do bundle: Locales como strings
+
+O tipo `Locales` não é mais um enum, o que significa que agora é totalmente tree-shakeable e não vai inflar seu bundle com milhares de registros de localidades não usados.
+
+**v6:**
+
+```typescript
+import { Locales } from "intlayer";
+// Enum incluindo todas as localidades -> não é tree-shakeable
+
+const locale: Locales = Locales.ENGLISH;
+```
+
+**v7:**
+
+```typescript
+import { Locales, Locale } from "intlayer";
+// Tipo string -> totalmente tree-shakeable
+
+const locale: Locale = Locales.ENGLISH;
+```
+
+> Como `Locales` não é mais um enum, você terá que mudar o tipo de `Locales` para `Locale` para obter a localidade como um tipo.
+
+Veja os [detalhes da implementação](https://github.com/aymericzip/intlayer/blob/main/packages/%40intlayer/types/src/index.ts) para mais informações.
+
+---
+
+## Novos modos de roteamento para maior flexibilidade
+
+A versão 7 introduz uma configuração unificada `routing.mode` que substitui as opções anteriores `prefixDefault` e `noPrefix`, oferecendo um controle mais granular sobre a estrutura da URL.
+
+### Modos de roteamento disponíveis
+
+- **`prefix-no-default`** (padrão): A localidade padrão não tem prefixo, as outras localidades têm
+  - `/dashboard` (en) ou `/fr/dashboard` (fr)
+- **`prefix-all`**: Todas as localidades têm prefixo
+  - `/en/dashboard` (en) ou `/fr/dashboard` (fr)
+- **`no-prefix`**: Sem prefixos de localidade nas URLs (localidade gerenciada via armazenamento/cabeçalhos)
+  - `/dashboard` para todas as localidades
+- **`search-params`**: Localidade passada como parâmetro de consulta
+  - `/dashboard?locale=en` ou `/dashboard?locale=fr`
+
+### Configuração básica
+
+```typescript
+// intlayer.config.ts
+export default {
+  internationalization: {
+    locales: ["en", "fr", "es"],
+    defaultLocale: "en",
+  },
+  routing: {
+    mode: "prefix-no-default", // padrão
+  },
+};
+```
+
+---
+
+## Conformidade com GDPR: armazenamento localStorage / cookies
+
+A versão 7 prioriza a privacidade do usuário utilizando `localStorage` como mecanismo de armazenamento padrão em vez de cookies. Essa mudança ajuda na conformidade com o GDPR ao evitar a necessidade de consentimento para cookies relacionados às preferências de localidade.
+
+### Opções de configuração de armazenamento
+
+O novo campo `routing.storage` também está disponível além das opções anteriores `middleware.cookieName` e `middleware.serverSetCookie`, oferecendo configurações flexíveis de armazenamento:
+
+```typescript
+// Desabilitar armazenamento
+storage: false
+
+// Tipos simples de armazenamento
+storage: 'cookie'
+storage: 'localStorage'
+storage: 'sessionStorage'
+
+// Cookie com atributos personalizados
+storage: {
+  type: 'cookie',
+  name: 'custom-locale',
+  domain: '.example.com',
+  secure: true,
+  sameSite: 'strict'
+}
+
+// localStorage com chave personalizada
+storage: {
+  type: 'localStorage',
+  name: 'custom-locale'
+}
+
+// Múltiplos tipos de armazenamento para redundância
+storage: ['cookie', 'localStorage']
+```
+
+### Exemplo de configuração compatível com GDPR
+
+Para aplicações em produção que precisam equilibrar funcionalidade com conformidade GDPR:
+
+```typescript
+// intlayer.config.ts
+export default {
+  internationalization: {
+    locales: ["en", "fr", "es"],
+    defaultLocale: "en",
+  },
+  routing: {
+    mode: "prefix-no-default",
+    storage: [
+      {
+        type: "localStorage", // Armazenamento principal (não requer consentimento)
+        name: "user-locale",
+      },
+      {
+        type: "cookie", // Armazenamento opcional em cookie (requer consentimento)
+        name: "user-locale",
+        secure: true,
+        sameSite: "strict",
+        httpOnly: false,
+      },
+    ],
+  },
+};
+```
+
+### Ativar / desativar o armazenamento em cookie
+
+Exemplo usando React / Next.js:
+
+Pode ser definido globalmente:
+
+```typescript
+<IntlayerProvider isCookieEnabled={false}>
+  <App />
+</IntlayerProvider>
+```
+
+Pode ser sobrescrito localmente para cada hook:
+
+```ts
+const { setLocale } = useLocale({ isCookieEnabled: false });
+
+setLocale("en");
+```
+
+**Nota:** Os cookies estão ativados por padrão.
+**Nota:** Verifique os [requisitos de cookies do GDPR](https://gdpr.eu/cookies/) para o seu caso específico.
+
+---
+
+## Editor Visual: pacote 30% menor
+
+O pacote do Editor Visual foi otimizado para ser 30% menor que a versão anterior, graças a:
+
+- Melhorias no desempenho do editor de código
+- Remoção de dependências desnecessárias dos pacotes principais do Intlayer
+- Melhor tree-shaking e empacotamento de módulos
+
+Isso resulta em tempos de download mais rápidos e melhor desempenho em tempo de execução para sua aplicação.
+
+---
+
+## Comando fill: comportamento atualizado para melhor gerenciamento de conteúdo
+
+A versão 7 introduz um comportamento aprimorado para o comando `fill`, proporcionando um gerenciamento de conteúdo mais previsível e flexível:
+
+### Novo comportamento do fill
+
+- **`fill: true`** - Reescreve o arquivo atual com o conteúdo preenchido para todos os idiomas
+- **`fill: "path/to/file"`** - Preenche o arquivo especificado sem modificar o arquivo atual
+- **`fill: false`** - Desativa completamente o auto-fill
+
+### Suporte aprimorado para estruturas de conteúdo complexas
+
+O comando fill agora suporta estruturas complexas de declaração de conteúdo, incluindo:
+
+- **Objetos compostos**: Declarações de conteúdo que referenciam outros objetos
+- **Conteúdo desestruturado**: Conteúdo que usa padrões de desestruturação
+- **Referências aninhadas**: Objetos que se chamam mutuamente em hierarquias complexas
+- **Estruturas de conteúdo dinâmicas**: Conteúdo com propriedades condicionais ou computadas
+
+### Benefícios
+
+- **Intenção mais clara**: O comportamento agora é mais explícito sobre o que é modificado
+- **Melhor separação**: Os arquivos de conteúdo podem ser mantidos separados das traduções preenchidas
+- **Fluxo de trabalho aprimorado**: Os desenvolvedores têm mais controle sobre onde as traduções são armazenadas
+- **Suporte a estruturas complexas**: Lida com arquiteturas de conteúdo sofisticadas com múltiplos objetos interconectados
+
+### Exemplo de uso
+
+```typescript
+// Reescreve o arquivo atual com todos os idiomas
+const content = {
+  key: "example",
+  fill: true, // Reescreve este arquivo
+  content: {
+    title: "Hello World",
+  },
+};
+
+// Preenche arquivo separado sem modificar o arquivo atual
+const content = {
+  key: "example",
+  fill: "./translations.json", // Cria/atualiza translations.json
+  content: {
+    title: "Hello World",
+  },
+};
+
+// Desabilita o preenchimento automático
+const content = {
+  key: "example",
+  fill: false, // Sem preenchimento automático
+  content: {
+    title: "Hello World",
+  },
+};
+
+// Estrutura complexa de conteúdo com objetos compostos
+const sharedContent = {
+  buttons: {
+    save: "Salvar",
+    cancel: "Cancelar",
+  },
+};
+
+const content = {
+  key: "complex-example",
+  fill: true,
+  content: {
+    // Referências a outros objetos
+    sharedContent,
+
+    // Conteúdo desestruturado
+    ...sharedContent,
+
+    // Referências aninhadas
+    sections: [
+      {
+        ...sharedContent.buttons,
+        header: "Seção 1",
+      },
+    ],
+  },
+};
+```
+
+---
+
+## Estabilidade aprimorada e gerenciamento de tradução
+
+A versão 7 introduz várias melhorias para tornar a tradução de conteúdo mais confiável e eficiente:
+
+### Atualizações completas dos arquivos de declaração de conteúdo
+
+O sistema agora atualiza arquivos `.content.{ts,js,cjs,mjs}` em vez de atualizações parciais, garantindo:
+
+- **Integridade dos dados**: Reescritas completas dos arquivos evitam atualizações parciais que poderiam corromper o conteúdo
+- **Consistência**: Todos os locais são atualizados de forma atômica, mantendo a sincronização
+- **Confiabilidade**: Reduz o risco de arquivos de conteúdo incompletos ou malformados
+
+### Gerenciamento inteligente de tentativas
+
+Novos mecanismos de retentativa evitam o envio de conteúdo em formatos incorretos e impedem que todo o processo de preenchimento seja interrompido se uma requisição falhar.
+
+### Paralelização para processamento mais rápido
+
+As operações de tradução agora são executadas em uma fila para rodar em paralelo. Isso acelera significativamente o processo.
+
+### Divisão inteligente para arquivos grandes
+
+Estratégias avançadas de divisão lidam com arquivos de conteúdo grandes sem exceder as janelas de contexto da IA:
+
+### Exemplo de fluxo de trabalho
+
+```typescript
+// Arquivo de conteúdo grande é automaticamente dividido
+const content = {
+  key: "large-documentation",
+  fill: true,
+  content: {
+    // Conteúdo grande automaticamente dividido para processamento pela IA
+    introduction: "..." // mais de 5000 caracteres
+    sections: [
+      // Múltiplas seções grandes
+    ]
+  }
+};
+```
+
+O sistema automaticamente:
+
+1. Analisa o tamanho e a estrutura do conteúdo
+2. Divide o conteúdo apropriadamente
+3. Processa os pedaços em paralelo
+4. Valida e tenta novamente se necessário
+5. Reconstrói o arquivo completo
+
+---
+
+## Notas de migração da versão 6
+
+### Configurações removidas
+
+- **`middleware.cookieName`**: Substituído por `routing.storage`
+- **`middleware.serverSetCookie`**: Substituído por `routing.storage`
+- **`middleware.prefixDefault`**: Substituído por `routing.mode`
+- **`middleware.noPrefix`**: Substituído por `routing.mode`
+
+### Mapeamento de migração
+
+#### Mapeamento de configuração
+
+| Configuração v6            | Configuração v7                                                |
+| -------------------------- | -------------------------------------------------------------- |
+| `autoFill: xxx`            | `fill: xxx`                                                    |
+| `prefixDefault: false`     | `mode: 'prefix-no-default'`                                    |
+| `prefixDefault: true`      | `mode: 'prefix-all'`                                           |
+| `noPrefix: true`           | `mode: 'no-prefix'`                                            |
+| `cookieName: 'my-locale'`  | `storage: { type: 'cookie', name: 'my-locale' }`               |
+| `serverSetCookie: 'never'` | `storage: false` ou remover o cookie do array de armazenamento |
+
+#### Exemplo de migração
+
+**Antes (v6):**
+
+```typescript
+export default {
+  middleware: {
+    headerName: "x-intlayer-locale",
+    cookieName: "intlayer-locale",
+    prefixDefault: false,
+    basePath: "",
+    serverSetCookie: "always",
+    noPrefix: false,
+  },
+};
+```
+
+**Depois (v7):**
+
+```typescript
+export default {
+  routing: {
+    mode: "prefix-no-default",
+    storage: "localStorage", // ou 'cookie' se precisar de armazenamento via cookie
+    headerName: "x-intlayer-locale",
+    basePath: "",
+    detectLocaleOnPrefetchNoPrefix: false,
+  },
+};
+```
+
+#### Mapeamento do conteúdo do dicionário
+
+| Conteúdo do dicionário v6 | Conteúdo do dicionário v7 |
+| ------------------------- | ------------------------- |
+| `autoFill: xxx`           | `fill: xxx`               |
+
+#### Exemplo de migração
+
+**Antes (v6):**
+
+```typescript
+const content = {
+  key: "example",
+  autoFill: true, // Reescreve este arquivo
+  content: {
+    title: "Olá Mundo",
+  },
+};
+```
+
+**Depois (v7):**
+
+```typescript
+const content = {
+  key: "example",
+  fill: true, // Reescreve este arquivo
+  content: {
+    title: "Olá Mundo",
+  },
+};
+```
+
+---
+
+## Notas de migração do v5 para o v6
+
+Consulte as [notas de migração do v5 para o v6](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/releases/v6.md) para mais informações.
+
+---
+
+## Links úteis
+
+- [Referência de Configuração](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/configuration.md)
+- [Documentação do Middleware](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/packages/next-intlayer/index.md)
+- [Tipos TypeScript](https://github.com/aymericzip/intlayer/blob/main/packages/%40intlayer/types/src/index.ts)
+- [Diretrizes de Cookies GDPR](https://gdpr.eu/cookies/)