Arquivo de Conteúdo

O que é um Arquivo de Conteúdo?

Um arquivo de conteúdo no Intlayer é um arquivo que contém definições de dicionário. Esses arquivos declaram o conteúdo de texto da sua aplicação, traduções e recursos. Os arquivos de conteúdo são processados pelo Intlayer para gerar dicionários.

Os dicionários serão o resultado final que sua aplicação importará usando o hook useIntlayer.

Conceitos Chave

Dicionário

Um dicionário é uma coleção estruturada de conteúdo organizada por chaves. Cada dicionário contém:

• Chave: Um identificador único para o dicionário
• Conteúdo: Os valores reais do conteúdo (texto, números, objetos, etc.)
• Metadados: Informações adicionais como título, descrição, tags, etc.

Arquivo de Conteúdo

Exemplo de arquivo de conteúdo:

import { type ReactNode } from "react";
import {
  t,
  enu,
  plural,
  cond,
  nest,
  md,
  insert,
  file,
  type Dictionary,
} from "intlayer";

interface Content {
  imbricatedContent: {
    imbricatedContent2: {
      stringContent: string;
      numberContent: number;
      booleanContent: boolean;
      javaScriptContent: string;
    };
  };
  multilingualContent: string;
  quantityContent: string;
  pluralContent: string;
  conditionalContent: string;
  markdownContent: never;
  htmlContent: never;
  externalContent: string;
  insertionContent: string;
  nestedContent: string;
  fileContent: string;
  jsxContent: ReactNode;
}

export default {
  key: "page",
  content: {
    imbricatedContent: {
      imbricatedContent2: {
        stringContent: "Olá Mundo",
        numberContent: 123,
        booleanContent: true,
        javaScriptContent: `${process.env.NODE_ENV}`,
      },
    },
    multilingualContent: t({
      pt: "Conteúdo em português",
      en: "English content",
      "en-GB": "English content (UK)",
      fr: "French content",
      es: "Spanish content",
    }),
    quantityContent: enu({
      "<-1": "Menos de menos um carro",
      "-1": "Menos um carro",
      "0": "Nenhum carro",
      "1": "Um carro",
      ">5": "Alguns carros",
      ">19": "Muitos carros",
    }),
    pluralContent: plural({
      one: "One car",
      other: "{{count}} cars",
    }),
    conditionalContent: cond({
      true: "Validação está ativada",
      false: "Validação está desativada",
    }),
    insertionContent: insert("Olá {{name}}!"),
    nestedContent: nest(
      "navbar", // A chave do dicionário para aninhar
      "login.button" // [Opcional] O caminho para o conteúdo a ser aninhado
    ),
    fileContent: file("./path/to/file.txt"),
    externalContent: fetch("https://example.com").then((res) => res.json()),
    markdownContent: md("# Exemplo de Markdown"),
    htmlContent: html("<p>Hello <strong>World</strong></p>"),

    /*
     * Disponível apenas usando `react-intlayer` ou `next-intlayer`
     */
    jsxContent: <h1>Meu título</h1>,
  },
} satisfies Dictionary<Content>; // [opcional] Dictionary é genérico e permite reforçar a formatação do seu dicionário

Nós de Conteúdo

Nós de conteúdo são os blocos de construção do conteúdo do dicionário. Eles podem ser:

• Valores primitivos: strings, números, booleanos, null, undefined
• Nós tipados: Tipos especiais de conteúdo como traduções, condições, markdown, etc.
• Funções: Conteúdo dinâmico que pode ser avaliado em tempo de execução veja Busca por Função
• Conteúdo Plural: Veja Conteúdo Plural Veja Conteúdo Plural
• Conteúdo aninhado: Referências a outros dicionários

Tipos de Conteúdo

Intlayer suporta vários tipos de conteúdo através de nós tipados:

• Conteúdo de Tradução: Texto multilíngue com valores específicos por localidade veja Conteúdo de Tradução
• Conteúdo Condicional: Conteúdo condicional baseado em expressões booleanas veja Conteúdo Condicional
• Conteúdo de Enumeração: Conteúdo que varia com base em valores enumerados veja Conteúdo de Enumeração
• Conteúdo de Inserção: Conteúdo que pode ser inserido em outro conteúdo veja Conteúdo de Inserção
• Conteúdo Markdown: Conteúdo de texto rico em formato Markdown veja Conteúdo Markdown
• Conteúdo HTML: Conteúdo HTML rico com componentes personalizados opcionais veja Conteúdo HTML
• Conteúdo Aninhado: Referências a outros dicionários veja Conteúdo Aninhado
• Conteúdo de Gênero: Conteúdo que varia com base no gênero veja Conteúdo de Gênero
• Conteúdo de Arquivo: Referências a arquivos externos veja Conteúdo de Arquivo

Estrutura do Dicionário

Um dicionário no Intlayer é definido pelo tipo Dictionary e contém várias propriedades que controlam seu comportamento:

Propriedades Obrigatórias

key (string)

O identificador do dicionário. Se múltiplos dicionários tiverem a mesma chave, o Intlayer irá mesclá-los automaticamente.

Use a convenção de nomenclatura kebab-case (por exemplo, "about-page-meta").

Content (string | number | boolean | object | array | function)

A propriedade content contém os dados reais do dicionário e suporta:

• Valores primitivos: strings, números, booleanos, null, undefined
• Nós tipados: Tipos especiais de conteúdo usando as funções auxiliares do Intlayer
• Objetos aninhados: Estruturas de dados complexas
• Arrays: Coleções de conteúdo
• Funções: Avaliação dinâmica de conteúdo

Propriedades Opcionais

title (string)

Título legível para humanos do dicionário que ajuda a identificá-lo em editores e sistemas CMS. Isso é particularmente útil ao gerenciar um grande número de dicionários ou ao trabalhar com interfaces de gerenciamento de conteúdo.

Exemplo:

{  key: "about-page-meta",  title: "Metadados da Página Sobre",  content: { /* ... */ }}

description (string)

Descrição detalhada que explica o propósito do dicionário, diretrizes de uso e quaisquer considerações especiais. Essa descrição também é usada como contexto para a geração de traduções assistida por IA, tornando-se valiosa para manter a qualidade e consistência das traduções.

Exemplo:

{  key: "about-page-meta",  description: [    "Este dicionário gerencia os metadados da Página Sobre",    "Considere boas práticas para SEO:",    "- O título deve ter entre 50 e 60 caracteres",    "- A descrição deve ter entre 150 e 160 caracteres",  ].join('\n'),  content: { /* ... */ }}

tags (string[])

Array de strings para categorizar e organizar dicionários. As tags fornecem contexto adicional e podem ser usadas para filtrar, pesquisar ou organizar dicionários em editores e sistemas CMS.

Exemplo:

{  key: "about-page-meta",  tags: ["metadata", "about-page", "seo"],  content: { /* ... */ }}

format ('intlayer' | 'icu' | 'i18next')

Especifica o formatador a ser usado para o conteúdo do dicionário. Isso permite usar diferentes sintaxes de formatação de mensagens.

• 'intlayer': O formatador Intlayer padrão.
• 'icu': Usa formatação de mensagens ICU.
• 'i18next': Usa formatação de mensagens i18next.

Exemplo:

{  key: "my-dictionary",  format: "icu",  content: {    message: "Hello {name}, you have {count, plural, one {# message} other {# messages}}"  }}

locale (LocalesValues)

Transforma o dicionário em um dicionário por localidade onde cada campo declarado no conteúdo será automaticamente transformado em um nó de tradução. Quando essa propriedade é definida:

• O dicionário é tratado como um dicionário de um único idioma
• Cada campo se torna um nó de tradução para esse idioma específico
• Você NÃO deve usar nós de tradução (t()) no conteúdo ao usar essa propriedade
• Se estiver ausente, o dicionário será tratado como um dicionário multilíngue

Veja Declaração de Conteúdo por Idioma no Intlayer para mais informações.

Exemplo:

// Dicionário por idioma{  "key": "about-page",  "locale": "en",  "content": {    "title": "About Us", // Isto se torna um nó de tradução para 'en'    "description": "Learn more about our company"  }}

schema (SchemaKeys)

O esquema do conteúdo do dicionário. Se definido, o conteúdo será validado contra este esquema. Isso permite que você imponha uma estrutura específica para o conteúdo do seu dicionário usando esquemas de validação personalizados definidos na sua configuração do Intlayer.

Exemplo:

import { z } from "zod";export default {  schemas: {    "seo-metadata": z.object({      title: z.string().min(50).max(60),      description: z.string().min(150).max(160),    }),  },};

import { type Dictionary } from "intlayer";const aboutPageMetaContent = {  key: "about-page-meta",  schema: "seo-metadata",  content: {    title: "About Our Company - Learn More About Us",    description: "Discover our company's mission, values, and team.",  },} satisfies Dictionary;export default aboutPageMetaContent;

location ('local' | 'remote' | 'hybrid' | string)

Indica a localização do dicionário e controla como ele sincroniza com o CMS:

• 'local': O dicionário é gerenciado apenas localmente. Ele não será enviado para o CMS remoto. Use isso para conteúdo que deve permanecer em sua base de código.
• 'remote': O dicionário é gerenciado apenas remotamente. Uma vez enviado para o CMS, ele será desvinculado do arquivo local. No momento do carregamento do conteúdo, o dicionário remoto será obtido do CMS. Um arquivo .content com localização remote será ignorado após o envio inicial.
• 'hybrid': O dicionário é gerenciado tanto localmente quanto remotamente. Uma vez enviado para o CMS, ele permanecerá sincronizado, alterações do arquivo local são enviadas para o CMS, e alterações remotas podem ser recuperadas no arquivo local.
• string (ex.: 'plugin'): O dicionário é gerenciado por um plugin ou uma fonte personalizada. Quando você tentar enviá-lo, o sistema perguntará o que fazer.

Exemplo:

{  key: "about-page",  location: "local", // O conteúdo permanece apenas em sua base de código  content: {    title: "About Us"  }}

autoFill (AutoFill)

Instruções para preenchimento automático do conteúdo do dicionário a partir de fontes externas. Isso pode ser configurado globalmente em intlayer.config.ts ou por dicionário. Suporta múltiplos formatos:

• true: Ativa o preenchimento automático para todas as localidades
• string: Caminho para um único arquivo ou modelo com variáveis
• object: Caminhos de arquivo por localidade

Exemplos:

// Ativa para todas as localidades{  "autoFill": true}// Arquivo único{  "autoFill": "./translations/aboutPage.content.json"}// Modelo com variáveis{  "autoFill": "/messages/{{locale}}/{{key}}/{{fileName}}.content.json"}// Configuração detalhada por localidade{  "autoFill": {    "en": "./translations/en/aboutPage.content.json",    "fr": "./translations/fr/aboutPage.content.json",    "es": "./translations/es/aboutPage.content.json"  }}

Variáveis disponíveis:

• {{locale}} – Código do idioma (ex.: fr, es)
• {{fileName}} – Nome do arquivo (ex.: example)
• {{key}} – Chave do dicionário (ex.: example)

Veja Configuração de Preenchimento Automático no Intlayer para mais informações.

priority (número)

Indica a prioridade do dicionário para resolução de conflitos. Quando múltiplos dicionários possuem a mesma chave, o dicionário com o maior número de prioridade irá sobrescrever os demais. Isso é útil para gerenciar hierarquias de conteúdo e substituições.

Exemplo:

// Dicionário base{  key: "welcome-message",  priority: 1,  content: { message: "Welcome!" }}// Dicionário de substituição{  key: "welcome-message",  priority: 10,  content: { message: "Bem-vindo ao nosso serviço premium!" }}// Isto irá sobrescrever o dicionário base

Propriedades do CMS

version (string)

Identificador de versão para dicionários remotos. Ajuda a rastrear qual versão do dicionário está sendo usada atualmente, especialmente útil ao trabalhar com sistemas de gerenciamento de conteúdo remotos.

importMode ('static' | 'dynamic' | 'fetch')

O modo de importação determina como seu dicionário é importado em sua aplicação.

• 'static': O dicionário é importado estaticamente no momento da compilação. Este é o modo padrão.
• 'dynamic': O dicionário é importado dinamicamente em tempo de execução usando a API de suspense.
• 'fetch': O dicionário é importado dinamicamente usando a API de sincronização ao vivo.

Se definido, esta propriedade substitui o importMode global definido em the dictionaryproperty ofintlayer.config.ts``.

Propriedades do Sistema (Geradas automaticamente)

Estas propriedades são geradas automaticamente pelo Intlayer e não devem ser modificadas manualmente:

$schema (string)

Esquema JSON usado para validação da estrutura do dicionário. Adicionado automaticamente pelo Intlayer para garantir a integridade do dicionário.

id (string)

Para dicionários remotos, este é o identificador único do dicionário no servidor remoto. Usado para buscar e gerenciar conteúdo remoto.

localId (LocalDictionaryId)

Identificador único para dicionários locais. Gerado automaticamente pelo Intlayer para ajudar a identificar o dicionário e determinar se é local ou remoto, junto com sua localização.

localIds (LocalDictionaryId[])

Para dicionários mesclados, este array contém os IDs de todos os dicionários que foram mesclados juntos. Útil para rastrear a origem do conteúdo mesclado.

filePath (string)

O caminho do arquivo do dicionário local, indicando de qual arquivo .content o dicionário foi gerado. Ajuda na depuração e no rastreamento da origem.

versions (string[])

Para dicionários remotos, este array contém todas as versões disponíveis do dicionário. Ajuda a rastrear quais versões estão disponíveis para uso.

autoFilled (true)

Indica se o dicionário foi preenchido automaticamente a partir de fontes externas. Em caso de conflitos, os dicionários base substituirão os dicionários preenchidos automaticamente.

location ('distant' | 'locale')

Indica a localização do dicionário:

• 'locale': Dicionário local (a partir dos arquivos de conteúdo)
• 'distant': Dicionário remoto (a partir de fonte externa)

Tipos de Nós de Conteúdo

O Intlayer fornece vários tipos especializados de nós de conteúdo que estendem valores primitivos básicos:

Conteúdo de Tradução (t)

Conteúdo multilíngue que varia conforme o locale:

import { t } from "intlayer";// TypeScript/JavaScriptmultilingualContent: t({  en: "Welcome to our website",  fr: "Bienvenue sur notre site web",  es: "Bienvenido a nuestro sitio web",});

Veja Conteúdo de Tradução (t) Doc para mais informações.

Conteúdo Condicional (cond)

Conteúdo que muda com base em condições booleanas:

import { cond } from "intlayer";conditionalContent: cond({  true: "User is logged in",  false: "Please log in to continue",});

Veja Conteúdo Condicional (cond) Doc para mais informações.

Conteúdo de Enumeração (enu)

Conteúdo que varia com base em valores enumerados:

import { enu } from "intlayer";statusContent: enu({  pending: "Sua solicitação está pendente",  approved: "Sua solicitação foi aprovada",  rejected: "Sua solicitação foi rejeitada",});

Veja Conteúdo de Enumeração (enu) Doc para mais informações.

Conteúdo Plural (plural)

Conteúdo que varia com base nas regras de plural:

import { plural } from "intlayer";pluralContent: plural({  one: "One car",  other: "{{count}} cars",});

Veja Conteúdo Plural Doc para mais informações.

Conteúdo de Inserção (insert)

Conteúdo que pode ser inserido em outros conteúdos:

import { insert } from "intlayer";insertionContent: insert("Este texto pode ser inserido em qualquer lugar");

Veja Conteúdo de Inserção (insert) Doc para mais informações.

Conteúdo Aninhado (nest)

Referências a outros dicionários:

import { nest } from "intlayer";nestedContent: nest("about-page");

Veja Conteúdo Aninhado (nest) Doc para mais informações.

Conteúdo Markdown (md)

Conteúdo de texto rico em formato Markdown:

import { md } from "intlayer";markdownContent: md(  "# Bem-vindo\n\nEste é um texto em **negrito** com [links](https://example.com)");

Veja Conteúdo Markdown (md) Doc para mais informações.

Conteúdo HTML (html)

Conteúdo HTML rico que pode usar tags padrão ou componentes personalizados:

import { html, file, t } from "intlayer";// HTML inlinehtmlContent: html("<p>Hello <strong>World</strong></p>");// HTML por localidade a partir de arquivos externoslocalizedHtmlContent: t({  en: html(file("./content.en.html")),  pt: html(file("./content.pt.html")),});

Veja Conteúdo HTML (html) Doc para mais informações.

Conteúdo por Gênero (gender)

Conteúdo que varia com base no gênero:

import { gender } from "intlayer";genderContent: gender({  male: "Ele é um desenvolvedor",  female: "Ela é uma desenvolvedora",  other: "Eles são desenvolvedores",});

Veja Conteúdo por Gênero (gender) Doc para mais informações.

Conteúdo de Arquivo (file)

Referências a arquivos externos:

import { file } from "intlayer";fileContent: file("./path/to/content.txt");

Veja Conteúdo de Arquivo (file) Doc para mais informações.

Criando Arquivos de Conteúdo

Estrutura Básica de Arquivo de Conteúdo

Um arquivo de conteúdo exporta um objeto padrão que satisfaz o tipo Dictionary:

// example.content.tsimport { t, cond, nest, md, insert, file } from "intlayer";export default {  key: "welcome-page",  title: "Conteúdo da Página de Boas-Vindas",  description:    "Conteúdo para a página principal de boas-vindas, incluindo a seção principal e recursos",  tags: ["página", "boas-vindas", "página-inicial"],  content: {    hero: {      title: t({        pt: "Bem-vindo à Nossa Plataforma",        fr: "Bienvenue sur Notre Plateforme",        es: "Bienvenido a Nuestra Plataforma",      }),      subtitle: t({        pt: "Crie aplicações incríveis com facilidade",        fr: "Construisez des applications incroyables avec facilité",        es: "Construye aplicaciones increíbles con facilidad",      }),      cta: cond({        true: t({          pt: "Começar",          fr: "Commencer",          es: "Comenzar",        }),        false: t({          pt: "Registrar-se",          fr: "S'inscrire",          es: "Registrarse",        }),      }),    },    features: [      {        title: t({          pt: "Fácil de Usar",          en: "Easy to Use",          fr: "Facile à Utiliser",          es: "Fácil de Usar",        }),        description: t({          pt: "Interface intuitiva para todos os níveis de habilidade",          en: "Intuitive interface for all skill levels",          fr: "Interface intuitive pour tous les niveaux",          es: "Interfaz intuitiva para todos los niveles",        }),      },    ],    documentation: nest("documentation"),    readme: file("./README.md"),  },} satisfies Dictionary;

Arquivo de Conteúdo JSON

Você também pode criar arquivos de conteúdo no formato JSON:

{  "key": "welcome-page",  "title": "Conteúdo da Página de Boas-Vindas",  "description": "Conteúdo para a página principal de boas-vindas",  "tags": ["page", "welcome"],  "content": {    "hero": {      "title": {        "nodeType": "translation",        "translation": {          "en": "Welcome to Our Platform",          "fr": "Bienvenue sur Notre Plateforme"        }      },      "subtitle": {        "nodeType": "translation",        "translation": {          "en": "Build amazing applications with ease",          "fr": "Construisez des applications incroyables avec facilité"        }      }    }  }}

Arquivo de Conteúdo Markdown

---key: welcome-pagelocale: entitle: Welcome Page Contentdescription: Content for the main welcome pagetags:  - page  - welcome---# Welcome to Our Platform## Build amazing applications with ease

Arquivo de Conteúdo YAML

key: welcome-pagetitle: Welcome Page Contentdescription: Content for the main welcome pagelocale: "en"tags:  - page  - welcomecontent:  hero:    title: Welcome to Our Platform    subtitle: Build amazing applications with ease

Ficheiros de Conteúdo por Localidade

Para dicionários por localidade, especifique a propriedade locale:

// welcome-page.en.content.tsexport default {  key: "welcome-page",  locale: "en",  content: {    hero: {      title: "Welcome to Our Platform",      subtitle: "Build amazing applications with ease",    },  },} satisfies Dictionary;

// welcome-page.fr.content.tsexport default {  key: "welcome-page",  locale: "fr",  content: {    hero: {      title: "Bienvenue sur Notre Plateforme",      subtitle: "Construisez des applications incroyables avec facilité",    },  },} satisfies Dictionary;

Extensões de Arquivos de Conteúdo

O Intlayer permite que você personalize as extensões dos seus arquivos de declaração de conteúdo. Essa personalização oferece flexibilidade para gerenciar projetos em larga escala e ajuda a evitar conflitos com outros módulos.

Extensões Padrão

Por padrão, o Intlayer monitora todos os arquivos com as seguintes extensões para declarações de conteúdo:

• .content.json
• .content.json5
• .content.jsonc
• .content.ts
• .content.tsx
• .content.js
• .content.jsx
• .content.mjs
• .content.mjx
• .content.cjs
• .content.cjx
• .content.md
• .content.mdx
• .content.yaml
• .content.yml

Essas extensões padrão são adequadas para a maioria das aplicações. No entanto, quando você tem necessidades específicas, pode definir extensões personalizadas para otimizar o processo de build e reduzir o risco de conflitos com outros componentes.

Para personalizar as extensões de arquivo que o Intlayer usa para identificar arquivos de declaração de conteúdo, você pode especificá-las no arquivo de configuração do Intlayer. Essa abordagem é benéfica para projetos em larga escala, onde limitar o escopo do processo de monitoramento melhora o desempenho do build.

Conceitos Avançados

Mesclagem de Dicionários

Quando múltiplos dicionários possuem a mesma chave, o Intlayer os mescla automaticamente. O comportamento da mesclagem depende de vários fatores:

• Prioridade: Dicionários com valores de priority mais altos substituem aqueles com valores mais baixos
• Auto-preenchimento vs Base: Dicionários base substituem dicionários auto-preenchidos
• Localização: Dicionários locais substituem dicionários remotos (quando as prioridades são iguais)

Segurança de Tipos

O Intlayer oferece suporte completo ao TypeScript para arquivos de conteúdo:

// Defina seu tipo de conteúdointerface WelcomePageContent {  hero: {    title: string;    subtitle: string;    cta: string;  };  features: Array<{    title: string;    description: string;  }>;}// Use-o no seu dicionárioexport default {  key: "welcome-page",  content: {    // O TypeScript fornecerá autocompletar e verificação de tipos    hero: {      title: "Welcome",      subtitle: "Build amazing apps",      cta: "Get Started",    },  },} satisfies Dictionary<WelcomePageContent>;

Imbricação de Nós

Você pode, sem problema, imbricar funções dentro de outras.

Exemplo:

import { t, enu, cond, nest, md, type Dictionary } from "intlayer";

const getName = async () => "John Doe";

export default {
  key: "page",
  content: {
    // `getIntlayer('page','en').hiMessage` retorna `['Hi', ' ', 'John Doe']`
    hiMessage: [
      t({
        en: "Hi",
        fr: "Salut",
        es: "Hola",
      }),
      " ",
      getName(),
    ],
    // Conteúdo composto imbricando condição, enumeração e conteúdo multilíngue
    // `getIntlayer('page','en').advancedContent(true)(10)` retorna 'Multiple items found'
    advancedContent: cond({
      true: enu({
        "0": t({
          en: "No items found",
          fr: "Aucun article trouvé",
          es: "Não foram encontrados artigos",
        }),
        "1": t({
          en: "One item found",
          fr: "Un article trouvé",
          es: "Foi encontrado um artigo",
        }),
        ">1": t({
          en: "Multiple items found",
          fr: "Plusieurs articles trouvés",
          es: "Foram encontrados múltiplos artigos",
        }),
      }),
      false: t({
        en: "No valid data available",
        fr: "Aucune donnée valide disponible",
        es: "Não há dados válidos disponíveis",
      }),
    }),
  },
} satisfies Dictionary;

Melhores Práticas

1. Convenções de Nomenclatura:

   • Use kebab-case para as chaves do dicionário ("about-page-meta")
   • Agrupe conteúdos relacionados sob o mesmo prefixo de chave

2. Organização do Conteúdo:

   • Mantenha conteúdos relacionados juntos no mesmo dicionário
   • Use objetos aninhados para organizar estruturas de conteúdo complexas
   • Aproveite as tags para categorização
   • Use o autoFill para preencher automaticamente as traduções faltantes

3. Desempenho:

   • Ajuste a configuração de conteúdo para limitar o escopo dos arquivos monitorados
   • Use dicionários ao vivo apenas quando atualizações em tempo real forem necessárias (por exemplo, testes A/B, etc.)
   • Garanta que o plugin de transformação de build (@intlayer/swc ou @intlayer/babel) esteja habilitado para otimizar o dicionário durante o build