Os textos do tema estão traduzidos em sete locales. Um site serve o subconjunto
que quiser, traduz os textos que ele próprio configurou e — se quiser — também
as páginas.

## Passos

::steps
1. **Reduz a lista com `duxt.locales`.**

   ```ts [app/app.config.ts]
   locales: ['en-GB', 'pt-PT']
   ```

   Não o array `locales` do i18n: esse combina entre camadas em vez de
   substituir, por isso declarar dois aí deixa os outros cinco roteados e
   anunciados em `hreflang`.

2. **Escolhe o que fica sem prefixo** no `nuxt.config.ts` com
   `i18n.defaultLocale`. É relevante para o URL: mudá-lo mais tarde move todas
   as páginas nos dois sentidos ao mesmo tempo.

3. **Traduz os teus próprios textos.** Para um punhado, a forma de registo custa
   menos do que um ficheiro de locale por idioma:

   ```ts
   sections: [
     {
       label: { 'en-GB': 'Guides', 'pt-PT': 'Guias' },
       to: '/guides',
       icon: 'lucide:book-open'
     }
   ]
   ```

   Para mais do que um punhado, regista as tuas próprias chaves i18n e escreve a
   chave. Não recorras a `duxt.defaults.*` — são as chaves internas da camada, e
   uma mudança de nome aí partiria o teu site em silêncio.

4. **Define a origem.** `hreflang` não é válido em relativo, por isso precisa de
   `i18n.baseUrl` ou `NUXT_PUBLIC_I18N_BASE_URL`.

5. **Traduz as páginas, se quiseres.** Uma pasta por idioma dentro da fonte; o
   locale por omissão fica onde está e não move nenhum URL:

   ```ts [app/app.config.ts]
   sources: [{ path: 'docs', locales: ['en-GB', 'pt'] }]
   ```

   ::file-tree{title="docs/"}
   ---
   tree:
     - name: index.md
     - name: 1.getting-started/
       children:
         - name: index.md
     - name: pt/
       children:
         - name: index.md
   ---
   ::

   Traduz tão poucas páginas quanto quiseres — tudo o resto recai no original,
   com um aviso que diz ao leitor porquê.

6. **Abre uma página em cada locale** e verifica que a interface mudou de
   idioma, que o caminho continua a resolver e que nenhum rótulo configurado
   aparece como chave em bruto.
::

## Só algumas versões, ou outro repositório

`locales` numa ref sobrepõe-se ao da fonte, que é a forma habitual: a versão
atual está traduzida e as duas anteriores não.

```ts
{
  path: 'docs',
  locales: ['en-GB', 'pt'],
  refs: [
    { tag: 'v2.0.0' },                     // ambos os idiomas
    { tag: 'v1.0.0', locales: ['en-GB'] }  // só o original
  ]
}
```

A forma de objeto move um idioma completamente para outro sítio — o seu próprio
repositório, com os seus próprios responsáveis e o seu próprio ritmo:

```ts
locales: ['en-GB', { locale: 'pt', repo: 'acme/docs-pt', path: 'docs' }]
```

É o que o React e o Vue fazem fora das suas ferramentas, com `de.react.dev` e a
organização `vuejs-translations`, porque quem traduz trabalha com o seu próprio
calendário e a sua própria revisão. Aqui é uma entrada de fonte em vez de um
segundo site — um índice de pesquisa, um seletor de idioma.

::callout{type="warning" title="O que custa compilar uma tradução"}
Cerca de **dois segundos de compilação e 0,6 MB de base de dados por idioma ×
versão × repositório**, medido linear até pelo menos 200 coleções. Traduzir
todas as versões de todos os repositórios multiplica os três; traduzir apenas a
versão atual é o que a maioria dos projetos faz.
::

## Direção da escrita

O locale ativo fornece a direção do documento além do idioma. A navegação, os
painéis, as setas e a disposição da página refletem-se quando um site consumidor
acrescenta um locale RTL, porque os componentes do duxt usam início e fim
lógicos. O material técnico não é refletido às cegas: código, comandos,
caminhos, nomes de API e outra sintaxe LTR mantêm a direção em que são legíveis.

O duxt não inclui atualmente nenhum locale RTL. Direction-aware significa que
um site pode acrescentar um sem fazer fork do tema, não que um dos sete locales
incluídos seja RTL.

## Quando uma página não tem tradução

O leitor recebe o idioma mais próximo que a tenha, com um aviso, e a página leva
`noindex` mais um canonical a apontar para o idioma em que realmente está. A
cadeia — locale, língua base, região irmã, `fallbackLocale`, original — está em
[Localização](/concepts/localisation).

## Lista de verificação

- [ ] `duxt.locales` lista exatamente os locales que serves
- [ ] `/sitemap.xml` contém uma entrada por página e locale, e mais nenhuma
- [ ] As ligações `hreflang` são absolutas
- [ ] Nenhum rótulo configurado aparece como chave em bruto
- [ ] Mudar de locale mantém o leitor na mesma página
- [ ] Uma página que não traduziste mostra o aviso de recurso, não um 404
- [ ] Um locale RTL acrescentado reflete a interface enquanto a sintaxe técnica
      permanece LTR
- [ ] `duxt.sourceOptions.defaultLocale` corresponde a `i18n.defaultLocale`