@intlayer/docs 8.7.6 → 8.7.8-canary.0

package/docs/pt/intlayer_with_astro.md

@@ -1,11 +1,11 @@
 ---
 createdAt: 2024-03-07
 updatedAt: 2025-12-30
-title: Astro i18n - Como traduzir uma aplicação Astro em 2026
-description: Aprenda como adicionar internacionalização (i18n) ao seu site Astro usando Intlayer. Siga este guia para tornar seu site multilíngue.
+title: Tradução do Astro i18n - Como traduzir uma aplicação Astro em 2026
+description: Aprenda como adicionar internacionalização (i18n) ao seu site Astro com o Intlayer. Siga este guia para tornar seu site multilíngue.
 keywords:
-  - Internacionalização
-  - Documentação
+  - internacionalização
+  - documentação
   - Intlayer
   - Vite
   - React
@@ -16,65 +16,95 @@ slugs:
   - environment
   - astro
 applicationTemplate: https://github.com/aymericzip/intlayer-astro-template
+applicationShowcase: https://intlayer-astro-template.vercel.app
 history:
   - version: 7.5.9
     date: 2025-12-30
-    changes: "Adicionar comando init"
+    changes: "Adicionado comando init"
   - version: 6.2.0
     date: 2025-10-03
-    changes: "Atualização para integração com Astro, configuração, uso"
+    changes: "Atualização da integração do Astro, configuração e uso"
 ---
 
-# Traduza seu Astro com Intlayer | Internacionalização (i18n)
+# Traduza o seu site Astro com o Intlayer | Internacionalização (i18n)
 
-Veja o [Modelo de Aplicação](https://github.com/aymericzip/intlayer-astro-template) no GitHub.
+<Tabs defaultTab="code">
+  <Tab label="Código" value="code">
 
-## O que é Intlayer?
+<iframe
+  src="https://ide.intlayer.org/aymericzip/intlayer-astro-template?file=intlayer.config.ts"
+  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
+  title="Demo CodeSandbox - Como internacionalizar sua aplicação com o Intlayer"
+  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+  loading="lazy"
+/>
 
-**Intlayer** é uma biblioteca inovadora e open-source de internacionalização (i18n) projetada para simplificar o suporte multilíngue em aplicações web modernas.
+  </Tab>
+  <Tab label="Demo" value="demo">
+
+<iframe
+  src="https://intlayer-astro-template.vercel.app"
+  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
+  title="Demo — intlayer-astro-template"
+  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+  loading="lazy"
+/>
+
+  </Tab>
+</Tabs>
+
+## Índice
+
+<TOC/>
+
+## O que é o Intlayer?
+
+**Intlayer** é uma biblioteca de internacionalização (i18n) inovadora e de código aberto projetada para simplificar o suporte multilíngue em aplicações web modernas.
 
 Com o Intlayer, você pode:
 
-- **Gerenciar traduções facilmente** usando dicionários declarativos no nível do componente.
-- **Localizar dinamicamente metadados**, rotas e conteúdo.
-- **Garantir suporte ao TypeScript** com tipos autogerados, melhorando o autocompletar e a detecção de erros.
-- **Aproveitar recursos avançados**, como detecção e troca dinâmica de localidade.
+- **Gerenciar traduções facilmente**: Usando dicionários declarativos ao nível do componente.
+- **Localizar metadados, rotas e conteúdo dinamicamente**.
+- **Garantir suporte TypeScript**: Com tipos gerados automaticamente para melhor preenchimento automático e detecção de erros.
+- **Beneficiar de recursos avançados**: Como detecção dinâmica de idioma e troca de idioma.
 
 ---
 
-## Guia Passo a Passo para Configurar o Intlayer no Astro
+## Guia passo a passo para configurar o Intlayer no Astro
+
+Confira o [modelo da aplicação](https://github.com/aymericzip/intlayer-astro-template) no GitHub.
 
 ### Passo 1: Instalar Dependências
 
-Instale os pacotes necessários usando seu gerenciador de pacotes:
+Instale os pacotes necessários usando seu gerenciador de pacotes preferido:
 
 ```bash packageManager="npm"
 npm install intlayer astro-intlayer
-# Opcional: adicionar suporte a React island
+# Opcional: Se você adicionar suporte para islands do React
 npm install react react-dom react-intlayer @astrojs/react
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer astro-intlayer
-# Opcional: adicionar suporte a React island
+# Opcional: Se você adicionar suporte para islands do React
 pnpm add react react-dom react-intlayer @astrojs/react
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer astro-intlayer
-# Opcional: adicionar suporte a React island
+# Opcional: Se você adicionar suporte para islands do React
 yarn add react react-dom react-intlayer @astrojs/react
 ```
 
 - **intlayer**
-  O pacote principal que fornece ferramentas de internacionalização para gerenciamento de configuração, tradução, [declaração de conteúdo](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dictionary/content_file.md), transpiração e [comandos CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/cli/index.md).
+  O pacote principal que fornece ferramentas de i18n para gerenciamento de configuração, traduções, [declaração de conteúdo](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dictionary/content_file.md), transpilação e [comandos CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/cli/index.md).
 
 - **astro-intlayer**
-  Inclui o plugin de integração do Astro para integrar o Intlayer com o [empacotador Vite](https://vite.dev/guide/why.html#why-bundle-for-production), assim como middleware para detectar o idioma preferido do usuário, gerenciar cookies e lidar com redirecionamento de URL.
+  Inclui o plugin de integração do Astro para vincular o Intlayer ao [bundler Vite](https://vite.dev/guide/why.html#why-bundle-for-production), bem como o middleware para detectar o idioma preferido do usuário, gerenciar cookies e lidar com redirecionamentos de URL.
 
-### Passo 2: Configuração do seu projeto
+### Passo 2: Configurar seu Projeto
 
-Crie um arquivo de configuração para configurar os idiomas da sua aplicação:
+Crie um arquivo de configuração para definir os idiomas da sua aplicação:
 
 ```typescript fileName="intlayer.config.ts"
 import { Locales, type IntlayerConfig } from "intlayer";
@@ -85,6 +115,7 @@ const config: IntlayerConfig = {
       Locales.ENGLISH,
       Locales.FRENCH,
       Locales.SPANISH,
+      Locales.PORTUGUESE,
       // Seus outros idiomas
     ],
     defaultLocale: Locales.ENGLISH,
@@ -94,11 +125,11 @@ const config: IntlayerConfig = {
 export default config;
 ```
 
-> Através deste arquivo de configuração, você pode configurar URLs localizadas, redirecionamento via middleware, nomes de cookies, a localização e extensão das suas declarações de conteúdo, desabilitar logs do Intlayer no console, e muito mais. Para uma lista completa dos parâmetros disponíveis, consulte a [documentação de configuração](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/configuration.md).
+> Através deste arquivo de configuração, você pode configurar URLs localizadas, redirecionamentos de middleware, nomes de cookies, localização e extensões de declarações de conteúdo, desativar logs do Intlayer no console e muito mais. Para uma lista completa de parâmetros disponíveis, consulte a [documentação de configuração](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/configuration.md).
 
-### Passo 3: Integre o Intlayer na sua Configuração do Astro
+### Passo 3: Integrar o Intlayer na sua configuração do Astro
 
-Adicione o plugin intlayer na sua configuração.
+Adicione o plugin `intlayer` à sua configuração do Astro.
 
 ```typescript fileName="astro.config.ts"
 // @ts-check
@@ -112,9 +143,9 @@ export default defineConfig({
 });
 ```
 
-> O plugin de integração `intlayer()` para Astro é usado para integrar o Intlayer com o Astro. Ele garante a construção dos arquivos de declaração de conteúdo e os monitora no modo de desenvolvimento. Define variáveis de ambiente do Intlayer dentro da aplicação Astro. Além disso, fornece aliases para otimizar o desempenho.
+> O plugin de integração `intlayer()` é usado para integrar o Intlayer ao Astro. Ele garante a geração dos arquivos de declaração de conteúdo e os monitora em modo de desenvolvimento. Ele define variáveis de ambiente do Intlayer dentro da aplicação Astro e fornece aliases para otimizar o desempenho.
 
-### Passo 4: Declare Seu Conteúdo
+### Passo 4: Declarar seu conteúdo
 
 Crie e gerencie suas declarações de conteúdo para armazenar traduções:
 
@@ -129,6 +160,7 @@ const appContent = {
       en: "Hello World",
       fr: "Bonjour le monde",
       es: "Hola mundo",
+      pt: "Olá Mundo",
     }),
   },
 } satisfies Dictionary;
@@ -136,16 +168,15 @@ const appContent = {
 export default appContent;
 ```
 
-> Suas declarações de conteúdo podem ser definidas em qualquer lugar da sua aplicação, desde que estejam incluídas no diretório `contentDir` (por padrão, `./src`). E correspondam à extensão do arquivo de declaração de conteúdo (por padrão, `.content.{json,ts,tsx,js,jsx,mjs,cjs}`).
+> As declarações de conteúdo podem ser definidas em qualquer lugar da sua aplicação, desde que estejam incluídas no `contentDir` (por padrão `./src`) e correspondam à extensão do arquivo de declaração de conteúdo (por padrão `.content.{json,ts,tsx,js,jsx,mjs,cjs}`).
 
-> Para mais detalhes, consulte a [documentação de declaração de conteúdo](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dictionary/content_file.md).
+> Para mais informações, consulte a [documentação de declaração de conteúdo](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dictionary/content_file.md).
 
-### Passo 5: Use seu conteúdo no Astro
+### Passo 5: Usar o conteúdo no Astro
 
-Você pode consumir dicionários diretamente em arquivos `.astro` usando os helpers principais exportados pelo `intlayer`.
+Você pode consumir os dicionários diretamente nos seus arquivos `.astro` usando os ajudantes principais exportados do `intlayer`.
 
 ```astro fileName="src/pages/index.astro"
-<!-- astro -->
 ---
 import { getIntlayer } from "intlayer";
 import appContent from "../app.content";
@@ -153,7 +184,7 @@ import appContent from "../app.content";
 const { title } = getIntlayer('app');
 ---
 
-<html lang="en">
+<html lang="pt">
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width" />
@@ -165,12 +196,11 @@ const { title } = getIntlayer('app');
 </html>
 ```
 
-### Passo 6: Roteamento localizado
+### Passo 6: Roteamento Localizado
 
-Crie um segmento de rota dinâmica para servir páginas localizadas, por exemplo `src/pages/[locale]/index.astro`:
+Crie segmentos de rota dinâmicos para servir páginas localizadas (por exemplo, `src/pages/[locale]/index.astro`):
 
 ```astro fileName="src/pages/[locale]/index.astro"
-<!-- astro -->
 ---
 import { getIntlayer } from "intlayer";
 
@@ -180,11 +210,11 @@ const { title } = getIntlayer('app');
 <h1>{title}</h1>
 ```
 
-A integração do Astro adiciona um middleware Vite durante o desenvolvimento que ajuda com o roteamento consciente de localidade e definições de ambiente. Você ainda pode criar links entre localidades usando sua própria lógica, ou funções utilitárias como `getLocalizedUrl` do `intlayer`.
+A integração do Astro adiciona um middleware Vite que ajuda no roteamento sensível ao idioma e nas definições de ambiente durante o desenvolvimento. Você também pode criar links entre idiomas usando sua própria lógica ou ferramentas do `intlayer`, como o `getLocalizedUrl`.
 
-### Passo 7: Continue usando seu framework favorito
+### Passo 7: Continuar usando seus frameworks favoritos
 
-Continue usando seu framework favorito para construir sua aplicação.
+Continue construindo sua aplicação usando o framework de sua escolha.
 
 - Intlayer + React: [Intlayer com React](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_with_vite+react.md)
 - Intlayer + Vue: [Intlayer com Vue](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_with_vite+vue.md)
@@ -192,56 +222,152 @@ Continue usando seu framework favorito para construir sua aplicação.
 - Intlayer + Solid: [Intlayer com Solid](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_with_vite+solid.md)
 - Intlayer + Preact: [Intlayer com Preact](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_with_vite+preact.md)
 
-### Configurar TypeScript
+### Configuração do TypeScript
 
-Intlayer usa a ampliação de módulos para obter os benefícios do TypeScript e tornar sua base de código mais robusta.
+O Intlayer usa o aumento de módulos (module augmentation) para aproveitar o TypeScript, tornando sua base de código mais robusta.
 
-![Autocompletion](https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png?raw=true)
+![Preenchimento automático](https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png?raw=true)
 
-![Translation error](https://github.com/aymericzip/intlayer/blob/main/docs/assets/translation_error.png?raw=true)
+![Erro de tradução](https://github.com/aymericzip/intlayer/blob/main/docs/assets/translation_error.png?raw=true)
 
 Certifique-se de que sua configuração do TypeScript inclua os tipos gerados automaticamente.
 
 ```json5 fileName="tsconfig.json"
 {
-  // ... Suas configurações existentes do TypeScript
+  // ... sua configuração existente do TypeScript
   "include": [
-    // ... Suas configurações existentes do TypeScript
-    ".intlayer/**/*.ts", // Inclua os tipos gerados automaticamente
+    // ... sua configuração existente do TypeScript
+    ".intlayer/**/*.ts", // Incluir tipos gerados automaticamente
   ],
 }
 ```
 
 ### Configuração do Git
 
-É recomendado ignorar os arquivos gerados pelo Intlayer. Isso permite evitar que eles sejam commitados no seu repositório Git.
+Recomenda-se ignorar os arquivos gerados pelo Intlayer. Isso evita committá-los no seu repositório Git.
 
-Para isso, você pode adicionar as seguintes instruções ao seu arquivo `.gitignore`:
+Para fazer isso, adicione as seguintes instruções ao seu arquivo `.gitignore`:
 
 ```bash
-#  Ignorar os arquivos gerados pelo Intlayer
+# Ignorar os arquivos gerados pelo Intlayer
 .intlayer
 ```
 
 ### Extensão do VS Code
 
-Para melhorar sua experiência de desenvolvimento com o Intlayer, você pode instalar a **Extensão oficial do Intlayer para VS Code**.
+Para melhorar sua experiência de desenvolvimento com o Intlayer, você pode instalar a **extensão oficial do Intlayer para VS Code**.
 
-[Instalar no Marketplace do VS Code](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
+[Instalação pelo VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
 
-Esta extensão oferece:
+Esta extensão fornece:
 
-- **Autocompletar** para chaves de tradução.
+- **Preenchimento automático** para chaves de tradução.
 - **Detecção de erros em tempo real** para traduções ausentes.
-- **Visualizações inline** do conteúdo traduzido.
+- **Visualização inline** do conteúdo traduzido.
 - **Ações rápidas** para criar e atualizar traduções facilmente.
 
-Para mais detalhes sobre como usar a extensão, consulte a [documentação da Extensão Intlayer para VS Code](https://intlayer.org/doc/vs-code-extension).
+Para mais informações sobre o uso da extensão, consulte a [documentação da Extensão do VS Code](https://intlayer.org/doc/vs-code-extension).
 
 ---
 
-### Ir Além
+### (Opcional) Passo 15: Extrair o conteúdo dos seus componentes
+
+Se você tiver uma base de código existente, transformar milhares de arquivos pode ser demorado.
+
+Para facilitar esse processo, o Intlayer propõe um [compilador](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/compiler.md) / [extrator](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/cli/extract.md) para transformar seus componentes e extrair o conteúdo.
+
+Para configurá-lo, você pode adicionar uma seção `compiler` no seu arquivo `intlayer.config.ts`:
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import { type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  // ... Resto da sua configuração
+  compiler: {
+    /**
+     * Indica se o compilador deve ser ativado.
+     */
+    enabled: true,
+
+    /**
+     * Define o caminho dos arquivos de saída
+     */
+    output: ({ fileName, extension }) => `./${fileName}${extension}`,
+
+    /**
+     * Indica se os componentes devem ser salvos após serem transformados. Dessa forma, o compilador pode ser executado apenas uma vez para transformar o aplicativo e depois removido.
+     */
+    saveComponents: false,
+
+    /**
+     * Prefixo da chave do dicionário
+     */
+    dictionaryKeyPrefix: "",
+  },
+};
+
+export default config;
+```
+
+<Tabs>
+ <Tab value='Comando de extração'>
+
+Execute o extrator para transformar seus componentes e extrair o conteúdo
+
+```bash packageManager="npm"
+npx intlayer extract
+```
+
+```bash packageManager="pnpm"
+pnpm intlayer extract
+```
+
+```bash packageManager="yarn"
+yarn intlayer extract
+```
+
+```bash packageManager="bun"
+bun x intlayer extract
+```
+
+ </Tab>
+ <Tab value='Compilador Babel'>
+
+Atualize seu `vite.config.ts` para incluir o plugin `intlayerCompiler`:
+
+```ts fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { intlayer, intlayerCompiler } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [
+    intlayer(),
+    intlayerCompiler(), // Adiciona o plugin do compilador
+  ],
+});
+```
+
+```bash packageManager="npm"
+npm run build # Ou npm run dev
+```
 
-Para ir além, você pode implementar o [editor visual](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_visual_editor.md) ou externalizar seu conteúdo usando o [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_CMS.md).
+```bash packageManager="pnpm"
+pnpm run build # Or pnpm run dev
+```
+
+```bash packageManager="yarn"
+yarn build # Or yarn dev
+```
+
+```bash packageManager="bun"
+bun run build # Or bun run dev
+```
+
+ </Tab>
+</Tabs>
 
 ---
+
+### Aprofunde seu conhecimento
+
+Se quiser saber mais, você também pode implementar o [Editor Visual](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_visual_editor.md) ou usar o [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_CMS.md) para externalizar seu conteúdo.