@intlayer/docs 5.5.8

package/pt/packages/next-intlayer/useLocale.md

@@ -0,0 +1,105 @@
+# Integração Next.js: Documentação do Hook `useLocale` para `next-intlayer`
+
+Esta seção oferece documentação detalhada sobre o hook `useLocale` adaptado para aplicações Next.js dentro da biblioteca `next-intlayer`. Ele é projetado para lidar com mudanças de localidade e roteamento de forma eficiente.
+
+## Importando `useLocale` no Next.js
+
+Para utilizar o hook `useLocale` na sua aplicação Next.js, importe-o conforme mostrado abaixo:
+
+```javascript
+import { useLocale } from "next-intlayer"; // Usado para gerenciar localidades e roteamento no Next.js
+```
+
+## Uso
+
+Veja como implementar o hook `useLocale` dentro de um componente Next.js:
+
+```tsx fileName="src/components/LocaleSwitcher.tsx" codeFormat="typescript"
+"use client";
+
+import type { FC } from "react";
+import { Locales } from "intlayer";
+import { useLocale } from "next-intlayer";
+
+const LocaleSwitcher: FC = () => {
+  const { locale, defaultLocale, availableLocales, setLocale } = useLocale();
+
+  return (
+    <div>
+      <h1>Localidade Atual: {locale}</h1>
+      <p>Localidade Padrão: {defaultLocale}</p>
+      <select value={locale} onChange={(e) => setLocale(e.target.value)}>
+        {availableLocales.map((loc) => (
+          <option key={loc} value={loc}>
+            {loc}
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/LocaleSwitcher.mjx" codeFormat="esm"
+"use client";
+
+import { Locales } from "intlayer";
+import { useLocale } from "next-intlayer";
+
+const LocaleSwitcher = () => {
+  const { locale, defaultLocale, availableLocales, setLocale } = useLocale();
+
+  return (
+    <div>
+      <h1>Localidade Atual: {locale}</h1>
+      <p>Localidade Padrão: {defaultLocale}</p>
+      <select value={locale} onChange={(e) => setLocale(e.target.value)}>
+        {availableLocales.map((loc) => (
+          <option key={loc} value={loc}>
+            {loc}
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/LocaleSwitcher.csx" codeFormat="commonjs"
+"use client";
+
+const { Locales } = require("intlayer");
+const { useLocale } = require("next-intlayer");
+
+const LocaleSwitcher = () => {
+  const { locale, defaultLocale, availableLocales, setLocale } = useLocale();
+
+  return (
+    <div>
+      <h1>Localidade Atual: {locale}</h1>
+      <p>Localidade Padrão: {defaultLocale}</p>
+      <select value={locale} onChange={(e) => setLocale(e.target.value)}>
+        {availableLocales.map((loc) => (
+          <option key={loc} value={loc}>
+            {loc}
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+};
+```
+
+## Parâmetros e Valores Retornados
+
+Quando você invoca o hook `useLocale`, ele retorna um objeto contendo as seguintes propriedades:
+
+- **`locale`**: A localidade atual definida no contexto do React.
+- **`defaultLocale`**: A localidade principal definida na configuração.
+- **`availableLocales`**: Uma lista de todas as localidades disponíveis conforme definido na configuração.
+- **`setLocale`**: Uma função para alterar a localidade da aplicação e atualizar a URL de forma correspondente. Ela cuida das regras de prefixo, seja para adicionar ou não a localidade ao caminho com base na configuração. Utiliza `useRouter` de `next/navigation` para funções de navegação como `push` e `refresh`.
+- **`pathWithoutLocale`**: Uma propriedade computada que retorna o caminho sem a localidade. É útil para comparar URLs. Por exemplo, se a localidade atual for `fr`, e a URL `fr/my_path`, o caminho sem localidade é `/my_path`. Utiliza `usePathname` de `next/navigation` para obter o caminho atual.
+
+## Conclusão
+
+O hook `useLocale` do `next-intlayer` é uma ferramenta crucial para gerenciar localidades em aplicações Next.js. Ele oferece uma abordagem integrada para adaptar sua aplicação para múltiplas localidades, lidando com armazenamento de localidade, gerenciamento de estado e modificações de URL de forma perfeita.

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

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

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

@@ -0,0 +1,261 @@
+# react-intlayer: Pacote NPM para internacionalizar (i18n) uma aplicação React
+
+**Intlayer** é um conjunto de pacotes projetados especificamente para desenvolvedores JavaScript. É compatível com frameworks como React, React e Express.js.
+
+**O pacote `react-intlayer`** permite que você internacionalize sua aplicação React. Ele fornece provedores de contexto e hooks para internacionalização no React.
+
+## Por que internacionalizar sua aplicação React?
+
+Internacionalizar sua aplicação React é essencial para atender efetivamente 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.
+
+## Por que integrar o Intlayer?
+
+- **Gerenciamento de Conteúdo com JavaScript**: Aproveite a flexibilidade do JavaScript para definir e gerenciar seu conteúdo de forma eficiente.
+- **Ambiente com Tipagem Segura**: Utilize TypeScript para garantir que todas as definições de conteúdo sejam precisas e livres de erros.
+- **Arquivos de Conteúdo Integrados**: Mantenha suas traduções próximas aos seus respectivos componentes, melhorando a manutenção e clareza.
+
+## Instalação
+
+Instale o pacote necessário usando seu gerenciador de pacotes preferido:
+
+```bash packageManager="npm"
+npm install react-intlayer
+```
+
+```bash packageManager="yarn"
+yarn add react-intlayer
+```
+
+```bash packageManager="pnpm"
+pnpm add react-intlayer
+```
+
+## Exemplo de uso
+
+Com o Intlayer, você pode declarar seu conteúdo de forma estruturada em qualquer lugar do seu código.
+
+Por padrão, o Intlayer procura por arquivos com a extensão `.content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}`.
+
+> Você pode modificar a extensão padrão configurando a propriedade `contentDir` no [arquivo de configuração](https://github.com/aymericzip/intlayer/blob/main/docs/pt/configuration.md).
+
+```bash codeFormat="typescript"
+.
+├── intlayer.config.ts
+└── src
+    └── components
+        ├── Component1
+        │   ├── index.content.ts
+        │   └── index.tsx
+        └── Component2
+            ├── index.content.ts
+            └── index.tsx
+```
+
+```bash codeFormat="esm"
+.
+├── intlayer.config.mjs
+└── src
+    └── components
+        ├── Component1
+        │   ├── index.content.mjs
+        │   └── index.mjx
+        └── Component2
+            ├── index.content.mjs
+            └── index.mjx
+```
+
+```bash codeFormat="commonjs"
+.
+├── intlayer.config.cjs
+└── src
+    └── components
+        ├── Component1
+        │   ├── index.content.cjs
+        │   └── index.cjx
+        └── Component2
+            ├── index.content.cjs
+            └── index.cjx
+```
+
+### Declare seu conteúdo
+
+O `react-intlayer` foi feito para funcionar com o pacote [`intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/pt/packages/intlayer/index.md). O `intlayer` é um pacote que permite declarar seu conteúdo em qualquer lugar do seu código. Ele converte declarações de conteúdo multilíngue em dicionários estruturados que se integram perfeitamente à sua aplicação.
+
+Aqui está um exemplo de declaração de conteúdo:
+
+```tsx fileName="src/Component1/index.content.ts" codeFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const component1Content = {
+  key: "component-1",
+  content: {
+    myTranslatedContent: t({
+      en: "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+      pt: "Olá Mundo",
+    }),
+    numberOfCar: enu({
+      "<-1": "Menos de menos um carro",
+      "-1": "Menos um carro",
+      "0": "Nenhum carro",
+      "1": "Um carro",
+      ">5": "Alguns carros",
+      ">19": "Muitos carros",
+    }),
+  },
+} satisfies Dictionary;
+
+export default component1Content;
+```
+
+```jsx fileName="src/Component1/index.content.mjs" contentDeclarationFormat="esm"
+import { t } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const component1Content = {
+  key: "component-1",
+  content: {
+    myTranslatedContent: t({
+      en: "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+      pt: "Olá Mundo",
+    }),
+    numberOfCar: enu({
+      "<-1": "Menos de menos um carro",
+      "-1": "Menos um carro",
+      "0": "Nenhum carro",
+      "1": "Um carro",
+      ">5": "Alguns carros",
+      ">19": "Muitos carros",
+    }),
+  },
+};
+
+export default component1Content;
+```
+
+```jsx fileName="src/Component1/index.content.cjs" contentDeclarationFormat="commonjs"
+const { t } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const component1Content = {
+  key: "component-1",
+  content: {
+    myTranslatedContent: t({
+      en: "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+      pt: "Olá Mundo",
+    }),
+    numberOfCar: enu({
+      "<-1": "Menos de menos um carro",
+      "-1": "Menos um carro",
+      "0": "Nenhum carro",
+      "1": "Um carro",
+      ">5": "Alguns carros",
+      ">19": "Muitos carros",
+    }),
+  },
+};
+
+module.exports = component1Content;
+```
+
+```json fileName="src/Component1/index.content.json" codeFormat="json"
+{
+  "key": "component-1",
+  "content": {
+    "myTranslatedContent": {
+      "nodeType": "translation",
+      "translation": {
+        "en": "Hello World",
+        "fr": "Bonjour le monde",
+        "es": "Hola Mundo",
+        "pt": "Olá Mundo"
+      }
+    },
+    "numberOfCar": {
+      "nodeType": "enumeration",
+      "enumeration": {
+        "<-1": "Menos de menos um carro",
+        "-1": "Menos um carro",
+        "0": "Nenhum carro",
+        "1": "Um carro",
+        ">5": "Alguns carros",
+        ">19": "Muitos carros"
+      }
+    }
+  }
+}
+```
+
+### Utilize o conteúdo no seu código
+
+Depois de declarar seu conteúdo, você pode usá-lo no seu código. Aqui está um exemplo de como usar o conteúdo em um componente React:
+
+```tsx {4,7} fileName="src/components/Component1Example.tsx" codeFormat="typescript"
+"use client";
+
+import type { FC } from "react";
+import { useIntlayer } from "react-intlayer";
+
+export const Component1Example: FC = () => {
+  const { myTranslatedContent } = useIntlayer("component-1"); // Criar declaração de conteúdo relacionada
+
+  return (
+    <div>
+      <p>{myTranslatedContent}</p>
+    </div>
+  );
+};
+```
+
+```jsx {3,6} fileName="src/components/Component1Example.mjx" codeFormat="esm"
+"use client";
+
+import { useIntlayer } from "react-intlayer";
+
+const Component1Example = () => {
+  const { myTranslatedContent } = useIntlayer("component-1"); // Criar declaração de conteúdo relacionada
+
+  return (
+    <div>
+      <p>{myTranslatedContent}</p>
+    </div>
+  );
+};
+```
+
+```jsx {3,6} fileName="src/components/Component1Example.csx" codeFormat="commonjs"
+"use client";
+
+const { useIntlayer } = require("react-intlayer");
+
+const Component1Example = () => {
+  const { myTranslatedContent } = useIntlayer("component-1"); // Criar declaração de conteúdo relacionada
+
+  return (
+    <div>
+      <p>{myTranslatedContent}</p>
+    </div>
+  );
+};
+```
+
+## Dominando a internacionalização da sua aplicação React
+
+O Intlayer oferece muitos recursos para ajudá-lo a internacionalizar sua aplicação React.
+
+**Para saber mais sobre esses recursos, consulte o guia [Internacionalização (i18n) no React com Intlayer e Vite e React](https://github.com/aymericzip/intlayer/blob/main/docs/pt/intlayer_with_vite+react.md) para aplicações Vite e React, ou o guia [Internacionalização (i18n) no React com Intlayer e React (CRA)](https://github.com/aymericzip/intlayer/blob/main/docs/pt/intlayer_with_create_react_app.md) para aplicações criadas com Create React App.**
+
+## Funções fornecidas pelo pacote `react-intlayer`
+
+O pacote `react-intlayer` também fornece algumas funções para ajudá-lo a internacionalizar sua aplicação.
+
+- [`t()`](https://github.com/aymericzip/intlayer/blob/main/docs/pt/packages/react-intlayer/t.md)
+- [`useIntlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/pt/packages/react-intlayer/useIntlayer.md)
+- [`useDictionary()`](https://github.com/aymericzip/intlayer/blob/main/docs/pt/packages/react-intlayer/useDictionary.md)
+- [`useLocale()`](https://github.com/aymericzip/intlayer/blob/main/docs/pt/packages/react-intlayer/useLocale.md)
+- [`useIntlayerAsync()`](https://github.com/aymericzip/intlayer/blob/main/docs/pt/packages/react-intlayer/useIntlayerAsync.md)

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

@@ -0,0 +1,289 @@
+# Documentação: Função `t` no `react-intlayer`
+
+A função `t` no pacote `react-intlayer` é uma ferramenta fundamental para internacionalização inline dentro da sua aplicação React. Ela permite definir traduções diretamente nos seus componentes, tornando simples exibir conteúdo localizado com base no idioma atual.
+
+---
+
+## Visão Geral
+
+A função `t` é usada para fornecer traduções para diferentes idiomas diretamente nos seus componentes. Ao passar um objeto contendo traduções para cada idioma suportado, `t` retorna a tradução apropriada com base no contexto de idioma atual na sua aplicação React.
+
+---
+
+## Principais Recursos
+
+- **Traduções Inline**: Ideal para textos rápidos e inline que não requerem uma declaração de conteúdo separada.
+- **Seleção Automática de Idioma**: Retorna automaticamente a tradução correspondente ao idioma atual.
+- **Suporte ao TypeScript**: Oferece segurança de tipos e autocompletar quando usado com TypeScript.
+- **Fácil Integração**: Funciona perfeitamente dentro de componentes React.
+
+---
+
+## Assinatura da Função
+
+```typescript
+t<T extends string>(content: Record<LocalesValues, T>, locale?: Locales): string
+```
+
+### Parâmetros
+
+- `translations`: Um objeto onde as chaves são códigos de idioma (por exemplo, `en`, `fr`, `es`) e os valores são as strings traduzidas correspondentes.
+
+### Retorna
+
+- Uma string representando o conteúdo traduzido para o idioma atual.
+
+---
+
+## Exemplos de Uso
+
+### Uso Básico de `t` em um Componente
+
+```tsx fileName="src/components/ComponentExample.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { t } from "react-intlayer";
+
+export const ComponentExample: FC = () => {
+  return (
+    <div>
+      <p>
+        {t({
+          en: "This is an example of a component",
+          fr: "Ceci est un exemple de composant",
+          es: "Este es un ejemplo de componente",
+          pt: "Este é um exemplo de componente",
+        })}
+      </p>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ComponentExample.mjx" codeFormat="esm"
+import { t } from "react-intlayer";
+
+const ComponentExample = () => {
+  return (
+    <div>
+      <p>
+        {t({
+          en: "This is an example of a component",
+          fr: "Ceci est un exemple de composant",
+          es: "Este es un ejemplo de componente",
+          pt: "Este é um exemplo de componente",
+        })}
+      </p>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ComponentExample.csx" codeFormat="commonjs"
+const { t } = require("react-intlayer");
+
+const ComponentExample = () => {
+  return (
+    <div>
+      <p>
+        {t({
+          en: "This is an example of a component",
+          fr: "Ceci est un exemple de composant",
+          es: "Este es un exemplo de componente",
+          pt: "Este é um exemplo de componente",
+        })}
+      </p>
+    </div>
+  );
+};
+```
+
+### Traduções Inline em Atributos
+
+A função `t` é particularmente útil para traduções inline em atributos JSX. Ao localizar atributos como `alt`, `title`, `href` ou `aria-label`, você pode usar `t` diretamente no atributo.
+
+```jsx
+<button
+  aria-label={t({
+    en: "Submit",
+    fr: "Soumettre",
+    es: "Enviar",
+    pt: "Enviar",
+  })}
+>
+  {t({
+    en: "Submit",
+    fr: "Soumettre",
+    es: "Enviar",
+    pt: "Enviar",
+  })}
+  <img
+    src="/path/to/image"
+    alt={t({
+      en: "A beautiful scenery",
+      fr: "Un beau paysage",
+      es: "Un hermoso paisaje",
+      pt: "Uma bela paisagem",
+    })}
+  />
+</button>
+```
+
+---
+
+## Tópicos Avançados
+
+### Integração com TypeScript
+
+A função `t` é segura para tipos quando usada com TypeScript, garantindo que todos os idiomas necessários sejam fornecidos.
+
+```typescript codeFormat="typescript"
+import { t, type IConfigLocales } from "react-intlayer";
+
+const translations: IConfigLocales<string> = {
+  en: "Welcome",
+  fr: "Bienvenue",
+  es: "Bienvenido",
+  pt: "Bem-vindo",
+};
+
+const greeting = t(translations);
+```
+
+```javascript codeFormat="esm"
+import { t, type IConfigLocales } from "react-intlayer";
+
+/** @type {import('react-intlayer').IConfigLocales<string>} */
+const translations = {
+  en: "Welcome",
+  fr: "Bienvenue",
+  es: "Bienvenido",
+  pt: "Bem-vindo",
+};
+
+const greeting = t(translations);
+```
+
+```javascript codeFormat="commonjs"
+const { t, type IConfigLocales } = require("react-intlayer");
+
+/** @type {import('react-intlayer').IConfigLocales<string>} */
+const translations = {
+  en: "Welcome",
+  fr: "Bienvenue",
+  es: "Bienvenido",
+  pt: "Bem-vindo",
+};
+
+const greeting = t(translations);
+```
+
+### Detecção de Idioma e Contexto
+
+No `react-intlayer`, o idioma atual é gerenciado através do `IntlayerProvider`. Certifique-se de que este provedor envolve seus componentes e que a propriedade `locale` seja passada corretamente.
+
+#### Exemplo:
+
+```tsx fileName="src/app.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import type { Locales } from "intlayer";
+import { IntlayerProvider } from "react-intlayer";
+
+const App: FC<{ locale: Locales }> = ({ locale }) => (
+  <IntlayerProvider locale={locale}>
+    {/* Seus componentes aqui */}
+  </IntlayerProvider>
+);
+```
+
+```jsx fileName="src/app.mjx" codeFormat="esm"
+import { IntlayerProvider } from "react-intlayer";
+
+const App = ({ locale }) => (
+  <IntlayerProvider locale={locale}>
+    {/* Seus componentes aqui */}
+  </IntlayerProvider>
+);
+```
+
+```jsx fileName="src/app.csx" codeFormat="commonjs"
+const { IntlayerProvider } = require("react-intlayer");
+
+const App = ({ locale }) => (
+  <IntlayerProvider locale={locale}>
+    {/* Seus componentes aqui */}
+  </IntlayerProvider>
+);
+```
+
+---
+
+## Erros Comuns e Soluções
+
+### `t` Retorna Undefined ou Tradução Incorreta
+
+- **Causa**: O idioma atual não está configurado corretamente ou a tradução para o idioma atual está ausente.
+- **Solução**:
+  - Verifique se o `IntlayerProvider` está configurado corretamente com o idioma apropriado.
+  - Certifique-se de que seu objeto de traduções inclui todos os idiomas necessários.
+
+### Traduções Ausentes no TypeScript
+
+- **Causa**: O objeto de traduções não satisfaz os idiomas necessários, resultando em erros no TypeScript.
+- **Solução**: Use o tipo `IConfigLocales` para garantir a completude das suas traduções.
+
+```typescript codeFormat="typescript"
+const translations: IConfigLocales<string> = {
+  en: "Text",
+  fr: "Texte",
+  // es: 'Texto', // Ausência de 'es' causará um erro no TypeScript
+  pt: "Texto",
+};
+
+const text = t(translations);
+```
+
+```javascript codeFormat="esm"
+const translations = {
+  en: "Text",
+  fr: "Texte",
+  // es: 'Texto', // Ausência de 'es' causará um erro no TypeScript
+  pt: "Texto",
+};
+
+const text = t(translations);
+```
+
+```javascript codeFormat="commonjs"
+const { t, type IConfigLocales } = require("react-intlayer");
+
+/** @type {import('react-intlayer').IConfigLocales<string>} */
+const translations = {
+  en: "Text",
+  fr: "Texte",
+  // es: 'Texto', // Ausência de 'es' causará um erro no TypeScript
+  pt: "Texto",
+};
+
+const text = t(translations);
+```
+
+---
+
+## Dicas para Uso Eficaz
+
+1. **Use `t` para Traduções Inline Simples**: Ideal para traduzir pequenos trechos de texto diretamente nos seus componentes.
+2. **Prefira `useIntlayer` para Conteúdo Estruturado**: Para traduções mais complexas e reutilização de conteúdo, defina o conteúdo em arquivos de declaração e use `useIntlayer`.
+3. **Consistência na Provisão de Idiomas**: Certifique-se de que seu idioma seja fornecido consistentemente em toda a aplicação através do `IntlayerProvider`.
+4. **Aproveite o TypeScript**: Use tipos do TypeScript para capturar traduções ausentes e garantir segurança de tipos.
+
+---
+
+## Conclusão
+
+A função `t` no `react-intlayer` é uma ferramenta poderosa e conveniente para gerenciar traduções inline em suas aplicações React. Ao integrá-la de forma eficaz, você melhora as capacidades de internacionalização do seu aplicativo, proporcionando uma melhor experiência para usuários em todo o mundo.
+
+Para mais detalhes sobre o uso e recursos avançados, consulte a [documentação do react-intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/pt/intlayer_visual_editor.md).
+
+---
+
+**Nota**: Lembre-se de configurar corretamente seu `IntlayerProvider` para garantir que o idioma atual seja passado corretamente para seus componentes. Isso é crucial para que a função `t` retorne as traduções corretas.