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.

Índice

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.

Formatação Automática de Código: configuração formatCommand

v7 introduz a opção formatCommand na configuração do editor, permitindo que você formate automaticamente os arquivos de conteúdo quando forem escritos pelo Intlayer. Isso garante um estilo de código e formatação consistentes em seus arquivos de declaração de conteúdo.

Se não definido, Intlayer tentará detectar o comando de formatação automaticamente. Tentando resolver os seguintes comandos: prettier, biome, eslint.

Configuração

A opção formatCommand aceita um template de string onde {{file}} será substituído pelo caminho do arquivo real:

export default {  content: {    formatCommand: 'bun x biome format "{{file}}" --write --log-level none',  },};

Formatadores suportados

Você pode usar qualquer formatador de código que aceite caminhos de arquivo como argumentos:

Usando Biome:

formatCommand: 'bun x biome format "{{file}}" --write --log-level none';

Usando Prettier:

formatCommand: 'npx prettier --write "{{file}}" --log-level silent';

Usando ESLint:

formatCommand: 'npx eslint --fix "{{file}}" --quiet';

Usando o formatador integrado do Bun:

formatCommand: 'bun format "{{file}}"';

Benefícios

• Formatação consistente: Todos os arquivos de conteúdo são automaticamente formatados de acordo com as diretrizes de estilo do seu projeto
• Experiência do desenvolvedor: Sem necessidade de formatar manualmente arquivos após o Intlayer escrevê-los
• Consistência da equipe: Garante que todos os membros da equipe tenham a mesma formatação aplicada aos arquivos de conteúdo
• Integração CI/CD: Arquivos de conteúdo mantêm formatação consistente em fluxos de trabalho automatizados

Como funciona

When Intlayer writes or updates a content declaration file (.content.ts, .content.js, etc.), it automatically runs the specified format command on the file. The {{file}} placeholder is replaced with the actual file path, and the command is executed in the project's base directory.

Configuração de Dicionário: Melhor organização e estrutura

v7 introduz uma nova seção de configuração dictionary dedicada que oferece melhor organização para configurações relacionadas a dicionários e gerenciamento de conteúdo aprimorado.

Nova estrutura de configuração de dicionário

A propriedade fill foi movida da seção content para uma nova seção dictionary, proporcionando uma separação de responsabilidades mais clara:

Configuração v6:

export default {  content: {    autoFill: "./{{fileName}}.content.json",    contentDir: ["src"],  },};

Configuração v7:

export default {  content: {    contentDir: ["src"],  },  dictionary: {    fill: "./{{fileName}}.content.json",  },};

Benefícios da nova estrutura

• Organização mais clara: As configurações específicas do dicionário agora estão agrupadas
• Melhor separação de responsabilidades: A descoberta de conteúdo versus operações de dicionário estão claramente separadas
• Manutenibilidade aprimorada: Mais fácil entender e modificar as configurações relacionadas ao dicionário
• Extensibilidade futura: A seção de dicionário pode acomodar configurações adicionais específicas do dicionário
• Gerenciamento abrangente de dicionário: Inclui propriedades como title, live, priority, tags, version e description para criar e gerenciar novos dicionários

Uso da configuração

A configuração do dicionário serve dois propósitos principais:

1. Valores padrão: Definir valores padrão ao criar ficheiros de declaração de conteúdo
2. Comportamento de fallback: Fornecer valores de fallback quando campos específicos não estão definidos, permitindo-lhe definir o comportamento da operação do dicionário globalmente

A seção do dicionário inclui propriedades abrangentes para gerenciamento de dicionário:

• fill: Comportamento de preenchimento automático para geração de conteúdo
• title: Título padrão para novos dicionários
• live: Configuração de sincronização em tempo real para atualizações em tempo real
• priority: Configurações de prioridade para resolução de dicionário
• tags: Tags padrão para organização de conteúdo
• version: Gerenciamento de versão para atualizações de dicionário
• description: Descrição padrão para novo conteúdo

Para mais informações sobre ficheiros de declaração de conteúdo e como os valores de configuração são aplicados, consulte a Documentação de Ficheiros de Conteúdo.

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

Novas configurações

• editor.formatCommand: Nova opção para formatação automática de código em arquivos de conteúdo

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