@intlayer/docs 5.7.2 → 5.7.4

package/docs/pt/dictionary/gender.md

@@ -0,0 +1,275 @@
+---
+createdAt: 2025-07-27
+updatedAt: 2025-07-27
+title: Conteúdo Baseado em Gênero
+description: Aprenda como usar conteúdo baseado em gênero no Intlayer para exibir conteúdo dinamicamente com base no gênero. Siga esta documentação para implementar conteúdo específico por gênero de forma eficiente em seu projeto.
+keywords:
+  - Conteúdo Baseado em Gênero
+  - Renderização Dinâmica
+  - Documentação
+  - Intlayer
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - concept
+  - content
+  - gender
+---
+
+# Conteúdo Baseado em Gênero / Gênero no Intlayer
+
+## Como o Gênero Funciona
+
+No Intlayer, o conteúdo baseado em gênero é realizado por meio da função `gender`, que mapeia valores específicos de gênero ('male', 'female') para seus conteúdos correspondentes. Essa abordagem permite selecionar dinamicamente o conteúdo com base em um gênero fornecido. Quando integrado com React Intlayer ou Next Intlayer, o conteúdo apropriado é automaticamente escolhido de acordo com o gênero fornecido em tempo de execução.
+
+## Configurando Conteúdo Baseado em Gênero
+
+Para configurar conteúdo baseado em gênero em seu projeto Intlayer, crie um módulo de conteúdo que inclua suas definições específicas por gênero. Abaixo estão exemplos em vários formatos.
+
+```typescript fileName="**/*.content.ts" contentDeclarationFormat="typescript"
+import { gender, type Dictionary } from "intlayer";
+
+const myGenderContent = {
+  key: "my_key",
+  content: {
+    myGender: gender({
+      male: "meu conteúdo para usuários do sexo masculino",
+      female: "meu conteúdo para usuários do sexo feminino",
+      fallback: "meu conteúdo quando o gênero não é especificado", // Opcional
+    }),
+  },
+} satisfies Dictionary;
+
+export default myGenderContent;
+```
+
+```javascript fileName="**/*.content.mjs" contentDeclarationFormat="esm"
+import { gender } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const myGenderContent = {
+  key: "my_key",
+  content: {
+    myGender: gender({
+      male: "meu conteúdo para usuários do sexo masculino",
+      female: "meu conteúdo para usuários do sexo feminino",
+      fallback: "meu conteúdo quando o gênero não é especificado", // Opcional
+    }),
+  },
+};
+
+export default myGenderContent;
+```
+
+```javascript fileName="**/*.content.cjs" contentDeclarationFormat="commonjs"
+const { gender } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const myGenderContent = {
+  key: "my_key",
+  content: {
+    myGender: gender({
+      male: "meu conteúdo para usuários do sexo masculino",
+      female: "meu conteúdo para usuários do sexo feminino",
+      fallback: "meu conteúdo quando o gênero não é especificado", // Opcional
+    }),
+  },
+};
+
+module.exports = myGenderContent;
+```
+
+```json5 fileName="**/*.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "my_key",
+  "content": {
+    "myGender": {
+      "nodeType": "gender",
+      "gender": {
+        "male": "meu conteúdo para usuários do sexo masculino",
+        "female": "meu conteúdo para usuários do sexo feminino",
+        "fallback": "meu conteúdo quando o gênero não é especificado", // Opcional
+      },
+    },
+  },
+}
+```
+
+> Se nenhum fallback for declarado, a última chave declarada será usada como fallback caso o gênero não seja especificado ou não corresponda a nenhum gênero definido.
+
+## Usando Conteúdo Baseado em Gênero com React Intlayer
+
+Para utilizar conteúdo baseado em gênero dentro de um componente React, importe e use o hook `useIntlayer` do pacote `react-intlayer`. Esse hook busca o conteúdo para a chave especificada e permite que você passe um gênero para selecionar a saída apropriada.
+
+```tsx fileName="**/*.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useIntlayer } from "react-intlayer";
+
+const GenderComponent: FC = () => {
+  const { myGender } = useIntlayer("my_key");
+
+  return (
+    <div>
+      <p>
+        {
+          /* Saída: meu conteúdo para usuários do sexo masculino */
+          myGender("male")
+        }
+      </p>
+      <p>
+        {
+          /* Saída: meu conteúdo para usuárias */
+          myGender("female")
+        }
+      </p>
+      <p>
+        {
+          /* Saída: meu conteúdo para usuários */
+          myGender("m")
+        }
+      </p>
+      <p>
+        {
+          /* Saída: meu conteúdo para usuárias */
+          myGender("f")
+        }
+      </p>
+      <p>
+        {
+          /* Saída: meu conteúdo quando o gênero não é especificado */
+          myGender("")
+        }
+      </p>
+      <p>
+        {
+          /* Saída: meu conteúdo quando o gênero não é especificado */
+          myGender(undefined)
+        }
+      </p>
+    </div>
+  );
+};
+
+export default GenderComponent;
+```
+
+```javascript fileName="**/*.mjx" codeFormat="esm"
+import { useIntlayer } from "react-intlayer";
+
+const GenderComponent = () => {
+  const { myGender } = useIntlayer("my_key");
+
+  return (
+    <div>
+      <p>
+        {
+          /* Saída: meu conteúdo para usuários */
+          myGender("male")
+        }
+      </p>
+      <p>
+        {
+          /* Saída: meu conteúdo para usuárias */
+          myGender("female")
+        }
+      </p>
+      <p>
+        {
+          /* Saída: meu conteúdo para usuários */
+          myGender("m")
+        }
+      </p>
+      <p>
+        {
+          /* Saída: meu conteúdo para usuárias */
+          myGender("f")
+        }
+      </p>
+      <p>
+        {
+          /* Saída: meu conteúdo quando o gênero não é especificado */
+          myGender("")
+        }
+      </p>
+      <p>
+        {
+          /* Saída: meu conteúdo quando o gênero não é especificado */
+          myGender(undefined)
+        }
+      </p>
+    </div>
+  );
+};
+
+export default GenderComponent;
+```
+
+```javascript fileName="**/*.cjs" codeFormat="commonjs"
+const { useIntlayer } = require("react-intlayer");
+
+const GenderComponent = () => {
+  const { myGender } = useIntlayer("my_key");
+
+  return (
+    <div>
+      <p>
+        {
+          /* Saída: meu conteúdo para usuários */
+          myGender("male")
+        }
+      </p>
+      <p>
+        {
+          /* Saída: meu conteúdo para usuárias */
+          myGender("female")
+        }
+      </p>
+      <p>
+        {
+          /* Saída: meu conteúdo para usuários */
+          myGender("m")
+        }
+      </p>
+      <p>
+        {
+          /* Saída: meu conteúdo para usuárias */
+          myGender("f")
+        }
+      </p>
+      <p>
+        {
+          /* Saída: meu conteúdo quando o gênero não é especificado */
+          myGender("")
+        }
+      </p>
+      <p>
+        {
+          /* Saída: meu conteúdo quando o gênero não é especificado */
+          myGender(undefined)
+        }
+      </p>
+    </div>
+  );
+};
+
+module.exports = GenderComponent;
+```
+
+## Recursos Adicionais
+
+Para informações mais detalhadas sobre configuração e uso, consulte os seguintes recursos:
+
+- [Documentação do Intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_cli.md)
+- [Documentação do React Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_with_create_react_app.md)
+- [Documentação do Next Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_with_nextjs_15.md)
+
+Estes recursos oferecem mais informações sobre a configuração e o uso do Intlayer em vários ambientes e frameworks.
+
+## Histórico do Documento
+
+| Versão | Data       | Alterações                               |
+| ------ | ---------- | ---------------------------------------- |
+| 5.7.2  | 2025-07-27 | Introdução de conteúdo baseado em gênero |

package/docs/pt/how_works_intlayer.md

@@ -94,7 +94,7 @@ O Intlayer também fornece um editor visual para permitir que você edite seu co
 
 - O servidor é uma aplicação simples em Express que escuta requisições do cliente e recupera o conteúdo da sua aplicação, como os `dictionaries` e a configuração para torná-los acessíveis no lado do cliente.
 - Por outro lado, o cliente é uma aplicação React que é usada para interagir com seu conteúdo usando uma interface visual.
-  Quando você chama seu conteúdo usando `useIntlayer` e o editor está ativado, ele automaticamente envolve suas strings com um objeto Proxy chamado `IntlayerNode`. Esse nó usa `window.sendMessage` para se comunicar com um iframe encapsulado que contém a interface do editor visual.  
+  Quando você chama seu conteúdo usando `useIntlayer` e o editor está ativado, ele automaticamente envolve suas strings com um objeto Proxy chamado `IntlayerNode`. Esse nó usa `window.postMessage` para se comunicar com um iframe encapsulado que contém a interface do editor visual.  
   No lado do editor, ele escuta essas mensagens e simula uma interação real com seu conteúdo, permitindo que você edite o texto diretamente no contexto da sua aplicação.
 
 ## Otimização da construção do aplicativo

package/docs/pt/locale_mapper.md

@@ -0,0 +1,244 @@
+---
+createdAt: 2025-07-27
+updatedAt: 2025-07-27
+title: Mapeador de Locale
+description: Descubra como o Mapeador de Locale funciona. Veja os passos usados pelo Mapeador de Locale na sua aplicação. Veja o que os diferentes pacotes fazem.
+keywords:
+  - Mapeador de Locale
+  - Começar
+  - Intlayer
+  - Aplicação
+  - Pacotes
+slugs:
+  - doc
+  - locale-mapper
+---
+
+# Mapeador de Locale
+
+O Mapeador de Locale é uma ferramenta poderosa que ajuda você a trabalhar com dados de internacionalização na sua aplicação Intlayer. Ele fornece três funções principais para transformar e organizar dados específicos de locale: `localeMap`, `localeFlatMap` e `localeRecord`.
+
+## Como o Mapeador de Locale Funciona
+
+O Mapeador de Locale opera sobre um objeto `LocaleData` que contém todas as informações necessárias sobre um locale:
+
+```typescript
+type LocaleData = {
+  locale: LocalesValues; // Código do locale atual (ex.: 'en', 'fr')
+  defaultLocale: LocalesValues; // Código do locale padrão
+  isDefault: boolean; // Indica se este é o locale padrão
+  locales: LocalesValues[]; // Array de todos os locales disponíveis
+  urlPrefix: string; // Prefixo de URL para este locale (ex.: '/fr' ou '')
+};
+```
+
+As funções do mapeador geram automaticamente esses dados para cada locale na sua configuração, levando em consideração:
+
+- Sua lista de locales configurados
+- A configuração do locale padrão
+- Se o locale padrão deve ser prefixado nas URLs
+
+## Funções Principais
+
+### `localeMap`
+
+Transforma cada locale em um único objeto usando uma função mapeadora.
+
+```typescript
+localeMap<T>(
+  mapper: (locale: LocaleData) => T,
+  locales?: LocalesValues[],
+  defaultLocale?: LocalesValues,
+  prefixDefault?: boolean
+): T[]
+```
+
+**Exemplo: Criando objetos de rotas**
+
+```typescript
+import { localeMap } from "intlayer";
+
+const routes = localeMap((localizedData) => ({
+  path: localizedData.urlPrefix,
+  name: localizedData.locale,
+  isDefault: localizedData.isDefault,
+  locales: localizedData.locales,
+  defaultLocale: localizedData.defaultLocale,
+}));
+
+// Resultado:
+// [
+//   { path: '/', name: 'en', isDefault: true, locales: ['en', 'fr', 'es'], defaultLocale: 'en' },
+//   { path: '/fr', name: 'fr', isDefault: false, locales: ['en', 'fr', 'es'], defaultLocale: 'en' },
+//   { path: '/es', name: 'es', isDefault: false, locales: ['en', 'fr', 'es'], defaultLocale: 'en' }
+// ]
+```
+
+### `localeFlatMap`
+
+Similar to `localeMap`, but the mapper function returns an array of objects that gets flattened into a single array.
+
+```typescript
+localeFlatMap<T>(
+  mapper: (locale: LocaleData) => T[],
+  locales?: LocalesValues[],
+  defaultLocale?: LocalesValues,
+  prefixDefault?: boolean
+): T[]
+```
+
+**Exemplo: Criando múltiplas rotas por localidade**
+
+```typescript
+import { localeFlatMap } from "intlayer";
+
+const routes = localeFlatMap((localizedData) => [
+  {
+    path: localizedData.urlPrefix,
+    name: localizedData.locale,
+    isDefault: localizedData.isDefault,
+  },
+  {
+    path: `${localizedData.urlPrefix}/about`,
+    name: `${localizedData.locale}-about`,
+    isDefault: localizedData.isDefault,
+  },
+]);
+
+// Resultado:
+// [
+//   { path: '/', name: 'en', isDefault: true },
+//   { path: '/about', name: 'en-about', isDefault: true },
+//   { path: '/fr', name: 'fr', isDefault: false },
+//   { path: '/fr/about', name: 'fr-about', isDefault: false },
+//   { path: '/es', name: 'es', isDefault: false },
+//   { path: '/es/about', name: 'es-about', isDefault: false }
+// ]
+```
+
+### `localeRecord`
+
+Cria um objeto record onde cada localidade é uma chave que mapeia para um valor transformado pela função mapper.
+
+```typescript
+localeRecord<T>(
+  mapper: (locale: LocaleData) => T,
+  locales?: Locales[],
+  defaultLocale?: Locales,
+  prefixDefault?: boolean
+): Record<Locales, T>
+```
+
+**Exemplo: Carregando arquivos de tradução**
+
+```typescript
+import { localeRecord } from "intlayer";
+
+const translations = localeRecord(({ locale }) =>
+  require(`./translations/${locale}.json`)
+);
+
+// Resultado:
+// {
+//   en: { welcome: 'Welcome', hello: 'Hello' },
+//   fr: { welcome: 'Bienvenue', hello: 'Bonjour' },
+//   es: { welcome: 'Bienvenido', hello: 'Hola' }
+// }
+```
+
+## Configurando o Locale Mapper
+
+O Locale Mapper usa automaticamente a configuração do seu Intlayer, mas você pode sobrescrever os padrões passando parâmetros:
+
+### Usando Configuração Padrão
+
+```typescript
+import { localeMap } from "intlayer";
+
+// Usa a configuração do intlayer.config.ts
+const routes = localeMap((data) => ({
+  path: data.urlPrefix,
+  locale: data.locale,
+}));
+```
+
+### Sobrescrevendo a Configuração
+
+```typescript
+import { localeMap } from "intlayer";
+
+// Sobrescreve os locais e o local padrão
+const customRoutes = localeMap(
+  (data) => ({ path: data.urlPrefix, locale: data.locale }),
+  //  ["en", "fr", "de"], // Locais personalizados
+  "en", // Local padrão personalizado
+  true // Prefixar local padrão nas URLs
+);
+```
+
+## Exemplos Avançados de Uso
+
+### Criando Menus de Navegação
+
+```typescript
+import { localeMap } from "intlayer";
+
+const navigationItems = localeMap((data) => ({
+  label: data.locale.toUpperCase(),
+  href: data.urlPrefix || "/",
+  isActive: data.isDefault,
+  flag: `/flags/${data.locale}.svg`,
+}));
+```
+
+### Gerando Dados para Sitemap
+
+```typescript
+import { localeFlatMap } from "intlayer";
+
+const sitemapUrls = localeFlatMap((data) => [
+  {
+    url: `${data.urlPrefix}/`,
+    lastmod: new Date().toISOString(),
+    changefreq: "daily",
+    priority: data.isDefault ? 1.0 : 0.8,
+  },
+  {
+    url: `${data.urlPrefix}/about`,
+    lastmod: new Date().toISOString(),
+    changefreq: "monthly",
+    priority: data.isDefault ? 0.8 : 0.6,
+  },
+]);
+```
+
+### Carregamento Dinâmico de Traduções
+
+```typescript
+import { localeRecord } from "intlayer";
+
+const translationModules = localeRecord(({ locale }) => ({
+  messages: import(`./locales/${locale}/messages.json`),
+  validation: import(`./locales/${locale}/validation.json`),
+  metadata: {
+    locale,
+    direction: ["ar", "he", "fa"].includes(locale) ? "rtl" : "ltr",
+  },
+}));
+```
+
+## Integração com Configuração
+
+O Locale Mapper integra-se perfeitamente com a sua configuração Intlayer:
+
+- **Locales**: Usa automaticamente `configuration.internationalization.locales`
+- **Local Padrão**: Usa `configuration.internationalization.defaultLocale`
+- **Prefixo de URL**: Respeita `configuration.middleware.prefixDefault`
+
+Isso garante consistência em toda a sua aplicação e reduz a duplicação de configuração.
+
+## Histórico da Documentação
+
+| Versão | Data       | Alterações                             |
+| ------ | ---------- | -------------------------------------- |
+| 5.7.2  | 2025-07-27 | Adiciona documentação do locale mapper |