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.

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:

const content = getIntlayer("my-title-content", "en");// typeof content = { title: "My title" } | { title: "Mon titre" } | { title: "Mi título" }

Comportamento na v7:

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:

import { Locales } from "intlayer";// Enum incluindo todas as localidades -> não é tree-shakeableconst locale: Locales = Locales.ENGLISH;

v7:

import { Locales, Locale } from "intlayer";// Tipo string -> totalmente tree-shakeableconst 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 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

// intlayer.config.tsexport 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:

// Desabilitar armazenamentostorage: false// Tipos simples de armazenamentostorage: 'cookie'storage: 'localStorage'storage: 'sessionStorage'// Cookie com atributos personalizadosstorage: {  type: 'cookie',  name: 'custom-locale',  domain: '.example.com',  secure: true,  sameSite: 'strict'}// localStorage com chave personalizadastorage: {  type: 'localStorage',  name: 'custom-locale'}// Múltiplos tipos de armazenamento para redundânciastorage: ['cookie', 'localStorage']

Exemplo de configuração compatível com GDPR

Para aplicações em produção que precisam equilibrar funcionalidade com conformidade GDPR:

// intlayer.config.tsexport 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:

<IntlayerProvider isCookieEnabled={false}>  <App /></IntlayerProvider>

Pode ser sobrescrito localmente para cada hook:

const { setLocale } = useLocale({ isCookieEnabled: false });setLocale("en");

Nota: Os cookies estão ativados por padrão. Nota: Verifique os requisitos de cookies do GDPR 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

// Reescreve o arquivo atual com todos os idiomasconst content = {  key: "example",  fill: true, // Reescreve este arquivo  content: {    title: "Hello World",  },};// Preenche arquivo separado sem modificar o arquivo atualconst content = {  key: "example",  fill: "./translations.json", // Cria/atualiza translations.json  content: {    title: "Hello World",  },};// Desabilita o preenchimento automáticoconst content = {  key: "example",  fill: false, // Sem preenchimento automático  content: {    title: "Hello World",  },};// Estrutura complexa de conteúdo com objetos compostosconst 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

// Arquivo de conteúdo grande é automaticamente divididoconst 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

Exemplo de migração

Antes (v6):

export default {  middleware: {    headerName: "x-intlayer-locale",    cookieName: "intlayer-locale",    prefixDefault: false,    basePath: "",    serverSetCookie: "always",    noPrefix: false,  },};

Depois (v7):

export default {  routing: {    mode: "prefix-no-default",    storage: "localStorage", // ou 'cookie' se precisar de armazenamento via cookie    headerName: "x-intlayer-locale",    basePath: "",  },};

Mapeamento do conteúdo do dicionário

Exemplo de migração

Antes (v6):

const content = {  key: "example",  autoFill: true, // Reescreve este arquivo  content: {    title: "Olá Mundo",  },};

Depois (v7):

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 para mais informações.

Links úteis

• Referência de Configuração
• Documentação do Middleware
• Tipos TypeScript
• Diretrizes de Cookies GDPR