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 gerenciamento 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 arquivo 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],  },  content: {    contentDir: ["src", "../ui-library"],  },  middleware: {    noPrefix: false,  },  editor: {    applicationURL: "https://example.com",  },  ai: {    apiKey: process.env.OPENAI_API_KEY,    applicationContext: "This is a test application",  },  build: {    importMode: "dynamic",  },};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 configurações relacionadas à internacionalização, incluindo os idiomas disponíveis e o idioma padrão para a aplicação.

Propriedades

• locales:

  • Tipo: string[]
  • Padrão: ['en']
  • Descrição: A lista de idiomas suportados na aplicação.
  • Exemplo: ['en', 'fr', 'es']

• requiredLocales:

  • Tipo: string[]
  • Padrão: []
  • Descrição: A lista de idiomas obrigatórios na aplicação.
  • Exemplo: []
  • Nota: Se estiver vazio, todos os idiomas serão obrigatórios no modo strict.
  • Nota: Certifique-se de que os idiomas 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 idioma declarado seja definido. Se um idioma estiver ausente ou não for declarado na sua configuração, será lançado um erro.
  • Nota: Se definido como "inclusive", a função de tradução t exigirá que cada idioma declarado seja definido. Se um idioma estiver ausente, será exibido um aviso. Mas aceitará se um idioma não for declarado na sua configuração, mas existir.
  • Nota: Se definido como "loose", a função de tradução t aceitará qualquer idioma existente.

• defaultLocale:

  • Tipo: string
  • Padrão: 'en'
  • Descrição: O idioma padrão usado como fallback se o idioma solicitado não for encontrado.
  • Exemplo: 'en'
  • Nota: Isso é usado para determinar o idioma quando nenhum é especificado 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 definido como '*', o editor estará 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 definido como '*', o editor estará acessível de qualquer origem. Deve ser configurado 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 do Intlayer.
  • Exemplo: 'https://intlayer.org'
  • Nota: A URL do CMS do 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 do 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. 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 do 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. Certifique-se de mantê-los em um local seguro, como variáveis de ambiente.

• liveSync:

  • Tipo: boolean
  • Padrão: false
  • Descrição: Indica se a aplicação deve recarregar automaticamente as configurações de idioma quando uma alteração for detectada.
  • Exemplo: true
  • Nota: Por exemplo, quando um novo dicionário é adicionado ou atualizado, a aplicação atualizará o conteúdo exibido na página.
  • Nota: Como o recarregamento automático requer uma conexão contínua com o servidor, ele está disponível apenas para clientes do plano enterprise.

• dictionaryPriorityStrategy:

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

Configuração de 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 idiomas.

Propriedades

• headerName:

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

• cookieName:

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

• prefixDefault:

  • Tipo: boolean
  • Padrão: false
  • Descrição: Indica se o idioma padrão deve ser incluído na URL.
  • Exemplo: true
  • Nota:
    • Se true e defaultLocale = 'en': path = /en/dashboard ou /fr/dashboard
    • Se false e defaultLocale = 'en': path = /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 está 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 idioma no servidor.
  • Opções: 'always', 'never'
  • Exemplo: 'never'
  • Nota: Controla se o cookie de idioma é definido em todas as requisições ou nunca.

• noPrefix:

  • Tipo: boolean
  • Padrão: false
  • Descrição: Indica se o prefixo de idioma deve ser omitido das URLs.
  • Exemplo: true
  • Nota:
    • Se true: Sem prefixo na URL
    • Se false: 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 idioma ocorre durante as requisições de prefetch do Next.js.
  • Exemplo: true
  • Nota: Esta configuração afeta como o Next.js gerencia o prefetch de idioma:
    • 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 idioma 'fr' do navegador
      • Redireciona o prefetch para /fr/about
    • Com detectLocaleOnPrefetchNoPrefix: false (padrão):
      • O prefetch usa o idioma 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ê quer comportamento consistente de detecção de idioma entre requisições normais e de prefetch
    • Quando usar false (padrão):
      • Sua aplicação usa links com prefixo de idioma (ex. <a href="/fr/about">)
      • Você quer otimizar a performance do prefetch
      • Você quer evitar loops de redirecionamento potenciais

Configuração de Conteúdo

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

Propriedades

• 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[]
  • Padrão: ['.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 as 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: Usado para resolver todos os diretórios relacionados ao Intlayer.

• dictionaryOutput:

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

• contentDir:

  • Tipo: string[]
  • Padrão: ['src']
  • 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 aumento de módulo, permitindo melhores sugestões de 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 esteja 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 é usada, 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 desativará o logger.

• prefix:

  • Tipo: string
  • Padrão: '[intlayer] '
  • Descrição: O prefixo do logger.
  • Exemplo: '[my custom prefix] '
  • 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 ambiente do Intlayer. Comandos CLI usarão essas configurações como padrão para os comandos (por exemplo, fill), bem 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 vários 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 ter diferentes modelos de preços.

• 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 de acordo com 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. 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 ao 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 aplicativo, público-alvo, tom ou terminologia específica.

Configuração de Build

Configurações que controlam como o Intlayer otimiza e compila a internacionalização do seu aplicativo.

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.

Durante a otimização, o Intlayer substituirá as chamadas aos dicionários para otimizar o chunking, de modo que o bundle final importe apenas os dicionários que são realmente utilizados.

Propriedades

• optimize:

  • Tipo: boolean
  • Padrão: process.env.NODE_ENV === 'production'
  • Descrição: Controla se o build deve ser otimizado.
  • Exemplo: true
  • Nota: Quando ativado, o Intlayer substituirá todas as chamadas de dicionários para otimizar o chunking. Dessa forma, o bundle final importará apenas os dicionários que são utilizados. 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 com o 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 useIntlayer. por exemplo: useIntlayer('navbar').

• importMode:

  • Tipo: 'static' | 'dynamic' | 'async'
  • 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.
    • "async": Os dicionários são importados dinamicamente de forma assíncrona. Substitui useIntlayer por await useDictionaryAsync.
  • Nota: Importações dinâmicas dependem do Suspense e podem impactar levemente o desempenho de renderização.
  • Nota: Se desativado, todos os idiomas serão carregados de uma vez, mesmo que não sejam utilizados.
  • 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 useIntlayer. por exemplo: useIntlayer('navbar').
  • Nota: Esta opção será ignorada se optimize estiver desativado.
  • Nota: Na maioria dos casos, "dynamic" será usado para aplicações React, "async" para aplicações Vue.js.
  • Nota: Esta opção não afetará 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 a arquivos de código relevantes e melhorar o desempenho do build.
  • Nota: Esta opção será ignorada se optimize estiver desativado.
  • Nota: Use padrão glob.

Histórico da Documentação

• 5.5.11 - 2025-06-29: Adicionado comandos docs