Documentação de Configuração do Intlayer

Visão Geral

Os arquivos de configuração do Intlayer permitem a personalização de vários aspectos do plugin, como internacionalização, middleware e manipulação de conteúdo. Este documento fornece uma descrição detalhada de cada propriedade na configuração.

Suporte a Arquivos de Configuração

O Intlayer aceita formatos de arquivos de configuração JSON, JS, MJS e TS:

• intlayer.config.ts
• intlayer.config.js
• intlayer.config.json
• intlayer.config.cjs
• intlayer.config.mjs
• .intlayerrc

Exemplo de arquivo de configuração

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH], // locais configurados para internacionalização  },  content: {    autoFill: "./{{fileName}}.content.json", // preenchimento automático do conteúdo    contentDir: ["src", "../ui-library"], // diretórios de conteúdo  },  middleware: {    noPrefix: false, // configuração do middleware para prefixo  },  editor: {    applicationURL: "https://example.com", // URL da aplicação para o editor  },  ai: {    apiKey: process.env.OPENAI_API_KEY, // chave da API para AI    applicationContext: "This is a test application", // contexto da aplicação para AI  },  build: {    importMode: "dynamic", // modo de importação para build  },};export default config;

Referência de Configuração

As seções a seguir descrevem as várias configurações disponíveis para o Intlayer.

Configuração de Internacionalização

Define as configurações relacionadas à internacionalização, incluindo os locais disponíveis e o local padrão para a aplicação.

Propriedades

• locales:

  • Tipo: string[]
  • Padrão: ['en']
  • Descrição: A lista de locais suportados na aplicação.
  • Exemplo: ['en', 'fr', 'es']
• requiredLocales:
  • Tipo: string[]
  • Padrão: []
  • Descrição: A lista de locais obrigatórios na aplicação.
  • Exemplo: []
  • Nota: Se estiver vazio, todos os locais são obrigatórios no modo strict.
  • Nota: Certifique-se de que os locais obrigatórios também estejam definidos no campo locales.

• strictMode:

  • Tipo: string
  • Padrão: inclusive
  • Descrição: Garante implementações rigorosas de conteúdo internacionalizado usando typescript.
  • Nota: Se definido como "strict", a função de tradução t exigirá que cada local declarado esteja definido. Se algum local estiver faltando, ou se um local não estiver declarado na sua configuração, isso gerará um erro.
  • Nota: Se definido como "inclusive", a função de tradução t exigirá que cada local declarado esteja definido. Se algum local estiver faltando, isso gerará um aviso. Mas aceitará se um local não estiver declarado na sua configuração, mas existir.
  • Nota: Se definido como "loose", a função de tradução t aceitará qualquer localidade existente.

• defaultLocale:

  • Tipo: string
  • Padrão: 'en'
  • Descrição: A localidade padrão usada como fallback caso a localidade solicitada não seja encontrada.
  • Exemplo: 'en'
  • Nota: Isso é usado para determinar a localidade quando nenhuma é especificada na URL, cookie ou cabeçalho.

Configuração do Editor

Define configurações relacionadas ao editor integrado, incluindo porta do servidor e status ativo.

Propriedades

• applicationURL:

  • Tipo: string
  • Padrão: http://localhost:3000
  • Descrição: A URL da aplicação. Usada para restringir a origem do editor por razões de segurança.
  • Exemplo:
    • 'http://localhost:3000'
    • 'https://example.com'
    • process.env.INTLAYER_EDITOR_URL
  • Nota: A URL da aplicação. Usada para restringir a origem do editor por razões de segurança. Se definida como '*', o editor fica acessível de qualquer origem.

• port:

  • Tipo: number
  • Padrão: 8000
  • Descrição: A porta usada pelo servidor do editor visual.

• editorURL:

  • Tipo: string
  • Padrão: 'http://localhost:8000'
  • Descrição: A URL do servidor do editor. Usada para restringir a origem do editor por razões de segurança.
    • 'http://localhost:3000'
    • 'https://example.com'
    • process.env.INTLAYER_EDITOR_URL
  • Nota: A URL do servidor do editor para acessar a partir da aplicação. Usada para restringir as origens que podem interagir com a aplicação por razões de segurança. Se definida como '*', o editor é acessível de qualquer origem. Deve ser configurada se a porta for alterada ou se o editor estiver hospedado em um domínio diferente.

• cmsURL:

  • Tipo: string
  • Padrão: 'https://intlayer.org'
  • Descrição: A URL do CMS Intlayer.
  • Exemplo: 'https://intlayer.org'
  • Nota: A URL do CMS Intlayer.

• backendURL:

  • Tipo: string
  • Padrão: https://back.intlayer.org
  • Descrição: A URL do servidor backend.
  • Exemplo: http://localhost:4000

• enabled:

  • Tipo: boolean
  • Padrão: true
  • Descrição: Indica se a aplicação interage com o editor visual.
  • Exemplo: process.env.NODE_ENV !== 'production'
  • Nota: Se verdadeiro, o editor poderá interagir com a aplicação. Se falso, o editor não poderá interagir com a aplicação. Em qualquer caso, o editor só pode ser ativado pelo editor visual. Desativar o editor para ambientes específicos é uma forma de reforçar a segurança.

• clientId:

  • Tipo: string | undefined
  • Padrão: undefined
  • Descrição: clientId e clientSecret permitem que os pacotes intlayer autentiquem com o backend usando autenticação oAuth2. Um token de acesso é usado para autenticar o usuário relacionado ao projeto. Para obter um token de acesso, acesse https://intlayer.org/dashboard/project e crie uma conta.
  • Exemplo: true
  • Nota: Importante: O clientId e o clientSecret devem ser mantidos em segredo e não compartilhados publicamente. Por favor, certifique-se de mantê-los em um local seguro, como variáveis de ambiente.

• clientSecret:

  • Tipo: string | undefined
  • Padrão: undefined
  • Descrição: clientId e clientSecret permitem que os pacotes intlayer se autentiquem com o backend usando autenticação oAuth2. Um token de acesso é usado para autenticar o usuário relacionado ao projeto. Para obter um token de acesso, acesse https://intlayer.org/dashboard/project e crie uma conta.
  • Exemplo: true
  • Nota: Importante: O clientId e o clientSecret devem ser mantidos em sigilo e não compartilhados publicamente. Por favor, certifique-se de mantê-los em um local seguro, como variáveis de ambiente.

• dictionaryPriorityStrategy:

  • Tipo: string
  • Padrão: 'local_first'
  • Descrição: A estratégia para priorizar dicionários no caso de ambos, dicionários locais e distantes, estarem presentes. Se definido como 'distant_first', a aplicação priorizará dicionários distantes sobre os locais. Se definido como 'local_first', a aplicação priorizará dicionários locais sobre os distantes.
  • Exemplo: 'distant_first'

• liveSync:

  • Tipo: boolean
  • Padrão: false
  • Descrição: Indica se o servidor da aplicação deve recarregar o conteúdo da aplicação automaticamente quando uma alteração for detectada no CMS / Editor Visual / Backend.
  • Exemplo: true
  • Nota: Por exemplo, quando um novo dicionário é adicionado ou atualizado, a aplicação atualizará o conteúdo para exibição na página.
  • Nota: A sincronização ao vivo precisa externalizar o conteúdo da aplicação para outro servidor. Isso significa que pode impactar ligeiramente o desempenho da aplicação. Para limitar isso, recomendamos hospedar a aplicação e o servidor de sincronização ao vivo na mesma máquina. Além disso, a combinação de sincronização ao vivo e optimize pode gerar um número considerável de requisições ao servidor de sincronização ao vivo. Dependendo da sua infraestrutura, recomendamos testar ambas as opções e sua combinação.

• liveSyncPort:

  • Tipo: number
  • Padrão: 4000
  • Descrição: A porta do servidor de sincronização ao vivo.
  • Exemplo: 4000
  • Nota: A porta do servidor de sincronização ao vivo.

• liveSyncURL:

  • Tipo: string
  • Padrão: 'http://localhost:{liveSyncPort}'
  • Descrição: A URL do servidor de sincronização ao vivo.
  • Exemplo: 'https://example.com'
  • Nota: Aponta para localhost por padrão, mas pode ser alterado para qualquer URL no caso de um servidor de sincronização ao vivo remoto.

Configuração do Middleware

Configurações que controlam o comportamento do middleware, incluindo como a aplicação lida com cookies, cabeçalhos e prefixos de URL para gerenciamento de localidade.

Propriedades

• headerName:

  • Tipo: string
  • Padrão: 'x-intlayer-locale'
  • Descrição: O nome do cabeçalho HTTP usado para determinar a localidade.
  • Exemplo: 'x-custom-locale'
  • Nota: Útil para determinação de localidade baseada em API.

• cookieName:

  • Tipo: string
  • Padrão: 'intlayer-locale'
  • Descrição: O nome do cookie usado para armazenar a localidade.
  • Exemplo: 'custom-locale'
  • Nota: Usado para persistir a localidade entre sessões.

• prefixDefault:

  • Tipo: boolean
  • Padrão: false
  • Descrição: Se deve incluir a localidade padrão na URL.
  • Exemplo: true
  • Nota:
    • Se true e defaultLocale = 'en': caminho = /en/dashboard ou /fr/dashboard
    • Se false e defaultLocale = 'en': caminho = /dashboard ou /fr/dashboard

• basePath:

  • Tipo: string
  • Padrão: ''
  • Descrição: O caminho base para as URLs da aplicação.
  • Exemplo: '/my-app'
  • Nota:
    • Se a aplicação estiver hospedada em https://example.com/my-app
    • O caminho base é '/my-app'
    • A URL será https://example.com/my-app/en
    • Se o caminho base não estiver definido, a URL será https://example.com/en

• serverSetCookie:

  • Tipo: string
  • Padrão: 'always'
  • Descrição: Regra para definir o cookie de localidade no servidor.
  • Opções: 'always', 'never'
  • Exemplo: 'never'
  • Nota: Controla se o cookie de localidade é definido a cada requisição ou nunca.

• noPrefix:

  • Tipo: boolean
  • Padrão: false
  • Descrição: Se deve omitir o prefixo da localidade nas URLs.
  • Exemplo: true
  • Nota:
    • Se true: Sem prefixo na URL
    • Se false: Com prefixo na URL
    • Exemplo com basePath = '/my-app':
      • Se noPrefix = false: a URL será https://example.com/my-app/en
      • Se noPrefix = true: a URL será https://example.com

• detectLocaleOnPrefetchNoPrefix:

  • Tipo: boolean
  • Padrão: false
  • Descrição: Controla se a detecção de local ocorre durante as requisições de prefetch do Next.js.
  • Exemplo: true
  • Nota: Esta configuração afeta como o Next.js lida com o prefetch de local:
    • Cenário de exemplo:
      • O idioma do navegador do usuário é 'fr'
      • A página atual é /fr/about
      • O link faz prefetch de /about
    • Com detectLocaleOnPrefetchNoPrefix: true:
      • O prefetch detecta o local 'fr' do navegador
      • Redireciona o prefetch para /fr/about
    • Com detectLocaleOnPrefetchNoPrefix: false (padrão):
      • O prefetch usa o local padrão
      • Redireciona o prefetch para /en/about (assumindo que 'en' é o padrão)
    • Quando usar true:
      • Sua aplicação usa links internos não localizados (ex: <a href="/about">)
      • Você deseja um comportamento consistente de detecção de localidade entre requisições normais e prefetch
    • Quando usar false (padrão):
      • Sua aplicação usa links com prefixo de localidade (ex: <a href="/fr/about">)
      • Você deseja otimizar a performance do prefetch
      • Você deseja evitar possíveis loops de redirecionamento

Configuração de Conteúdo

Configurações relacionadas ao manuseio de conteúdo dentro da aplicação, incluindo nomes de diretórios, extensões de arquivos e configurações derivadas.

Propriedades

• autoFill:

  • Tipo: boolean | string | { [key in Locales]?: string }
  • Padrão: undefined
  • Descrição: Indica como o conteúdo deve ser preenchido automaticamente usando IA. Pode ser declarado globalmente no arquivo intlayer.config.ts.
  • Exemplo: true
  • Exemplo: './{{fileName}}.content.json'
  • Exemplo: { fr: './{{fileName}}.fr.content.json', es: './{{fileName}}.es.content.json' }
  • Nota: A configuração de preenchimento automático pode ser:
    • booleano: Ativa o preenchimento automático para todos os locais
    • string: Caminho para um único arquivo ou template com variáveis
    • objeto: Caminhos de arquivos por localidade

• watch:

  • Tipo: boolean
  • Padrão: process.env.NODE_ENV === 'development'
  • Descrição: Indica se o Intlayer deve monitorar alterações nos arquivos de declaração de conteúdo na aplicação para reconstruir os dicionários relacionados.

• fileExtensions:

  • Tipo: string[]
  • Default: ['.content.ts', '.content.js', '.content.cjs', '.content.mjs', '.content.json', '.content.tsx', '.content.jsx']
  • Descrição: Extensões de arquivo a serem procuradas ao construir dicionários.
  • Exemplo: ['.data.ts', '.data.js', '.data.json']
  • Nota: Personalizar extensões de arquivo pode ajudar a evitar conflitos.

• baseDir:

  • Tipo: string
  • Padrão: process.cwd()
  • Descrição: O diretório base para o projeto.
  • Exemplo: '/path/to/project'
  • Nota: Isso é usado para resolver todos os diretórios relacionados ao Intlayer.

• dictionaryOutput:

  • Tipo: string[]
  • Padrão: ['intlayer']
  • Descrição: O tipo de saída do dicionário a ser usado, por exemplo, 'intlayer' ou 'i18next'.

• contentDir:

  • Tipo: string[]
  • Padrão: ['.']
  • Exemplo: ['src', '../../ui-library', require.resolve("@my-package/content")]
  • Descrição: O caminho do diretório onde o conteúdo é armazenado.

• dictionariesDir:

  • Tipo: string
  • Padrão: '.intlayer/dictionaries'
  • Descrição: O caminho do diretório para armazenar resultados intermediários ou de saída.

• moduleAugmentationDir:

  • Tipo: string
  • Padrão: '.intlayer/types'
  • Descrição: Diretório para a ampliação de módulos, permitindo melhores sugestões na IDE e verificação de tipos.
  • Exemplo: 'intlayer-types'
  • Nota: Certifique-se de incluir isso no tsconfig.json.

• unmergedDictionariesDir:

  • Tipo: string
  • Padrão: '.intlayer/unmerged_dictionary'
  • Descrição: O diretório para armazenar dicionários não mesclados.
  • Exemplo: 'translations'

• dictionariesDir:

  • Tipo: string
  • Padrão: '.intlayer/dictionary'
  • Descrição: O diretório para armazenar dicionários de localização.
  • Exemplo: 'translations'

• i18nextResourcesDir:

  • Tipo: string
  • Padrão: 'i18next_dictionary'
  • Descrição: O diretório para armazenar dicionários i18n.
  • Exemplo: 'translations'
  • Nota: Certifique-se de que este diretório está configurado para o tipo de saída i18next.

• typesDir:

  • Tipo: string
  • Padrão: 'types'
  • Descrição: O diretório para armazenar tipos de dicionário.
  • Exemplo: 'intlayer-types'

• mainDir:

  • Tipo: string
  • Padrão: 'main'
  • Descrição: O diretório onde os arquivos principais da aplicação são armazenados.
  • Exemplo: 'intlayer-main'

• excludedPath:

  • Tipo: string[]
  • Padrão: ['node_modules']
  • Descrição: Diretórios excluídos da busca de conteúdo.
  • Nota: Esta configuração ainda não é utilizada, mas está planejada para implementação futura.

Configuração do Logger

Configurações que controlam o logger, incluindo o prefixo a ser usado.

Propriedades

• mode:

  • Tipo: string
  • Padrão: default
  • Descrição: Indica o modo do logger.
  • Opções: default, verbose, disabled
  • Exemplo: default
  • Nota: O modo do logger. O modo verbose registrará mais informações, mas pode ser usado para fins de depuração. O modo disabled desabilitará o logger.

• prefix:

  • Tipo: string
  • Padrão: '[intlayer] '
  • Descrição: O prefixo do logger.
  • Exemplo: '[meu prefixo personalizado] '
  • Nota: O prefixo do logger.

Configuração de IA

Configurações que controlam os recursos de IA do Intlayer, incluindo o provedor, modelo e chave de API.

Esta configuração é opcional se você estiver registrado no Painel do Intlayer usando uma chave de acesso. O Intlayer gerenciará automaticamente a solução de IA mais eficiente e econômica para suas necessidades. Usar as opções padrão garante melhor manutenção a longo prazo, pois o Intlayer atualiza continuamente para usar os modelos mais relevantes.

Se preferir usar sua própria chave de API ou modelo específico, você pode definir sua configuração personalizada de IA. Esta configuração de IA será usada globalmente em todo o seu ambiente Intlayer. Os comandos CLI usarão essas configurações como padrão para os comandos (por exemplo, fill), assim como o SDK, Editor Visual e CMS. Você pode substituir esses valores padrão para casos de uso específicos usando parâmetros de comando.

O Intlayer suporta múltiplos provedores de IA para maior flexibilidade e escolha. Os provedores atualmente suportados são:

• OpenAI (padrão)
• Anthropic Claude
• Mistral AI
• DeepSeek
• Google Gemini
• Meta Llama

Propriedades

• provider:

  • Tipo: string
  • Padrão: 'openai'
  • Descrição: O provedor a ser usado para os recursos de IA do Intlayer.
  • Opções: 'openai', 'anthropic', 'mistral', 'deepseek', 'gemini'
  • Exemplo: 'anthropic'
  • Nota: Diferentes provedores podem exigir diferentes chaves de API e possuir modelos de preços distintos.

• model:

  • Tipo: string
  • Padrão: Nenhum
  • Descrição: O modelo a ser usado para os recursos de IA do Intlayer.
  • Exemplo: 'gpt-4o-2024-11-20'
  • Nota: O modelo específico a ser usado varia conforme o provedor.

• temperature:

  • Tipo: number
  • Padrão: Nenhum
  • Descrição: A temperatura controla a aleatoriedade das respostas da IA.
  • Exemplo: 0.1
  • Nota: Uma temperatura mais alta tornará a IA mais criativa e menos previsível.

• apiKey:

  • Tipo: string
  • Padrão: Nenhum
  • Descrição: Sua chave de API para o provedor selecionado.
  • Exemplo: process.env.OPENAI_API_KEY
  • Nota: Importante: As chaves de API devem ser mantidas em segredo e não compartilhadas publicamente. Por favor, certifique-se de mantê-las em um local seguro, como variáveis de ambiente.

• applicationContext:

  • Tipo: string
  • Padrão: Nenhum
  • Descrição: Fornece contexto adicional sobre sua aplicação para o modelo de IA, ajudando-o a gerar traduções mais precisas e contextualmente apropriadas. Isso pode incluir informações sobre o domínio do seu app, público-alvo, tom ou terminologia específica.

Configuração de Build

Configurações que controlam como o Intlayer otimiza e constrói a internacionalização da sua aplicação.

As opções de build se aplicam aos plugins @intlayer/babel e @intlayer/swc.

No modo de desenvolvimento, o Intlayer usa importações estáticas para dicionários para simplificar a experiência de desenvolvimento.

Quando otimizado, o Intlayer substituirá as chamadas de dicionários para otimizar a divisão em chunks, de modo que o pacote final importe apenas os dicionários que são realmente usados.

Propriedades

• optimize:

  • Tipo: boolean
  • Padrão: process.env.NODE_ENV === 'production'
  • Descrição: Controla se a build deve ser otimizada.
  • Exemplo: true
  • Nota: Quando ativado, o Intlayer substituirá todas as chamadas de dicionários para otimizar a divisão em chunks. Dessa forma, o pacote final importará apenas os dicionários que são usados. Todas as importações permanecerão como importações estáticas para evitar processamento assíncrono ao carregar os dicionários.
  • Nota: O Intlayer substituirá todas as chamadas de useIntlayer pelo modo definido pela opção importMode e getIntlayer por getDictionary.
  • Nota: Esta opção depende dos plugins @intlayer/babel e @intlayer/swc.
  • Nota: Certifique-se de que todas as chaves sejam declaradas estaticamente nas chamadas de useIntlayer. Exemplo: useIntlayer('navbar').

• importMode:

  • Tipo: 'static' | 'dynamic' | 'live'
  • Padrão: 'static'
  • Descrição: Controla como os dicionários são importados.
  • Exemplo: 'dynamic'
  • Nota: Modos disponíveis:
    • "static": Os dicionários são importados estaticamente. Substitui useIntlayer por useDictionary.
    • "dynamic": Os dicionários são importados dinamicamente usando Suspense. Substitui useIntlayer por useDictionaryDynamic.
  • "live": Os dicionários são buscados dinamicamente usando a API de sincronização ao vivo. Substitui useIntlayer por useDictionaryFetch.
  • Nota: Importações dinâmicas dependem do Suspense e podem impactar levemente o desempenho da renderização.
  • Nota: Se desativado, todos os idiomas serão carregados de uma vez, mesmo que não sejam usados.
  • Nota: Esta opção depende dos plugins @intlayer/babel e @intlayer/swc.
  • Nota: Garanta que todas as chaves sejam declaradas estaticamente nas chamadas useIntlayer. Exemplo: useIntlayer('navbar').
  • Nota: Esta opção será ignorada se optimize estiver desativado.
  • Nota: Se definido como "live", apenas os dicionários que incluem conteúdo remoto e estão marcados como "live" serão transformados no modo live. Os outros serão importados dinamicamente no modo "dynamic" para otimizar o número de consultas fetch e o desempenho de carregamento.
  • Nota: O modo live usará a API de sincronização ao vivo para buscar os dicionários. Se a chamada da API falhar, os dicionários serão importados dinamicamente no modo "dynamic".
  • Nota: Esta opção não impactará as funções getIntlayer, getDictionary, useDictionary, useDictionaryAsync e useDictionaryDynamic.

• traversePattern:

  • Tipo: string[]
  • Padrão: ['**/*.{js,ts,mjs,cjs,jsx,tsx,mjx,cjx}', '!**/node_modules/**']
  • Descrição: Padrões que definem quais arquivos devem ser percorridos durante a otimização.
    • Exemplo: ['src/**/*.{ts,tsx}', '../ui-library/**/*.{ts,tsx}', '!**/node_modules/**']
  • Nota: Use isso para limitar a otimização aos arquivos de código relevantes e melhorar o desempenho da compilação.
  • Nota: Esta opção será ignorada se optimize estiver desativado.
  • Nota: Use padrão glob.

Histórico da Documentação

• Descrição: Padrões que definem quais arquivos devem ser percorridos durante a otimização.
• Exemplo: ['src/**/*.{ts,tsx}', '../ui-library/**/*.{ts,tsx}', '!**/node_modules/**']
• Nota: Use isso para limitar a otimização aos arquivos de código relevantes e melhorar o desempenho da build.
• Nota: Esta opção será ignorada se optimize estiver desativado.
• Nota: Use padrão glob.

Histórico da Documentação