Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

i18n(pt-br): update guides/i18n.mdx #1197

Merged
merged 4 commits into from
Dec 15, 2023
Merged

i18n(pt-br): update guides/i18n.mdx #1197

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a6fb514
i18n(pt-br): update `guides/i18n.mdx`
daniloraisi Dec 1, 2023
75170e4
i18n(pt-br): update `guides/i18n.mdx`
daniloraisi Dec 5, 2023
bc500a9
Merge branch 'withastro:main' into main
daniloraisi Dec 5, 2023
6c04ebf
Merge branch 'main' into main
delucis Dec 15, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
116 changes: 77 additions & 39 deletions docs/src/content/docs/pt-br/guides/i18n.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,17 @@
---
title: Internacionalização (i18n)
description: Aprenda como configurar seu site Starlight para suportar várias línguas.
description: Aprenda como configurar seu site Starlight para suportar vários idiomas.
---

import FileTree from '../../../../components/file-tree.astro';

Starlight providencia suporte integrado para sites multilíngue, incluindo roteamento, conteúdo de fallback e suporte completo para línguas right-to-left (RTL).
O Starlight oferece suporte integrado para sites multi-idioma, incluindo roteamento, conteúdo de fallback e suporte completo para idiomas direita para esquerda (RTL).

## Configure i18n
## Configurar i18n

1. Diga ao Starlight as línguas que você suporta passando [`locales`](/pt-br/reference/configuration/#locales) e [`defaultLocale`](/pt-br/reference/configuration/#defaultlocale) para a integração Starlight:
1. Diga ao Starlight os idiomas que você suporta, passando [`locales`](/pt-br/reference/configuration/#locales) e [`defaultLocale`](/pt-br/reference/configuration/#defaultlocale) para a integração Starlight:

```js
```js {9-26}
// astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
Expand All @@ -20,12 +20,12 @@ Starlight providencia suporte integrado para sites multilíngue, incluindo rotea
integrations: [
starlight({
title: 'Minha Documentação',
// Define Português como a língua padrão deste site.
defaultLocale: 'pt',
// Define Português do Brasil como o idioma padrão deste site.
defaultLocale: 'pt-br',
locales: {
// Documentação em Português em `src/content/docs/pt/`
pt: {
label: 'Português',
// Documentação em Português do Brasil em `src/content/docs/pt-br/`
'pt-br': {
label: 'Português do Brasil',
},
// Documentação em Chinês Simplificado em `src/content/docs/zh-cn/`
'zh-cn': {
Expand All @@ -43,9 +43,9 @@ Starlight providencia suporte integrado para sites multilíngue, incluindo rotea
});
```

Seu `defaultLocale` será utilizado para o conteúdo de fallback e rótulos da UI, então escolha a língua que é a mais provável para você começar a escrever conteúdo em, ou já tem conteúdo para ela.
Seu `defaultLocale` será utilizado para o conteúdo de fallback e rótulos da UI, então escolha o idioma que é a mais provável que você começe a escrever conteúdo, ou já tem conteúdo escrito.

2. Crie um diretório para cada língua em `src/content/docs/`.
2. Crie um diretório para cada idioma em `src/content/docs/`.
Por exemplo, para a configuração mostrada acima, crie as seguintes pastas:

<FileTree>
Expand All @@ -54,22 +54,22 @@ Starlight providencia suporte integrado para sites multilíngue, incluindo rotea
- content/
- docs/
- ar/
- pt/
- pt-br/
- zh-cn/

</FileTree>

3. Você agora pode adicionar arquivos de conteúdo em seus diretórios da língua. Use o mesmo nome de arquivo para associar páginas entre línguas e se aproveite do conjunto completo de funcionalidades de i18n do Starlight, incluindo conteúdo de fallback, avisos de tradução e mais.
3. Você agora pode adicionar arquivos de conteúdo em seus diretórios de idioma. Use o mesmo nome de arquivo para associar páginas entre idiomas e se aproveite do conjunto completo de funcionalidades de internacionalização do Starlight, incluindo conteúdo de fallback, avisos de tradução e mais.

Por exemplo, crie `ar/index.md` e `pt/index.md` para representar a página inicial em Árabe e Português respectivamente.
Por exemplo, crie `ar/index.md` e `pt-br/index.md` para representar a página inicial em Árabe e Português do Brasil respectivamente.

### Use um local raiz
### Use uma localidade raiz

Você pode usar um local “raiz” para servir uma língua sem nenhum prefixo de i18n no seu caminho. Por exemplo, se Português é seu local raiz, um caminho de página em Português se pareceria com `/sobre` ao invés de `/pt/sobre`.
Você pode usar uma localidade “raiz” para servir um idioma sem nenhum prefixo de internacionalização no seu diretório. Por exemplo, se Português do Brasil é sua localidade raiz, um diretório de página em Português do Brasil seria `/sobre` ao invés de `/pt-br/sobre`.

Para definir um local raiz, use a chave `root` na sua configuração de `locales`. Se o local raiz também for o local padrão do seu conteúdo, remova `defaultLocale` ou defina-o como `'root'`.
Para definir uma localidade raiz, use a chave `root` na sua configuração de `locales`. Se a localidade raiz também for a localidade padrão do seu conteúdo, remova `defaultLocale` ou defina como `'root'`.

```js
```js {9,11-14}
// astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
Expand All @@ -81,8 +81,8 @@ export default defineConfig({
defaultLocale: 'root', // opcional
locales: {
root: {
label: 'Português',
lang: 'pt', // lang é obrigatório para locais raiz
label: 'Português do Brasil',
lang: 'pt-br', // lang é obrigatório para localidade raiz
},
'zh-cn': {
label: '简体中文',
Expand All @@ -94,7 +94,7 @@ export default defineConfig({
});
```

Ao utilizar um local `root`, mantenha as páginas para aquela língua diretamente em `src/content/docs/` ao invés de em uma pasta dedicada para a língua. Por exemplo, aqui está os arquivos para a página inicial em Português e Chinês ao utilizar a configuração acima:
Ao utilizar uma localidade `root`, mantenha as páginas para aquele idioma diretamente em `src/content/docs/` ao invés de em uma pasta dedicada para o idioma. Por exemplo, aqui estão os arquivos para a página inicial em Português do Brasil e Chinês ao utilizar a configuração acima:

<FileTree>

Expand All @@ -107,11 +107,11 @@ Ao utilizar um local `root`, mantenha as páginas para aquela língua diretament

</FileTree>

#### Sites monolíngue
#### Sites mono-idioma

Por padrão, Starlight é um site (Inglês) monolíngue. Para criar um site de língua única em outra língua, a defina como o `root` na sua configuração de `locales`:
Por padrão, Starlight é um site mono-idioma (em Inglês). Para criar um site de idioma único em outro idioma, o defina como o `root` na sua configuração de `locales`:

```js
```diff lang="js" {10-13}
// astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
Expand All @@ -122,45 +122,47 @@ export default defineConfig({
title: 'Minha Documentação',
locales: {
root: {
label: '简体中文',
lang: 'zh-CN',
label: 'Português do Brasil',
lang: 'pt-br',
},
},
}),
],
});
```

Isso te permite sobrescrever a língua padrão do Starlight sem habilitar outras funcionalidades de internacionalização para sites multilíngue, como o seletor de língua.
Isso te permite sobrescrever o idioma padrão do Starlight sem habilitar outras funcionalidades de internacionalização para sites multi-idioma, como o seletor de idiomas.

## Conteúdo de Fallback

Starlight espera que você crie páginas equivalentes em todas as suas línguas. Por exemplo, se você tem um arquivo `en/about.md` crie, um `about.md` para cada outra língua que você suporta. Isso permite que Starlight providencie conteúdo de fallback automático para páginas que você ainda não tenha traduzidas.
Starlight espera que você crie páginas equivalentes em todos os idiomas. Por exemplo, se você tem um arquivo `en/about.md` crie, um `about.md` para cada outro idioma que o site suporta. Isso permite ao Starlight oferecer conteúdo de fallback automático para páginas que você ainda não tenha traduzido.

Se uma tradução ainda não está disponível para uma língua, Starlight irá mostrar aos leitores o conteúdo dessa página na língua padrão (definida através de `defaultLocale`). Por exemplo, se você ainda não criou uma versão em Francês da sua página "Sobre" e sua língua padrão é Inglês, visitantes de `/fr/about` irão ver o conteúdo em Inglês de `/en/about` com um aviso de que esta página ainda não foi traduzida. Isso te ajuda a adicionar conteúdo na sua língua padrão e então progressivamente traduzí-la quando seus tradutores tiverem tempo.
Se uma tradução ainda não está disponível para um idioma, Starlight irá mostrar aos leitores o conteúdo dessa página no idioma padrão (definido através de `defaultLocale`). Por exemplo, se você ainda não criou uma versão em Francês da sua página "Sobre" e seu idioma padrão é Português do Brasil, visitantes de `/fr/about` verão o conteúdo em Português do Brasil de `/pt-br/about` com um aviso de que esta página ainda não foi traduzida. Isso te ajuda a adicionar conteúdo no seu idioma padrão e então progressivamente traduzí-lo quando seus tradutores tiverem tempo.

## Traduza a UI do Starlight

Em adição a hospedar arquivos de conteúdo traduzido, Starlight te permite traduzir as strings padrões da UI (e.x. o cabeçalho "Nesta página" no índice) para que seus leitores possam experienciar seu site inteiramente na língua selecionada.
import LanguagesList from '../../../../components/languages-list.astro';

Strings da UI são providenciadas para Inglês, Tcheco, Francês, Alemão, Italiano, Japonês, Português, Holandês, Dinamarquês, Espanhol, Turco, Árabe, Norueguês, Persa, Hebraico, Chinês Simplificado, Coreano, Indonésio, Russo, Sueco, Ucraniano e Vietnamita por padrão, e nós aceitamos [contribuições para adicionar mais línguas padrões](https://github.com/withastro/starlight/blob/main/CONTRIBUTING.md).
Além de arquivos de conteúdo traduzido, o Starlight te permite traduzir as strings padrão da UI (e.x. o cabeçalho "Nesta página" no índice) para que seus leitores possam utilizar seu site inteiramente no idioma selecionado.

Você pode fornecer traduções para línguas adicionais que você suporta — ou sobrescrever nossos rótulos padrões — através da coleção de dados `i18n`.
Strings da UI estão disponíveis para <LanguagesList /> por padrão, e são bem vindas [contribuições para adicionar mais idiomas padrão](https://github.com/withastro/starlight/blob/main/CONTRIBUTING.md).

1. Configure a coleção de dados `i18n` em `src/content/config.ts` se já não estiver configurado:
Você pode fornecer traduções para idiomas adicionais que você suporta — ou sobrescrever nossos rótulos padrões — através da coleção de dados `i18n`.

```js
1. Configure a coleção de dados `i18n` em `src/content/config.ts` se já não tiver configurado:

```diff lang="js" ins=/, (i18nSchema)/
// src/content/config.ts
import { defineCollection } from 'astro:content';
import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';

export const collections = {
docs: defineCollection({ schema: docsSchema() }),
i18n: defineCollection({ type: 'data', schema: i18nSchema() }),
+ i18n: defineCollection({ type: 'data', schema: i18nSchema() }),
};
```

2. Crie um arquivo JSON em `src/content/i18n/` para cada local adicional que você quer providenciar tradução de strings da UI.
2. Crie um arquivo JSON em `src/content/i18n/` para cada localidade adicional que você quer oferecer tradução de strings da UI.
Por exemplo, isso adicionaria arquivos de tradução para Árabe e Chinês Simplificado:

<FileTree>
Expand All @@ -173,7 +175,7 @@ Você pode fornecer traduções para línguas adicionais que você suporta — o

</FileTree>

3. Adicione traduções para as chaves que você quer traduzir para os arquivos JSON. Traduza apenas os valores, deixando as chaves em Inglês (e.x. `"search.label": "Buscar"`).
3. Adicione traduções para os rótulos que você quer traduzir nos arquivos JSON. Traduza apenas os valores, deixando as chaves em Inglês (e.x. `"search.label": "Buscar"`).

Essas são as strings padrões existentes em Inglês que vem com o Starlight:

Expand Down Expand Up @@ -202,8 +204,19 @@ Você pode fornecer traduções para línguas adicionais que você suporta — o
}
```

O blocos de código do Starlight usam a biblioteca [Expressive Code](https://github.com/expressive-code/expressive-code).
Você pode traduzir as strings de UI do Expressive Code no mesmo arquivo JSON usando as chaves `expressiveCode`:

```json
{
"expressiveCode.copyButtonCopied": "Copiado!",
"expressiveCode.copyButtonTooltip": "Copiar",
"expressiveCode.terminalWindowFallbackTitle": "Janela do Terminal"
}
```

O modal de pesquisa do Starlight é fornecido pela biblioteca [Pagefind](https://pagefind.app/).
Você pode definir traduções para a UI do Pagefind no mesmo arquivo JSON utilizando chaves com `pagefind`:
Você pode traduzir as strings de UI do Pagefind no mesmo arquivo JSON utilizando chaves com `pagefind`:

```json
{
Expand All @@ -219,3 +232,28 @@ Você pode fornecer traduções para línguas adicionais que você suporta — o
"pagefind.searching": "Searching for [SEARCH_TERM]..."
}
```

### Esquema de tradução extendida

Você pode adicionar chaves personalizadas no dicionário de tradução do seu site configurando a propriedade `extend` nas opções do `i18nSchema()`.
No exemplo a seguir, a nova chave `custom.label`, opcional, é adicionada às chaves padrão:

```diff lang="js"
// src/content/config.ts
import { defineCollection, z } from 'astro:content';
import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';

export const collections = {
docs: defineCollection({ schema: docsSchema() }),
i18n: defineCollection({
type: 'data',
schema: i18nSchema({
+ extend: z.object({
+ 'custom.label': z.string().optional(),
+ }),
}),
}),
};
```

Saiba mais sobre o esquemas de coleções de conteúdos em [“Definindo um esquema de coleção”](https://docs.astro.build/pt-br/guides/content-collections/#definindo-um-esquema-de-cole%C3%A7%C3%A3o) na documentação do Astro.