@intlayer/docs 5.5.8

package/pt/packages/@intlayer/webpack/index.md

@@ -0,0 +1,35 @@
+# @intlayer/webpack: Pacote NPM para usar o Plugin Intlayer Webpack em sua aplicação
+
+**Intlayer** é um conjunto de pacotes projetados especificamente para desenvolvedores JavaScript. É compatível com frameworks como React, React e Express.js.
+
+O pacote **`@intlayer/webpack`** é usado para fornecer uma configuração do Webpack para facilitar o trabalho com uma aplicação baseada em Webpack com Intlayer. O pacote também fornece um plugin para adicionar em uma aplicação Webpack existente.
+
+## Uso
+
+```ts
+import { IntlayerPlugin } from "@intlayer/webpack";
+
+export default {
+  plugins: [
+    new IntlayerPlugin({
+      // Opções
+    }),
+  ],
+};
+```
+
+## Instalação
+
+Instale o pacote necessário usando o gerenciador de pacotes de sua preferência:
+
+```bash packageManager="npm"
+npm install @intlayer/webpack
+```
+
+```bash packageManager="pnpm"
+pnpm add @intlayer/webpack
+```
+
+```bash packageManager="yarn"
+yarn add @intlayer/webpack
+```

package/pt/packages/angular-intlayer/index.md

@@ -0,0 +1,3 @@
+this doc will be automatically generated translated from the english doc
+
+see /docs/en/packages/angular-intlayer/index.md

package/pt/packages/express-intlayer/index.md

@@ -0,0 +1,232 @@
+# express-intlayer: Pacote JavaScript para internacionalizar (i18n) uma aplicação Express.js
+
+**Intlayer** é um conjunto de pacotes projetados especificamente para desenvolvedores JavaScript. É compatível com frameworks como React, Next.js e Express.js.
+
+**O pacote `express-intlayer`** permite que você internacionalize sua aplicação Express.js. Ele fornece um middleware para detectar o idioma preferido do usuário e retorna o dicionário apropriado para o usuário.
+
+## Por que Internacionalizar seu Backend?
+
+Internacionalizar seu backend é essencial para atender de forma eficaz a um público global. Isso permite que sua aplicação entregue conteúdo e mensagens no idioma preferido de cada usuário. Essa capacidade melhora a experiência do usuário e amplia o alcance da sua aplicação, tornando-a mais acessível e relevante para pessoas de diferentes origens linguísticas.
+
+### Casos de Uso Práticos
+
+- **Exibir Erros do Backend no Idioma do Usuário**: Quando ocorre um erro, exibir mensagens no idioma nativo do usuário melhora a compreensão e reduz a frustração. Isso é especialmente útil para mensagens de erro dinâmicas que podem ser exibidas em componentes do front-end, como toasts ou modais.
+
+- **Recuperar Conteúdo Multilíngue**: Para aplicações que buscam conteúdo de um banco de dados, a internacionalização garante que você possa servir esse conteúdo em vários idiomas. Isso é crucial para plataformas como sites de e-commerce ou sistemas de gerenciamento de conteúdo que precisam exibir descrições de produtos, artigos e outros conteúdos no idioma preferido pelo usuário.
+
+- **Enviar E-mails Multilíngues**: Seja para e-mails transacionais, campanhas de marketing ou notificações, enviar e-mails no idioma do destinatário pode aumentar significativamente o engajamento e a eficácia.
+
+- **Notificações Push Multilíngues**: Para aplicativos móveis, enviar notificações push no idioma preferido do usuário pode melhorar a interação e a retenção. Esse toque pessoal pode fazer com que as notificações pareçam mais relevantes e acionáveis.
+
+- **Outras Comunicações**: Qualquer forma de comunicação do backend, como mensagens SMS, alertas do sistema ou atualizações da interface do usuário, se beneficia ao estar no idioma do usuário, garantindo clareza e melhorando a experiência geral do usuário.
+
+Ao internacionalizar o backend, sua aplicação não apenas respeita as diferenças culturais, mas também se alinha melhor às necessidades do mercado global, tornando-se um passo fundamental para escalar seus serviços mundialmente.
+
+## Por que integrar o Intlayer?
+
+- **Ambiente Seguro para Tipos**: Aproveite o TypeScript para garantir que todas as definições de conteúdo sejam precisas e livres de erros.
+
+## Instalação
+
+Instale o pacote necessário usando seu gerenciador de pacotes preferido:
+
+```bash
+npm install express-intlayer
+```
+
+```bash
+yarn add express-intlayer
+```
+
+```bash
+pnpm add express-intlayer
+```
+
+### Configurar o Intlayer
+
+O Intlayer fornece um arquivo de configuração para configurar seu projeto. Coloque este arquivo na raiz do seu projeto.
+
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.mjs" codeFormat="esm"
+import { Locales } from "intlayer";
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+const { Locales } = require("intlayer");
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+module.exports = config;
+```
+
+> Para uma lista completa de parâmetros disponíveis, consulte a [documentação de configuração](https://github.com/aymericzip/intlayer/blob/main/docs/pt/configuration.md).
+
+## Exemplo de uso
+
+Configure sua aplicação Express para usar o `express-intlayer`:
+
+```typescript fileName="src/index.ts" codeFormat="typescript"
+import express, { type Express } from "express";
+import { intlayer, t } from "express-intlayer";
+
+const app: Express = express();
+
+// Carregar manipulador de requisições de internacionalização
+app.use(intlayer());
+
+// Rotas
+app.get("/", (_req, res) => {
+  res.send(
+    t({
+      en: "Example of returned content in English",
+      fr: "Exemple de contenu renvoyé en français",
+      "es-ES": "Ejemplo de contenido devuelto en español (España)",
+      "es-MX": "Ejemplo de contenido devuelto en español (México)",
+      pt: "Exemplo de conteúdo retornado em português",
+    })
+  );
+});
+
+// Iniciar servidor
+app.listen(3000, () => console.log(`Listening on port 3000`));
+```
+
+```javascript fileName="src/index.mjs" codeFormat="esm"
+import express from "express";
+import { intlayer, t } from "express-intlayer";
+
+const app = express();
+
+// Carregar manipulador de requisições de internacionalização
+app.use(intlayer());
+
+// Rotas
+app.get("/", (_req, res) => {
+  res.send(
+    t({
+      en: "Example of returned content in English",
+      fr: "Exemple de contenu renvoyé en français",
+      "es-MX": "Ejemplo de contenido devuelto en español (México)",
+      "es-ES": "Ejemplo de contenido devuelto en español (España)",
+      pt: "Exemplo de conteúdo retornado em português",
+    })
+  );
+});
+
+// Iniciar servidor
+app.listen(3000, () => console.log(`Listening on port 3000`));
+```
+
+```javascript fileName="src/index.cjs" codeFormat="commonjs"
+const express = require("express");
+const { intlayer, t } = require("express-intlayer");
+
+const app = express();
+
+// Carregar manipulador de requisições de internacionalização
+app.use(intlayer());
+
+// Rotas
+app.get("/", (_req, res) => {
+  res.send(
+    t({
+      en: "Example of returned content in English",
+      fr: "Exemple de contenu renvoyé en français",
+      "es-MX": "Ejemplo de contenido devuelto en español (México)",
+      "es-ES": "Ejemplo de contenido devuelto en español (España)",
+      pt: "Exemplo de conteúdo retornado em português",
+    })
+  );
+});
+
+// Iniciar servidor
+app.listen(3000, () => console.log(`Listening on port 3000`));
+```
+
+### Compatibilidade
+
+`express-intlayer` é totalmente compatível com:
+
+- [`react-intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/pt/packages/react-intlayer/index.md) para aplicações React
+- [`next-intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/pt/packages/next-intlayer/index.md) para aplicações Next.js
+- [`vite-intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/pt/packages/vite-intlayer/index.md) para aplicações Vite
+
+Ele também funciona perfeitamente com qualquer solução de internacionalização em vários ambientes, incluindo navegadores e requisições de API. Você pode personalizar o middleware para detectar o idioma por meio de cabeçalhos ou cookies:
+
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  // ... Outras opções de configuração
+  middleware: {
+    headerName: "my-locale-header",
+    cookieName: "my-locale-cookie",
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.mjs" codeFormat="esm"
+import { Locales } from "intlayer";
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  // ... Outras opções de configuração
+  middleware: {
+    headerName: "my-locale-header",
+    cookieName: "my-locale-cookie",
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+const { Locales } = require("intlayer");
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  // ... Outras opções de configuração
+  middleware: {
+    headerName: "my-locale-header",
+    cookieName: "my-locale-cookie",
+  },
+};
+
+module.exports = config;
+```
+
+Por padrão, o `express-intlayer` interpretará o cabeçalho `Accept-Language` para determinar o idioma preferido do cliente.
+
+## Funções fornecidas pelo pacote `express-intlayer`
+
+- [`t()`](https://github.com/aymericzip/intlayer/blob/main/docs/pt-PT/packages/express-intlayer/t.md)

package/pt/packages/express-intlayer/t.md

@@ -0,0 +1,267 @@
+# Documentação: Função `t` no `express-intlayer`
+
+A função `t` no pacote `express-intlayer` é a principal utilidade para fornecer respostas localizadas em sua aplicação Express. Ela simplifica a internacionalização (i18n) selecionando dinamicamente o conteúdo com base no idioma preferido do usuário.
+
+---
+
+## Visão Geral
+
+A função `t` é usada para definir e recuperar traduções para um conjunto de idiomas. Ela determina automaticamente o idioma apropriado para retornar com base nas configurações da solicitação do cliente, como o cabeçalho `Accept-Language`. Se o idioma preferido não estiver disponível, ela recai graciosamente para o local padrão especificado na sua configuração.
+
+---
+
+## Principais Recursos
+
+- **Localização Dinâmica**: Seleciona automaticamente a tradução mais apropriada para o cliente.
+- **Fallback para Local Padrão**: Recorre a um local padrão se o idioma preferido do cliente não estiver disponível, garantindo continuidade na experiência do usuário.
+- **Leve e Rápido**: Projetado para aplicações de alto desempenho, garantindo sobrecarga mínima.
+- **Suporte ao Modo Estrito**: Impõe aderência estrita aos locais declarados para comportamento confiável.
+
+---
+
+## Assinatura da Função
+
+```typescript
+t(translations: Record<string, string>): string;
+```
+
+### Parâmetros
+
+- `translations`: Um objeto onde as chaves são códigos de localidade (por exemplo, `en`, `fr`, `es-MX`) e os valores são as strings traduzidas correspondentes.
+
+### Retorna
+
+- Uma string representando o conteúdo no idioma preferido do cliente.
+
+---
+
+## Carregando o Manipulador de Solicitações de Internacionalização
+
+Para garantir que a funcionalidade de internacionalização fornecida pelo `express-intlayer` funcione corretamente, você **deve** carregar o middleware de internacionalização no início da sua aplicação Express. Isso habilita a função `t` e garante o manuseio adequado da detecção de localidade e tradução.
+
+Coloque o middleware `app.use(intlayer())` **antes de qualquer rota** em sua aplicação para garantir que todas as rotas se beneficiem da internacionalização:
+
+```typescript {7} fileName="src/index.ts" codeFormat="typescript"
+import express, { type Express } from "express";
+import { intlayer } from "express-intlayer";
+
+const app: Express = express();
+
+// Carregar o manipulador de solicitações de internacionalização
+app.use(intlayer());
+
+// Defina suas rotas após carregar o middleware
+app.get("/", (_req, res) => {
+  res.send(
+    t({
+      en: "Hello, World!",
+      fr: "Bonjour le monde!",
+      es: "¡Hola, Mundo!",
+      pt: "Olá, Mundo!",
+    })
+  );
+});
+```
+
+```javascript {7} fileName="src/index.mjs" codeFormat="esm"
+import express from "express";
+import { intlayer } from "express-intlayer";
+
+const app = express();
+
+// Carregar o manipulador de solicitações de internacionalização
+app.use(intlayer());
+
+// Defina suas rotas após carregar o middleware
+app.get("/", (_req, res) => {
+  res.send(
+    t({
+      en: "Hello, World!",
+      fr: "Bonjour le monde!",
+      es: "¡Hola, Mundo!",
+      pt: "Olá, Mundo!",
+    })
+  );
+});
+```
+
+```javascript {7} fileName="src/index.cjs" codeFormat="commonjs"
+const express = require("express");
+const { intlayer } = require("express-intlayer");
+
+const app = express();
+
+// Carregar o manipulador de solicitações de internacionalização
+app.use(intlayer());
+
+// Defina suas rotas após carregar o middleware
+app.get("/", (_req, res) => {
+  res.send(
+    t({
+      en: "Hello, World!",
+      fr: "Bonjour le monde!",
+      es: "¡Hola, Mundo!",
+      pt: "Olá, Mundo!",
+    })
+  );
+});
+```
+
+### Por Que Isso é Necessário
+
+- **Detecção de Localidade**: O middleware `intlayer` processa solicitações recebidas para detectar o local preferido do usuário com base em cabeçalhos, cookies ou outros métodos configurados.
+- **Contexto de Tradução**: Configura o contexto necessário para a função `t` operar corretamente, garantindo que as traduções sejam retornadas no idioma correto.
+- **Prevenção de Erros**: Sem este middleware, o uso da função `t` resultará em erros de tempo de execução porque as informações necessárias sobre o local não estarão disponíveis.
+
+---
+
+## Exemplos de Uso
+
+### Exemplo Básico
+
+Servir conteúdo localizado em diferentes idiomas:
+
+```typescript fileName="src/index.ts" codeFormat="typescript"
+app.get("/", (_req, res) => {
+  res.send(
+    t({
+      en: "Welcome!",
+      fr: "Bienvenue!",
+      es: "¡Bienvenido!",
+      pt: "Bem-vindo!",
+    })
+  );
+});
+```
+
+```javascript fileName="src/index.mjs" codeFormat="esm"
+app.get("/", (_req, res) => {
+  res.send(
+    t({
+      en: "Welcome!",
+      fr: "Bienvenue!",
+      es: "¡Bienvenido!",
+      pt: "Bem-vindo!",
+    })
+  );
+});
+```
+
+```javascript fileName="src/index.cjs" codeFormat="commonjs"
+app.get("/", (_req, res) => {
+  res.send(
+    t({
+      en: "Welcome!",
+      fr: "Bienvenue!",
+      es: "¡Bienvenido!",
+      pt: "Bem-vindo!",
+    })
+  );
+});
+```
+
+**Solicitações do Cliente:**
+
+- Um cliente com `Accept-Language: fr` receberá `Bienvenue!`.
+- Um cliente com `Accept-Language: es` receberá `¡Bienvenido!`.
+- Um cliente com `Accept-Language: de` receberá `Welcome!` (local padrão).
+
+### Tratando Erros
+
+Forneça mensagens de erro em vários idiomas:
+
+```typescript fileName="src/index.ts" codeFormat="typescript"
+app.get("/error", (_req, res) => {
+  res.status(500).send(
+    t({
+      en: "An unexpected error occurred.",
+      fr: "Une erreur inattendue s'est produite.",
+      es: "Ocurrió un error inesperado.",
+      pt: "Ocorreu um erro inesperado.",
+    })
+  );
+});
+```
+
+```javascript fileName="src/index.mjs" codeFormat="esm"
+app.get("/error", (_req, res) => {
+  res.status(500).send(
+    t({
+      en: "An unexpected error occurred.",
+      fr: "Une erreur inattendue s'est produite.",
+      es: "Ocurrió un error inesperado.",
+      pt: "Ocorreu um erro inesperado.",
+    })
+  );
+});
+```
+
+```javascript fileName="src/index.cjs" codeFormat="commonjs"
+app.get("/error", (_req, res) => {
+  res.status(500).send(
+    t({
+      en: "An unexpected error occurred.",
+      fr: "Une erreur inattendue s'est produite.",
+      es: "Ocurrió un error inesperado.",
+      pt: "Ocorreu um erro inesperado.",
+    })
+  );
+});
+```
+
+---
+
+### Usando Variantes de Localidade
+
+Especifique traduções para variantes específicas de localidade:
+
+```typescript fileName="src/index.ts" codeFormat="typescript"
+app.get("/greet", (_req, res) => {
+  res.send(
+    t({
+      en: "Hello!",
+      "en-GB": "Hello, mate!",
+      fr: "Bonjour!",
+      "es-MX": "¡Hola, amigo!",
+      "es-ES": "¡Hola!",
+      pt: "Olá!",
+    })
+  );
+});
+```
+
+```javascript fileName="src/index.cjs" codeFormat="commonjs"
+app.get("/greet", (_req, res) => {
+  res.send(
+    t({
+      en: "Hello!",
+      "en-GB": "Hello, mate!",
+      fr: "Bonjour!",
+      "es-MX": "¡Hola, amigo!",
+      "es-ES": "¡Hola!",
+      pt: "Olá!",
+    })
+  );
+});
+```
+
+```javascript fileName="src/index.mjs" codeFormat="esm"
+app.get("/greet", (_req, res) => {
+  res.send(
+    t({
+      en: "Hello!",
+      "en-GB": "Hello, mate!",
+      fr: "Bonjour!",
+      "es-MX": "¡Hola, amigo!",
+      "es-ES": "¡Hola!",
+      pt: "Olá!",
+    })
+  );
+});
+```
+
+---
+
+## Conclusão
+
+A função `t` é uma ferramenta poderosa para internacionalização no backend. Usando-a de forma eficaz, você pode criar uma aplicação mais inclusiva e amigável para um público global. Para uso avançado e opções detalhadas de configuração, consulte a [documentação](https://github.com/aymericzip/intlayer/blob/main/docs/pt/configuration.md).

package/pt/packages/intlayer/getConfiguration.md

@@ -0,0 +1,120 @@
+# Documentação: Função `getConfiguration` no `intlayer`
+
+## Descrição
+
+A função `getConfiguration` recupera toda a configuração para a aplicação `intlayer` extraindo variáveis de ambiente. Esta função oferece a flexibilidade de usar a mesma configuração tanto no lado do cliente quanto no lado do servidor, garantindo consistência em toda a aplicação.
+
+---
+
+## Parâmetros
+
+A função não recebe nenhum parâmetro. Em vez disso, utiliza variáveis de ambiente para configuração.
+
+### Retornos
+
+- **Tipo**: `IntlayerConfig`
+- **Descrição**: Um objeto contendo a configuração completa para o `intlayer`. A configuração inclui as seguintes seções:
+
+  - `internationalization`: Configurações relacionadas a locais e modo estrito.
+  - `middleware`: Configurações relacionadas ao gerenciamento de URLs e cookies.
+  - `content`: Configurações relacionadas a arquivos de conteúdo, diretórios e padrões.
+  - `editor`: Configurações específicas do editor.
+
+Veja a [documentação de configuração do Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/pt/configuration.md) para mais detalhes.
+
+---
+
+## Exemplo de Uso
+
+### Recuperando a Configuração Completa
+
+```typescript codeFormat="typescript"
+import { getConfiguration } from "intlayer";
+
+const config = getConfiguration();
+console.log(config);
+// Saída:
+// {
+//   internationalization: { ... },
+//   middleware: { ... },
+//   content: { ... },
+//   editor: { ... }
+// }
+```
+
+```javascript codeFormat="esm"
+import { getConfiguration } from "intlayer";
+
+const config = getConfiguration();
+console.log(config);
+// Saída:
+// {
+//   internationalization: { ... },
+//   middleware: { ... },
+//   content: { ... },
+//   editor: { ... }
+// }
+```
+
+```javascript codeFormat="commonjs"
+const { getConfiguration } = require("intlayer");
+
+const config = getConfiguration();
+console.log(config);
+// Saída:
+// {
+//   internationalization: { ... },
+//   middleware: { ... },
+//   content: { ... },
+//   editor: { ... }
+// }
+```
+
+### Extraindo `availableLocales` e `defaultLocale`
+
+A seção `internationalization` da configuração fornece configurações relacionadas a locais, como `locales` (locais disponíveis) e `defaultLocale` (idioma padrão).
+
+```typescript codeFormat="typescript"
+import { getConfiguration } from "intlayer";
+
+const { internationalization, middleware } = getConfiguration();
+const { locales: availableLocales, defaultLocale } = internationalization;
+const { cookieName } = middleware;
+
+console.log(availableLocales); // Exemplo de saída: ["en", "fr", "es"]
+console.log(defaultLocale); // Exemplo de saída: "en"
+console.log(cookieName); // Saída: "INTLAYER_LOCALE"
+```
+
+```javascript codeFormat="esm"
+import { getConfiguration } from "intlayer";
+
+const { internationalization, middleware } = getConfiguration();
+const { locales: availableLocales, defaultLocale } = internationalization;
+const { cookieName } = middleware;
+
+console.log(availableLocales); // Exemplo de saída: ["en", "fr", "es"]
+console.log(defaultLocale); // Exemplo de saída: "en"
+console.log(cookieName); // Saída: "INTLAYER_LOCALE"
+```
+
+```javascript codeFormat="commonjs"
+const { getConfiguration } = require("intlayer");
+
+const { internationalization, middleware } = getConfiguration();
+const { locales: availableLocales, defaultLocale } = internationalization;
+const { cookieName } = middleware;
+
+console.log(availableLocales); // Exemplo de saída: ["en", "fr", "es"]
+console.log(defaultLocale); // Exemplo de saída: "en"
+console.log(cookieName); // Saída: "INTLAYER_LOCALE"
+```
+
+## Notas
+
+- Certifique-se de que todas as variáveis de ambiente necessárias estejam configuradas corretamente antes de chamar esta função. Variáveis ausentes causarão erros durante a inicialização.
+- Esta função pode ser usada tanto no lado do cliente quanto no lado do servidor, tornando-se uma ferramenta versátil para gerenciar configurações de forma unificada.
+
+## Uso em Aplicações
+
+A função `getConfiguration` é uma utilidade fundamental para inicializar e gerenciar a configuração de uma aplicação `intlayer`. Ao fornecer acesso a configurações como locais, middleware e diretórios de conteúdo, ela garante consistência e escalabilidade em aplicações multilíngues e orientadas a conteúdo.