@intlayer/docs 5.5.8

package/pt/packages/intlayer/getEnumeration.md

@@ -0,0 +1,138 @@
+# Documentação: Função `getEnumeration` em `intlayer`
+
+## Descrição
+
+A função `getEnumeration` recupera o conteúdo correspondente a uma quantidade específica com base em condições predefinidas em um objeto de enumeração. As condições são definidas como chaves, e sua prioridade é determinada pela ordem no objeto.
+
+## Parâmetros
+
+- `enumerationContent: QuantityContent<Content>`
+
+  - **Descrição**: Um objeto onde as chaves representam condições (por exemplo, `<=`, `<`, `>=`, `=`) e os valores representam o conteúdo correspondente. A ordem das chaves define a prioridade de correspondência.
+  - **Tipo**: `QuantityContent<Content>`
+    - `Content` pode ser de qualquer tipo.
+
+- `quantity: number`
+
+  - **Descrição**: O valor numérico usado para corresponder às condições em `enumerationContent`.
+  - **Tipo**: `number`
+
+## Retornos
+
+- **Tipo**: `Content`
+- **Descrição**: O conteúdo correspondente à primeira condição correspondente em `enumerationContent`. Se nenhuma correspondência for encontrada, ele retorna para o tratamento com base na implementação (por exemplo, erro ou conteúdo de fallback).
+
+## Exemplo de Uso
+
+### Uso Básico
+
+```typescript codeFormat="typescript"
+import { getEnumeration } from "intlayer";
+
+const content = getEnumeration(
+  {
+    "<=-2.3": "Você tem menos de -2.3",
+    "<1": "Você tem menos de um",
+    "2": "Você tem dois",
+    ">=3": "Você tem três ou mais",
+  },
+  2
+);
+
+console.log(content); // Saída: "Você tem dois"
+```
+
+```javascript codeFormat="esm"
+import { getEnumeration } from "intlayer";
+
+const content = getEnumeration(
+  {
+    "<1": "Você tem menos de um",
+    "2": "Você tem dois",
+    ">=3": "Você tem três ou mais",
+  },
+  2
+);
+
+console.log(content); // Saída: "Você tem dois"
+```
+
+```javascript codeFormat="commonjs"
+const { getEnumeration } = require("intlayer");
+
+const content = getEnumeration(
+  {
+    "<1": "Você tem menos de um",
+    "2": "Você tem dois",
+    ">=3": "Você tem três ou mais",
+  },
+  2
+);
+
+console.log(content); // Saída: "Você tem dois"
+```
+
+### Prioridade das Condições
+
+```typescript codeFormat="typescript"
+import { getEnumeration } from "intlayer";
+
+const content = getEnumeration(
+  {
+    "<4": "Você tem menos de quatro",
+    "2": "Você tem dois",
+  },
+  2
+);
+
+console.log(content); // Saída: "Você tem menos de quatro"
+```
+
+```javascript codeFormat="esm"
+import { getEnumeration } from "intlayer";
+
+const content = getEnumeration(
+  {
+    "<4": "Você tem menos de quatro",
+    "2": "Você tem dois",
+  },
+  2
+);
+
+console.log(content); // Saída: "Você tem menos de quatro"
+```
+
+```javascript codeFormat="commonjs"
+const { getEnumeration } = require("intlayer");
+
+const content = getEnumeration(
+  {
+    "<4": "Você tem menos de quatro",
+    "2": "Você tem dois",
+  },
+  2
+);
+
+console.log(content); // Saída: "Você tem menos de quatro"
+```
+
+## Casos de Borda
+
+- **Nenhuma Condição Correspondente:**
+
+  - Se nenhuma condição corresponder à quantidade fornecida, a função retornará `undefined` ou tratará explicitamente o cenário padrão/fallback.
+
+- **Condições Ambíguas:**
+
+  - Se as condições se sobrepuserem, a primeira condição correspondente (com base na ordem do objeto) terá precedência.
+
+- **Chaves Inválidas:**
+
+  - A função assume que todas as chaves em `enumerationContent` são válidas e analisáveis como condições. Chaves inválidas ou formatadas incorretamente podem levar a comportamentos inesperados.
+
+- **Aplicação do TypeScript:**
+  - A função garante que o tipo `Content` seja consistente em todas as chaves, permitindo segurança de tipo no conteúdo recuperado.
+
+## Notas
+
+- A utilidade `findMatchingCondition` é usada para determinar a condição apropriada com base na quantidade fornecida.

package/pt/packages/intlayer/getHTMLTextDir.md

@@ -0,0 +1,97 @@
+# Documentação: Função `getHTMLTextDir` em `intlayer`
+
+## Descrição
+
+A função `getHTMLTextDir` determina a direção do texto (`ltr`, `rtl` ou `auto`) com base no locale fornecido. Ela é projetada para ajudar os desenvolvedores a definir o atributo `dir` no HTML para uma renderização de texto adequada.
+
+## Parâmetros
+
+- `locale?: Locales`
+
+  - **Descrição**: A string do locale (por exemplo, `Locales.ENGLISH`, `Locales.ARABIC`) usada para determinar a direção do texto.
+  - **Tipo**: `Locales` (opcional)
+
+## Retornos
+
+- **Tipo**: `Dir` (`'ltr' | 'rtl' | 'auto'`)
+- **Descrição**: A direção do texto correspondente ao locale:
+  - `'ltr'` para idiomas da esquerda para a direita.
+  - `'rtl'` para idiomas da direita para a esquerda.
+  - `'auto'` se o locale não for reconhecido.
+
+## Exemplo de Uso
+
+### Determinando a Direção do Texto
+
+```typescript codeFormat="typescript"
+import { getHTMLTextDir } from "intlayer";
+
+getHTMLTextDir(Locales.ENGLISH); // Saída: "ltr"
+getHTMLTextDir(Locales.FRENCH); // Saída: "ltr"
+getHTMLTextDir(Locales.ARABIC); // Saída: "rtl"
+```
+
+```javascript codeFormat="esm"
+import { getHTMLTextDir } from "intlayer";
+
+getHTMLTextDir(Locales.ENGLISH); // Saída: "ltr"
+getHTMLTextDir(Locales.FRENCH); // Saída: "ltr"
+getHTMLTextDir(Locales.ARABIC); // Saída: "rtl"
+```
+
+```javascript codeFormat="commonjs"
+const { getHTMLTextDir } = require("intlayer");
+
+getHTMLTextDir(Locales.ENGLISH); // Saída: "ltr"
+getHTMLTextDir(Locales.FRENCH); // Saída: "ltr"
+getHTMLTextDir(Locales.ARABIC); // Saída: "rtl"
+```
+
+## Casos de Borda
+
+- **Nenhum Locale Fornecido:**
+
+  - A função retorna `'auto'` quando `locale` é `undefined`.
+
+- **Locale Não Reconhecido:**
+  - Para locales não reconhecidos, a função retorna `'auto'`.
+
+## Uso em Componentes:
+
+A função `getHTMLTextDir` pode ser usada para definir dinamicamente o atributo `dir` em um documento HTML para uma renderização de texto adequada com base no locale.
+
+```tsx codeFormat="typescript"
+import type { FC } from "react";
+import { getHTMLTextDir, type Locales } from "intlayer";
+
+export const HTMLLayout: FC<PropsWithChildren<{ locale: Locales }>> = ({
+  children,
+  locale,
+}) => (
+  <html dir={getHTMLTextDir(locale)} locale={locale}>
+    <body>{children}</body>
+  </html>
+);
+```
+
+```jsx codeFormat="esm"
+import { getHTMLTextDir } from "intlayer";
+
+const HTMLLayout = ({ children, locale }) => (
+  <html dir={getHTMLTextDir(locale)} locale={locale}>
+    <body>{children}</body>
+  </html>
+);
+```
+
+```jsx codeFormat="commonjs"
+const { getHTMLTextDir } = require("intlayer");
+
+const HTMLLayout = ({ children, locale }) => (
+  <html dir={getHTMLTextDir(locale)} locale={locale}>
+    <body>{children}</body>
+  </html>
+);
+```
+
+No exemplo acima, o atributo `dir` é definido dinamicamente com base no locale.

package/pt/packages/intlayer/getLocaleLang.md

@@ -0,0 +1,57 @@
+# Documentação: Função `getLocaleLang` em `intlayer`
+
+## Descrição
+
+A função `getLocaleLang` extrai o código do idioma de uma string de localidade. Ela suporta localidades com ou sem códigos de país. Se nenhuma localidade for fornecida, ela retorna uma string vazia por padrão.
+
+## Parâmetros
+
+- `locale?: Locales`
+
+  - **Descrição**: A string de localidade (por exemplo, `Locales.ENGLISH_UNITED_STATES`, `Locales.FRENCH_CANADA`) da qual o código do idioma é extraído.
+  - **Tipo**: `Locales` (opcional)
+
+## Retornos
+
+- **Tipo**: `string`
+- **Descrição**: O código do idioma extraído da localidade. Se a localidade não for fornecida, retorna uma string vazia (`''`).
+
+## Exemplo de Uso
+
+### Extraindo Códigos de Idioma:
+
+```typescript codeFormat="typescript"
+import { getLocaleLang, Locales } from "intlayer";
+
+getLocaleLang(Locales.ENGLISH_UNITED_STATES); // Saída: "en"
+getLocaleLang(Locales.ENGLISH); // Saída: "en"
+getLocaleLang(Locales.FRENCH_CANADA); // Saída: "fr"
+getLocaleLang(Locales.FRENCH); // Saída: "fr"
+```
+
+```javascript codeFormat="esm"
+import { getLocaleLang } from "intlayer";
+
+getLocaleLang(Locales.ENGLISH_UNITED_STATES); // Saída: "en"
+getLocaleLang(Locales.ENGLISH); // Saída: "en"
+getLocaleLang(Locales.FRENCH_CANADA); // Saída: "fr"
+getLocaleLang(Locales.FRENCH); // Saída: "fr"
+```
+
+```javascript codeFormat="commonjs"
+const { getLocaleLang } = require("intlayer");
+
+getLocaleLang(Locales.ENGLISH_UNITED_STATES); // Saída: "en"
+getLocaleLang(Locales.ENGLISH); // Saída: "en"
+getLocaleLang(Locales.FRENCH_CANADA); // Saída: "fr"
+getLocaleLang(Locales.FRENCH); // Saída: "fr"
+```
+
+## Casos de Borda
+
+- **Nenhuma Localidade Fornecida:**
+
+  - A função retorna uma string vazia quando `locale` é `undefined`.
+
+- **Strings de Localidade Malformadas:**
+  - Se o `locale` não seguir o formato `idioma-país` (por exemplo, `Locales.ENGLISH-US`), a função retorna com segurança a parte antes de `'-'` ou a string inteira se não houver `'-'`.

package/pt/packages/intlayer/getLocaleName.md

@@ -0,0 +1,93 @@
+# Documentação: Função `getLocaleName` em `intlayer`
+
+## Descrição
+
+A função `getLocaleName` retorna o nome localizado de um determinado locale (`targetLocale`) no locale de exibição (`displayLocale`). Se nenhum `targetLocale` for fornecido, ela retorna o nome do `displayLocale` em seu próprio idioma.
+
+## Parâmetros
+
+- `displayLocale: Locales`
+
+  - **Descrição**: O locale no qual o nome do locale alvo será exibido.
+  - **Tipo**: Enum ou string representando locales válidos.
+
+- `targetLocale?: Locales`
+  - **Descrição**: O locale cujo nome será localizado.
+  - **Tipo**: Opcional. Enum ou string representando locales válidos.
+
+## Retorno
+
+- **Tipo**: `string`
+- **Descrição**: O nome localizado do `targetLocale` no `displayLocale`, ou o próprio nome do `displayLocale` se `targetLocale` não for fornecido. Se nenhuma tradução for encontrada, retorna `"Unknown locale"`.
+
+## Exemplo de Uso
+
+```typescript codeFormat="typescript"
+import { Locales, getLocaleName } from "intlayer";
+
+getLocaleName(Locales.ENGLISH); // Saída: "English"
+getLocaleName(Locales.ENGLISH, Locales.FRENCH); // Saída: "Anglais"
+getLocaleName(Locales.ENGLISH, Locales.ESPANOL); // Saída: "Inglés"
+getLocaleName(Locales.ENGLISH, Locales.ENGLISH); // Saída: "English"
+
+getLocaleName(Locales.FRENCH); // Saída: "Français"
+getLocaleName(Locales.FRENCH, Locales.FRENCH); // Saída: "Français"
+getLocaleName(Locales.FRENCH, Locales.ESPANOL); // Saída: "Francés"
+getLocaleName(Locales.FRENCH, Locales.ENGLISH); // Saída: "French"
+
+getLocaleName(Locales.CHINESE); // Saída: "中文"
+getLocaleName(Locales.CHINESE, Locales.FRENCH); // Saída: "Chinois"
+getLocaleName(Locales.CHINESE, Locales.ESPANOL); // Saída: "Chino"
+getLocaleName(Locales.CHINESE, Locales.ENGLISH); // Saída: "Chinese"
+
+getLocaleName("unknown-locale"); // Saída: "Unknown locale"
+```
+
+```javascript codeFormat="esm"
+import { Locales, getLocaleName } from "intlayer";
+
+getLocaleName(Locales.ENGLISH); // Saída: "English"
+getLocaleName(Locales.ENGLISH, Locales.FRENCH); // Saída: "Anglais"
+getLocaleName(Locales.ENGLISH, Locales.ESPANOL); // Saída: "Inglés"
+getLocaleName(Locales.ENGLISH, Locales.ENGLISH); // Saída: "English"
+
+getLocaleName(Locales.FRENCH); // Saída: "Français"
+getLocaleName(Locales.FRENCH, Locales.FRENCH); // Saída: "Français"
+getLocaleName(Locales.FRENCH, Locales.ESPANOL); // Saída: "Francés"
+getLocaleName(Locales.FRENCH, Locales.ENGLISH); // Saída: "French"
+
+getLocaleName(Locales.CHINESE); // Saída: "中文"
+getLocaleName(Locales.CHINESE, Locales.FRENCH); // Saída: "Chinois"
+getLocaleName(Locales.CHINESE, Locales.ESPANOL); // Saída: "Chino"
+getLocaleName(Locales.CHINESE, Locales.ENGLISH); // Saída: "Chinese"
+
+getLocaleName("unknown-locale"); // Saída: "Unknown locale"
+```
+
+```javascript codeFormat="commonjs"
+const { Locales, getLocaleName } = require("intlayer");
+
+getLocaleName(Locales.ENGLISH); // Saída: "English"
+getLocaleName(Locales.ENGLISH, Locales.FRENCH); // Saída: "Anglais"
+getLocaleName(Locales.ENGLISH, Locales.ESPANOL); // Saída: "Inglés"
+getLocaleName(Locales.ENGLISH, Locales.ENGLISH); // Saída: "English"
+
+getLocaleName(Locales.FRENCH); // Saída: "Français"
+getLocaleName(Locales.FRENCH, Locales.FRENCH); // Saída: "Français"
+getLocaleName(Locales.FRENCH, Locales.ESPANOL); // Saída: "Francés"
+getLocaleName(Locales.FRENCH, Locales.ENGLISH); // Saída: "French"
+
+getLocaleName(Locales.CHINESE); // Saída: "中文"
+getLocaleName(Locales.CHINESE, Locales.FRENCH); // Saída: "Chinois"
+getLocaleName(Locales.CHINESE, Locales.ESPANOL); // Saída: "Chino"
+getLocaleName(Locales.CHINESE, Locales.ENGLISH); // Saída: "Chinese"
+
+getLocaleName("unknown-locale"); // Saída: "Unknown locale"
+```
+
+## Casos de Borda
+
+- **Nenhum `targetLocale` fornecido:**
+  - A função retorna o próprio nome do `displayLocale`.
+- **Traduções ausentes:**
+  - Se `localeNameTranslations` não contiver uma entrada para o `targetLocale` ou o `displayLocale` específico, a função retorna o `ownLocalesName` ou `"Unknown locale"`.

package/pt/packages/intlayer/getLocalizedUrl.md

@@ -0,0 +1,221 @@
+# Documentação: Função `getLocalizedUrl` em `intlayer`
+
+## Descrição
+
+A função `getLocalizedUrl` gera uma URL localizada prefixando a URL fornecida com o idioma especificado. Ela lida com URLs absolutas e relativas, garantindo que o prefixo de idioma correto seja aplicado com base na configuração.
+
+---
+
+## Parâmetros
+
+- `url: string`
+
+  - **Descrição**: A string da URL original a ser prefixada com um idioma.
+  - **Tipo**: `string`
+
+- `currentLocale: Locales`
+
+  - **Descrição**: O idioma atual para o qual a URL está sendo localizada.
+  - **Tipo**: `Locales`
+
+- `locales: Locales[]`
+
+  - **Descrição**: Array opcional de idiomas suportados. Por padrão, os idiomas configurados no projeto são fornecidos.
+  - **Tipo**: `Locales[]`
+  - **Padrão**: [`Configuração do Projeto`](https://github.com/aymericzip/intlayer/blob/main/docs/pt/configuration.md#middleware)
+
+- `defaultLocale: Locales`
+
+  - **Descrição**: O idioma padrão para a aplicação. Por padrão, o idioma padrão configurado no projeto é fornecido.
+  - **Tipo**: `Locales`
+  - **Padrão**: [`Configuração do Projeto`](https://github.com/aymericzip/intlayer/blob/main/docs/pt/configuration.md#middleware)
+
+- `prefixDefault: boolean`
+  - **Descrição**: Indica se a URL deve ser prefixada para o idioma padrão. Por padrão, o valor configurado no projeto é fornecido.
+  - **Tipo**: `boolean`
+  - **Padrão**: [`Configuração do Projeto`](https://github.com/aymericzip/intlayer/blob/main/docs/pt/configuration.md#middleware)
+
+### Retorno
+
+- **Tipo**: `string`
+- **Descrição**: A URL localizada para o idioma especificado.
+
+---
+
+## Exemplo de Uso
+
+### URLs Relativas
+
+```typescript codeFormat="typescript"
+import { getLocalizedUrl, Locales } from "intlayer";
+
+getLocalizedUrl(
+  "/about",
+  Locales.FRENCH,
+  [Locales.ENGLISH, Locales.FRENCH],
+  Locales.ENGLISH,
+  false
+);
+
+// Saída: "/fr/about" para o idioma francês
+// Saída: "/about" para o idioma padrão (inglês)
+```
+
+```javascript codeFormat="esm"
+import { getLocalizedUrl, Locales } from "intlayer";
+
+getLocalizedUrl(
+  "/about",
+  Locales.FRENCH,
+  [Locales.ENGLISH, Locales.FRENCH],
+  Locales.ENGLISH,
+  false
+);
+
+// Saída: "/fr/about" para o idioma francês
+// Saída: "/about" para o idioma padrão (inglês)
+```
+
+```javascript codeFormat="esm"
+import { getLocalizedUrl, Locales } from "intlayer";
+
+getLocalizedUrl(
+  "/about",
+  Locales.FRENCH,
+  [Locales.ENGLISH, Locales.FRENCH],
+  Locales.ENGLISH,
+  false
+);
+
+// Saída: "/fr/about" para o idioma francês
+// Saída: "/about" para o idioma padrão (inglês)
+```
+
+```javascript codeFormat="commonjs"
+const { getLocalizedUrl, Locales } = require("intlayer");
+
+getLocalizedUrl(
+  "/about",
+  Locales.FRENCH,
+  [Locales.ENGLISH, Locales.FRENCH],
+  Locales.ENGLISH,
+  false
+);
+
+// Saída: "/fr/about" para o idioma francês
+// Saída: "/about" para o idioma padrão (inglês)
+```
+
+### URLs Absolutas
+
+```typescript
+getLocalizedUrl(
+  "https://example.com/about",
+  Locales.FRENCH, // Idioma Atual
+  [Locales.ENGLISH, Locales.FRENCH], // Idiomas Suportados
+  Locales.ENGLISH, // Idioma Padrão
+  false // Prefixar Idioma Padrão
+); // Saída: "https://example.com/fr/about" para o idioma francês
+
+getLocalizedUrl(
+  "https://example.com/about",
+  Locales.ENGLISH, // Idioma Atual
+  [Locales.ENGLISH, Locales.FRENCH], // Idiomas Suportados
+  Locales.ENGLISH, // Idioma Padrão
+  false // Prefixar Idioma Padrão
+); // Saída: "https://example.com/about" para o idioma inglês
+
+getLocalizedUrl(
+  "https://example.com/about",
+  Locales.ENGLISH, // Idioma Atual
+  [Locales.ENGLISH, Locales.FRENCH], // Idiomas Suportados
+  Locales.ENGLISH, // Idioma Padrão
+  true // Prefixar Idioma Padrão
+); // Saída: "https://example.com/en/about" para o idioma inglês
+```
+
+### Idioma Não Suportado
+
+```typescript
+getLocalizedUrl(
+  "/about",
+  Locales.ITALIAN, // Idioma Atual
+  [Locales.ENGLISH, Locales.FRENCH], // Idiomas Suportados
+  Locales.ENGLISH // Idioma Padrão
+); // Saída: "/about" (nenhum prefixo aplicado para idioma não suportado)
+```
+
+---
+
+## Casos Especiais
+
+- **Sem Segmento de Idioma:**
+
+  - Se a URL não contiver nenhum segmento de idioma, a função adiciona com segurança o idioma apropriado.
+
+- **Idioma Padrão:**
+
+  - Quando `prefixDefault` é `false`, a função não adiciona prefixo à URL para o idioma padrão.
+
+- **Idiomas Não Suportados:**
+  - Para idiomas não listados em `locales`, a função não aplica nenhum prefixo.
+
+---
+
+## Uso em Aplicações
+
+Em uma aplicação multilíngue, configurar as definições de internacionalização com `locales` e `defaultLocale` é essencial para garantir que o idioma correto seja exibido. Abaixo está um exemplo de como a função `getLocalizedUrl` pode ser usada na configuração de uma aplicação:
+
+```tsx codeFormat="typescript"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+// Configuração para idiomas suportados e idioma padrão
+export default {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+} satisfies IntlayerConfig;
+
+export default config;
+```
+
+```javascript 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 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;
+```
+
+A configuração acima garante que a aplicação reconheça `ENGLISH`, `FRENCH` e `SPANISH` como idiomas suportados e use `ENGLISH` como idioma de fallback.
+
+Usando essa configuração, a função `getLocalizedUrl` pode gerar dinamicamente URLs localizadas com base na preferência de idioma do usuário:
+
+```typescript
+getLocalizedUrl("/about", Locales.FRENCH); // Saída: "/fr/about"
+getLocalizedUrl("/about", Locales.SPANISH); // Saída: "/es/about"
+getLocalizedUrl("/about", Locales.ENGLISH); // Saída: "/about"
+```
+
+Ao integrar `getLocalizedUrl`, os desenvolvedores podem manter estruturas de URL consistentes em vários idiomas, melhorando tanto a experiência do usuário quanto o SEO.