i18n(pt-BR): Translate `customization.mdx` (#511)

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

1 files changed, 416 insertions, 0 deletions

diff --git a/docs/src/content/docs/pt-br/guides/customization.mdx b/docs/src/content/docs/pt-br/guides/customization.mdx
new file mode 100644
index 00000000..917046a2
--- /dev/null
+++ b/docs/src/content/docs/pt-br/guides/customization.mdx
@@ -0,0 +1,416 @@
+---
+title: Customizando Starlight
+description: Aprenda como fazer seu site Starlight único com sua própria logo, fontes customizadas, design de página inicial e mais.
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+import FileTree from '../../../../components/file-tree.astro';
+
+Starlight providencia uma estilização e funcionalidades sensíveis padrões, para que você inicie rapidamente sem nenhuma configuração necessária.
+
+Quando você quiser começar a customizar a aparência e sensação do seu site Starlight, este guia tem tudo o que você precisa.
+
+## Adicione sua logo
+
+Adicionar uma logo customizada ao cabeçalho do site é uma forma rápida de adicionar sua marca individual a um site Starlight.
+
+1. Adicione o arquivo de imagem da sua logo para o diretório `src/assets/`:
+
+   <FileTree>
+
+   - src/
+     - assets/
+       - **minha-logo.svg**
+     - content/
+   - astro.config.mjs
+
+   </FileTree>
+
+2. Adicione o caminho para sua logo como a opção [`logo.src`](/pt-br/reference/configuration/#logo) do Starlight em `astro.config.mjs`:
+
+   ```js
+   // astro.config.mjs
+   import { defineConfig } from 'astro/config';
+   import starlight from '@astrojs/starlight';
+
+   export default defineConfig({
+   	integrations: [
+   		starlight({
+   			title: 'Documentação com Minha Logo',
+   			logo: {
+   				src: './src/assets/minha-logo.svg',
+   			},
+   		}),
+   	],
+   });
+   ```
+
+Por padrão, a logo será mostrada ao lado do `title` do seu site.
+Se sua imagem da logo já inclui o título do site, você pode esconder o texto do título visualmente ao definir a opção `replacesTitle`.
+O texto do `title` ainda será incluido para leitores de tela para que o cabeçalho continue acessível.
+
+```js
+starlight({
+  title: 'Documentação com Minha Logo',
+  logo: {
+    src: './src/assets/minha-logo.svg',
+    replacesTitle: true,
+  },
+}),
+```
+
+### Variantes clara e escura da logo
+
+Você pode mostrar diferentes versões da sua logo no modo claro e escuro.
+
+1. Adicione um arquivo de imagem para cada variante em `src/assets/`:
+
+   <FileTree>
+
+   - src/
+     - assets/
+       - **logo-clara.svg**
+       - **logo-escura.svg**
+     - content/
+   - astro.config.mjs
+
+   </FileTree>
+
+2. Adicione o caminho para suas variantes da logo como as opções `light` e `dark` ao invés de `src` em `astro.config.mjs`:
+
+   ```js
+   starlight({
+     title: 'Documentação com Minha Logo',
+     logo: {
+       light: './src/assets/logo-clara.svg',
+       dark: './src/assets/logo-escura.svg',
+     },
+   }),
+   ```
+
+## Layout da página
+
+Por padrão, páginas do Starlight usam um layout com uma barra de navegação lateral global e um índice que mostra os cabeçalhos da página atual.
+
+Você pode aplicar um layout de página maior sem barras laterais definindo [`template: splash`](/pt-br/reference/frontmatter/#template) no frontmatter de uma página.
+Isso funciona particularmente bem para páginas iniciais e você pode vê-lo em ação na [página inicial deste site](/pt-br/).
+
+```md
+---
+# src/content/docs/index.md
+
+title: Minha Página Inicial
+template: splash
+---
+```
+
+## Índice
+
+Starlight mostra um índice para cada página para tornar mais fácil para leitores pularem ao cabeçalho no qual estão procurando.
+Você pode customizar - ou até desabilitar - o índice globalmente na integração Starlight ou página a página no frontmatter.
+
+Por padrão, cabeçalhos `<h2>` e `<h3>` são inclusos no índice. Modifique quais níveis de cabeçalho incluir ao redor do site utilizando as opções `minHeadingLevel` e `maxHeadingLevel` na [global `tableOfContents`](/pt-br/reference/configuration/#tableofcontents). Sobrescreva esses padrões em uma página individual adicionando as propriedades correspondentes do [frontmatter `tableOfContents`](/pt-br/reference/frontmatter/#tableofcontents):
+
+<Tabs>
+  <TabItem label="Frontmatter">
+
+```md
+---
+# src/content/docs/exemplo.md
+title: Página com apenas H2s no índice
+tableOfContents:
+  minHeadingLevel: 2
+  maxHeadingLevel: 2
+---
+```
+
+  </TabItem>
+  <TabItem label="Configuração global">
+
+```js
+// astro.config.mjs
+
+defineConfig({
+	integrations: [
+		starlight({
+			title: '',
+			tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 2 },
+		}),
+	],
+});
+```
+
+  </TabItem>
+</Tabs>
+
+Desabilite o índice completamente definindo a opção `tableOfContents` como `false`:
+
+<Tabs>
+  <TabItem label="Frontmatter">
+
+```md
+---
+# src/content/docs/exemplo.md
+title: Página sem um índice
+tableOfContents: false
+---
+```
+
+  </TabItem>
+  <TabItem label="Configuração global">
+
+```js
+// astro.config.mjs
+
+defineConfig({
+	integrations: [
+		starlight({
+			title: 'Documentação com um índice desabilitado globalmente',
+			tableOfContents: false,
+		}),
+	],
+});
+```
+
+  </TabItem>
+</Tabs>
+
+## Links de redes sociais
+
+Starlight tem suporte integrado para adicionar links de suas contas de redes sociais ao cabeçalho do site através da opção [`social`](/pt-br/reference/configuration/#social) na integração Starlight.
+
+Atualmente, links para Bitbucket, Codeberg, CodePen, Discord, GitHub, GitLab, Gitter, LinkedIn, Mastodon, Microsoft Teams, Threads, Twitch, Twitter e Youtube são suportados.
+Nos avise no GitHub ou Discord se você precisa de suporte para outro serviço!
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+
+export default defineConfig({
+	integrations: [
+		starlight({
+			title: 'Documentação com Links de Redes Sociais',
+			social: {
+				discord: 'https://astro.build/chat',
+				github: 'https://github.com/withastro/starlight',
+			},
+		}),
+	],
+});
+```
+
+## Links de Edição
+
+Starlight pode mostrar um link de "Editar página" no rodapé de cada página.
+Isso faz fácil para um leitor encontrar o arquivo para editar para melhorar sua documentação.
+Particularmente para projetos open-source, isso pode ajudar a encorajar contribuições da sua comunidade.
+
+Para habilitar links de edição, defina [`editLink.baseUrl`](/pt-br/reference/configuration/#editlink) para a URL usada para editar seu repositório na configuração da integração Starlight.
+O valor de `editLink.baseUrl` será anexado ao caminho para a página atual para formar o link de edição completo.
+
+Padrões comuns incluem:
+
+- GitHub: `https://github.com/USUARIO/REPOSITORIO/edit/BRANCH/`
+- GitLab: `https://gitlab.com/USUARIO/REPOSITORIO/-/edit/BRANCH/`
+
+Se o seu projeto Starlight não está na raiz do seu repositório, inclua o caminho ao projeto no fim da URL base.
+
+Este exemplo mostra o link de edição configurado para a documentação do Starlight, que vive no subdiretório `docs/` da branch `main` do repositório `withastro/starlight` no GitHub:
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+
+export default defineConfig({
+	integrations: [
+		starlight({
+			title: 'Documentação com Links de Edição',
+			editLink: {
+				baseUrl: 'https://github.com/withastro/starlight/edit/main/docs/',
+			},
+		}),
+	],
+});
+```
+
+## Página 404 Customizada
+
+Sites Starlight mostram uma página 404 simples por padrão.
+Você pode customizá-la adicionando um arquivo `404.md` (ou `404.mdx`) ao seu diretório `src/content/docs/`:
+
+<FileTree>
+
+- src/
+  - content/
+    - docs/
+      - **404.md**
+      - index.md
+- astro.config.mjs
+
+</FileTree>
+
+Você pode utilizar todas as técnicas de customização e layout de página do Starlight em sua página 404. Por exemplo, a página 404 padrão utiliza o [template `splash`](#layout-da-página) e o componente [`hero`](/pt-br/reference/frontmatter/#hero) no frontmatter:
+
+```md
+---
+title: '404'
+template: splash
+editUrl: false
+hero:
+  title: '404'
+  tagline: Página não encontrada. Verifique a URL ou tenta utilizar a barra de pesquisa.
+---
+```
+
+## Fontes customizadas
+
+Por padrão, Starlight utiliza fontes sans-serif disponíveis no dispositivo local do usuário para todo o texto.
+Isso garante que a documentação carrega rapidamente em uma fonte que é familiar para cada usuário, sem precisar de largura de banda para baixar grandes arquivos de fonte.
+
+Se você deve adicionar uma fonte customizada ao seu site Starlight, você pode definir fontes para usar em arquivos CSS customizados ou com qualquer outra [técnica de estilização do Astro](https://docs.astro.build/pt-br/guides/styling/).
+
+### Configure fontes
+
+Se você já tem arquivos de fonte, siga o [guia de configuração local](#configure-arquivos-de-fonte-locais).
+Para utilizar Google Fonts, siga o [guia de configuração do Fontsource](#configure-uma-fonte-do-fontsource).
+
+#### Configure arquivos de fonte locais
+
+1. Adicione seus arquivos de fonte para o diretório `src/fonts/` e crie um arquivo vazio `font-face.css`:
+
+   <FileTree>
+
+   - src/
+     - content/
+     - fonts/
+       - **FonteCustomizada.woff2**
+       - **font-face.css**
+   - astro.config.mjs
+
+   </FileTree>
+
+2. Adicione uma [declaração `@font-face`](https://developer.mozilla.org/pt-BR/docs/Web/CSS/@font-face) para cada uma de suas fontes em `src/fonts/font-face.css`.
+   Utilize um caminho relativo para o arquivo de fonte na função `url()`.
+
+   ```css
+   /* src/fonts/font-face.css */
+
+   @font-face {
+   	font-family: 'Fonte Customizada';
+   	/* Use um caminho relativo para o arquivo de fonte local em `url()`. */
+   	src: url('./FonteCustomizada.woff2') format('woff2');
+   	font-weight: normal;
+   	font-style: normal;
+   	font-display: swap;
+   }
+   ```
+
+3. Adicione o caminho para seu arquivo `font-face.css` ao array `customCss` do Starlight em `astro.config.mjs`:
+
+   ```js
+   // astro.config.mjs
+   import { defineConfig } from 'astro/config';
+   import starlight from '@astrojs/starlight';
+
+   export default defineConfig({
+   	integrations: [
+   		starlight({
+   			title: 'Documentação Com Meu Tipo de Letra Customizado',
+   			customCss: [
+   				// Caminho relativo para seu arquivo CSS @font-face.
+   				'./src/fonts/font-face.css',
+   			],
+   		}),
+   	],
+   });
+   ```
+
+#### Configure uma fonte do Fontsource
+
+O projeto [Fontsource](https://fontsource.org/) simplifica a utilização de Google Fonts e outras fontes open-source.
+Ele providencia módulos do npm que você pode isntalar para as fontes que você quer usar e inclui arquivos CSS prontos para adicionar ao seu projeto.
+
+1.  Encontre a fonte que você quer utilizar no [catálogo do Fontsource](https://fontsource.org/).
+    Este exemplo irá utilizar [IBM Plex Serif](https://fontsource.org/fonts/ibm-plex-serif).
+
+2.  Instale o pacote da sua fonte escolhida.
+    Você pode encontrar o nome do pacote clicando em “Install” na página de fontes do Fontsource.
+
+         <Tabs>
+
+    <TabItem label="npm">
+
+    ```sh
+    npm install @fontsource/ibm-plex-serif
+    ```
+
+           </TabItem>
+
+        <TabItem label="pnpm">
+
+    ```sh
+    pnpm install @fontsource/ibm-plex-serif
+    ```
+
+           </TabItem>
+
+        <TabItem label="Yarn">
+
+    ```sh
+    yarn add @fontsource/ibm-plex-serif
+    ```
+
+           </TabItem>
+
+      </Tabs>
+
+3.  Adicione os arquivos CSS do Fontsource ao array `customCss` do Starlight em `astro.config.mjs`:
+
+    ```js
+    // astro.config.mjs
+    import { defineConfig } from 'astro/config';
+    import starlight from '@astrojs/starlight';
+
+    export default defineConfig({
+    	integrations: [
+    		starlight({
+    			title: 'Documentação Com Meu Tipo de Letra Customizado',
+    			customCss: [
+    				// Arquivos do Fontsource para as espessuras de fonte regular e semi-negrito.
+    				'@fontsource/ibm-plex-serif/400.css',
+    				'@fontsource/ibm-plex-serif/600.css',
+    			],
+    		}),
+    	],
+    });
+    ```
+
+    Fontsource envia múltiplos arquivos CSS para cada fonte. Veja a [documentação do Fontsource](https://fontsource.org/docs/getting-started/install#4-weights-and-styles) em como incluir diferentes espessuras e estilos para entender quais utilizar.
+
+### Utilize fontes
+
+Para aplicar a fonte que você definiu para o seu site, utilize o nome da sua fonte escolhida em um [arquivo CSS customizado](/pt-br/guides/css-and-tailwind/#estilos-css-customizados).
+Por exemplo, para sobrescrever a fonte padrão do Starlight em todo lugar, defina a propriedade customizada `--sl-font`:
+
+```css
+/* src/styles/customizada.css */
+
+:root {
+	--sl-font: 'IBM Plex Serif', serif;
+}
+```
+
+Você também pode escrever CSS mais específico se você quiser aplicar sua fonte mais seletivamente.
+Por exemplo, para definir uma fonte no conteúdo principal apenas, mas não nas barras laterais:
+
+```css
+/* src/styles/customizada.css */
+
+main {
+	font-family: 'IBM Plex Serif', serif;
+}
+```
+
+Siga as [instruções de CSS customizado](/pt-br/guides/css-and-tailwind/#estilos-css-customizados) para adicionar seus estilos ao seu site.