@intlayer/docs 5.5.8

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

@@ -0,0 +1,270 @@
+# next-intlayer: Pacote NPM para internacionalizar (i18n) uma aplicação Next.js
+
+**Intlayer** é um conjunto de pacotes projetados especificamente para desenvolvedores JavaScript. É compatível com frameworks como React, Next.js e Express.js.
+
+**O pacote `next-intlayer`** permite que você internacionalize sua aplicação Next.js. Ele fornece provedores de contexto e hooks para internacionalização no Next.js. Além disso, inclui o plugin Next.js para integrar o Intlayer com [Webpack](https://webpack.js.org/) ou [Turbopack](https://nextjs.org/docs/app/api-reference/turbopack), bem como middleware para detectar o idioma preferido do usuário, gerenciar cookies e lidar com redirecionamento de URLs.
+
+## Por que internacionalizar sua aplicação Next.js?
+
+Internacionalizar sua aplicação Next.js é 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.
+
+## 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 a clareza.
+
+## Instalação
+
+Instale o pacote necessário usando o gerenciador de pacotes de sua preferência:
+
+```bash packageManager="npm"
+npm install next-intlayer
+```
+
+```bash packageManager="yarn"
+yarn add next-intlayer
+```
+
+```bash packageManager="pnpm"
+pnpm add next-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
+        ├── ClientComponent
+        │   ├── index.content.ts
+        │   └── index.tsx
+        └── ServerComponent
+            ├── index.content.ts
+            └── index.tsx
+```
+
+```bash codeFormat="esm"
+.
+├── intlayer.config.mjs
+└── src
+    └── components
+        ├── ClientComponent
+        │   ├── index.content.mjs
+        │   └── index.mjx
+        └── ServerComponent
+            ├── index.content.mjs
+            └── index.mjx
+```
+
+```bash codeFormat="commonjs"
+.
+├── intlayer.config.cjs
+└── src
+    └── components
+        ├── ClientComponent
+        │   ├── index.content.cjs
+        │   └── index.cjx
+        └── ServerComponent
+            ├── index.content.cjs
+            └── index.cjx
+```
+
+### Declare seu conteúdo
+
+O `next-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/ClientComponent/index.content.ts" codeFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+// Declaração de conteúdo traduzido
+const clientComponentContent = {
+  key: "client-component",
+  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 clientComponentContent;
+```
+
+```jsx fileName="src/ClientComponent/index.content.mjs" contentDeclarationFormat="esm"
+import { t } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+// Declaração de conteúdo traduzido
+const clientComponentContent = {
+  key: "client-component",
+  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 clientComponentContent;
+```
+
+```jsx fileName="src/ClientComponent/index.content.cjs" contentDeclarationFormat="commonjs"
+const { t } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+// Declaração de conteúdo traduzido
+const clientComponentContent = {
+  key: "client-component",
+  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 = clientComponentContent;
+```
+
+```json fileName="src/ClientComponent/index.content.json" codeFormat="json"
+{
+  "key": "client-component",
+  "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/ClientComponentExample.tsx" codeFormat="typescript"
+"use client";
+
+import type { FC } from "react";
+import { useIntlayer } from "next-intlayer";
+
+export const ClientComponentExample: FC = () => {
+  const { myTranslatedContent } = useIntlayer("client-component"); // Criação da declaração de conteúdo relacionada
+
+  return (
+    <div>
+      <p>{myTranslatedContent}</p>
+    </div>
+  );
+};
+```
+
+```jsx {3,6} fileName="src/components/ClientComponentExample.mjx" codeFormat="esm"
+"use client";
+
+import { useIntlayer } from "next-intlayer";
+
+const ClientComponentExample = () => {
+  const { myTranslatedContent } = useIntlayer("client-component"); // Criação da declaração de conteúdo relacionada
+
+  return (
+    <div>
+      <p>{myTranslatedContent}</p>
+    </div>
+  );
+};
+```
+
+```jsx {3,6} fileName="src/components/ClientComponentExample.csx" codeFormat="commonjs"
+"use client";
+
+const { useIntlayer } = require("next-intlayer");
+
+const ClientComponentExample = () => {
+  const { myTranslatedContent } = useIntlayer("client-component"); // Criação da declaração de conteúdo relacionada
+
+  return (
+    <div>
+      <p>{myTranslatedContent}</p>
+    </div>
+  );
+};
+```
+
+## Dominando a internacionalização da sua aplicação Next.js
+
+O Intlayer oferece muitos recursos para ajudá-lo a internacionalizar sua aplicação Next.js. Aqui estão alguns dos principais recursos:
+
+- **Internacionalização de componentes do servidor**: O Intlayer permite que você internacionalize seus componentes do servidor da mesma forma que seus componentes do cliente. Isso significa que você pode usar as mesmas declarações de conteúdo para ambos.
+- **Middleware para Detecção de Idioma**: O Intlayer fornece middleware para detectar o idioma preferido do usuário. Esse middleware é usado para detectar o idioma preferido do usuário e redirecioná-lo para a URL apropriada, conforme especificado na [configuração](https://github.com/aymericzip/intlayer/blob/main/docs/pt/configuration.md).
+- **Internacionalização de metadados**: O Intlayer oferece uma maneira de internacionalizar seus metadados, como o título da sua página, usando a função `generateMetadata` fornecida pelo Next.js. Você pode usar a função `getTranslation` para traduzir seus metadados.
+- **Internacionalização de sitemap.xml e robots.txt**: O Intlayer permite que você internacionalize seus arquivos sitemap.xml e robots.txt. Você pode usar a função `getMultilingualUrls` para gerar URLs multilíngues para seu sitemap.
+- **Internacionalização de URLs**: O Intlayer permite que você internacionalize suas URLs usando a função `getMultilingualUrls`. Essa função gera URLs multilíngues para seu sitemap.
+
+**Para saber mais sobre esses recursos, consulte o guia [Internacionalização (i18n) do Next.js com Intlayer e Next.js 15 App Router](https://github.com/aymericzip/intlayer/blob/main/docs/pt/intlayer_with_nextjs_15.md).**
+
+## Funções fornecidas pelo pacote `next-intlayer`
+
+O pacote `next-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/next-intlayer/t.md)
+- [`useIntlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/pt/packages/next-intlayer/useIntlayer.md)
+- [`useDictionary()`](https://github.com/aymericzip/intlayer/blob/main/docs/pt/packages/next-intlayer/useDictionary.md)
+- [`useLocale()`](https://github.com/aymericzip/intlayer/blob/main/docs/pt/packages/next-intlayer/useLocale.md)
+- [`useIntlayerAsync()`](https://github.com/aymericzip/intlayer/blob/main/docs/pt/packages/next-intlayer/useIntlayerAsync.md)

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

@@ -0,0 +1,341 @@
+# Documentação: Função `t` no `next-intlayer`
+
+A função `t` no pacote `next-intlayer` é uma ferramenta fundamental para internacionalização inline dentro da sua aplicação Next.js. Ela permite definir traduções diretamente nos seus componentes, facilitando a exibição de 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 Next.js.
+
+---
+
+## Principais Recursos
+
+- **Traduções Inline**: Ideal para textos rápidos e inline que não exigem 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.
+- **Integração Fácil**: Funciona perfeitamente em componentes cliente e servidor no Next.js.
+
+---
+
+## 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
+
+### Usando `t` em um Componente Cliente
+
+Certifique-se de incluir a diretiva `'use client';` no topo do arquivo do componente ao usar `t` em um componente do lado do cliente.
+
+```tsx codeFormat="typescript"
+"use client";
+
+import type { FC } from "react";
+import { t } from "next-intlayer";
+
+export const ClientComponentExample: FC = () => (
+  <p>
+    {t({
+      en: "This is the content of a client component example",
+      fr: "Ceci est le contenu d'un exemple de composant client",
+      es: "Este es el contenido d un exemplo de componente cliente",
+      pt: "Este é o conteúdo de um exemplo de componente cliente",
+    })}
+  </p>
+);
+```
+
+```javascript codeFormat="esm"
+import { t } from "next-intlayer";
+
+const ClientComponentExample = () => (
+  <p>
+    {t({
+      en: "This is the content of a client component example",
+      fr: "Ceci est le contenu d'un exemple de composant client",
+      es: "Este es el conteúdo d un exemplo de componente cliente",
+      pt: "Este é o conteúdo de um exemplo de componente cliente",
+    })}
+  </p>
+);
+```
+
+```javascript codeFormat="commonjs"
+const { t } = require("next-intlayer");
+
+const ClientComponentExample = () => (
+  <p>
+    {t({
+      en: "This is the content of a client component example",
+      fr: "Ceci est le contenu d'un exemple de composant client",
+      es: "Este es el conteúdo d un exemplo de componente cliente",
+      pt: "Este é o conteúdo de um exemplo de componente cliente",
+    })}
+  </p>
+);
+```
+
+### Usando `t` em um Componente Servidor
+
+```tsx codeFormat="typescript"
+import type { FC } from "react";
+import { t } from "next-intlayer/server";
+
+export const ServerComponentExample: FC = () => (
+  <p>
+    {t({
+      en: "This is the content of a server component example",
+      fr: "Ceci est le contenu d'un exemple de composant serveur",
+      es: "Este es el conteúdo de un exemplo de componente servidor",
+      pt: "Este é o conteúdo de um exemplo de componente servidor",
+    })}
+  </p>
+);
+```
+
+```javascript codeFormat="esm"
+import { t } from "next-intlayer/server";
+
+const ServerComponentExample = () => (
+  <p>
+    {t({
+      en: "This is the content of a server component example",
+      fr: "Ceci est le contenu d'un exemple de composant serveur",
+      es: "Este es el conteúdo de un exemplo de componente servidor",
+      pt: "Este é o conteúdo de um exemplo de componente servidor",
+    })}
+  </p>
+);
+```
+
+```javascript codeFormat="commonjs"
+const { t } = require("next-intlayer/server");
+
+const ServerComponentExample = () => (
+  <p>
+    {t({
+      en: "This is the content of a server component example",
+      fr: "Ceci est le contenu d'un exemple de composant serveur",
+      es: "Este es el conteúdo de un exemplo de componente servidor",
+      pt: "Este é o conteúdo de um exemplo de componente servidor",
+    })}
+  </p>
+);
+```
+
+### 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 paisagem bonita",
+    })}
+  />
+</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 type { IConfigLocales } from "intlayer";
+import { t } from "next-intlayer";
+
+const translations: IConfigLocales<string> = {
+  en: "Welcome",
+  fr: "Bienvenue",
+  es: "Bienvenido",
+  pt: "Bem-vindo",
+};
+
+const greeting = t(translations);
+```
+
+```javascript codeFormat="esm"
+import type { IConfigLocales } from "intlayer";
+import { t } from "next-intlayer";
+
+/** @type {import('next-intlayer').IConfigLocales<string>} */
+const translations = {
+  en: "Welcome",
+  fr: "Bienvenue",
+  es: "Bienvenido",
+  pt: "Bem-vindo",
+};
+
+const greeting = t(translations);
+```
+
+```javascript codeFormat="commonjs"
+const { t } = require("next-intlayer");
+
+/** @type {import('next-intlayer').IConfigLocales<string>} */
+const translations = {
+  en: "Welcome",
+  fr: "Bienvenue",
+  es: "Bienvenido",
+  pt: "Bem-vindo",
+};
+
+const greeting = t(translations);
+```
+
+### Detecção e Contexto de Idioma
+
+No `next-intlayer`, o idioma atual é gerenciado por meio de provedores de contexto: `IntlayerClientProvider` e `IntlayerServerProvider`. Certifique-se de que esses provedores envolvam seus componentes e que a propriedade `locale` seja passada corretamente.
+
+#### Exemplo:
+
+```tsx codeFormat="typescript"
+import type { FC } from "react";
+import type { Locales } from "intlayer";
+import { IntlayerClientProvider } from "next-intlayer";
+import { IntlayerServerProvider } from "next-intlayer/server";
+
+const Page: FC<{ locale: Locales }> = ({ locale }) => (
+  <IntlayerServerProvider locale={locale}>
+    <IntlayerClientProvider locale={locale}>
+      {/* Seus componentes aqui */}
+    </IntlayerClientProvider>
+  </IntlayerServerProvider>
+);
+```
+
+```javascript codeFormat="esm"
+import { IntlayerClientProvider } from "next-intlayer";
+import { IntlayerServerProvider } from "next-intlayer/server";
+
+const Page = ({ locale }) => (
+  <IntlayerServerProvider locale={locale}>
+    <IntlayerClientProvider locale={locale}>
+      {/* Seus componentes aqui */}
+    </IntlayerClientProvider>
+  </IntlayerServerProvider>
+);
+```
+
+```javascript codeFormat="commonjs"
+const { IntlayerClientProvider } = require("next-intlayer");
+const { IntlayerServerProvider } = require("next-intlayer/server");
+
+const Page = ({ locale }) => (
+  <IntlayerServerProvider locale={locale}>
+    <IntlayerClientProvider locale={locale}>
+      {/* Seus componentes aqui */}
+    </IntlayerClientProvider>
+  </IntlayerServerProvider>
+);
+```
+
+---
+
+## 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 `IntlayerClientProvider` ou `IntlayerServerProvider` está configurado corretamente com o `locale` apropriado.
+  - Certifique-se de que seu objeto de traduções inclua 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 [!code error]
+  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 [!code error]
+  pt: "Texto",
+};
+
+const text = t(translations);
+```
+
+```javascript codeFormat="commonjs"
+const { t } = require("next-intlayer");
+
+/** @type {import('next-intlayer').IConfigLocales<string>} */
+const translations = {
+  en: "Text",
+  fr: "Texte",
+  // es: 'Texto', // Ausência de 'es' causará um erro no TypeScript [!code error]
+  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. **Provisão Consistente de Idioma**: Certifique-se de que seu idioma seja fornecido consistentemente em toda a aplicação por meio dos provedores apropriados.
+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 `next-intlayer` é uma ferramenta poderosa e conveniente para gerenciar traduções inline em suas aplicações Next.js. Ao integrá-la de forma eficaz, você aprimora 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 next-intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/pt/intlayer_visual_editor.md).
+
+---
+
+**Nota**: Lembre-se de configurar corretamente seus `IntlayerClientProvider` e `IntlayerServerProvider` 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.