Skip to content

Commit

Permalink
i18n(pt-BR): Update imports.mdx and troubleshooting.mdx translati…
Browse files Browse the repository at this point in the history 
…ons (withastro#2411)
  • Loading branch information
@yanthomasdev
yanthomasdev authored Jan 24, 2023
1 parent ee31918 commit b0db05e
Show file tree
Hide file tree
Showing 3 changed files with 150 additions and 33 deletions.
2 changes: 1 addition & 1 deletion src/i18n/pt-br/nav.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ export default NavDictionary({
features: 'Guias',
'guides/styling': 'Estilização e CSS',
'core-concepts/framework-components': 'Frameworks de UI',
'guides/imports': 'Assets Estáticos',
'guides/imports': 'Importações',
'guides/integrations-guide': 'Integrações',
'guides/server-side-rendering': 'Renderização no lado do Servidor (SSR)',
'guides/data-fetching': 'Busca de Dados',
Expand Down
144 changes: 125 additions & 19 deletions src/pages/pt-br/guides/imports.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,18 +1,18 @@
---
layout: ~/layouts/MainLayout.astro
title: Assets Estáticos
title: Importações
description: Aprenda como importar diferentes tipos de conteúdo com Astro.
i18nReady: true
---

Astro suporta a maioria dos assets estáticos com zero configurações necessárias. Você pode usar a declaração `import` em qualquer lugar do seu projeto JavaScript (incluindo o script do "front matter" de seu componente Astro) e Astro irá incluir uma cópia otimizada do asset estático na build final do seu projeto. `@import` também é suportado dentro de CSS e tags `<style>`.
Astro suporta a maioria dos assets estáticos com zero configurações necessárias. Você pode usar a declaração `import` em qualquer lugar do seu projeto JavaScript (incluindo seu frontmatter Astro) e Astro irá incluir uma cópia otimizada do asset estático na build final do seu projeto. `@import` também é suportado dentro de CSS e tags `<style>`.

## Tipos de Arquivos Suportados

Os tipos de arquivos abaixo são suportados por padrão pelo Astro:

- Componentes Astro (`.astro`)
- Markdown (`.md`)
- Markdown (`.md`, `.markdown`, etc.)
- JavaScript (`.js`, `.mjs`)
- TypeScript (`.ts`, `.tsx`)
- Pacotes NPM
Expand All @@ -22,21 +22,27 @@ Os tipos de arquivos abaixo são suportados por padrão pelo Astro:
- Módulos CSS (`.module.css`)
- Imagens e Assets (`.svg`, `.jpg`, `.png`, etc.)

Se você não encontrou o tipo de asset que está procurando, veja a nossa [Biblioteca de Integrações](https://astro.build/integrations/). Você pode expandir o Astro para adicionar suporte a diferente tipos de arquivos, como componentes Svelte e Vue.
Adicionalmente, você pode estender o Astro para adicionar suporte a diferentes [Frameworks de UI](/pt-br/core-concepts/framework-components/) como componentes React, Svelte e Vue. Você também pode instalar a [integração MDX do Astro](/pt-br/guides/integrations-guide/mdx/) e utilizar arquivos `.mdx` em seu projeto.

Este guia detalha como os diferentes tipos de assets passam por build pelo Astro e como importá-los corretamente.

Lembre-se que você pode colocar qualquer asset estático no [diretório `public/`](/pt-br/core-concepts/project-structure/#public) do seu projeto e Astro irá copiá-los diretamente em sua build final. Arquivos do diretório `public/` não passam por build ou bundle por Astro, o que significa que qualquer tipo de arquivo é suportado. Você pode referenciar um arquivo do diretório `public/` por um caminho de URL diretamente em seus templates HTML.
### Arquivos em `public/`

## JavaScript
Você pode colocar qualquer asset estático no [diretório `public/`](/pt-br/core-concepts/project-structure/#public) do seu projeto, e o Astro irá copiá-lo diretamente em sua build final sem mudanças. Arquivos do diretório `public/` não passam por build ou bundle por Astro, o que significa que qualquer tipo de arquivo é suportado. Você pode referenciar um arquivo do diretório `public/` por um caminho de URL diretamente em seus templates HTML.

## Declarações de importação

Astro utiliza ESM, a mesma sintaxe de [`import`](https://developer.mozilla.org/pt-BR/docs/Web/JavaScript/Reference/Statements/import#sintaxe) e [`export`](https://developer.mozilla.org/pt-BR/docs/Web/JavaScript/Reference/Statements/export#sintaxe) suportada no navegador.

### JavaScript

```js
import { getUsuario } from './usuario.js';
```

JavaScript pode ser importado usando a sintaxe normal de ESM `import` e `export`. Isto funciona como o esperado, baseado no comportamento padrão do Node.js e do Browser.
JavaScript pode ser importado usando a sintaxe de `import` e `export` normal do ESM.

## TypeScript
### TypeScript

```js
import { getUsuario } from './usuario';
Expand All @@ -59,7 +65,7 @@ import MeuComponente from "./MeuComponente"; // MeuComponente.tsx

📚 Leia mais sobre o [suporte para TypeScript no Astro](/pt-br/guides/typescript/).

## JSX / TSX
### JSX / TSX

```js
import { MeuComponente } from './MeuComponente.jsx';
Expand All @@ -73,17 +79,23 @@ Apesar do Astro entender a sintaxe JSX por padrão, você deverá incluir a inte
**Astro não dá suporte à JSX em arquivos `.js`/`.ts`**. JSX será manipulado apenas dentro de arquivos que terminam com as extensões `.jsx` ou `.tsx`.
:::

## Pacotes NPM
### Pacotes do NPM

```js
// Importa os pacotes npm React e React-DOM
import React from 'react';
import ReactDOM from 'react-dom';
Se você instalou um pacote do NPM, você pode importá-lo no Astro.

```astro
---
import { Icon } from 'astro-icon';
---
```

Astro permite que você importe pacotes NPM diretamente no navegador. Mesmo se um pacote foi publicado usando um formato legado, Astro irá convertê-lo para ESM antes de servi-lo ao navegador.
Se um pacote foi publicado em um formato antigo, Astro irá tentar converter o pacote para ESM para que então declarações de `import` funcionem. Em alguns casos, você pode precisar ajustar sua [configuração do `vite`](/pt-br/reference/configuration-reference/#vite) para que ele funcione.

## JSON
:::caution
Alguns pacotes dependem de um ambiente de navegador. Componentes Astro são executados no servidor, então importar esses pacotes no frontmatter pode [levar a erros](/pt-br/guides/troubleshooting/#document-or-window-is-not-defined).
:::

### JSON

```js
// Carrega o objeto JSON pelo "export" padrão.
Expand All @@ -92,7 +104,7 @@ import json from './dados.json';

Astro dá suporte para a importação de arquivos JSON diretamente em sua aplicação. Arquivos importados retornam o objeto JSON completo no `import` padrão.

## CSS
### CSS

```js
// Carrega e injeta o arquivo 'estilos.css' na página
Expand All @@ -101,7 +113,7 @@ import './estilos.css';

Astro suporta a importação de arquivos CSS diretamente em sua aplicação. Estilos importados não proveem nenhum "export", mas importar um arquivo CSS irá automaticamente adicionar seus estilos à página. Isto funciona para todos os arquivos CSS por padrão e pode suportar também pré-processadores como Sass e Less via plugins.

## Módulos CSS
### Módulos CSS

```jsx
// 1. Converte os nomes das classes de `./estilos.module.css` para valores únicos e escopados.
Expand All @@ -115,7 +127,7 @@ Astro suporta Módulos CSS usando a convenção de nome `[nome].module.css`. Com

Módulos CSS ajudam a reforçar o escopo e o isolamento de componentes no frontend com nomes de classes únicos gerados para suas folhas de estilos.

## Outros Assets
### Outros Assets

```jsx
import referenciaImg from './imagem.png'; // referenciaImg === '/src/imagem.png'
Expand All @@ -134,6 +146,62 @@ Também pode ser útil colocar as imagens no diretório `public/` como explicado
Adicionar **texto alternativo** a tags `<img>` é encorajado por acessibilidade! Não se esqueça de adicionar um atributo `alt="uma descrição útil"` para seus elementos de imagem. Você pode deixar o atributo vazio se a imagem for puramente decorativa.
:::

## `Astro.glob()`

[`Astro.glob()`](/pt-br/reference/api-reference/#astroglob) é uma forma de importar vários arquivos de uma vez.

`Astro.glob()` apenas recebe um parâmetro: um [padrão de glob relativo](/pt-br/guides/imports/#padrões-de-glob) correspondendo aos arquivos locais que você gostaria de importar. É assíncrono, e retorna um array com as exportações de cada arquivo correspondente.

```astro title="src/components/meu-componente.astro"
---
// importa todos os arquivos que terminam com `.md` em `./src/pages/postagens/`
const postagens = await Astro.glob('../pages/postagens/*.md');
---
<!-- Renderiza um <article> para as 5 primeiras postagens do blog -->
<div>
{postagens.slice(0, 4).map((postagem) => (
<article>
<h1>{postagem.frontmatter.titulo}</h1>
<p>{postagem.frontmatter.descricao}</p>
<a href={postagem.url}>Leia mais</a>
</article>
))}
</div>
```

Componentes Astro importados com `Astro.glob` são do tipo [`AstroInstance`](/pt-br/reference/api-reference/#arquivos-astro). Você pode renderizar cada instância de componente usando sua propriedade `default`:

```astro title="src/pages/component-library.astro" {8}
---
// importa todos os arquivos que terminam com `.astro` em `./src/components/`
const componentes = await Astro.glob('../components/*.astro');
---
<!-- Mostra todos os nossos componentes -->
{componentes.map((componente) => (
<div>
<componente.default size={24} />
</div>
))}
```

### Padrões de Glob

Um padrão de glob é um caminho de arquivo que suporta caracteres curinga especiais. Eles são usados para referenciar múltiplos arquivos em seu projeto de uma vez.

Por exemplo, o padrão de glob `./pages/**/*.{md,mdx}` começa no subdiretório "pages", vendo através de todos os seus subdiretórios (`/**`), e corresponde a qualquer nome de arquivo (`/*`) que termine em `.md` ou `.mdx` (`.{md,mdx}`).

#### Padrões de Glob no Astro

Para utilizar com `Astro.glob()`, o padrão de glob precisa ser uma string literal e não pode conter nenhuma variável. Veja [o guia de solução de problemas](/pt-br/guides/troubleshooting/#astroglob---no-matches-found) para uma solução alternativa.

Adicionalmente, padrões de glob devem começar com um dos seguintes:
- `./` (para começar no diretório atual)
- `../` (para começar no diretório parente)
- `/` (para começar na raiz do projeto)


[Leia mais sobre a sintaxe de padrões de glob](https://github.com/mrmlnc/fast-glob#pattern-syntax).

## WASM

```js
Expand Down Expand Up @@ -161,3 +229,41 @@ const dados = JSON.parse(json);
---
<span>Versão: {dados.version}</span>
```

## Estendendo suporte de tipos de arquivo

Com plugins **Vite** e **Rollup** compatíveis, você pode importar tipos de arquivos que não são nativamente suportados pelo Astro. Para como encontrar os plugins que você precisa na seção [Finding Plugins](https://vitejs.dev/guide/using-plugins.html#finding-plugins) da documentação do Vite.


:::note[configuração de plugins]
Use a documentação do seu plugin como referência para opções de configuração e como corretamente instalá-lo.
:::

### Exemplo: suporte para YAML

O formato de dados YAML (`.yml`) não é nativamente suportado pelo Astro, mas você pode adicionar suporte para ele ao usar um plugin compatível do Rollup como [`@rollup/plugin-yaml`](https://www.npmjs.com/package/@rollup/plugin-yaml):

1. Instale `@rollup/plugin-yaml`:

```bash
npm install @rollup/plugin-yaml --save-dev
```

2. Importe o plugin em seu `astro.config.mjs` e adicione-o ao array de plugins do Vite:

```js title="astro.config.mjs" ins={2,5-7}
import { defineConfig } from 'astro/config';
import yaml from '@rollup/plugin-yaml';
export default defineConfig({
vite: {
plugins: [yaml()]
}
});
```


3. Finalmente, você pode importar dados YAML usando uma declaração de `import`:

```js
import yml from './data.yml';
```
37 changes: 24 additions & 13 deletions src/pages/pt-br/guides/troubleshooting.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,24 +21,21 @@ Em componentes Astro, tags `<script>` são movidas para o topo do escopo (hoiste

**Não tem certeza se este é o seu problema?** Verifique nossas issues e veja se mais alguém reportou [esse problema](https://github.com/withastro/astro/issues?q=is%3Aissue+is%3Aopen+Cannot+use+import+statement)!

### Unable to render component
### `document` (or `window`) is not defined

Isto indica um erro em um componente que você importou e está utilizando no seu template Astro.
Esse erro ocorre ao tentar acessar `document` ou `window` no servidor.

#### Causa comum
Componentes Astro são executados no servidor, então você não pode acessar esses objetos específicos do navegador dentro do frontmatter.

Isto pode ser causado por tentar acessar o objeto `window` ou `document` em tempo de renderização. Por padrão, Astro irá renderizar seu componente [isomorficamente](https://en.wikipedia.org/wiki/Isomorphic_JavaScript), o que significa que ele será executado no servidor, onde o runtime do navegador não está disponível. Você pode desabilitar essa etapa de pré-renderização utilizando [a diretiva `client:only`](/pt-br/reference/directives-reference/#clientonly).
Componentes de frameworks são executados no servidor por padrão, então esse erro pode ocorrer ao acessar `document` ou `window` durante a renderização.

**Solução**: Tente acessar esses objetos após a renderização (ex: [`useEffect()`](https://reactjs.org/docs/hooks-reference.html#useeffect) no React ou [`onMounted()`](https://vuejs.org/api/composition-api-lifecycle.html#onmounted) no Vue e [`onMount()`](https://svelte.dev/docs#run-time-svelte-onmount) no Svelte).
**Solução**: Determine o código que chama `document` ou `window`. Se você não estiver utilizando `document` ou `window` diretamente e ainda está recebendo esse erro, verifique para ver se algum pacote que você está importando foi feito para ser executado no cliente.

**Status**: Comportamento esperado do Astro, como pretendido.

#### Não é isso?

**Solução**: Verifique a documentação apropriada do seu componente [Astro](/pt-br/core-concepts/astro-components/) ou a do seu [framework de UI](/pt-br/core-concepts/framework-components/). Considere abrir um dos templates iniciais do Astro em [astro.new](https://astro.new) e tente solucionar o problema do seu componente em um projeto Astro mínimo.
- Se o código está em um componente Astro, mova-o para uma tag `<script>` fora do frontmatter. Isso diz ao Astro para executar esse código no cliente, onde `document` e `window` estão disponíveis.

**Não tem certeza se este é o seu problema?** Verifique nossas issues e veja se mais alguém reportou [esse problema](https://github.com/withastro/astro/issues?q=is%3Aissue+is%3Aopen+Unable+to+render+Component)!
- Se o código está em um componente de framework, tente acessar esses objetos após renderizar usando métodos de lifecycle (e.x. [`useEffect()`](https://reactjs.org/docs/hooks-reference.html#useeffect) no React, [`onMounted()`](https://vuejs.org/api/composition-api-lifecycle.html#onmounted) no Vue e [`onMount()`](https://svelte.dev/docs#run-time-svelte-onmount) no Svelte). Você também pode prevenir o componente de ser renderizado no servidor ao adicionar a diretiva [`client:only`](/pt-br/reference/directives-reference/#clientonly).

**Status**: Comportamento esperado do Astro, como pretendido.

### Expected a default export

Expand All @@ -48,6 +45,16 @@ Este erro pode ser lançado ao tentar importar ou renderizar um componente invá

**Status**: Comportamento esperado do Astro, como pretendido.

### Refused to execute inline script

Você pode ver o seguinte erro no log do console do navegador:

> Refused to execute inline script because it violates the following Content Security Policy directive: …
Isso significa que a [Política de Segurança de Conteúdo](https://developer.mozilla.org/pt-BR/docs/Web/HTTP/CSP) (CSP) do seu site desativou a exeução de tags `<script>` inline, que o Astro gera por padrão.

**Solução:** Atualize sua CSP para incluir `script-src: 'unsafe-inline'` para permitir que scripts inline sejam executados.

## Pegadinhas comuns

### Meu componente não está sendo renderizado
Expand Down Expand Up @@ -120,12 +127,16 @@ const minhaPostagemDestacada = postagens.find(post => post.file.includes(caminho

### Utilizando Astro com Yarn 2+ (Berry)

Yarn 2+, também conhecido como Berry, utiliza uma técnica chamada [Plug'n'Play (PnP)](https://yarnpkg.com/features/pnp) para armazenar e gerenciar módulos Node e que pode [causar problemas](https://github.com/withastro/astro/issues/3450) durante a inicialização de um novo projeto Astro utilizando `create-astro` ou enquanto você trabalha com Astro. Uma solução para este problema é definir a [propriedade `nodeLinker`](https://yarnpkg.com/configuration/yarnrc#nodeLinker) em `yarnrc.yml` para `node-modules`:
Yarn 2+, também conhecido como Berry, utiliza uma técnica chamada [Plug'n'Play (PnP)](https://yarnpkg.com/features/pnp) para armazenar e gerenciar módulos Node e que pode [causar problemas](https://github.com/withastro/astro/issues/3450) durante a inicialização de um novo projeto Astro utilizando `create astro` ou enquanto você trabalha com Astro. Uma solução para este problema é definir a [propriedade `nodeLinker`](https://yarnpkg.com/configuration/yarnrc#nodeLinker) em `.yarnrc.yml` para `node-modules`:

```yaml
```yaml title=".yarnrc.yml"
nodeLinker: "node-modules"
```
### Utilizando `<head>` em um componente

No Astro, utilizar uma tag `<head>` funciona como qualquer outra tag HTML: ela não é movida para o topo da página ou combinada com a `<head>` existente. Por causa disso, você geralmente apenas quer incluir uma tag `<head>` pela a página. Nós recomendamos escrever aquela única `<head>` e seus conteúdos em um [componente de layout](/pt-br/core-concepts/layouts/).

## Dicas e truques

### Depurando com `console.log()`
Expand Down

0 comments on commit b0db05e

Please sign in to comment.